# `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.