# `ocra/ocra`

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs --> - ocra.schema — Zod boundary schema for `OcraParams`……
- [ocra.schema](./ocra.schema.md) — Zod boundary schema for `OcraParams` — the runtime parameter bag passed alongside a suite string and a key. Optional fi…
- [suite](./suite.md) — Parse an OCRA suite string into a typed `OcraSuite` AST per RFC 6287 §6.1. Exposed separately so callers can validate s…
- [verify-ocra](./verify-ocra.md) — Constant-time verify of an OCRA response. Recomputes the response under the supplied suite, key, and params, then compa…
- ocra.schema — Zod boundary schema for `OcraParams`……

- [ocra.schema](./ocra.schema.md) — Zod boundary schema for `OcraParams` — the runtime parameter bag passed alongside a suite string and a key. Optional fi…
- [suite](./suite.md) — Parse an OCRA suite string into a typed `OcraSuite` AST per RFC 6287 §6.1. Exposed separately so callers can validate s…
- [verify-ocra](./verify-ocra.md) — Constant-time verify of an OCRA response. Recomputes the response under the supplied suite, key, and params, then compa…

- ocra.schema — Zod boundary schema for `OcraParams`……

- [ocra.schema](./ocra.schema.md) — Zod boundary schema for `OcraParams` — the runtime parameter bag passed alongside a suite string and a key. Optional fi…
- [suite](./suite.md) — Parse an OCRA suite string into a typed `OcraSuite` AST per RFC 6287 §6.1. Exposed separately so callers can validate s…
- [verify-ocra](./verify-ocra.md) — Constant-time verify of an OCRA response. Recomputes the response under the supplied suite, key, and params, then compa…

- ocra.schema — Zod boundary schema for `OcraParams`…

- [ocra.schema](./ocra.schema.md) — Zod boundary schema for `OcraParams` — the runtime parameter bag passed alongside a suite string and a key. Optional fi…
- [suite](./suite.md) — Parse an OCRA suite string into a typed `OcraSuite` AST per RFC 6287 §6.1. Exposed separately so callers can validate s…
- [verify-ocra](./verify-ocra.md) — Constant-time verify of an OCRA response. Recomputes the response under the supplied suite, key, and params, then compa…
- [ocra.schema](./ocra.schema.md) — Zod boundary schema for `OcraParams` — the runtime parameter bag passed alongside a suite string and a key. Optional fi…
- [suite](./suite.md) — Parse an OCRA suite string into a typed `OcraSuite` AST per RFC 6287 §6.1. Exposed separately so callers can validate s…
- [verify-ocra](./verify-ocra.md) — Constant-time verify of an OCRA response. Recomputes the response under the supplied suite, key, and params, then compa…

## Purpose

RFC 6287 OCRA — OATH Challenge-Response Algorithm. Supports the full
`OCRA-1:HOTP-{H}-{N}:[C-]Q{A|N|H}NN[-PSHA{1,256,512}][-Snnn][-T{n}{S|M|H}]`
suite-string grammar. Validated against RFC 6287 Appendix C.1 reference
vectors so call-site implementations have a known-good baseline.

## Features

- All hash algorithms: SHA-1 / SHA-256 / SHA-512.
- Digits 4 / 6 / 7 / 8 (RFC 6287 §6.2 widens HOTP's 6/7/8 to also include 4).
- Optional counter (`C` directive), password hash (`PSHA{1,256,512}`),
  session info (`Snnn`), and timestamp (`T{n}{S|M|H}`) blocks.
- Three challenge formats: `QN` (decimal), `QA` (printable ASCII), `QH` (hex).
- Constant-time verify via `verifyOcra`.

## Usage: Basic Example

```ts
import { ocra } from "@suaveplan/otp/ocra";

const r = ocra("OCRA-1:HOTP-SHA1-6:QN08", key, { challenge: "12345678" });
```

## Usage: Advanced Example

```ts
import { ocra } from "@suaveplan/otp/ocra";

// Counter + password-hashed plus timestamp-bound suite.
const r = ocra("OCRA-1:HOTP-SHA256-8:C-QN08-PSHA256-T1M", key, {
  counter: 17n,
  challenge: "12345678",
  passwordHash: sha256(passwordBytes),
  timestampMs: Date.now(),
});
```

## API Reference

- `ocra(suite, key, params): string` — primary computation API.
- `buildOcraMessage(parsed, params): Uint8Array` — exposed for benchmarks
  and KAT harnesses that want to inspect the pre-HMAC byte stream.
- `OcraDigits` — alias for the digit literal-union shared with HOTP.

## Implementation Notes

The HMAC input layout follows RFC 6287 §5.1 exactly: suite ASCII, NUL
separator, then the directive blocks in fixed order (counter, challenge,
password hash, session info, timestamp). Each block is omitted if the suite
does not declare it; callers supplying an unexpected block are silently
ignored — the suite is the source of truth.