first commit

docs/security-stack/crypto/crypto-vault/src/srp/srp-group.md

@@ -0,0 +1,71 @@
+# SRP-6a 2048-bit group
+
+## Purpose
+
+`srp-group.ts` exports the canonical 2048-bit MODP group from RFC 5054
+Appendix A as `bigint` constants. The SRP-6a client uses this group to
+exchange ephemeral keys, derive the shared secret, and produce mutual
+proofs. The constants are pinned because they are part of the protocol
+contract — switching groups silently would break interoperability with
+every server using the same RFC.
+
+## Features
+
+- `SRP_N_2048` — the 2048-bit safe prime `N` as a positive `bigint`.
+- `SRP_G` — the generator `g = 2`.
+- `SRP_N_BITLEN = 2048`, `SRP_N_BYTELEN = 256` — convenience constants for
+  byte-padding and validation.
+
+## Usage: Basic Example
+
+```ts
+import { SRP_G, SRP_N_2048 } from "@suaveplan/crypto-vault/srp/srp-group";
+console.log(SRP_N_2048.toString(2).length); // 2048
+console.log(SRP_G); // 2n
+```
+
+## Usage: Advanced Example
+
+```ts
+import {
+    SRP_G,
+    SRP_N_2048,
+    SRP_N_BITLEN,
+    SRP_N_BYTELEN,
+} from "@suaveplan/crypto-vault/srp/srp-group";
+import { pow } from "@noble/curves/abstract/modular";
+
+// Compute v = g^x mod N for an arbitrary private key x.
+function makeVerifier(x: bigint): bigint {
+    return pow(SRP_G, x, SRP_N_2048);
+}
+
+console.log(SRP_N_BITLEN); // 2048
+console.log(SRP_N_BYTELEN); // 256
+console.log(typeof makeVerifier(123n)); // bigint
+```
+
+## API Reference
+
+### `SRP_N_2048: bigint`
+
+The exact 2048-bit safe prime defined in RFC 5054 Appendix A, parsed from
+the canonical hex constant.
+
+### `SRP_G: bigint`
+
+The generator: `2n`.
+
+### `SRP_N_BITLEN: number`, `SRP_N_BYTELEN: number`
+
+Bit length (`2048`) and byte length (`256`) of the prime.
+
+## Implementation Notes
+
+- The hex string is laid out as a TypeScript string concatenation matching
+  the line breaks in the RFC for diffability against the source.
+- The constant is parsed once at module load; subsequent imports share the
+  resulting `bigint`.
+- The 1024-bit and 1536-bit groups from the same RFC are intentionally
+  omitted. RFC 5054 §1 states they should be deprecated for new
+  deployments, and the proposal pins us to ≥ 2048 bits.