Initial Commit

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.