@dejadex/web 0.0.0-stage → 0.1.0

package/src/lease/verify.ts

@@ -0,0 +1,252 @@
+/**
+ * Lease verification on the device: an Ed25519 compact JWS (RFC 7515,
+ * `alg: EdDSA` per RFC 8037), `typ: dejadex-lease+jwt`, checked against the
+ * public keys the host embeds. Mirrors `service/src/leases/jws.ts` check for
+ * check, in the same order:
+ *
+ *   structure → header → signature (over the raw bytes) → claims shape →
+ *   time → origin → domains
+ *
+ * Nothing in an unsigned payload is looked at before the signature holds, and
+ * the algorithm comes from this code, never from the token.
+ *
+ * Signature: WebCrypto Ed25519 where the browser has it (Chrome 137+, Safari
+ * 17+, Firefox 129+, Node 22); elsewhere `@noble/ed25519` (MIT, audited,
+ * zero dependencies), loaded only then.
+ *
+ * The browser is untrusted: this check keeps an honest host from running on a
+ * lease it should not, and bounds what a dishonest one gets. The service
+ * checks every lease again.
+ */
+import { ScannerError } from '../errors.js'
+import type { Lease, LeaseClaims } from '../types.js'
+
+export const LEASE_ALG = 'EdDSA'
+export const LEASE_TYP = 'dejadex-lease+jwt'
+export const MAX_LEASE_TTL_SECONDS = 86_400
+export const DEFAULT_CLOCK_SKEW_SECONDS = 60
+
+/** An Ed25519 public key as a JWK (`kty: OKP`, `crv: Ed25519`), or just its `x`. */
+export interface LeasePublicKey {
+  readonly kty?: 'OKP'
+  readonly crv?: 'Ed25519'
+  /** The raw 32-byte key, base64url. */
+  readonly x: string
+  /** When set, only leases whose header names this `kid` are checked against it. */
+  readonly kid?: string
+  /** Carried by a JWKS entry; `EdDSA` / `sig` when present. */
+  readonly alg?: string
+  readonly use?: string
+}
+
+export type Ed25519Verify = (publicKey: Uint8Array<ArrayBuffer>, message: Uint8Array<ArrayBuffer>, signature: Uint8Array<ArrayBuffer>) => Promise<boolean>
+
+export interface VerifyLeaseOptions {
+  readonly publicKeys: readonly LeasePublicKey[]
+  /** The page origin, matched exactly against `origins`; null skips the check (no page). */
+  readonly origin: string | null
+  /** Domains the caller wants; each must be granted. */
+  readonly domains: readonly string[]
+  /** Unix seconds. Default: the device clock. */
+  readonly now?: number
+  readonly clockSkewSeconds?: number
+  /** Test seam; default WebCrypto, then `@noble/ed25519`. */
+  readonly verify?: Ed25519Verify
+}
+
+/** The service's reason, first in every message, so support can match the two sides. */
+export type LeaseFailure =
+  | 'LEASE_MALFORMED'
+  | 'LEASE_BAD_SIGNATURE'
+  | 'LEASE_EXPIRED'
+  | 'LEASE_NOT_YET_VALID'
+  | 'LEASE_ORIGIN_NOT_ALLOWED'
+  | 'LEASE_DOMAIN_NOT_ALLOWED'
+
+const SCANNER_CODE = {
+  LEASE_MALFORMED: 'LEASE_INVALID',
+  LEASE_BAD_SIGNATURE: 'LEASE_INVALID',
+  LEASE_NOT_YET_VALID: 'LEASE_INVALID',
+  LEASE_EXPIRED: 'LEASE_EXPIRED',
+  LEASE_ORIGIN_NOT_ALLOWED: 'ORIGIN_NOT_ALLOWED',
+  LEASE_DOMAIN_NOT_ALLOWED: 'DOMAIN_NOT_ALLOWED',
+} as const
+
+export class LeaseVerificationError extends ScannerError {
+  constructor(
+    readonly reason: LeaseFailure,
+    message: string,
+  ) {
+    super(SCANNER_CODE[reason], `${reason}: ${message}`)
+  }
+}
+
+const fail = (reason: LeaseFailure, message: string): never => {
+  throw new LeaseVerificationError(reason, message)
+}
+const malformed = (why: string): never => fail('LEASE_MALFORMED', `malformed lease: ${why}`)
+
+const B64URL = /^[A-Za-z0-9_-]*$/
+
+/** Strict unpadded base64url: one decoding and one encoding per string, or null. */
+export function base64urlDecodeStrict(s: string): Uint8Array<ArrayBuffer> | null {
+  if (!B64URL.test(s) || s.length % 4 === 1) return null
+  const b64 = s.replace(/-/g, '+').replace(/_/g, '/') + '='.repeat((4 - (s.length % 4)) % 4)
+  let bin: string
+  try {
+    bin = atob(b64)
+  } catch {
+    return null
+  }
+  const out = new Uint8Array(bin.length)
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i)
+  // Non-zero trailing bits decode like the canonical form; re-encoding exposes them.
+  if (base64urlEncode(out) !== s) return null
+  return out
+}
+
+export function base64urlEncode(bytes: Uint8Array): string {
+  let bin = ''
+  for (const b of bytes) bin += String.fromCharCode(b)
+  return btoa(bin).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+}
+
+function jsonObject(bytes: Uint8Array): Record<string, unknown> | null {
+  let value: unknown
+  try {
+    value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes))
+  } catch {
+    return null
+  }
+  return typeof value === 'object' && value !== null && !Array.isArray(value) ? (value as Record<string, unknown>) : null
+}
+
+interface Header {
+  readonly kid?: string
+}
+
+function decodeHeader(segment: string): Header {
+  const bytes = base64urlDecodeStrict(segment)
+  if (bytes === null || bytes.length === 0) return malformed('header is not base64url')
+  const header = jsonObject(bytes)
+  if (header === null) return malformed('header is not a JSON object')
+  if (header.alg !== LEASE_ALG) return malformed(`unsupported alg ${JSON.stringify(header.alg)}`)
+  if (header.typ !== LEASE_TYP) return malformed(`unexpected typ ${JSON.stringify(header.typ)}`)
+  if ('crit' in header) return malformed('crit header not supported')
+  for (const key of Object.keys(header)) {
+    if (key !== 'alg' && key !== 'typ' && key !== 'kid') return malformed(`unexpected header parameter ${key}`)
+  }
+  if (header.kid !== undefined && (typeof header.kid !== 'string' || header.kid.length === 0)) return malformed('kid must be a non-empty string')
+  return header.kid === undefined ? {} : { kid: header.kid as string }
+}
+
+const nonEmpty = (v: unknown): v is string => typeof v === 'string' && v.length > 0
+const stringArray = (v: unknown): v is string[] => Array.isArray(v) && v.length > 0 && v.every(nonEmpty)
+const unixSeconds = (v: unknown): v is number => Number.isSafeInteger(v) && (v as number) >= 0
+
+function toClaims(raw: Record<string, unknown>): LeaseClaims {
+  const { iss, sub, uid, jti, origins, domains, modelVersion, indexVersion, allowance, iat, exp } = raw
+  if (!nonEmpty(iss)) return malformed('iss')
+  if (!nonEmpty(sub)) return malformed('sub')
+  if (!nonEmpty(uid)) return malformed('uid')
+  if (!nonEmpty(jti)) return malformed('jti')
+  if (!stringArray(origins)) return malformed('origins')
+  if (!stringArray(domains)) return malformed('domains')
+  if (!nonEmpty(modelVersion)) return malformed('modelVersion')
+  if (!nonEmpty(indexVersion)) return malformed('indexVersion')
+  if (!Number.isSafeInteger(allowance) || (allowance as number) <= 0) return malformed('allowance')
+  if (!unixSeconds(iat)) return malformed('iat')
+  if (!unixSeconds(exp)) return malformed('exp')
+  if (exp <= iat) return malformed('exp must be after iat')
+  if (exp - iat > MAX_LEASE_TTL_SECONDS) return malformed('lifetime exceeds 24 h')
+  return { iss, sub, uid, jti, origins: [...origins], domains: [...domains], modelVersion, indexVersion, allowance: allowance as number, iat, exp }
+}
+
+/** The encoding of the Ed25519 base point: a key every implementation must accept. */
+const BASE_POINT = new Uint8Array([0x58, ...new Array<number>(31).fill(0x66)])
+let webCryptoEd25519: Promise<boolean> | null = null
+
+/** Whether this runtime's WebCrypto does Ed25519, probed once with a known-good key. */
+export function hasWebCryptoEd25519(): Promise<boolean> {
+  webCryptoEd25519 ??= (async () => {
+    const subtle = globalThis.crypto?.subtle
+    if (!subtle) return false
+    try {
+      await subtle.importKey('raw', BASE_POINT, { name: 'Ed25519' }, false, ['verify'])
+      return true
+    } catch {
+      return false
+    }
+  })()
+  return webCryptoEd25519
+}
+
+/** WebCrypto Ed25519 when the runtime has it, else `@noble/ed25519`. Any error is "does not verify". */
+export const defaultEd25519Verify: Ed25519Verify = async (publicKey, message, signature) => {
+  try {
+    if (await hasWebCryptoEd25519()) {
+      const subtle = globalThis.crypto.subtle
+      const key = await subtle.importKey('raw', publicKey, { name: 'Ed25519' }, false, ['verify'])
+      return await subtle.verify({ name: 'Ed25519' }, key, signature, message)
+    }
+    return await nobleEd25519Verify(publicKey, message, signature)
+  } catch {
+    return false
+  }
+}
+
+/** The fallback on its own, for runtimes without WebCrypto Ed25519 (and its tests). */
+export const nobleEd25519Verify: Ed25519Verify = async (publicKey, message, signature) => {
+  const noble = await import('@noble/ed25519')
+  try {
+    return await noble.verifyAsync(signature, message, publicKey)
+  } catch {
+    return false
+  }
+}
+
+/** Verifies `token` and returns the lease, or throws a `LeaseVerificationError`. */
+export async function verifyLease(token: string, options: VerifyLeaseOptions): Promise<Lease> {
+  if (typeof token !== 'string') return malformed('token is not a string')
+  const parts = token.split('.')
+  if (parts.length !== 3) return malformed('expected three dot-separated segments')
+  const [headerB64 = '', payloadB64 = '', signatureB64 = ''] = parts
+  const header = decodeHeader(headerB64)
+  const payload = base64urlDecodeStrict(payloadB64)
+  if (payload === null || payload.length === 0) return malformed('payload is not base64url')
+  const signature = base64urlDecodeStrict(signatureB64)
+  if (signature === null) return malformed('signature is not base64url')
+  if (signature.length !== 64) return fail('LEASE_BAD_SIGNATURE', 'signature has the wrong length')
+
+  const keys = options.publicKeys.filter((k) => header.kid === undefined || k.kid === undefined || k.kid === header.kid)
+  if (keys.length === 0) return fail('LEASE_BAD_SIGNATURE', header.kid ? `no public key with kid ${header.kid}` : 'no public key')
+  const message = new TextEncoder().encode(`${headerB64}.${payloadB64}`)
+  const verify = options.verify ?? defaultEd25519Verify
+  let valid = false
+  for (const key of keys) {
+    if ((key.kty !== undefined && key.kty !== 'OKP') || (key.crv !== undefined && key.crv !== 'Ed25519')) continue
+    if ((key.alg !== undefined && key.alg !== LEASE_ALG) || (key.use !== undefined && key.use !== 'sig')) continue
+    const raw = base64urlDecodeStrict(key.x)
+    if (raw === null || raw.length !== 32) continue
+    if (await verify(raw, message, signature)) {
+      valid = true
+      break
+    }
+  }
+  if (!valid) return fail('LEASE_BAD_SIGNATURE', 'signature does not verify')
+
+  const raw = jsonObject(payload)
+  if (raw === null) return malformed('payload is not a JSON object')
+  const claims = toClaims(raw)
+
+  const now = options.now ?? Math.floor(Date.now() / 1000)
+  const skew = options.clockSkewSeconds ?? DEFAULT_CLOCK_SKEW_SECONDS
+  if (now >= claims.exp) return fail('LEASE_EXPIRED', `lease expired at ${claims.exp}`)
+  if (claims.iat > now + skew) return fail('LEASE_NOT_YET_VALID', `lease issued at ${claims.iat}, in the future`)
+  if (options.origin !== null && !claims.origins.includes(options.origin)) {
+    return fail('LEASE_ORIGIN_NOT_ALLOWED', `origin ${options.origin} is not allowed by this lease`)
+  }
+  const missing = options.domains.filter((d) => !claims.domains.includes(d))
+  if (missing.length > 0) return fail('LEASE_DOMAIN_NOT_ALLOWED', `domains not granted: ${missing.join(', ')}`)
+  return { token, claims }
+}

package/src/scanner.ts

@@ -0,0 +1,56 @@
+import { ScannerError } from './errors.js'
+import type { DeviceTier, Scanner, ScannerOptions, ScannerState, TrackResult } from './types.js'
+
+const DOMAIN_CODE = /^[a-z][a-z0-9]*_[a-z]{2}$/
+
+/**
+ * Creates a scanner. Options are checked now, so a misconfigured host fails
+ * at the call site rather than at the first frame.
+ *
+ * STUB: the pipeline (openspec/changes/web-sdk-pipeline) is not built yet.
+ * `start` and `identify` reject with `NOT_IMPLEMENTED`; the shape is final.
+ */
+export function createScanner(options: ScannerOptions): Scanner {
+  validate(options)
+
+  let state: ScannerState = 'idle'
+  const notYet = (what: string) =>
+    Promise.reject(new ScannerError('NOT_IMPLEMENTED', `${what} is not implemented yet`))
+
+  return {
+    get state() {
+      return state
+    },
+    get tier(): DeviceTier | null {
+      return null
+    },
+    start() {
+      if (state === 'destroyed') return Promise.reject(new ScannerError('INVALID_OPTIONS', 'scanner was destroyed'))
+      return notYet('live scanning')
+    },
+    stop() {
+      if (state === 'running') state = 'stopped'
+    },
+    identify(): Promise<readonly TrackResult[]> {
+      return notYet('snapshot identification')
+    },
+    async destroy() {
+      state = 'destroyed'
+    },
+  }
+}
+
+function validate(options: ScannerOptions): void {
+  const fail = (message: string): never => {
+    throw new ScannerError('INVALID_OPTIONS', message)
+  }
+  if (typeof options?.getLease !== 'function') fail('getLease must be a function')
+  if (typeof options.reportUsage !== 'function') fail('reportUsage must be a function')
+  if (typeof options.onTracks !== 'function') fail('onTracks must be a function')
+  if (!Array.isArray(options.domains) || options.domains.length === 0) fail('domains must list at least one domain')
+  for (const d of options.domains) {
+    if (typeof d !== 'string' || !DOMAIN_CODE.test(d)) fail(`not a domain code: ${String(d)}`)
+  }
+  const tiers: readonly unknown[] = ['auto', 'live_full', 'live_reduced', 'snapshot']
+  if (options.tier !== undefined && !tiers.includes(options.tier)) fail(`unknown tier: ${String(options.tier)}`)
+}

package/src/types.ts

@@ -0,0 +1,196 @@
+/**
+ * The SDK's public types. These are the contract the first client tenant (and
+ * every later one) builds against, so they are settled before the pipeline
+ * behind them exists: see openspec/changes/web-sdk-pipeline and
+ * openspec/changes/lease-licensing for the behaviour each field promises.
+ */
+import type { Homography, Quad } from './geometry/homography.js'
+
+/**
+ * A catalogue domain: one franchise in one language, and one index shard.
+ * Codes are neutral by rule (`tcg01_en`, `tcg01_ja`, `tcg02_en`, …); a
+ * franchise name never appears in one.
+ */
+export type DomainCode = string
+
+/** A print's platform-owned id. Opaque to clients; map through `externalIds`. */
+export type PrintId = string
+
+/**
+ * Ids of the same print in third-party catalogues, keyed by source
+ * (e.g. `{ tcgdex: "<set>-<number>" }`). A client maps its own ids through
+ * the source it already uses.
+ */
+export type ExternalIds = Readonly<Record<string, string>>
+
+/** A finish of a print, e.g. `normal`, `holo`, `reverse_holo`, `first_edition`. Domain-defined. */
+export type VariantCode = string
+
+/** What the device can sustain, chosen at start-up (`auto`) or forced by the host. */
+export type DeviceTier = 'live_full' | 'live_reduced' | 'snapshot'
+
+/** The claims of a lease, as the service signs them. Times are Unix seconds. */
+export interface LeaseClaims {
+  /** The issuing service. */
+  readonly iss: string
+  /** The tenant the lease bills to. */
+  readonly sub: string
+  /** The tenant's end user, hashed by the service; never the client's raw id. */
+  readonly uid: string
+  /** This lease's id; usage reports and renewals name it. */
+  readonly jti: string
+  /** Page origins the lease runs on, exact `scheme://host[:port]` matches. */
+  readonly origins: readonly string[]
+  /** Index shards the lease unlocks. */
+  readonly domains: readonly DomainCode[]
+  /** The embedding model version; locked to `indexVersion`. */
+  readonly modelVersion: string
+  readonly indexVersion: string
+  /** Identifications this lease permits before it must be renewed. */
+  readonly allowance: number
+  readonly iat: number
+  readonly exp: number
+}
+
+/** A verified lease: the compact JWS the client's backend handed over, and its claims. */
+export interface Lease {
+  readonly token: string
+  readonly claims: LeaseClaims
+}
+
+/** What the SDK asks the host for when it needs a lease. */
+export interface LeaseRequest {
+  /** The lease being renewed, or null for the first one on this device. */
+  readonly previousLeaseId: string | null
+  /**
+   * The last usage sequence number already accepted by `reportUsage` for the
+   * previous lease. The service refuses a renewal whose previous lease has
+   * unreported usage.
+   */
+  readonly usageReportedThrough: number | null
+}
+
+/** What the host's backend returns from the service's `POST /v1/leases`, passed through as is. */
+export interface LeaseGrant {
+  /** The signed lease, compact JWS. */
+  readonly token: string
+  /** Signed URL of the manifest that lists model and index files for this lease. */
+  readonly manifestUrl: string
+}
+
+/** One of the top-K guesses for a track. */
+export interface Candidate {
+  readonly printId: PrintId
+  readonly externalIds: ExternalIds
+  /** Cosine similarity to the reference embedding, in [-1, 1]. */
+  readonly score: number
+}
+
+/**
+ * One physical card the SDK is following, as of the latest processed frame.
+ *
+ * `printId` is null until the track is confirmed, and stays null when the
+ * crop matched nothing above the threshold (`status: 'unknown'`): the
+ * catalogue is closed, so a miss is reported as a miss with its best guesses,
+ * never as a near neighbour.
+ */
+export interface TrackResult {
+  /** Stable for as long as the card stays tracked. */
+  readonly trackId: number
+  readonly status: 'pending' | 'confirmed' | 'unknown'
+  /** Corners in the source frame's pixel space (y down): TL, TR, BR, BL of the card. The host maps them to its own layout (e.g. object-fit: cover) before drawing. */
+  readonly quad: Quad
+  /** Unit card rectangle → `quad`; `toCssMatrix3d` turns it into a transform. */
+  readonly homography: Homography
+  readonly domain: DomainCode | null
+  readonly printId: PrintId | null
+  readonly externalIds: ExternalIds
+  /** Null when the variant is unresolved: the host shows a picker, never a guess. */
+  readonly variant: VariantCode | null
+  /** In [0, 1]; the SDK's own calibrated belief in `printId`. */
+  readonly confidence: number
+  /** The top-K candidates (K = 5), best first, including the chosen one. */
+  readonly alternates: readonly Candidate[]
+}
+
+/**
+ * What one scan session counted under one lease since its previous report.
+ *
+ * The billing unit is a distinct card per scan session: a card is charged the
+ * first time it is identified in a session, by whichever side identified it,
+ * and never again in that session however often it is seen. Misses, "not a
+ * card" answers and retries are never charged. See openspec/changes/
+ * lease-licensing, usage-metering.
+ */
+export interface UsageReport {
+  /** Unique per report, so a report sent twice is counted once. */
+  readonly reportId: string
+  /** The lease's `jti`. */
+  readonly leaseId: string
+  /** Per lease, from 1, up by exactly 1 per report; renewals name the last one accepted. */
+  readonly seq: number
+  /** The scan session: random, at least 128 bits, one per scanner session. */
+  readonly sessionId: string
+  /** Cards first identified in this session since its previous report, excluding any the service counted. */
+  readonly distinctCards: number
+  /** Those cards' print ids, so the service can charge each at most once per session. */
+  readonly cardIds?: readonly PrintId[]
+  /** Identify attempts behind this report, retries and "not a card" answers included. Informational, never charged. */
+  readonly calls?: number
+  /** Device clock, Unix milliseconds. Informational; the service orders by `seq`. */
+  readonly at?: number
+}
+
+/** A batch the SDK hands to `reportUsage`, flushed from its IndexedDB queue. */
+export interface UsageBatch {
+  /** A random per-install id (not a fingerprint), for monthly active devices. */
+  readonly deviceId: string
+  /** May be empty: one batch per lease used is delivered even with nothing to report. */
+  readonly reports: readonly UsageReport[]
+}
+
+/** Where live frames come from. */
+export type FrameSourceInput = MediaStream | HTMLVideoElement
+
+export interface ScannerOptions {
+  /**
+   * Obtain a lease. The host calls its own backend, which calls the service's
+   * `POST /v1/leases` with the tenant's secret key; the secret never reaches
+   * the browser. Called at start and before the current lease runs out.
+   */
+  getLease(request: LeaseRequest): Promise<LeaseGrant>
+  /**
+   * Deliver queued usage. The host's backend forwards it to `POST /v1/usage`.
+   * Resolve only once it is accepted; a rejection leaves the batch queued.
+   */
+  reportUsage(batch: UsageBatch): Promise<void>
+  /** The domains to search; each must be granted by the lease. */
+  readonly domains: readonly DomainCode[]
+  /** Every processed frame's tracks, on the main thread. */
+  onTracks(tracks: readonly TrackResult[]): void
+  /** Errors the host should know about (lease, device, downloads). */
+  onError?(error: Error): void
+  /** Force a tier, or let the SDK pick from the device's capabilities. Default `auto`. */
+  readonly tier?: DeviceTier | 'auto'
+  /**
+   * The scan session usage is charged by (each distinct card once per session).
+   * Give one per visit to the host's scanner; default: a new random id per scanner.
+   */
+  readonly sessionId?: string
+}
+
+export type ScannerState = 'idle' | 'starting' | 'running' | 'stopped' | 'failed' | 'destroyed'
+
+export interface Scanner {
+  readonly state: ScannerState
+  /** The tier in use, once started. */
+  readonly tier: DeviceTier | null
+  /** Live mode: follow and identify every card in `source`. */
+  start(source: FrameSourceInput): Promise<void>
+  /** Pause live mode; tracks are dropped, caches are kept. */
+  stop(): void
+  /** Snapshot mode: identify every card in one image. */
+  identify(image: ImageBitmap | Blob): Promise<readonly TrackResult[]>
+  /** Release the Worker, the sessions and the camera hooks. */
+  destroy(): Promise<void>
+}

package/src/usage/meter.ts

@@ -0,0 +1,165 @@
+/**
+ * What an identification costs: one per distinct card per scan session
+ * (lease-licensing, usage-metering).
+ *
+ * A session is one visit to a host's scanner (the host's `session` id, or the
+ * identifier's own). Within it, the first confident `card` answer for a
+ * `cardId` is charged once; the same card again in the session is free, and
+ * so are `not_a_card` answers, answers that are not confident (the host asks
+ * the user instead of asserting), and `retry` calls.
+ *
+ * A server answer that carries an `identificationId` was charged by the
+ * service itself: it adds no card to the report, but still marks the card as
+ * seen in the session and still counts toward the lease's allowance.
+ *
+ * Every call is tallied in the `UsageStore` before its answer reaches the
+ * host. `drain` seals the open tallies into `UsageReport`s and hands them to
+ * the host in batches; a batch leaves the store only once the host's delivery
+ * resolves.
+ */
+import type { LeaseClaims, LeaseRequest, UsageBatch } from '../types.js'
+import type { IdentifyPurpose, IdentifyResult } from '../identify/types.js'
+import { randomId, type UsageStore } from './store.js'
+
+/** Reports per batch handed to the host. */
+export const MAX_BATCH_REPORTS = 500
+/** Sessions whose seen cards are remembered at once; the oldest is forgotten first. */
+const MAX_SESSIONS = 32
+
+export interface MeterOptions {
+  readonly store: UsageStore
+  readonly now?: () => number
+  readonly newId?: () => string
+}
+
+export interface MeterInput {
+  readonly lease: LeaseClaims
+  readonly session: string
+  readonly purpose: IdentifyPurpose | undefined
+  readonly results: readonly IdentifyResult[]
+}
+
+export interface DrainResult {
+  /** Reports delivered by this drain. */
+  readonly delivered: number
+  /** Reports and open tallies still queued. */
+  readonly pending: number
+}
+
+export interface RecordResult {
+  /** Cards this call charged on the device (first seen in the session, not counted by the service). */
+  readonly charged: readonly string[]
+  /** Cards the service had already charged (`identificationId`). */
+  readonly serverCharged: number
+}
+
+export class UsageMeter {
+  private readonly store: UsageStore
+  private readonly now: () => number
+  private readonly newId: () => string
+  /** session → card ids already charged (by either side) in it. */
+  private readonly seen = new Map<string, Set<string>>()
+  /** lease id → cards charged under it on this page (device + service). */
+  private readonly used = new Map<string, number>()
+  private chain: Promise<unknown> = Promise.resolve()
+
+  constructor(options: MeterOptions) {
+    this.store = options.store
+    this.now = options.now ?? (() => Date.now())
+    this.newId = options.newId ?? (() => (typeof crypto.randomUUID === 'function' ? crypto.randomUUID() : randomId()))
+  }
+
+  /** Cards charged under `leaseId` on this page so far. */
+  usedUnder(leaseId: string): number {
+    return this.used.get(leaseId) ?? 0
+  }
+
+  /** Whether the lease's allowance is used up. */
+  exhausted(lease: LeaseClaims): boolean {
+    return this.usedUnder(lease.jti) >= lease.allowance
+  }
+
+  /** Tallies one call's answers; resolves once the tally is stored. */
+  record(input: MeterInput): Promise<RecordResult> {
+    return this.serial(async () => {
+      const charged: string[] = []
+      let serverCharged = 0
+      if (input.purpose !== 'retry') {
+        const seen = this.sessionSet(input.session)
+        for (const r of input.results) {
+          const top = r.candidates[0]
+          if (r.kind !== 'card' || !r.confident || !top || seen.has(top.cardId)) continue
+          seen.add(top.cardId)
+          if (r.identificationId !== undefined) serverCharged++
+          else charged.push(top.cardId)
+        }
+      }
+      const leaseId = input.lease.jti
+      this.used.set(leaseId, this.usedUnder(leaseId) + serverCharged + charged.length)
+      await this.store.tally(leaseId, input.session, charged, 1, this.now())
+      return { charged, serverCharged }
+    })
+  }
+
+  /**
+   * Seals the open tallies and hands the queued reports to `deliver` in
+   * batches of at most 500, oldest first. Each batch is removed once `deliver`
+   * resolves; a rejection stops the drain, leaves that batch queued, and is
+   * rethrown.
+   */
+  async drain(deliver: (batch: UsageBatch) => Promise<void>): Promise<DrainResult> {
+    // Sealing goes through the record queue, so a tally being written is not split.
+    await this.serial(() => this.store.seal(this.newId))
+    const deviceId = await this.store.deviceId()
+    let delivered = 0
+    for (;;) {
+      const reports = await this.store.peek(MAX_BATCH_REPORTS)
+      if (reports.length === 0) break
+      await deliver({ deviceId, reports })
+      await this.store.remove(reports.map((r) => r.reportId))
+      await this.store.markReported(reports)
+      delivered += reports.length
+    }
+    return { delivered, pending: await this.store.size() }
+  }
+
+  pending(): Promise<number> {
+    return this.store.size()
+  }
+
+  /**
+   * Makes sure the lease gets at least one report, even if nothing is ever
+   * identified under it: the service renews a lease only once the previous
+   * one has reported (an empty report counts).
+   */
+  touch(leaseId: string, session: string): Promise<void> {
+    return this.serial(() => this.store.tally(leaseId, session, [], 0, this.now()))
+  }
+
+  /** What the host's lease request carries about the lease being renewed. */
+  async leaseRequest(previousLeaseId: string | null): Promise<LeaseRequest> {
+    return {
+      previousLeaseId,
+      usageReportedThrough: previousLeaseId === null ? null : await this.store.reportedThrough(previousLeaseId),
+    }
+  }
+
+  private sessionSet(session: string): Set<string> {
+    let set = this.seen.get(session)
+    if (!set) {
+      set = new Set()
+      this.seen.set(session, set)
+      if (this.seen.size > MAX_SESSIONS) {
+        const oldest = this.seen.keys().next().value
+        if (oldest !== undefined) this.seen.delete(oldest)
+      }
+    }
+    return set
+  }
+
+  private serial<T>(task: () => Promise<T>): Promise<T> {
+    const run = this.chain.then(task, task)
+    this.chain = run.catch(() => undefined)
+    return run
+  }
+}