first commit

docs/security-stack/security/otp/src/ocra/suite.md

@@ -0,0 +1,55 @@
+# `ocra/suite`
+
+## Purpose
+
+Parse an OCRA suite string into a typed `OcraSuite` AST per RFC 6287 §6.1.
+Exposed separately so callers can validate suite strings before using them
+(e.g. on enrollment) without paying the cost of an HMAC computation.
+
+## Features
+
+- Three colon-separated segments: `OCRA-1`, `CryptoFunction`, `DataInput`.
+- CryptoFunction: `HOTP-{SHA1|SHA256|SHA512}-{4|6|7|8}`.
+- DataInput directives: `C`, `Q{A|N|H}NN`, `PSHA{1,256,512}`, `Snnn`,
+  `T{n}{S|M|H}`.
+- Strict grammar — every malformed segment raises
+  `OtpError(OTP.OCRA_SUITE_INVALID)` with a descriptive message.
+
+## Usage: Basic Example
+
+```ts
+import { parseOcraSuite } from "@suaveplan/otp/ocra";
+
+const s = parseOcraSuite("OCRA-1:HOTP-SHA1-6:QN08");
+// s.cryptoFunction.hash === "SHA1"
+```
+
+## Usage: Advanced Example
+
+```ts
+import { parseOcraSuite } from "@suaveplan/otp/ocra";
+
+const s = parseOcraSuite("OCRA-1:HOTP-SHA256-8:C-QN10-PSHA256-S128-T30S");
+// every directive surfaces as a typed property on s.dataInput.
+```
+
+## API Reference
+
+- `parseOcraSuite(suite: string): OcraSuite` — returns the parsed AST.
+  Throws `OtpError(OTP.OCRA_SUITE_INVALID)` on any grammar error.
+
+## Implementation Notes
+
+The `Q{A|N|H}NN` directive constrains length to `4..64` per RFC 6287 §6.1.
+The `Snnn` directive constrains length to `1..512`. Both bounds are
+enforced here at parse time so downstream code paths can trust the
+constraints. The suite parser is the single source of truth for grammar —
+adding a new directive requires updating only this module.
+
+Because suite strings are configuration data — they end up in databases,
+provisioning URIs, and KAT vector files — parsing must be tolerant of
+spaces between directives is NOT allowed (the RFC grammar uses `-` as
+the directive separator and a literal space would silently produce a
+different suite). The parser treats any unrecognised directive as an
+error rather than silently ignoring it, which is the right default when
+the suite is treated as a security parameter.