Initial Commit

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

@@ -0,0 +1,55 @@
+# `groups-8192`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+RFC 5054 Appendix A 8192-bit safe-prime group with generator `g = 19`. Reachable via `@suaveplan/srp/groups/8192`. The largest bundled group RFC 5054 specifies. Use only when verifier-database lifetime extends beyond the practical horizon of precomputed-discrete-log attacks against bundled primes; for almost every contemporary deployment the 2048-bit default is sufficient and the 8192-bit group's ~64x `modPow` slowdown is not justified.
+
+## Features
+
+- `N_8192` byte-exact to RFC 5054 Appendix A "8192-bit Group".
+- `g_8192 = Uint8Array([19])` — RFC 5054 mandates `g = 19` for this size.
+- `BIT_LENGTH` literal `8192`.
+- Subpath-only.
+
+## Usage: Basic Example
+
+```ts
+import { N_8192, g_8192, BIT_LENGTH } from "@suaveplan/srp/groups/8192";
+
+console.log(N_8192.byteLength); // 1024
+console.log(g_8192[0]); // 19
+console.log(BIT_LENGTH); // 8192
+```
+
+## Usage: Advanced Example
+
+```ts
+import { N_8192, g_8192 } from "@suaveplan/srp/groups/8192";
+import { defaultHashBridge } from "@suaveplan/srp/hash";
+import type { SrpParams } from "@suaveplan/srp/params";
+
+const params: SrpParams = {
+    N: N_8192,
+    g: g_8192,
+    bitLength: 8192,
+    hash: defaultHashBridge("SHA256"),
+    algorithm: "SHA256",
+};
+```
+
+## API Reference
+
+| Export       | Type         | Description                 |
+| ------------ | ------------ | --------------------------- |
+| `N_8192`     | `Uint8Array` | 1024-byte 8192-bit modulus. |
+| `g_8192`     | `Uint8Array` | Generator `0x13` (19).      |
+| `BIT_LENGTH` | `8192`       | Literal bit length.         |
+
+## Implementation Notes
+
+An 8192-bit `modPow` typically costs hundreds of milliseconds on contemporary hardware. Interactive login flows MUST NOT use this group on the request critical path; instead schedule the handshake off the perceptual deadline (e.g. background-thread the auth call, show a placeholder for the duration). The benchmark suite skips 8192 by default because the per-iteration cost dominates the warmup statistics.
+
+The generator `g = 19` is unique to this size in RFC 5054. Consumers building `SrpParams` from raw constants MUST use `g_8192` rather than hard-coding `0x02` or `0x05`.