agent-passport-system 3.0.0 → 3.2.0

package/dist/src/v2/read_fidelity_receipt/receipt.js

@@ -0,0 +1,283 @@
+// Copyright 2024-2026 Tymofii Pidlisnyi. Apache-2.0 license. See LICENSE.
+// ══════════════════════════════════════════════════════════════════
+// read_fidelity_receipt (v2): create and verify
+// ══════════════════════════════════════════════════════════════════
+// Signature convention: sig is EXCLUDED from the signing preimage.
+// The preimage is canonicalizeJCS(record with the sig key removed
+// entirely). Verification order: shape checks and n consistency,
+// then the Ed25519 signature against the embedded attester, then the
+// seed derivation. A record tampered after signing fails on the
+// signature; a record re-signed after a nonce or presentation swap
+// carries a valid signature and fails on the seed derivation, which
+// is the replay binding doing its job.
+// ══════════════════════════════════════════════════════════════════
+import { createHash } from 'node:crypto';
+import { canonicalizeJCS } from '../../core/canonical-jcs.js';
+import { sign, verify as edVerify, publicKeyFromPrivate } from '../../crypto/keys.js';
+import { commitSpans, deriveSeed, sampleSpans, scoreResponses } from './sampler.js';
+const DIGEST_RE = /^sha256:[0-9a-f]{64}$/;
+const HEX64_RE = /^[0-9a-f]{64}$/;
+const HEX128_RE = /^[0-9a-f]{128}$/;
+const ISO_8601_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2})$/;
+function sha256hex(input) {
+    return createHash('sha256').update(input, 'utf8').digest('hex');
+}
+/**
+ * Canonical signing preimage: RFC 8785 JCS of the record with the
+ * `sig` key removed entirely. Accepts a signed record (sig dropped)
+ * or an unsigned draft (no sig key present).
+ */
+export function canonicalNoSig(record) {
+    const { sig: _sig, ...rest } = record;
+    return canonicalizeJCS(rest);
+}
+/**
+ * Structural checks shared by verifyReadFidelityReceipt and
+ * verifyAgainstSource. Returns the first failing reason, or null when
+ * the value is structurally a ReadFidelityReceipt. Does NOT check the
+ * signature or the seed derivation.
+ */
+function shapeReason(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return 'INVALID_TYPE';
+    }
+    const r = value;
+    if (r.type !== 'read_fidelity_receipt')
+        return 'INVALID_TYPE';
+    if (typeof r.content_digest !== 'string' || !DIGEST_RE.test(r.content_digest)) {
+        return 'INVALID_CONTENT_DIGEST';
+    }
+    if (r.presentation_digest !== null &&
+        (typeof r.presentation_digest !== 'string' ||
+            !DIGEST_RE.test(r.presentation_digest))) {
+        return 'INVALID_PRESENTATION_DIGEST';
+    }
+    const challengeReason = challengeShapeReason(r.challenge);
+    if (challengeReason !== null)
+        return challengeReason;
+    const c = r.challenge;
+    const commitments = c.span_commitments;
+    if (typeof r.n !== 'number' || !Number.isInteger(r.n) || r.n < 1) {
+        return 'INVALID_N';
+    }
+    if (r.n !== commitments.length)
+        return 'N_MISMATCH';
+    if (typeof r.k !== 'number' ||
+        !Number.isInteger(r.k) ||
+        r.k < 0 ||
+        r.k > r.n) {
+        return 'INVALID_K';
+    }
+    if (typeof r.response_digest !== 'string' || !DIGEST_RE.test(r.response_digest)) {
+        return 'INVALID_RESPONSE_DIGEST';
+    }
+    if (r.scoring_method !== 'exact_match_v1')
+        return 'INVALID_SCORING_METHOD';
+    if (typeof r.attester !== 'string' || !HEX64_RE.test(r.attester)) {
+        return 'INVALID_ATTESTER';
+    }
+    if (typeof r.model_claim !== 'string' || typeof r.runtime_claim !== 'string') {
+        return 'INVALID_CLAIMS';
+    }
+    if (r.verification_method !== 'asserted' &&
+        r.verification_method !== 'provider_attestation') {
+        return 'INVALID_VERIFICATION_METHOD';
+    }
+    for (const field of [
+        'challenge_issued_at',
+        'response_observed_at',
+        'receipt_issued_at',
+    ]) {
+        const t = r[field];
+        if (typeof t !== 'string' || !ISO_8601_RE.test(t))
+            return 'INVALID_TIMESTAMP';
+    }
+    if ('lexicon_id' in r || 'lexicon_profile' in r) {
+        if (typeof r.lexicon_id !== 'string' || !DIGEST_RE.test(r.lexicon_id)) {
+            return 'INVALID_LEXICON_FIELDS';
+        }
+        if ('lexicon_profile' in r &&
+            (typeof r.lexicon_profile !== 'string' || r.lexicon_profile.length === 0)) {
+            return 'INVALID_LEXICON_FIELDS';
+        }
+    }
+    if (typeof r.sig !== 'string' || !HEX128_RE.test(r.sig)) {
+        return 'INVALID_SIG_FORMAT';
+    }
+    return null;
+}
+function challengeShapeReason(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return 'INVALID_CHALLENGE';
+    }
+    const c = value;
+    if (typeof c.nonce !== 'string' || c.nonce.length === 0)
+        return 'INVALID_CHALLENGE';
+    if (typeof c.seed !== 'string' || !HEX64_RE.test(c.seed))
+        return 'INVALID_CHALLENGE';
+    if (c.algorithm !== 'span_sample_v1')
+        return 'INVALID_CHALLENGE';
+    if (c.version !== '1')
+        return 'INVALID_CHALLENGE';
+    if (typeof c.span_len !== 'number' ||
+        !Number.isInteger(c.span_len) ||
+        c.span_len < 1) {
+        return 'INVALID_CHALLENGE';
+    }
+    if (!Array.isArray(c.span_commitments) || c.span_commitments.length === 0) {
+        return 'INVALID_CHALLENGE';
+    }
+    for (const s of c.span_commitments) {
+        if (typeof s !== 'string' || !DIGEST_RE.test(s))
+            return 'INVALID_CHALLENGE';
+    }
+    return null;
+}
+function seedMatches(record) {
+    return (record.challenge.seed ===
+        deriveSeed(record.content_digest, record.presentation_digest, record.challenge.nonce, record.challenge.version));
+}
+/**
+ * Build and sign a read fidelity receipt. Validates the input
+ * (n MUST equal challenge.span_commitments.length, challenge.seed MUST
+ * equal the seed derivation, every digest MUST be
+ * "sha256:<64 lowercase hex>", timestamps MUST be ISO 8601), sets
+ * `attester` from the private key, and signs the JCS canonical form of
+ * the record with the sig key excluded. Throws on any validation
+ * failure; nothing is signed unless the record is internally
+ * consistent.
+ */
+export function createReadFidelityReceipt(fields, privateKeyHex) {
+    const attester = publicKeyFromPrivate(privateKeyHex);
+    const draft = {
+        type: 'read_fidelity_receipt',
+        content_digest: fields.content_digest,
+        presentation_digest: fields.presentation_digest,
+        challenge: {
+            nonce: fields.challenge.nonce,
+            seed: fields.challenge.seed,
+            algorithm: fields.challenge.algorithm,
+            version: fields.challenge.version,
+            span_len: fields.challenge.span_len,
+            span_commitments: [...fields.challenge.span_commitments],
+        },
+        response_digest: fields.response_digest,
+        k: fields.k,
+        n: fields.n,
+        scoring_method: fields.scoring_method,
+        attester,
+        model_claim: fields.model_claim,
+        runtime_claim: fields.runtime_claim,
+        verification_method: fields.verification_method,
+        challenge_issued_at: fields.challenge_issued_at,
+        response_observed_at: fields.response_observed_at,
+        receipt_issued_at: fields.receipt_issued_at,
+        ...(fields.lexicon_id !== undefined ? { lexicon_id: fields.lexicon_id } : {}),
+        ...(fields.lexicon_profile !== undefined
+            ? { lexicon_profile: fields.lexicon_profile }
+            : {}),
+    };
+    if (fields.n !== fields.challenge.span_commitments.length) {
+        throw new Error(`n (${fields.n}) must equal challenge.span_commitments.length ` +
+            `(${fields.challenge.span_commitments.length})`);
+    }
+    // Full structural validation on the draft plus a placeholder sig so
+    // create and verify enforce the identical shape rules.
+    const reason = shapeReason({ ...draft, sig: '0'.repeat(128) });
+    if (reason !== null) {
+        throw new Error(`invalid read fidelity receipt input: ${reason}`);
+    }
+    const expectedSeed = deriveSeed(fields.content_digest, fields.presentation_digest, fields.challenge.nonce, fields.challenge.version);
+    if (fields.challenge.seed !== expectedSeed) {
+        throw new Error('challenge.seed does not match the seed derivation over ' +
+            'content_digest, presentation_digest, nonce, and version');
+    }
+    const sig = sign(canonicalNoSig(draft), privateKeyHex);
+    return { ...draft, sig };
+}
+/**
+ * Verify a read fidelity receipt: shape checks, n consistency against
+ * challenge.span_commitments, Ed25519 signature against the embedded
+ * attester, and the seed derivation recompute. Accepts unknown and
+ * never throws on malformed input; failures carry a reason code.
+ */
+export function verifyReadFidelityReceipt(record) {
+    const reason = shapeReason(record);
+    if (reason !== null)
+        return { valid: false, reason };
+    const r = record;
+    if (!edVerify(canonicalNoSig(r), r.sig, r.attester)) {
+        return { valid: false, reason: 'SIGNATURE_INVALID' };
+    }
+    if (!seedMatches(r)) {
+        return { valid: false, reason: 'SEED_MISMATCH' };
+    }
+    return { valid: true };
+}
+/**
+ * Verify a receipt against the source text it claims to sample:
+ * everything verifyReadFidelityReceipt checks, plus a recompute of the
+ * spans from challenge.seed / n / span_len over `sourceText`, a sha256
+ * commitment of each recomputed span, and a positionwise comparison
+ * against challenge.span_commitments. ALL commitments must match.
+ * `signature_valid` and `seed_valid` are reported independently.
+ */
+export function verifyAgainstSource(record, sourceText) {
+    const reason = shapeReason(record);
+    if (reason !== null) {
+        return {
+            valid: false,
+            reason,
+            commitment_matches: [],
+            signature_valid: false,
+            seed_valid: false,
+        };
+    }
+    const r = record;
+    const signature_valid = edVerify(canonicalNoSig(r), r.sig, r.attester);
+    const seed_valid = seedMatches(r);
+    let commitment_matches = [];
+    let spanReason = null;
+    try {
+        const spans = sampleSpans(sourceText, r.challenge.seed, r.n, r.challenge.span_len);
+        const recomputed = commitSpans(spans.map((s) => s.text));
+        commitment_matches = recomputed.map((c, i) => c === r.challenge.span_commitments[i]);
+    }
+    catch {
+        spanReason = 'SPAN_RECOMPUTE_FAILED';
+    }
+    const allMatch = spanReason === null && commitment_matches.every((m) => m === true);
+    const valid = signature_valid && seed_valid && allMatch;
+    let failure;
+    if (!signature_valid)
+        failure = 'SIGNATURE_INVALID';
+    else if (!seed_valid)
+        failure = 'SEED_MISMATCH';
+    else if (spanReason !== null)
+        failure = spanReason;
+    else if (!allMatch)
+        failure = 'COMMITMENT_MISMATCH';
+    return valid
+        ? { valid, commitment_matches, signature_valid, seed_valid }
+        : { valid, reason: failure, commitment_matches, signature_valid, seed_valid };
+}
+/**
+ * Recompute k for a set of readback responses against the source text:
+ * resample the spans the record commits to, score `responses` under
+ * exact_match_v1, and compare the recomputed k with the recorded k and
+ * the responses JCS digest with the recorded response_digest. Throws
+ * when the source cannot produce the spans (wrong length) or when
+ * `responses` has the wrong length; use verifyAgainstSource first to
+ * establish that the record matches the source at all.
+ */
+export function verifyResponses(record, sourceText, responses) {
+    const spans = sampleSpans(sourceText, record.challenge.seed, record.n, record.challenge.span_len);
+    const { k } = scoreResponses(spans.map((s) => s.text), responses);
+    const digest = `sha256:${sha256hex(canonicalizeJCS(responses))}`;
+    return {
+        k_recomputed: k,
+        matches_claimed_k: k === record.k,
+        response_digest_ok: digest === record.response_digest,
+    };
+}
+//# sourceMappingURL=receipt.js.map

package/dist/src/v2/read_fidelity_receipt/receipt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"receipt.js","sourceRoot":"","sources":["../../../../src/v2/read_fidelity_receipt/receipt.ts"],"names":[],"mappings":"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"}

package/dist/src/v2/read_fidelity_receipt/sampler.d.ts

@@ -0,0 +1,35 @@
+import type { SampledSpan, ScoreResponsesResult } from './types.js';
+/**
+ * Derive the challenge seed. The preimage is the RFC 8785 JCS
+ * canonicalization of an object carrying the four bound fields, so the
+ * component boundaries are unambiguous: presentation_digest is a
+ * distinct JSON member (null when absent), never foldable into the
+ * nonce. An earlier concatenation preimage let a null-presentation
+ * record with nonce = P || N derive the same seed as a P-presentation
+ * record with nonce N; the structured preimage closes that.
+ */
+export declare function deriveSeed(contentDigest: string, presentationDigestOrNull: string | null, nonce: string, version: string): string;
+/**
+ * Sample `n` spans of `spanLen` code points from `sourceText` at
+ * distinct positions determined by `seed` (algorithm span_sample_v1).
+ *
+ * The source is split into code points via Array.from, so astral
+ * characters (emoji) count as one position each and spans never split
+ * a surrogate pair. With L code points the position range is
+ * L - spanLen + 1. Throws when spanLen or n is not a positive integer,
+ * when the source is shorter than spanLen code points, or when n
+ * exceeds the position range.
+ */
+export declare function sampleSpans(sourceText: string, seed: string, n: number, spanLen: number): SampledSpan[];
+/**
+ * Commit to span texts: "sha256:" + sha256hex(UTF-8 of each span
+ * text), in the given (sampling) order.
+ */
+export declare function commitSpans(spanTexts: readonly string[]): string[];
+/**
+ * Score responses against span texts under exact_match_v1: exact
+ * string equality per index. Throws when the arrays differ in length;
+ * a missing response is a protocol error, not a miss.
+ */
+export declare function scoreResponses(spanTexts: readonly string[], responses: readonly string[]): ScoreResponsesResult;
+//# sourceMappingURL=sampler.d.ts.map

package/dist/src/v2/read_fidelity_receipt/sampler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampler.d.ts","sourceRoot":"","sources":["../../../../src/v2/read_fidelity_receipt/sampler.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAA;AAMnE;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CACxB,aAAa,EAAE,MAAM,EACrB,wBAAwB,EAAE,MAAM,GAAG,IAAI,EACvC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,GACd,MAAM,CASR;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CACzB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,CAAC,EAAE,MAAM,EACT,OAAO,EAAE,MAAM,GACd,WAAW,EAAE,CAqCf;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAElE;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,SAAS,MAAM,EAAE,EAC5B,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,oBAAoB,CAYtB"}

package/dist/src/v2/read_fidelity_receipt/sampler.js

@@ -0,0 +1,110 @@
+// Copyright 2024-2026 Tymofii Pidlisnyi. Apache-2.0 license. See LICENSE.
+// ══════════════════════════════════════════════════════════════════
+// read_fidelity_receipt (v2): seed derivation, span sampler, scoring
+// ══════════════════════════════════════════════════════════════════
+// Deterministic, pure functions: no I/O, no clock, no randomness.
+// Bit-exact across languages:
+//   seed = sha256hex(utf8( canonicalizeJCS({
+//            content_digest, presentation_digest (null when absent),
+//            nonce, version }) ))           (RFC 8785 JCS preimage)
+//   position i, attempt j:
+//     h = sha256(utf8(seed + ":" + i + ":" + j))
+//     pos = BE-uint64(first 8 bytes of h) mod range
+//     bump j on repeat until the position is unused
+//   span text = code points [pos, pos + spanLen), Array.from slicing.
+// ══════════════════════════════════════════════════════════════════
+import { createHash } from 'node:crypto';
+import { canonicalizeJCS } from '../../core/canonical-jcs.js';
+function sha256hex(input) {
+    return createHash('sha256').update(input, 'utf8').digest('hex');
+}
+/**
+ * Derive the challenge seed. The preimage is the RFC 8785 JCS
+ * canonicalization of an object carrying the four bound fields, so the
+ * component boundaries are unambiguous: presentation_digest is a
+ * distinct JSON member (null when absent), never foldable into the
+ * nonce. An earlier concatenation preimage let a null-presentation
+ * record with nonce = P || N derive the same seed as a P-presentation
+ * record with nonce N; the structured preimage closes that.
+ */
+export function deriveSeed(contentDigest, presentationDigestOrNull, nonce, version) {
+    return sha256hex(canonicalizeJCS({
+        content_digest: contentDigest,
+        presentation_digest: presentationDigestOrNull,
+        nonce,
+        version,
+    }));
+}
+/**
+ * Sample `n` spans of `spanLen` code points from `sourceText` at
+ * distinct positions determined by `seed` (algorithm span_sample_v1).
+ *
+ * The source is split into code points via Array.from, so astral
+ * characters (emoji) count as one position each and spans never split
+ * a surrogate pair. With L code points the position range is
+ * L - spanLen + 1. Throws when spanLen or n is not a positive integer,
+ * when the source is shorter than spanLen code points, or when n
+ * exceeds the position range.
+ */
+export function sampleSpans(sourceText, seed, n, spanLen) {
+    if (!Number.isInteger(spanLen) || spanLen < 1) {
+        throw new Error(`spanLen must be a positive integer, got ${spanLen}`);
+    }
+    if (!Number.isInteger(n) || n < 1) {
+        throw new Error(`n must be a positive integer, got ${n}`);
+    }
+    const cps = Array.from(sourceText);
+    const L = cps.length;
+    if (L < spanLen) {
+        throw new Error(`source has ${L} code points, need at least spanLen ${spanLen}`);
+    }
+    const range = L - spanLen + 1;
+    if (n > range) {
+        throw new Error(`n ${n} exceeds the position range ${range}`);
+    }
+    const used = new Set();
+    const spans = [];
+    for (let i = 0; i < n; i++) {
+        for (let j = 0;; j++) {
+            const h = createHash('sha256')
+                .update(`${seed}:${i}:${j}`, 'utf8')
+                .digest();
+            const pos = Number(h.readBigUInt64BE(0) % BigInt(range));
+            if (used.has(pos))
+                continue;
+            used.add(pos);
+            spans.push({
+                pos,
+                len: spanLen,
+                text: cps.slice(pos, pos + spanLen).join(''),
+            });
+            break;
+        }
+    }
+    return spans;
+}
+/**
+ * Commit to span texts: "sha256:" + sha256hex(UTF-8 of each span
+ * text), in the given (sampling) order.
+ */
+export function commitSpans(spanTexts) {
+    return spanTexts.map((t) => `sha256:${sha256hex(t)}`);
+}
+/**
+ * Score responses against span texts under exact_match_v1: exact
+ * string equality per index. Throws when the arrays differ in length;
+ * a missing response is a protocol error, not a miss.
+ */
+export function scoreResponses(spanTexts, responses) {
+    if (spanTexts.length !== responses.length) {
+        throw new Error(`responses length ${responses.length} does not match span count ${spanTexts.length}`);
+    }
+    const results = spanTexts.map((t, i) => responses[i] === t);
+    let k = 0;
+    for (const r of results) {
+        if (r)
+            k++;
+    }
+    return { k, results };
+}
+//# sourceMappingURL=sampler.js.map

package/dist/src/v2/read_fidelity_receipt/sampler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampler.js","sourceRoot":"","sources":["../../../../src/v2/read_fidelity_receipt/sampler.ts"],"names":[],"mappings":"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"}

package/dist/src/v2/read_fidelity_receipt/types.d.ts

@@ -0,0 +1,139 @@
+/** Literal tag for record discrimination at the wire level. */
+export type ReadFidelityReceiptType = 'read_fidelity_receipt';
+/** The v1 sampling algorithm identifier. */
+export type ReadFidelitySamplingAlgorithm = 'span_sample_v1';
+/** The v1 scoring method identifier: exact string equality per span. */
+export type ReadFidelityScoringMethod = 'exact_match_v1';
+/**
+ * How the executor claims were checked. `asserted` means the attester
+ * simply asserts model_claim and runtime_claim; `provider_attestation`
+ * means a provider-level attestation backs them.
+ */
+export type ReadFidelityVerificationMethod = 'asserted' | 'provider_attestation';
+/**
+ * The challenge block. The nonce is verifier-supplied and never
+ * derivable from the document alone. The seed MUST equal
+ *   sha256hex(utf8( canonicalizeJCS({
+ *     content_digest, presentation_digest, nonce, version }) ))
+ * the RFC 8785 JCS preimage of those four fields (presentation_digest
+ * null when absent); verifiers recompute and reject on mismatch, which
+ * is the replay binding: reusing commitments under a different nonce,
+ * content, or presentation breaks the derivation.
+ */
+export interface ReadFidelityChallenge {
+    /** Verifier-supplied; never derivable from the document alone. */
+    readonly nonce: string;
+    /** MUST equal the seed derivation over content, presentation, nonce, version. */
+    readonly seed: string;
+    readonly algorithm: ReadFidelitySamplingAlgorithm;
+    readonly version: '1';
+    /** Span length in code points; required to recompute spans. */
+    readonly span_len: number;
+    /**
+     * sha256 of the UTF-8 bytes of each span text, in sampling order,
+     * each as "sha256:<64 lowercase hex>". Raw span texts are NOT in
+     * the record.
+     */
+    readonly span_commitments: readonly string[];
+}
+/**
+ * A read fidelity receipt proves sampled readback fidelity at the stated n under the declared sampling
+ * assumptions. It does not prove every byte was read correctly, does not prove perception or comprehension,
+ * does not prove which channel was used, and carries no normative pass threshold: the consumer judges k of n.
+ */
+export interface ReadFidelityReceipt {
+    readonly type: ReadFidelityReceiptType;
+    /** Digest of the canonical content bytes, "sha256:<64 lowercase hex>". */
+    readonly content_digest: string;
+    /** Digest of the rendered presentation as served, or null. */
+    readonly presentation_digest: string | null;
+    readonly challenge: ReadFidelityChallenge;
+    /**
+     * "sha256:" + sha256hex(canonicalizeJCS(responses)) where responses
+     * is the ordered array of readback strings.
+     */
+    readonly response_digest: string;
+    /** Count of responses that exactly matched their span text. */
+    readonly k: number;
+    /** Sample count; MUST equal challenge.span_commitments.length. */
+    readonly n: number;
+    readonly scoring_method: ReadFidelityScoringMethod;
+    /**
+     * Ed25519 public key hex of the SIGNING identity. May differ from
+     * the executing model; model_claim and runtime_claim are claims
+     * about the executor, not proofs.
+     */
+    readonly attester: string;
+    readonly model_claim: string;
+    readonly runtime_claim: string;
+    readonly verification_method: ReadFidelityVerificationMethod;
+    /** ISO 8601, caller-provided; the library never reads a wall clock. */
+    readonly challenge_issued_at: string;
+    /** ISO 8601, caller-provided; the library never reads a wall clock. */
+    readonly response_observed_at: string;
+    /** ISO 8601, caller-provided; the library never reads a wall clock. */
+    readonly receipt_issued_at: string;
+    /** Optional; present when word_digest_handles appear in the flow. */
+    readonly lexicon_id?: string;
+    /** Optional; "single-list-v1", alongside lexicon_id. */
+    readonly lexicon_profile?: string;
+    /** 128 hex chars, Ed25519 over canonicalizeJCS(record with sig excluded). */
+    readonly sig: string;
+}
+/**
+ * Input to createReadFidelityReceipt: the record minus the fields the
+ * library sets itself (`type` is the literal, `attester` is derived
+ * from the private key, `sig` is computed).
+ */
+export type CreateReadFidelityReceiptInput = Omit<ReadFidelityReceipt, 'type' | 'attester' | 'sig'>;
+/** One sampled span: code-point position, length, and text. */
+export interface SampledSpan {
+    /** Start position in code points (Array.from indexing). */
+    readonly pos: number;
+    /** Span length in code points; equals the requested spanLen. */
+    readonly len: number;
+    readonly text: string;
+}
+/** Result of scoreResponses: per-span exact-match flags and their count. */
+export interface ScoreResponsesResult {
+    readonly k: number;
+    readonly results: readonly boolean[];
+}
+/**
+ * Failure reasons for verifyReadFidelityReceipt and verifyAgainstSource.
+ * Check order in verifyReadFidelityReceipt: shape (INVALID_* and
+ * N_MISMATCH), then SIGNATURE_INVALID, then SEED_MISMATCH. A record
+ * tampered after signing therefore fails on the signature; a record
+ * re-signed after a nonce or presentation swap carries a valid
+ * signature and fails on the seed derivation instead.
+ */
+export type ReadFidelityVerifyReason = 'INVALID_TYPE' | 'INVALID_CONTENT_DIGEST' | 'INVALID_PRESENTATION_DIGEST' | 'INVALID_CHALLENGE' | 'INVALID_N' | 'N_MISMATCH' | 'INVALID_K' | 'INVALID_RESPONSE_DIGEST' | 'INVALID_SCORING_METHOD' | 'INVALID_ATTESTER' | 'INVALID_CLAIMS' | 'INVALID_VERIFICATION_METHOD' | 'INVALID_TIMESTAMP' | 'INVALID_LEXICON_FIELDS' | 'INVALID_SIG_FORMAT' | 'SIGNATURE_INVALID' | 'SEED_MISMATCH' | 'SPAN_RECOMPUTE_FAILED' | 'COMMITMENT_MISMATCH';
+/** Result of verifyReadFidelityReceipt. */
+export interface ReadFidelityVerifyResult {
+    readonly valid: boolean;
+    readonly reason?: ReadFidelityVerifyReason;
+}
+/**
+ * Result of verifyAgainstSource. `commitment_matches[i]` compares the
+ * recomputed commitment of span i against challenge.span_commitments[i];
+ * ALL must match for validity. `signature_valid` and `seed_valid` are
+ * reported independently so a caller can see which binding broke.
+ */
+export interface VerifyAgainstSourceResult {
+    readonly valid: boolean;
+    readonly reason?: ReadFidelityVerifyReason;
+    readonly commitment_matches: readonly boolean[];
+    readonly signature_valid: boolean;
+    readonly seed_valid: boolean;
+}
+/**
+ * Result of verifyResponses: the recomputed k over the supplied
+ * responses, whether it equals the recorded k, and whether the
+ * responses JCS-hash to the recorded response_digest.
+ */
+export interface VerifyResponsesResult {
+    readonly k_recomputed: number;
+    readonly matches_claimed_k: boolean;
+    readonly response_digest_ok: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/src/v2/read_fidelity_receipt/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/v2/read_fidelity_receipt/types.ts"],"names":[],"mappings":"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"}

package/dist/src/v2/read_fidelity_receipt/types.js

@@ -0,0 +1,17 @@
+// Copyright 2024-2026 Tymofii Pidlisnyi. Apache-2.0 license. See LICENSE.
+// ══════════════════════════════════════════════════════════════════
+// read_fidelity_receipt (v2): TypeScript types
+// ══════════════════════════════════════════════════════════════════
+// A signed record of a sampled readback challenge: a verifier supplies
+// a nonce, the seed binds that nonce to the exact content digest and
+// presentation digest, spans are sampled deterministically from the
+// seed, and the record commits to the span hashes and the scored
+// readback result (k of n). The raw span texts and responses are NOT
+// in the record; only their commitments and digests are.
+//
+// Signature convention: `sig` is EXCLUDED from the signing preimage.
+// The preimage is canonicalizeJCS(record with the sig key removed
+// entirely), NOT a record with sig set to an empty string.
+// ══════════════════════════════════════════════════════════════════
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/v2/read_fidelity_receipt/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/v2/read_fidelity_receipt/types.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,qEAAqE;AACrE,+CAA+C;AAC/C,qEAAqE;AACrE,uEAAuE;AACvE,qEAAqE;AACrE,oEAAoE;AACpE,iEAAiE;AACjE,qEAAqE;AACrE,yDAAyD;AACzD,EAAE;AACF,qEAAqE;AACrE,kEAAkE;AAClE,2DAA2D;AAC3D,qEAAqE"}

package/dist/src/v2/read_fidelity_receipt/vectors/generate.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=generate.d.ts.map

package/dist/src/v2/read_fidelity_receipt/vectors/generate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../../../../src/v2/read_fidelity_receipt/vectors/generate.ts"],"names":[],"mappings":""}