Skip to content

armgit / bento

Public Imported from GitHub
0

Bento, the office suite that fits in a file

30.0 KB
Raw Blame
// SPDX-License-Identifier: MIT
// Copyright (c) 2026 The Bento authors
//
// bento/id — the signed statements: one definition of every byte, for every host.
//
// Identity is keys, and everything anyone trusts is a SIGNED STATEMENT: "this
// device is mine" (dev.), "this key is [email protected]" (bind.), "the directory
// checked that binding" (att.), "this person consented to exactly this action"
// (cns.), and the directory's deletion record, delete request and email-code
// completion (tomb., del., cmp.). The agents (Swift, Kotlin, Rust, and the
// extension's JS) build and check them, and so do the directory and the
// document. If two of them read the same bytes differently, a signature means
// different things to different verifiers. So this module is the reference,
// and kernel/fixtures/identity-v1.json is the conformance contract every host
// must pass.
//
// THE FAMILY RULES — the same as the shipped collab statements (inv./dlg./rev.):
//   - A statement is dot-joined UTF-8 text, signed over its EXACT bytes. Nobody
//     re-serialises or canonicalises; the text is stored and hashed verbatim.
//     No JSON ever sits inside a signed statement.
//   - Every field is either a token from a CLOSED, dot-free grammar (a purpose
//     word, a kid, an integer) or FREE TEXT encoded as base64url without padding
//     (an email address, a display name). A raw email would break the split: it
//     has dots.
//   - Parsing is strict: split on '.', keep empty fields, require the EXACT field
//     count, check every field against its grammar. A stray field is a rejection,
//     never a re-join. The whole text must be printable ASCII.
//   - An ABSENT value is an EMPTY field, and only where its grammar allows one.
//   - Times are epoch MILLISECONDS, everywhere.
//   - The VERSION is the prefix: `bind.` is version 1; a breaking change is `bind2.`.
//   - Keys are raw uncompressed P-256 points (65 bytes), base64url. Signatures are
//     raw r‖s (64 bytes), base64url, LOW-S — never DER. A host whose platform
//     emits DER converts before anything crosses the bridge; a high-S or DER
//     signature here is a rejection, so a forgotten conversion fails loudly.

import { isNormalAddress } from './address.ts'
import { DISPLAY_FORBIDDEN_FLAT, DISPLAY_FORBIDDEN_UNICODE } from './display-table.ts'
import type { SignPurpose } from './identity.ts'

// --- strict base64url --------------------------------------------------------

const B64U_RE = /^[A-Za-z0-9_-]*$/

export function b64uEnc(bytes: Uint8Array): string {
  let s = ''
  for (const b of bytes) s += String.fromCharCode(b)
  return btoa(s).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
}

/** Canonical base64url only: the alphabet, no padding, and it must re-encode to
 *  exactly the same string (so trailing bits are zero). Null otherwise. */
export function b64uDec(s: string): Uint8Array | null {
  if (typeof s !== 'string' || !B64U_RE.test(s) || s.length % 4 === 1) return null
  let bin: string
  try { bin = atob(s.replace(/-/g, '+').replace(/_/g, '/') + '==='.slice((s.length + 3) % 4)) } catch { return null }
  const out = new Uint8Array(bin.length)
  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i)
  return b64uEnc(out) === s ? out : null
}

const te = new TextEncoder()
const utf8 = (s: string) => te.encode(s)
const strictUtf8 = new TextDecoder('utf-8', { fatal: true })

/** base64url-of-UTF-8 → text, canonical both ways; null if not. */
function freeText(f: string): string | null {
  const b = b64uDec(f)
  if (!b) return null
  let t: string
  try { t = strictUtf8.decode(b) } catch { return null }
  return b64uEnc(utf8(t)) === f ? t : null
}

/**
 * Display text a person sees (a name, a device label): bounded, in NFC, and free
 * of anything invisible or layout-changing that could make "alice ✓" read as
 * something else on screen. Refused:
 *   - controls (Cc), private use (Co), line and paragraph separators (Zl, Zp);
 *   - UNASSIGNED code points (Cn), the 66 noncharacters among them: one assigned
 *     later could be an invisible format character, and NFC is stable across
 *     Unicode versions only for assigned characters (security, #764);
 *   - every format character (Cf): bidi overrides and marks (including U+061C),
 *     zero-width space, word joiner, BOM, soft hyphen, the Mongolian vowel
 *     separator — EXCEPT ZWNJ/ZWJ (U+200C/U+200D), which Persian, Indic scripts
 *     and emoji sequences need, and which are refused only at either end;
 *   - the Hangul fill letters U+115F, U+1160, U+3164, U+FFA0, which render blank.
 * No filter stops homoglyphs, so a name is SELF-ASSERTED and must never be shown
 * without the verified address beside it (docs/DECISIONS.md).
 *
 * The set is FROZEN as explicit code-point ranges, not resolved through `\p{…}`.
 * General categories come from each platform's Unicode tables, so a character
 * newly assigned to Cf would be refused by one host and accepted by another until
 * both updated, and a name would verify on one device and not the next. These
 * ranges are the categories above as of Unicode 17.0, generated into
 * kernel/src/display-table.ts by scripts/gen-display-table.ts (which refuses to
 * run on any other Unicode version); the fixture carries the same table for the
 * native hosts, and the rig recomputes it. Changing it is a deliberate format
 * decision, never a side effect of a platform update.
 */
const MAX_DISPLAY = 64
export { DISPLAY_FORBIDDEN_UNICODE }
/** The frozen table as [first, last] pairs (kernel/src/display-table.ts, generated). */
export const DISPLAY_FORBIDDEN_RANGES: ReadonlyArray<readonly [number, number]> = Object.freeze(
  Array.from({ length: DISPLAY_FORBIDDEN_FLAT.length / 2 },
    (_, i) => Object.freeze([DISPLAY_FORBIDDEN_FLAT[2 * i], DISPLAY_FORBIDDEN_FLAT[2 * i + 1]]) as readonly [number, number])
)
/** Is this code point refused in display text? A binary search over the frozen ranges. */
export function displayForbidden(cp: number): boolean {
  let lo = 0, hi = DISPLAY_FORBIDDEN_RANGES.length - 1
  while (lo <= hi) {
    const mid = (lo + hi) >> 1
    const [a, b] = DISPLAY_FORBIDDEN_RANGES[mid]
    if (cp < a) hi = mid - 1
    else if (cp > b) lo = mid + 1
    else return true
  }
  return false
}
const ZWNJ = 0x200c, ZWJ = 0x200d
function displayText(f: string): string | null {
  const t = freeText(f)
  if (t === null || t.length === 0) return null
  const cps = [...t].map((c) => c.codePointAt(0)!)
  if (cps.length > MAX_DISPLAY) return null
  if (t.normalize('NFC') !== t) return null
  if (cps.some(displayForbidden)) return null
  const ends = [cps[0], cps[cps.length - 1]]
  if (ends.some((c) => c === ZWNJ || c === ZWJ)) return null
  return t
}

export async function sha256b64u(text: string): Promise<string> {
  return b64uEnc(new Uint8Array(await crypto.subtle.digest('SHA-256', utf8(text) as BufferSource)))
}

// --- keys and signatures -----------------------------------------------------

const EC_SIGN = { name: 'ECDSA', namedCurve: 'P-256' } as const
const EC_KX = { name: 'ECDH', namedCurve: 'P-256' } as const
const SIGN_ALG = { name: 'ECDSA', hash: 'SHA-256' } as const
/** the P-256 group order */
const N = 0xffffffff00000000ffffffffffffffffbce6faada7179e84f3b9cac2fc632551n
const HALF_N = N >> 1n

const toBig = (b: Uint8Array) => b.reduce((x, v) => (x << 8n) | BigInt(v), 0n)
function to32(x: bigint): Uint8Array {
  const out = new Uint8Array(32)
  for (let i = 31; i >= 0; i--) { out[i] = Number(x & 0xffn); x >>= 8n }
  return out
}

/** A raw r‖s signature in range with s in the lower half. */
function sigInRange(sig: Uint8Array): boolean {
  if (sig.length !== 64) return false
  const r = toBig(sig.subarray(0, 32)), s = toBig(sig.subarray(32))
  return r > 0n && r < N && s > 0n && s <= HALF_N
}

/** The low-S form of a raw r‖s signature (what every signer must emit). */
export function lowS(sig: Uint8Array): Uint8Array {
  const s = toBig(sig.subarray(32))
  if (s <= HALF_N) return sig
  const out = new Uint8Array(64)
  out.set(sig.subarray(0, 32))
  out.set(to32(N - s), 32)
  return out
}

/** A raw uncompressed P-256 point that the platform accepts for `alg`. */
async function point(b64: string, alg: typeof EC_SIGN | typeof EC_KX): Promise<CryptoKey | null> {
  const raw = b64uDec(b64)
  if (!raw || raw.length !== 65 || raw[0] !== 0x04) return null
  try {
    return await crypto.subtle.importKey('raw', raw as BufferSource, alg, false,
      alg.name === 'ECDSA' ? ['verify'] : [])
  } catch { return null }
}
export const isSigningKey = async (b64: string) => (await point(b64, EC_SIGN)) !== null
export const isKxKey = async (b64: string) => (await point(b64, EC_KX)) !== null

/** Verify `sigB64` (raw r‖s, low-S) by `pubB64` over the exact UTF-8 of `text`. */
export async function verifyStatementSig(pubB64: string, sigB64: string, text: string): Promise<boolean> {
  const sig = b64uDec(sigB64)
  if (!sig || !sigInRange(sig)) return false
  const key = await point(pubB64, EC_SIGN)
  if (!key) return false
  try { return await crypto.subtle.verify(SIGN_ALG, key, sig as BufferSource, utf8(text) as BufferSource) } catch { return false }
}

/** Sign `text` with `key`, emitting the low-S raw form. For JS agents and the
 *  vector generator; native agents produce the same bytes from their key stores. */
export async function signStatement(key: CryptoKey, text: string): Promise<string> {
  const sig = new Uint8Array(await crypto.subtle.sign(SIGN_ALG, key, utf8(text) as BufferSource))
  return b64uEnc(lowS(sig))
}

// --- strict parsing ------------------------------------------------------------

export type Verdict<T> = { ok: true; value: T } | { ok: false; reason: string }
const no = (reason: string): { ok: false; reason: string } => ({ ok: false, reason })

const MAX_STATEMENT = 4096

/** Split a statement: printable ASCII only, exact prefix and field count, empty
 *  fields kept. `count` includes the prefix. */
function fields(text: unknown, prefix: string, count: number): string[] | null {
  if (typeof text !== 'string' || text.length === 0 || text.length > MAX_STATEMENT) return null
  for (let i = 0; i < text.length; i++) {
    const c = text.charCodeAt(i)
    if (c < 0x21 || c > 0x7e) return null
  }
  const parts = text.split('.')
  return parts.length === count && parts[0] === prefix ? parts : null
}

const INT_RE = /^(0|[1-9][0-9]{0,15})$/
function int(f: string): number | null {
  if (!INT_RE.test(f)) return null
  const n = Number(f)
  return Number.isSafeInteger(n) ? n : null
}
const ms = (f: string) => { const n = int(f); return n !== null && n > 0 ? n : null }
/** a SHA-256 digest, base64url (32 bytes, 43 characters) */
const isHash = (f: string) => b64uDec(f)?.length === 32

const KID_RE = /^[a-z0-9][a-z0-9-]{0,62}$/
const RP_RE = /^(bento|vault-[a-z0-9][a-z0-9-]{0,62})$/
const DOCID_RE = /^[A-Za-z0-9_-]{1,128}$/          // security §19i
const ROOM_RE = /^w[A-Za-z0-9_-]{43}$/             // 'w' + b64u(sha256(owner pub))
/** The email code: exactly 8 characters from a 31-character alphabet with no
 *  0/O or 1/I/L, always UPPERCASE (agents uppercase what was typed before
 *  signing). About 39.6 bits, behind 5 attempts and a 20-minute TTL. */
const CODE_RE = /^[23456789ABCDEFGHJKMNPQRSTUVWXYZ]{8}$/

/** Clock skew tolerated for "issued in the future". */
export const SKEW_MS = 5 * 60_000
const DAY = 86_400_000
/** A certificate lives at most 13 months, plus a day of slack: 13 × 30.5 days + 1. */
export const CERT_MAX_MS = (13 * 30.5 + 1) * DAY

function lifetime(created: number, expires: number, now: number): string | null {
  if (expires <= created) return 'lifetime'
  if (expires - created > CERT_MAX_MS) return 'lifetime'
  if (created > now + SKEW_MS) return 'not-yet-valid'
  if (now >= expires) return 'expired'
  return null
}

// --- kx placement (pending the maintainer, identity-design §6b) ----------------

/**
 * Where the key-agreement key lives is a maintainer decision (§6b): A shared kx
 * in bind.; B per-device kx in dev.; C per-device kx in dev. AND a recovery kx in
 * bind. Both certificates carry a kx SLOT now, so the ruling changes which slot
 * is required, never the format. Until it is ruled, the strictest reading holds:
 * BOTH slots must be empty, so nothing accepts a placement nobody chose. Phase 1
 * shares nothing, so it needs no kx.
 */
export type KxMode = 'unruled' | 'A' | 'B' | 'C'
export const KX_MODE: KxMode = 'unruled'
const KX_SLOT: Record<KxMode, { bind: 'empty' | 'required'; dev: 'empty' | 'required' }> = {
  unruled: { bind: 'empty', dev: 'empty' },
  A: { bind: 'required', dev: 'empty' },
  B: { bind: 'empty', dev: 'required' },
  C: { bind: 'required', dev: 'required' },
}

/** Check a kx slot: present only when the mode requires it, a valid ECDH point,
 *  and never equal to any signing key in the same certificate. */
async function kxSlot(f: string, rule: 'empty' | 'required', others: string[]): Promise<string | null | false> {
  if (rule === 'empty') return f === '' ? null : false
  if (f === '' || !(await isKxKey(f)) || others.includes(f)) return false
  return f
}

// --- dev. — the device certificate (signed by the account key) ---------------

/**
 * `dev.<devicePub>.<consentPub|empty>.<accountPub>.<kx|empty>.<b64u(label)|empty>.<created>.<expires>`
 *
 * Binds this device's ROUTINE key and its hardware CONSENT key to the account.
 * The consent key is a separate, non-exportable key (Secure Enclave
 * `.userPresence`, a BiometricPrompt-bound Keystore key, Windows Hello); a
 * consent statement (cns.) is accepted only from a key certified here. The light
 * tier has no hardware consent key, so consentPub is empty there, and that
 * device can never produce an accepted cns.
 */
export interface DeviceCert {
  devicePub: string
  consentPub: string | null
  accountPub: string
  kx: string | null
  label: string | null
  created: number
  expires: number
}

export function buildDev(c: DeviceCert): string {
  return ['dev', c.devicePub, c.consentPub ?? '', c.accountPub, c.kx ?? '',
    c.label ? b64uEnc(utf8(c.label)) : '', c.created, c.expires].join('.')
}

export async function verifyDev(text: string, sig: string, opts: { now: number; kxMode?: KxMode }):
  Promise<Verdict<DeviceCert>> {
  const p = fields(text, 'dev', 8)
  if (!p) return no('grammar')
  const [, devicePub, consentF, accountPub, kxF, labelF, createdF, expiresF] = p
  if (!(await isSigningKey(devicePub)) || !(await isSigningKey(accountPub))) return no('key')
  if (devicePub === accountPub) return no('key')
  let consentPub: string | null = null
  if (consentF !== '') {
    if (!(await isSigningKey(consentF)) || consentF === devicePub || consentF === accountPub) return no('consent-key')
    consentPub = consentF
  }
  const kx = await kxSlot(kxF, KX_SLOT[opts.kxMode ?? KX_MODE].dev, [devicePub, accountPub, consentF])
  if (kx === false) return no('kx')
  let label: string | null = null
  if (labelF !== '') { label = displayText(labelF); if (label === null) return no('label') }
  const created = ms(createdF), expires = ms(expiresF)
  if (created === null || expires === null) return no('grammar')
  const life = lifetime(created, expires, opts.now)
  if (life) return no(life)
  if (!(await verifyStatementSig(accountPub, sig, text))) return no('signature')
  return { ok: true, value: { devicePub, consentPub, accountPub, kx, label, created, expires } }
}

// --- bind. — the person certificate (signed by the account key) --------------

/**
 * `bind.<b64u(address)>.<accountPub>.<kx|empty>.<b64u(name)|empty>.<seq>.<prev|empty>.<created>.<expires>`
 *
 * "This account key is this address", signed by the holder; the directory then
 * attests it (att.). `address` must already be in normal form (address.ts).
 * `seq` starts at 1; `prev` is the hash of the previous bind. text for this
 * address, empty exactly when seq is 1, so a rotation chain cannot be forked
 * silently.
 */
export interface BindCert {
  address: string
  accountPub: string
  kx: string | null
  name: string | null
  seq: number
  prev: string | null
  created: number
  expires: number
}

export function buildBind(c: BindCert): string {
  return ['bind', b64uEnc(utf8(c.address)), c.accountPub, c.kx ?? '',
    c.name ? b64uEnc(utf8(c.name)) : '', c.seq, c.prev ?? '', c.created, c.expires].join('.')
}

export async function verifyBind(text: string, sig: string, opts: { now: number; kxMode?: KxMode }):
  Promise<Verdict<BindCert>> {
  const p = fields(text, 'bind', 9)
  if (!p) return no('grammar')
  const [, addressF, accountPub, kxF, nameF, seqF, prevF, createdF, expiresF] = p
  const address = freeText(addressF)
  if (address === null || !isNormalAddress(address)) return no('address')
  if (!(await isSigningKey(accountPub))) return no('key')
  const kx = await kxSlot(kxF, KX_SLOT[opts.kxMode ?? KX_MODE].bind, [accountPub])
  if (kx === false) return no('kx')
  let name: string | null = null
  if (nameF !== '') { name = displayText(nameF); if (name === null) return no('name') }
  const seq = int(seqF)
  if (seq === null || seq < 1) return no('seq')
  if ((seq === 1) !== (prevF === '')) return no('prev')
  if (prevF !== '' && !isHash(prevF)) return no('prev')
  const created = ms(createdF), expires = ms(expiresF)
  if (created === null || expires === null) return no('grammar')
  const life = lifetime(created, expires, opts.now)
  if (life) return no(life)
  if (!(await verifyStatementSig(accountPub, sig, text))) return no('signature')
  return { ok: true, value: { address, accountPub, kx, name, seq, prev: prevF || null, created, expires } }
}

// --- att. — the directory's attestation (signed by a directory key) ----------

export type AttState = 'active' | 'pending' | 'frozen'

/**
 * `att.<sha256(bind text)>.<verifiedAt>.<issuedAt>.<kid>.<active|pending|frozen>`
 *
 * The directory's signed answer to a lookup. `issuedAt` is fresh on every
 * answer, so a client can refuse a replayed one; `state` is inside the
 * signature, so a directory answer cannot be replayed as "active" during a
 * rotation freeze (security §25). Signed by the directory's ONLINE key named by
 * `kid` — never the release key.
 */
export interface Attestation {
  bindHash: string
  verifiedAt: number
  issuedAt: number
  kid: string
  state: AttState
}

export function buildAtt(a: Attestation): string {
  return ['att', a.bindHash, a.verifiedAt, a.issuedAt, a.kid, a.state].join('.')
}

export async function verifyAtt(text: string, sig: string, opts: {
  directoryKeys: Readonly<Record<string, string>>
  bindText: string
  now: number
  maxAgeMs: number
}): Promise<Verdict<Attestation>> {
  const p = fields(text, 'att', 6)
  if (!p) return no('grammar')
  const [, bindHash, verifiedF, issuedF, kid, state] = p
  if (!isHash(bindHash) || !KID_RE.test(kid)) return no('grammar')
  if (state !== 'active' && state !== 'pending' && state !== 'frozen') return no('grammar')
  const verifiedAt = ms(verifiedF), issuedAt = ms(issuedF)
  if (verifiedAt === null || issuedAt === null || verifiedAt > issuedAt) return no('grammar')
  if (issuedAt > opts.now + SKEW_MS) return no('not-yet-valid')
  if (opts.now - issuedAt > opts.maxAgeMs) return no('stale')
  if (bindHash !== (await sha256b64u(opts.bindText))) return no('bind-mismatch')
  if (!Object.hasOwn(opts.directoryKeys, kid)) return no('unknown-kid')
  if (!(await verifyStatementSig(opts.directoryKeys[kid], sig, text))) return no('signature')
  return { ok: true, value: { bindHash, verifiedAt, issuedAt, kid, state: state as AttState } }
}

// --- tomb. — the directory's deletion record ---------------------------------

export type TombBy = 'holder' | 'mailbox' | 'operator'

/**
 * `tomb.<sha256(last bind text)|empty>.<seq>.<deletedAt>.<holder|mailbox|operator>.<kid>`
 *
 * Lets a client tell "deleted" from "never bound". The hash is empty when the
 * directory holds no previous binding text for the address.
 */
export interface Tombstone {
  lastBindHash: string | null
  seq: number
  deletedAt: number
  by: TombBy
  kid: string
}

export function buildTomb(t: Tombstone): string {
  return ['tomb', t.lastBindHash ?? '', t.seq, t.deletedAt, t.by, t.kid].join('.')
}

export async function verifyTomb(text: string, sig: string, opts: {
  directoryKeys: Readonly<Record<string, string>>
  now: number
}): Promise<Verdict<Tombstone>> {
  const p = fields(text, 'tomb', 6)
  if (!p) return no('grammar')
  const [, hashF, seqF, deletedF, by, kid] = p
  if (hashF !== '' && !isHash(hashF)) return no('grammar')
  const seq = int(seqF), deletedAt = ms(deletedF)
  if (seq === null || seq < 1 || deletedAt === null) return no('grammar')
  if (by !== 'holder' && by !== 'mailbox' && by !== 'operator') return no('grammar')
  if (!KID_RE.test(kid)) return no('grammar')
  if (deletedAt > opts.now + SKEW_MS) return no('not-yet-valid')
  if (!Object.hasOwn(opts.directoryKeys, kid)) return no('unknown-kid')
  if (!(await verifyStatementSig(opts.directoryKeys[kid], sig, text))) return no('signature')
  return { ok: true, value: { lastBindHash: hashF || null, seq, deletedAt, by: by as TombBy, kid } }
}

// --- del. — a holder's delete request (signed by the account key) ------------

/** `del.<b64u(address)>.<ts>`, valid within ±5 minutes of `ts`. */
export const DELETE_WINDOW_MS = 5 * 60_000

export function buildDel(address: string, ts: number): string {
  return ['del', b64uEnc(utf8(address)), ts].join('.')
}

export async function verifyDel(text: string, sig: string, opts: { accountPub: string; now: number }):
  Promise<Verdict<{ address: string; ts: number }>> {
  const p = fields(text, 'del', 3)
  if (!p) return no('grammar')
  const address = freeText(p[1])
  if (address === null || !isNormalAddress(address)) return no('address')
  const ts = ms(p[2])
  if (ts === null) return no('grammar')
  if (Math.abs(opts.now - ts) > DELETE_WINDOW_MS) return no('expired')
  if (!(await verifyStatementSig(opts.accountPub, sig, text))) return no('signature')
  return { ok: true, value: { address, ts } }
}

// --- cmp. — the email-code completion (signed by the binding's account key) --

/** `cmp.<sha256(bind text)>.<code>`: the person typed `code` into their agent,
 *  and the agent signs that it completes THIS binding. */
export function buildCmp(bindHash: string, code: string): string {
  return ['cmp', bindHash, code].join('.')
}

export async function verifyCmp(text: string, sig: string, opts: { accountPub: string; bindText: string }):
  Promise<Verdict<{ bindHash: string; code: string }>> {
  const p = fields(text, 'cmp', 3)
  if (!p) return no('grammar')
  const [, bindHash, code] = p
  if (!isHash(bindHash) || !CODE_RE.test(code)) return no('grammar')
  if (bindHash !== (await sha256b64u(opts.bindText))) return no('bind-mismatch')
  if (!(await verifyStatementSig(opts.accountPub, sig, text))) return no('signature')
  return { ok: true, value: { bindHash, code } }
}

// --- cns. — host-stamped consent (signed by a certified consent key) ---------

/**
 * The consent purposes a cns. may carry, a CLOSED set, and the statement family
 * each one authorises. `grant` and `role` are reserved for phase 2 and refused
 * until defined. (Distinct from identity.ts SignPurpose, which is about routine
 * signing with the device key.)
 */
export type ConsentPurpose = 'invite' | 'revoke' | 'link' | 'rotate' | 'unbind'
const CONSENT_FAMILY: Record<ConsentPurpose, string> = {
  invite: 'inv.', revoke: 'rev.', link: 'dev.', rotate: 'bind.', unbind: 'del.',
}
const RESERVED_PURPOSES = new Set(['grant', 'role'])
/** Purposes about one document carry its docId; account-scoped ones carry none. */
const DOC_SCOPED = new Set<ConsentPurpose>(['invite', 'revoke'])

/** A consent signature is good for at most this long after it is made. */
export const CONSENT_MAX_TTL_MS = 5 * 60_000

const AUDIENCE_RE = new RegExp(`^(dir|room:${ROOM_RE.source.slice(1, -1)})$`)

/**
 * The channel binding (security §24): it ties the consent to WHO verifies it
 * (the audience: `dir`, or `room:<roomName>`), to the single-use CHALLENGE that
 * verifier issued, and to the EXACT statement being authorised. A relayed
 * signature fails the audience, a replayed one the spent challenge, and a swapped
 * payload the hash. Null if a part breaks its grammar.
 *
 *   transcript = b64u( SHA-256( UTF-8( "cnst.v1." ‖ audience ‖ "." ‖ challenge ‖ "." ‖ b64u(SHA-256(payload)) ) ) )
 */
export async function consentTranscript(audience: string, challenge: string, payloadText: string): Promise<string | null> {
  if (!AUDIENCE_RE.test(audience)) return null
  const c = b64uDec(challenge)
  if (!c || c.length < 16 || c.length > 64) return null
  return sha256b64u(`cnst.v1.${audience}.${challenge}.${await sha256b64u(payloadText)}`)
}

export interface Consent {
  rp: string
  purpose: ConsentPurpose
  docId: string | null
  transcript: string
  exp: number
}

/** `cns.<rp>.<purpose>.<docId|empty>.<transcript>.<exp>`, every field host-stamped. */
export function buildConsent(c: Consent): string {
  return ['cns', c.rp, c.purpose, c.docId ?? '', c.transcript, c.exp].join('.')
}

/**
 * Verify a consent signature. The verifier RECOMPUTES the transcript from its
 * OWN audience, the challenge it issued and the payload it is about to apply —
 * it never trusts a transcript from the request. `spend(challenge)` must mark
 * the challenge used and return false if it was already spent or has expired;
 * it is called first, so any attempt consumes the challenge. That is the right
 * default for races (no second try against one challenge), and it relies on
 * challenges being SESSION-BOUND: one issued to one session, so a stranger who
 * spends it can only fail that session's attempt, never take it over.
 *
 * `consentPub` must come from a verified dev. certificate's consentPub field;
 * that is what makes it a consent key and not merely a key.
 */
export async function verifyConsent(text: string, sig: string, opts: {
  consentPub: string
  rp: string
  audience: string
  challenge: string
  payloadText: string
  docId: string | null
  now: number
  spend: (challenge: string) => boolean
}): Promise<Verdict<Consent>> {
  const p = fields(text, 'cns', 6)
  if (!p) return no('grammar')
  if (!opts.spend(opts.challenge)) return no('replay')
  const [, rp, purposeF, docIdF, transcript, expF] = p
  if (!RP_RE.test(rp) || !isHash(transcript)) return no('grammar')
  if (RESERVED_PURPOSES.has(purposeF)) return no('reserved-purpose')
  if (!Object.hasOwn(CONSENT_FAMILY, purposeF)) return no('grammar')
  const purpose = purposeF as ConsentPurpose
  const exp = ms(expF)
  if (exp === null) return no('grammar')
  if (rp !== opts.rp) return no('rp')
  // the payload must be of the family this purpose authorises
  if (!opts.payloadText.startsWith(CONSENT_FAMILY[purpose])) return no('payload-family')
  // document-scoped purposes name the document; account-scoped ones name none
  if (DOC_SCOPED.has(purpose)) {
    if (!DOCID_RE.test(docIdF) || docIdF !== opts.docId) return no('docid')
  } else if (docIdF !== '' || opts.docId !== null) return no('docid')
  const expected = await consentTranscript(opts.audience, opts.challenge, opts.payloadText)
  if (expected === null || transcript !== expected) return no('transcript')
  if (opts.now >= exp) return no('expired')
  if (exp - opts.now > CONSENT_MAX_TTL_MS) return no('lifetime')
  if (!(await verifyStatementSig(opts.consentPub, sig, text))) return no('signature')
  return { ok: true, value: { rp, purpose, docId: docIdF || null, transcript, exp } }
}

/**
 * The light tier has no hardware consent key (its dev. consentPub is empty). In
 * phase 1 its consent is a WebAuthn assertion verified only by the directory
 * (every phase-1 cns. has audience `dir`), and the assertion carries the
 * statement as `clientDataJSON.challenge` = this value: base64url of SHA-256 over
 * the EXACT cns. bytes (security §27).
 */
export const webauthnChallengeFor = (cnsText: string): Promise<string> => sha256b64u(cnsText)

/**
 * Prefixes reserved for statements not defined yet, so nothing else takes them:
 *   pk.   — an account-signed passkey statement (phase 2), for room-audience
 *           verifiers of light-tier consent. Never the dev. consentPub slot.
 *   drev. — an account-signed device revocation. Not needed in phase 1: a device
 *           retired without rotating the account key is one whose hardware-wrapped
 *           keys were destroyed by a confirmed wipe, so its dev. cert names a key
 *           nobody holds. It arrives with per-device kx, when senders wrap to
 *           device keys (security §25b).
 */
export const RESERVED_PREFIXES: readonly string[] = Object.freeze(['pk', 'drev'])

// --- routine signing: what payload each SignPurpose (identity.ts) may sign ----

/** A canonical base64url field decoding to at least `min` (exactly `exact`) bytes. */
const b64Len = (f: string, min: number, exact?: number) => {
  const b = b64uDec(f)
  return !!b && (exact === undefined ? b.length >= min : b.length === exact)
}
const isPubField = (f: string) => { const b = b64uDec(f); return !!b && b.length === 65 && b[0] === 0x04 }
const IV = (f: string) => b64Len(f, 0, 12)   // AES-GCM iv
const CT = (f: string) => b64Len(f, 16)      // ciphertext with its 16-byte tag

/**
 * Does `payload` have the exact shape of the statement `purpose` names? The
 * agent signs only a matching payload, so a prompt shown for one kind of action
 * can never yield a signature on another. Shapes are the shipped collab
 * statements (kernel/src/sync/online.ts, verified by the relay).
 */
export function payloadMatchesPurpose(purpose: SignPurpose, payload: string): boolean {
  if (typeof payload !== 'string' || payload.length > MAX_STATEMENT) return false
  const p = payload.split('.')
  switch (purpose) {
    case 'frame': return p.length === 2 && IV(p[0]) && CT(p[1])                       // `${i}.${d}`
    case 'prove': return p.length === 3 && p[0] === 'prove' && b64Len(p[1], 16) && /^[rw][A-Za-z0-9_-]{1,64}$/.test(p[2])
    case 'delegate': return p.length === 2 && p[0] === 'dlg' && isPubField(p[1])
    case 'show':
      return (p.length === 1 && (p[0] === 'live' || p[0] === 'end')) ||
        (p.length === 4 && (p[0] === 'nav' || p[0] === 'black') && p[1] === 'aud' && IV(p[2]) && CT(p[3]))
    case 'invite': return p.length === 4 && p[0] === 'inv' && isPubField(p[1]) &&
      (p[2] === 'writer' || p[2] === 'commenter' || p[2] === 'audience') && INT_RE.test(p[3])
    case 'revoke': return p.length === 2 && p[0] === 'rev' && isPubField(p[1])
    default: return false
  }
}