first commit

docs/security-stack/crypto/crypto-curve/src/primitives/x25519/x25519.select/x25519.select.md

@@ -0,0 +1,54 @@
+# x25519.select
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+`x25519.select.ts` is the build-time primitive selector for X25519 in `@suaveplan/crypto-curve`. Generated by `bun scripts/gen-crypto-selects.ts`, it re-exports one backend — `x25519.noble.ts` or `x25519.native.ts` — based on the `x25519` entry in `crypto.config.ts`.
+
+Callers import through `x25519.ts`, which delegates here. The selector isolates callers from backend changes: switching from Noble to a native implementation requires only regenerating this file. Currently the Noble backend is active because the native stub throws `PrimitiveNotImplemented`.
+
+## Features
+
+- Single re-export of `getPublicKey`, `getSharedSecret`, and `randomPrivateKey`.
+- Generated — never hand-edited.
+- Controlled by `crypto.config.ts`: set `x25519` to `'noble'` or `'native'`.
+- Enables dead-code elimination of the inactive backend.
+
+## Usage: Basic Example
+
+```ts
+import * as x25519 from "@suaveplan/crypto-curve/x25519";
+
+const sk = x25519.randomPrivateKey();
+const pk = x25519.getPublicKey(sk);
+console.log(pk.length); // 32
+```
+
+## Usage: Advanced Example
+
+```ts
+import * as x25519 from "@suaveplan/crypto-curve/x25519";
+
+// Simple ECDH exchange.
+function exchange(localSk: Uint8Array, remotePk: Uint8Array): Uint8Array {
+    return x25519.getSharedSecret(localSk, remotePk);
+}
+```
+
+## API Reference
+
+Re-exports from the active implementation:
+
+- `getPublicKey(privateKey: Uint8Array): Uint8Array` — 32-byte public key.
+- `getSharedSecret(privateKey: Uint8Array, peerPublicKey: Uint8Array): Uint8Array` — 32-byte raw shared secret.
+- `randomPrivateKey(): Uint8Array` — 32 random bytes.
+
+## Implementation Notes
+
+This file is a generated one-liner: `export * from "./impl/x25519.noble.js"`. The generator resolves the configured backend and writes the appropriate path. The file is idempotent and safe to regenerate at any time. Do not add logic here — it will be overwritten.
+
+### Selection Logic
+
+At build time `crypto.config.ts` picks either the Noble or the native engine for every primitive; the selector exported here reads the generated `crypto-selects` map and routes calls to the chosen impl. When the selected engine is not yet implemented, the `PrimitiveNotImplemented` sentinel from `@suaveplan/crypto-utils` is thrown with the primitive-id baked in so logs identify the exact missing slot.