Initial Commit

packages/security-stack/crypto/crypto-hash/src/primitives/sha384/impl/sha384.native/index.ts

@@ -0,0 +1 @@
+export { sha384 } from "./sha384.native.js";

packages/security-stack/crypto/crypto-hash/src/primitives/sha384/impl/sha384.native/sha384.native.md

@@ -0,0 +1,64 @@
+# sha384.native
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+`sha384.native.ts` is the native-backend placeholder for the SHA-384 primitive in `@suaveplan/crypto-hash`. It exposes the same `sha384(data: Uint8Array): Uint8Array` signature as the Noble implementation but throws `PrimitiveNotImplemented("sha384")` unconditionally.
+
+The file exists to keep the two-implementation primitive selector layout structurally complete for all primitives in the package. Having both `sha384.noble.ts` and `sha384.native.ts` present means the generator script can switch backends without any missing-file errors, and CI can validate the native stub's presence as part of the layout test.
+
+## Features
+
+- Satisfies `sha384(data: Uint8Array): Uint8Array` interface for the selector.
+- Throws `PrimitiveNotImplemented("sha384")` unconditionally.
+- Signals clearly that this path is not yet active.
+- Zero runtime dependencies beyond `@suaveplan/crypto-utils/errors`.
+
+## Usage: Basic Example
+
+```ts
+// Active only when crypto.config.ts sets sha384 to 'native'.
+// Currently throws unconditionally.
+import { sha384 } from "@suaveplan/crypto-hash/primitives/sha384/sha384";
+
+try {
+    sha384(new Uint8Array(32));
+} catch (err) {
+    // PrimitiveNotImplemented: sha384
+    console.error(err);
+}
+```
+
+## Usage: Advanced Example
+
+```ts
+// Pattern for graceful capability detection during native migration.
+import { sha384 } from "@suaveplan/crypto-hash/primitives/sha384/sha384";
+
+function isSha384Available(): boolean {
+    try {
+        sha384(new Uint8Array(1));
+        return true;
+    } catch {
+        return false;
+    }
+}
+```
+
+## API Reference
+
+### `sha384(_data: Uint8Array): Uint8Array`
+
+Placeholder that always throws.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `_data` | `Uint8Array` | Ignored. |
+
+**Throws:** `PrimitiveNotImplemented("sha384")` — always.
+
+## Implementation Notes
+
+Like all native stubs in the package, the underscore prefix on `_data` suppresses unused-parameter warnings from TypeScript and Biome without requiring a lint-disable comment. When the in-house SHA-384 implementation is complete and has passed the NIST CAVP test suite (via the KAT harness in `@suaveplan/crypto-utils`), this file is updated with the real implementation and the selector is regenerated to point here.

packages/security-stack/crypto/crypto-hash/src/primitives/sha384/impl/sha384.native/sha384.native.ts

@@ -0,0 +1,5 @@
+import { PrimitiveNotImplemented } from "@suaveplan/crypto-utils/errors";
+
+export function sha384(_data: Uint8Array): Uint8Array {
+    throw new PrimitiveNotImplemented("sha384");
+}

packages/security-stack/crypto/crypto-hash/src/primitives/sha384/impl/sha384.noble/index.ts

@@ -0,0 +1 @@
+export { sha384 } from "./sha384.noble.js";

packages/security-stack/crypto/crypto-hash/src/primitives/sha384/impl/sha384.noble/sha384.noble.md

@@ -0,0 +1,59 @@
+# sha384.noble
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+`sha384.noble.ts` is the Noble-backed concrete implementation of the SHA-384 primitive in `@suaveplan/crypto-hash`. It delegates to `sha384` from `@noble/hashes/sha2`, exposing a minimal one-shot interface that the selector and public façade expect.
+
+SHA-384 is the FIPS 180-4 truncation of SHA-512 to 48 bytes. It is preferred in high-throughput 64-bit environments over SHA-256 because SHA-512's 64-bit word arithmetic is natively fast on modern hardware, and the truncation gives a slight output-size reduction. This file is the production-quality side of the two-implementation layout.
+
+## Features
+
+- Delegates entirely to `@noble/hashes/sha2` SHA-384 implementation.
+- Returns a fresh 48-byte `Uint8Array` on every call.
+- Zero side effects; no global state or lazy initialisation.
+- Tree-shakeable: unreachable when the native backend is selected.
+
+## Usage: Basic Example
+
+```ts
+import { sha384 } from "@suaveplan/crypto-hash/primitives/sha384/sha384";
+
+const digest = sha384(new TextEncoder().encode("hello"));
+console.log(digest.length); // 48
+```
+
+## Usage: Advanced Example
+
+```ts
+import { sha384 } from "@suaveplan/crypto-hash/primitives/sha384/sha384";
+import { toHex } from "@suaveplan/crypto-hash/encoding";
+
+// Compute a SHA-384 content hash for cache busting.
+function contentHash(payload: Uint8Array): string {
+    return `sha384-${toHex(sha384(payload))}`;
+}
+
+const tag = contentHash(new TextEncoder().encode("bundle contents"));
+console.log(tag.startsWith("sha384-")); // true
+```
+
+## API Reference
+
+### `sha384(data: Uint8Array): Uint8Array`
+
+Computes the SHA-384 digest of `data`.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `data` | `Uint8Array` | Arbitrary byte sequence. |
+
+**Returns:** Fresh 48-byte `Uint8Array`.
+
+**Throws:** Never.
+
+## Implementation Notes
+
+The function body is `return nobleSha384(data)` — a single pass-through with no added logic. Noble allocates the output buffer internally. SHA-384 shares the SHA-512 compression function and differs only in the initial hash values and the truncation of the final state to 384 bits. The Noble implementation passes NIST CAVP vectors for SHA-384. No streaming interface is exposed at this layer.

packages/security-stack/crypto/crypto-hash/src/primitives/sha384/impl/sha384.noble/sha384.noble.ts

@@ -0,0 +1,8 @@
+import { sha384 as nobleSha384 } from "@noble/hashes/sha2";
+
+/**
+ * SHA-384 noble-backed impl. One-shot digest → 48 bytes.
+ */
+export function sha384(data: Uint8Array): Uint8Array {
+    return nobleSha384(data);
+}

packages/security-stack/crypto/crypto-hash/src/primitives/sha384/index.ts

@@ -0,0 +1 @@
+export { sha384 } from "./sha384.select/sha384.select";

packages/security-stack/crypto/crypto-hash/src/primitives/sha384/sha384.select/index.ts

@@ -0,0 +1 @@
+export * from "./sha384.select.js";

packages/security-stack/crypto/crypto-hash/src/primitives/sha384/sha384.select/sha384.select.md

@@ -0,0 +1,60 @@
+# sha384.select
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+`sha384.select.ts` is the build-time primitive selector for the SHA-384 implementation. It is a generated file that re-exports exactly one concrete implementation — either `sha384.noble.ts` (the audited `@noble/hashes` backend) or `sha384.native.ts` (the in-house native backend) — based on the setting in `crypto.config.ts`.
+
+Consumers import SHA-384 through the stable public entry point, which resolves here; they are insulated from backend changes. Regenerating this file via `bun scripts/gen-crypto-selects.ts` is the only step required to swap implementations.
+
+## Features
+
+- Single-symbol re-export of `sha384(data: Uint8Array): Uint8Array`.
+- Generated by `bun scripts/gen-crypto-selects.ts` — never hand-edited.
+- Controlled by `crypto.config.ts`: set `sha384` to `'noble'` or `'native'`.
+- Maintains a stable public API across backend switches.
+- Enables static dead-code elimination of the unused backend.
+
+## Usage: Basic Example
+
+```ts
+import { sha384 } from "@suaveplan/crypto-hash/primitives/sha384/sha384";
+
+const digest = sha384(new TextEncoder().encode("hello"));
+console.log(digest.length); // 48
+```
+
+## Usage: Advanced Example
+
+```ts
+import { sha384 } from "@suaveplan/crypto-hash/primitives/sha384/sha384";
+
+// Compute a commitment to a serialised record.
+function commit(record: Record<string, string>): Uint8Array {
+    const encoded = new TextEncoder().encode(JSON.stringify(record));
+    return sha384(encoded);
+}
+
+const hash = commit({ userId: "u_123", action: "login" });
+console.log(hash.length); // 48
+```
+
+## API Reference
+
+Re-exports the following from the active implementation:
+
+### `sha384(data: Uint8Array): Uint8Array`
+
+One-shot SHA-384 digest.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `data` | `Uint8Array` | Arbitrary byte sequence to hash. |
+
+**Returns:** Fresh 48-byte `Uint8Array` containing the SHA-384 digest.
+
+## Implementation Notes
+
+SHA-384 is a truncation of SHA-512 that shares the same 64-bit word operations and block size. It is preferred over SHA-256 in environments that process large amounts of data on 64-bit processors because the 64-bit arithmetic is natively fast, and the truncation provides a modest reduction in output size relative to SHA-512. The Noble backend delegates to `@noble/hashes/sha2` without any added overhead. The native stub throws `PrimitiveNotImplemented("sha384")` until the in-house implementation is ready and has passed the NIST CAVP test vectors.

packages/security-stack/crypto/crypto-hash/src/primitives/sha384/sha384.select/sha384.select.ts

@@ -0,0 +1,2 @@
+/* GENERATED — DO NOT EDIT. Regenerate with `bun scripts/gen-crypto-selects.ts`. */
+export * from "../impl/sha384.noble/sha384.noble.js";