first commit

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

@@ -0,0 +1,70 @@
+# p521.select
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+`p521.select.ts` is the build-time primitive selector for NIST P-521 in
+`@suaveplan/crypto-curve`. Generated by `bun scripts/gen-crypto-selects.ts`,
+it re-exports one concrete backend — `p521.noble.ts` or `p521.native.ts` —
+according to the `p521` field in `crypto.config.ts`.
+
+Callers import through the stable `p521.ts` entry point. This selector
+level insulates all call sites from backend changes: regenerating this
+file is the only step required to switch implementations. Currently the
+Noble backend is active because the native stub throws
+`PrimitiveNotImplemented`.
+
+## Features
+
+- Single re-export of `getPublicKey`, `sign`, `verify`, and `randomPrivateKey`.
+- Generated — never hand-edited.
+- Controlled by `crypto.config.ts`: set `p521` to `'noble'` or `'native'`.
+- Enables dead-code elimination of the inactive backend.
+- Maintains a stable API across backend switches.
+
+## Usage: Basic Example
+
+```ts
+import * as p521 from "@suaveplan/crypto-curve/p521";
+
+const sk = p521.randomPrivateKey();
+const pk = p521.getPublicKey(sk);
+console.log(pk.length); // 67
+```
+
+## Usage: Advanced Example
+
+```ts
+import * as p521 from "@suaveplan/crypto-curve/p521";
+import { sha512 } from "@suaveplan/crypto-hash";
+
+function roundTrip(message: Uint8Array): boolean {
+    const sk = p521.randomPrivateKey();
+    const pk = p521.getPublicKey(sk);
+    const digest = sha512(message);
+    const sig = p521.sign(digest, sk);
+    return p521.verify(sig, digest, pk);
+}
+```
+
+## API Reference
+
+Re-exports from the active implementation:
+
+- `getPublicKey(privateKey: Uint8Array): Uint8Array` — 67-byte compressed
+  P-521 public key.
+- `sign(digest: Uint8Array, privateKey: Uint8Array): Uint8Array` — 132-byte
+  compact ECDSA signature.
+- `verify(signature: Uint8Array, digest: Uint8Array, publicKey: Uint8Array): boolean`
+- `randomPrivateKey(): Uint8Array` — rejection-sampled 66-byte key.
+
+## Implementation Notes
+
+The selector file contains a single `export * from` line and is marked
+`/* GENERATED — DO NOT EDIT */`. P-521 keys carry an additional invariant
+that callers need to be aware of: the high byte of every scalar / coordinate
+must have the top 7 bits zero (the curve has a 521-bit order, byte-aligned
+to 66 bytes). The noble backend enforces this in `isValidPrivateKey`; the
+rejection loop in `randomPrivateKey` retries until the constraint holds.