Initial Commit

packages/security-stack/security/srp/src/groups/4096/groups-4096.md

@@ -0,0 +1,56 @@
+# `groups-4096`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+RFC 5054 Appendix A 4096-bit safe-prime group with generator `g = 5`. Reachable via `@suaveplan/srp/groups/4096`. Suitable for deployments that want headroom above the contemporary 2048-bit default at the cost of roughly 8x the `modPow` wall-clock time. Recommended when verifier-database lifetime is measured in decades or when the threat model includes well-resourced precomputed-discrete-log attacks against bundled groups.
+
+## Features
+
+- `N_4096` byte-exact to RFC 5054 Appendix A "4096-bit Group".
+- `g_4096 = Uint8Array([5])`.
+- `BIT_LENGTH` literal `4096`.
+- Subpath-only.
+
+## Usage: Basic Example
+
+```ts
+import { N_4096, g_4096, BIT_LENGTH } from "@suaveplan/srp/groups/4096";
+
+console.log(N_4096.byteLength); // 512
+console.log(BIT_LENGTH); // 4096
+```
+
+## Usage: Advanced Example
+
+```ts
+import { N_4096, g_4096 } from "@suaveplan/srp/groups/4096";
+import { defaultHashBridge } from "@suaveplan/srp/hash";
+import type { SrpParams } from "@suaveplan/srp/params";
+
+const params: SrpParams = {
+    N: N_4096,
+    g: g_4096,
+    bitLength: 4096,
+    hash: defaultHashBridge("SHA256"),
+    algorithm: "SHA256",
+};
+```
+
+## API Reference
+
+| Export       | Type         | Description                |
+| ------------ | ------------ | -------------------------- |
+| `N_4096`     | `Uint8Array` | 512-byte 4096-bit modulus. |
+| `g_4096`     | `Uint8Array` | Generator `0x05`.          |
+| `BIT_LENGTH` | `4096`       | Literal bit length.        |
+
+## Implementation Notes
+
+A 4096-bit `modPow` takes roughly 8x the time of a 2048-bit `modPow`. On a contemporary laptop this is ~40–160 ms per handshake step. Interactive login flows that target sub-200 ms perceptual budgets SHOULD pre-warm `modPow` (run a no-op call during page load) or schedule the handshake outside the critical path.
+
+The byte-exact correctness gate lives in the spec-conformance suite. The constant is reviewed against RFC 5054 Appendix A's literal at every package release.
+
+The generator `g = 5` is unique to the larger RFC 5054 groups (3072, 4096, 6144); the smaller groups (1024, 1536, 2048) all use `g = 2`. The chosen generator depends on the modulus's quadratic-residue structure — RFC 5054 picked it once at design time so `g` generates a large prime-order subgroup of `Z_N*`. Consumers building `SrpParams` from raw constants MUST use `g_4096` rather than hard-coding `0x02`; using the wrong generator weakens the discrete-log hardness guarantee that backs SRP-6a's zero-knowledge property.