@ageprotocol/receipts 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SAYGE
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/canonical.d.ts

@@ -0,0 +1,3 @@
+export declare function canonicalize(value: unknown): string;
+export declare function canonicalBytes(value: unknown): Uint8Array;
+export declare const MAX_DEPTH = 64;

package/dist/canonical.js

@@ -0,0 +1,37 @@
+// RFC 8785 JSON Canonicalization Scheme. JSON.stringify already serializes
+// numbers and strings the way JCS requires; what it lacks is deterministic
+// key order, which sortKeysDeep supplies.
+export function canonicalize(value) {
+    return JSON.stringify(sortKeysDeep(value));
+}
+export function canonicalBytes(value) {
+    return new TextEncoder().encode(canonicalize(value));
+}
+// A verifier is handed JSON by strangers, and recursion on attacker-chosen
+// nesting is a stack overflow waiting to happen. No honest AGE document comes
+// close to this depth, so exceeding it is a rejection, not a crash.
+export const MAX_DEPTH = 64;
+function sortKeysDeep(value, depth = 0) {
+    if (depth > MAX_DEPTH) {
+        throw new RangeError(`canonicalize: nesting deeper than ${MAX_DEPTH} levels`);
+    }
+    if (Array.isArray(value))
+        return value.map((item) => sortKeysDeep(item, depth + 1));
+    if (value !== null && typeof value === 'object') {
+        const source = value;
+        // A null prototype keeps a member named __proto__ an own property instead
+        // of letting the assignment below set the prototype and drop the member.
+        const out = Object.create(null);
+        for (const key of Object.keys(source).sort()) {
+            const item = source[key];
+            if (item === undefined)
+                continue;
+            out[key] = sortKeysDeep(item, depth + 1);
+        }
+        return out;
+    }
+    if (typeof value === 'number' && !Number.isFinite(value)) {
+        throw new TypeError('canonicalize: non-finite number cannot be represented in JSON');
+    }
+    return value;
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { canonicalize, canonicalBytes, MAX_DEPTH } from './canonical.ts';
+export { generateKeyPair, thumbprint, isPublicJwk, keyMapFromJwks, withKid, bareJwk, toPublicJwk, publicKeyFromJwk, privateKeyFromJwk, type PublicJwk, type PrivateJwk, } from './keys.ts';
+export { signBytes, verifyBytes } from './signature.ts';
+export { leafHash, merkleRoot, inclusionProof, verifyInclusion, type InclusionProof } from './merkle.ts';
+export { RECEIPT_VERSION, ATTESTATION_VERSION, AGENT_ID_PREFIX, REGISTRY_ID_PREFIX, DIGEST_PREFIX, sha256Digest, agentIdOf, registryIdOf, thumbprintOfId, coreOf, receiptShapeProblem, coreNumberProblem, receiptIdOf, agentSigningInput, attestationOf, registrySigningInput, agentSignaturesOf, registrySignaturesOf, agentSignatureOf, registrySignatureOf, registrySignatureFor, agentSign, registrySign, verifyReceipt, type ReceiptArtifact, type ReceiptTask, type ReceiptPolicy, type ReceiptCore, type AgentSignature, type RegistrySignature, type OtherSignature, type ReceiptSignature, type Receipt, type RegistryAttestation, type RegistryAssignment, type CheckStatus, type Check, type VerifyReceiptResult, type VerifyReceiptOptions, } from './receipt.ts';
+export { ROOT_VERSION, sequenceOf, rootLeaves, rootSigningInput, buildRoot, proofFor, verifyRoot, verifyRootInclusion, type RootDocument, type RootProof, } from './root.ts';

package/dist/index.js

@@ -0,0 +1,6 @@
+export { canonicalize, canonicalBytes, MAX_DEPTH } from "./canonical.js";
+export { generateKeyPair, thumbprint, isPublicJwk, keyMapFromJwks, withKid, bareJwk, toPublicJwk, publicKeyFromJwk, privateKeyFromJwk, } from "./keys.js";
+export { signBytes, verifyBytes } from "./signature.js";
+export { leafHash, merkleRoot, inclusionProof, verifyInclusion } from "./merkle.js";
+export { RECEIPT_VERSION, ATTESTATION_VERSION, AGENT_ID_PREFIX, REGISTRY_ID_PREFIX, DIGEST_PREFIX, sha256Digest, agentIdOf, registryIdOf, thumbprintOfId, coreOf, receiptShapeProblem, coreNumberProblem, receiptIdOf, agentSigningInput, attestationOf, registrySigningInput, agentSignaturesOf, registrySignaturesOf, agentSignatureOf, registrySignatureOf, registrySignatureFor, agentSign, registrySign, verifyReceipt, } from "./receipt.js";
+export { ROOT_VERSION, sequenceOf, rootLeaves, rootSigningInput, buildRoot, proofFor, verifyRoot, verifyRootInclusion, } from "./root.js";

package/dist/keys.d.ts

@@ -0,0 +1,22 @@
+import { type KeyObject } from 'node:crypto';
+export interface PublicJwk {
+    kty: 'OKP';
+    crv: 'Ed25519';
+    x: string;
+    kid?: string;
+}
+export interface PrivateJwk extends PublicJwk {
+    d: string;
+}
+export declare function thumbprint(jwk: PublicJwk): string;
+export declare function isPublicJwk(value: unknown): value is PublicJwk;
+export declare function keyMapFromJwks(keys: PublicJwk[]): Map<string, PublicJwk>;
+export declare function withKid(jwk: PublicJwk): PublicJwk;
+export declare function toPublicJwk(jwk: PrivateJwk): PublicJwk;
+export declare function generateKeyPair(): {
+    publicJwk: PublicJwk;
+    privateJwk: PrivateJwk;
+};
+export declare function publicKeyFromJwk(jwk: PublicJwk): KeyObject;
+export declare function privateKeyFromJwk(jwk: PrivateJwk): KeyObject;
+export declare function bareJwk(jwk: PublicJwk): PublicJwk;

package/dist/keys.js

@@ -0,0 +1,52 @@
+import { createHash, createPrivateKey, createPublicKey, generateKeyPairSync } from 'node:crypto';
+import { canonicalize } from "./canonical.js";
+// RFC 7638: SHA-256 over the canonical JSON of the required members only.
+export function thumbprint(jwk) {
+    const canonical = canonicalize({ crv: jwk.crv, kty: jwk.kty, x: jwk.x });
+    return createHash('sha256').update(canonical).digest('base64url');
+}
+export function isPublicJwk(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const jwk = value;
+    return typeof jwk.kty === 'string' && typeof jwk.crv === 'string' && typeof jwk.x === 'string';
+}
+// Index a JWKS by the RFC 7638 thumbprint of each key, so lookup is
+// cryptographic and a wrong or missing kid label cannot bind a jkt to a key
+// that does not hash to it. The first entry for a thumbprint wins.
+export function keyMapFromJwks(keys) {
+    const map = new Map();
+    if (!Array.isArray(keys))
+        return map;
+    for (const key of keys) {
+        if (!isPublicJwk(key))
+            continue;
+        const jkt = thumbprint(key);
+        if (!map.has(jkt))
+            map.set(jkt, key);
+    }
+    return map;
+}
+export function withKid(jwk) {
+    return { kty: jwk.kty, crv: jwk.crv, x: jwk.x, kid: thumbprint(jwk) };
+}
+export function toPublicJwk(jwk) {
+    return withKid({ kty: jwk.kty, crv: jwk.crv, x: jwk.x });
+}
+export function generateKeyPair() {
+    const { privateKey } = generateKeyPairSync('ed25519');
+    const exported = privateKey.export({ format: 'jwk' });
+    const privateJwk = { kty: 'OKP', crv: 'Ed25519', x: exported.x, d: exported.d };
+    const publicJwk = withKid({ kty: 'OKP', crv: 'Ed25519', x: exported.x });
+    return { publicJwk, privateJwk };
+}
+export function publicKeyFromJwk(jwk) {
+    return createPublicKey({ key: { kty: jwk.kty, crv: jwk.crv, x: jwk.x }, format: 'jwk' });
+}
+export function privateKeyFromJwk(jwk) {
+    return createPrivateKey({ key: { kty: jwk.kty, crv: jwk.crv, x: jwk.x, d: jwk.d }, format: 'jwk' });
+}
+// The three required members and nothing else, which is what a receipt embeds.
+export function bareJwk(jwk) {
+    return { kty: jwk.kty, crv: jwk.crv, x: jwk.x };
+}

package/dist/merkle.d.ts

@@ -0,0 +1,9 @@
+export declare function leafHash(data: Uint8Array): Buffer;
+export declare function merkleRoot(leaves: Uint8Array[]): Buffer;
+export interface InclusionProof {
+    index: number;
+    size: number;
+    path: string[];
+}
+export declare function inclusionProof(leaves: Uint8Array[], index: number): InclusionProof;
+export declare function verifyInclusion(leafData: Uint8Array, proof: InclusionProof, rootHex: string): boolean;

package/dist/merkle.js

@@ -0,0 +1,94 @@
+import { createHash } from 'node:crypto';
+const LEAF_PREFIX = Buffer.from([0x00]);
+const NODE_PREFIX = Buffer.from([0x01]);
+function sha256(...parts) {
+    const hash = createHash('sha256');
+    for (const part of parts)
+        hash.update(part);
+    return hash.digest();
+}
+export function leafHash(data) {
+    return sha256(LEAF_PREFIX, data);
+}
+function nodeHash(left, right) {
+    return sha256(NODE_PREFIX, left, right);
+}
+// Largest power of two strictly less than n, for n >= 2.
+function splitPoint(n) {
+    let k = 1;
+    while (k * 2 < n)
+        k *= 2;
+    return k;
+}
+function rootOf(hashes) {
+    if (hashes.length === 0)
+        return sha256();
+    if (hashes.length === 1)
+        return hashes[0];
+    const k = splitPoint(hashes.length);
+    return nodeHash(rootOf(hashes.slice(0, k)), rootOf(hashes.slice(k)));
+}
+export function merkleRoot(leaves) {
+    return rootOf(leaves.map(leafHash));
+}
+function pathOf(hashes, index) {
+    if (hashes.length <= 1)
+        return [];
+    const k = splitPoint(hashes.length);
+    if (index < k)
+        return [...pathOf(hashes.slice(0, k), index), rootOf(hashes.slice(k))];
+    return [...pathOf(hashes.slice(k), index - k), rootOf(hashes.slice(0, k))];
+}
+export function inclusionProof(leaves, index) {
+    if (!Number.isInteger(index) || index < 0 || index >= leaves.length) {
+        throw new RangeError(`inclusionProof: index ${index} out of range for ${leaves.length} leaves`);
+    }
+    const path = pathOf(leaves.map(leafHash), index).map((h) => h.toString('hex'));
+    return { index, size: leaves.length, path };
+}
+// Lowercase only. Accepting both cases would mean two spellings of one proof,
+// and an implementation that emits uppercase would interoperate here and
+// nowhere else.
+const HEX_32_BYTES = /^[0-9a-f]{64}$/;
+// RFC 9162 section 2.1.3.2. A malformed proof is a false, never an exception.
+//
+// The walk uses division and remainder rather than the bitwise operators the
+// RFC's pseudocode implies. JavaScript's >>> and & coerce to 32 bits, so a
+// tree with more than 2**32 leaves made sn truncate to a small number and the
+// walk was abandoned partway, rejecting proofs that are correct. Arithmetic
+// is exact to 2**53, which is the range the format allows anyway.
+export function verifyInclusion(leafData, proof, rootHex) {
+    if (!Number.isSafeInteger(proof.size) || proof.size < 1)
+        return false;
+    if (!Number.isSafeInteger(proof.index) || proof.index < 0 || proof.index >= proof.size)
+        return false;
+    if (!Array.isArray(proof.path))
+        return false;
+    const isRight = (n) => n % 2 === 1;
+    const up = (n) => Math.floor(n / 2);
+    let fn = proof.index;
+    let sn = proof.size - 1;
+    let r = leafHash(leafData);
+    for (const entry of proof.path) {
+        if (sn === 0)
+            return false;
+        if (typeof entry !== 'string' || !HEX_32_BYTES.test(entry))
+            return false;
+        const p = Buffer.from(entry, 'hex');
+        if (isRight(fn) || fn === sn) {
+            r = nodeHash(p, r);
+            if (!isRight(fn)) {
+                while (!isRight(fn) && fn !== 0) {
+                    fn = up(fn);
+                    sn = up(sn);
+                }
+            }
+        }
+        else {
+            r = nodeHash(r, p);
+        }
+        fn = up(fn);
+        sn = up(sn);
+    }
+    return sn === 0 && r.toString('hex') === rootHex.toLowerCase();
+}

package/dist/receipt.d.ts

@@ -0,0 +1,108 @@
+import { type PrivateJwk, type PublicJwk } from './keys.ts';
+export declare const RECEIPT_VERSION = "0.1";
+export declare const ATTESTATION_VERSION = "0.1";
+export declare const AGENT_ID_PREFIX = "age:agent:";
+export declare const REGISTRY_ID_PREFIX = "age:registry:";
+export declare const DIGEST_PREFIX = "sha256:";
+export declare function sha256Digest(bytes: Uint8Array): string;
+export declare function agentIdOf(key: PublicJwk): string;
+export declare function registryIdOf(key: PublicJwk): string;
+export declare function thumbprintOfId(id: string, prefix: string): string | undefined;
+export interface ReceiptArtifact {
+    kind: string;
+    digest: string;
+    ref?: string;
+    [member: string]: unknown;
+}
+export interface ReceiptTask {
+    id?: string;
+    description?: string;
+    [member: string]: unknown;
+}
+export type ReceiptPolicy = Record<string, unknown>;
+export interface ReceiptCore {
+    receipt_version: typeof RECEIPT_VERSION;
+    agent: string;
+    timestamp: string;
+    task: ReceiptTask;
+    action: {
+        type: string;
+    } & Record<string, unknown>;
+    inputs: ReceiptArtifact[];
+    outputs: ReceiptArtifact[];
+    environment: Record<string, unknown>;
+    policy: ReceiptPolicy | null;
+}
+export interface AgentSignature {
+    role: 'agent';
+    signer: string;
+    alg: 'Ed25519';
+    key: PublicJwk;
+    signature: string;
+}
+export interface RegistrySignature {
+    role: 'registry';
+    signer: string;
+    alg: 'Ed25519';
+    sequence: number;
+    registered_at: string;
+    jwks?: string;
+    signature: string;
+}
+export interface OtherSignature {
+    role: string;
+    signer: string;
+    alg: string;
+    signature: string;
+    [member: string]: unknown;
+}
+export type ReceiptSignature = AgentSignature | RegistrySignature | OtherSignature;
+export interface Receipt extends ReceiptCore {
+    id: string;
+    signatures: ReceiptSignature[];
+}
+export declare function coreOf(value: ReceiptCore | Receipt): ReceiptCore;
+export declare function receiptIdOf(value: ReceiptCore | Receipt): string;
+export declare function agentSigningInput(value: ReceiptCore | Receipt): Uint8Array;
+export interface RegistryAttestation {
+    attestation_version: typeof ATTESTATION_VERSION;
+    receipt: string;
+    agent: string;
+    sequence: number;
+    registered_at: string;
+    registry: string;
+}
+type RegistryEntryFields = Pick<RegistrySignature, 'sequence' | 'registered_at' | 'signer'>;
+export declare function attestationOf(receipt: Receipt, entry: RegistryEntryFields): RegistryAttestation;
+export declare function registrySigningInput(receipt: Receipt, entry: RegistryEntryFields): Uint8Array;
+export declare function agentSignaturesOf(receipt: Receipt): AgentSignature[];
+export declare function registrySignaturesOf(receipt: Receipt): RegistrySignature[];
+/** The first agent entry. Never use this to decide a verdict; see the note above. */
+export declare function agentSignatureOf(receipt: Receipt): AgentSignature | undefined;
+/** The first registry entry. Never use this to decide a verdict; see the note above. */
+export declare function registrySignatureOf(receipt: Receipt): RegistrySignature | undefined;
+export declare function registrySignatureFor(receipt: Receipt, registryId: string): RegistrySignature | undefined;
+export declare function coreNumberProblem(value: unknown, path?: string, depth?: number): string | undefined;
+export declare function receiptShapeProblem(value: unknown): string | undefined;
+export declare function agentSign(core: ReceiptCore, agentPrivate: PrivateJwk): Receipt;
+export interface RegistryAssignment {
+    sequence: number;
+    registered_at: string;
+    jwks?: string;
+}
+export declare function registrySign(receipt: Receipt, assigned: RegistryAssignment, registryPrivate: PrivateJwk): Receipt;
+export type CheckStatus = 'pass' | 'fail' | 'skip';
+export interface Check {
+    name: string;
+    status: CheckStatus;
+    detail: string;
+}
+export interface VerifyReceiptResult {
+    ok: boolean;
+    checks: Check[];
+}
+export interface VerifyReceiptOptions {
+    registryKeys?: PublicJwk[] | Map<string, PublicJwk>;
+}
+export declare function verifyReceipt(receipt: Receipt, options?: VerifyReceiptOptions): VerifyReceiptResult;
+export {};

package/dist/receipt.js

@@ -0,0 +1,373 @@
+import { createHash } from 'node:crypto';
+import { canonicalBytes, MAX_DEPTH } from "./canonical.js";
+import { bareJwk, isPublicJwk, keyMapFromJwks, thumbprint, toPublicJwk } from "./keys.js";
+import { signBytes, verifyBytes } from "./signature.js";
+export const RECEIPT_VERSION = '0.1';
+export const ATTESTATION_VERSION = '0.1';
+export const AGENT_ID_PREFIX = 'age:agent:';
+export const REGISTRY_ID_PREFIX = 'age:registry:';
+export const DIGEST_PREFIX = 'sha256:';
+export function sha256Digest(bytes) {
+    return `${DIGEST_PREFIX}${createHash('sha256').update(bytes).digest('hex')}`;
+}
+// Identities are derived from keys, never assigned: the id is the RFC 7638
+// thumbprint behind a prefix that names the kind of thing it identifies.
+export function agentIdOf(key) {
+    return `${AGENT_ID_PREFIX}${thumbprint(key)}`;
+}
+export function registryIdOf(key) {
+    return `${REGISTRY_ID_PREFIX}${thumbprint(key)}`;
+}
+export function thumbprintOfId(id, prefix) {
+    if (typeof id !== 'string' || !id.startsWith(prefix) || id.length === prefix.length)
+        return undefined;
+    return id.slice(prefix.length);
+}
+export function coreOf(value) {
+    const { id, signatures, ...core } = value;
+    return core;
+}
+export function receiptIdOf(value) {
+    return sha256Digest(canonicalBytes(coreOf(value)));
+}
+export function agentSigningInput(value) {
+    return canonicalBytes(coreOf(value));
+}
+// The registry countersigns the receipt hash and its place in the sequence,
+// nothing else. It does not re-sign the agent's content.
+export function attestationOf(receipt, entry) {
+    return {
+        attestation_version: ATTESTATION_VERSION,
+        receipt: receipt.id,
+        agent: receipt.agent,
+        sequence: entry.sequence,
+        registered_at: entry.registered_at,
+        registry: entry.signer,
+    };
+}
+export function registrySigningInput(receipt, entry) {
+    return canonicalBytes(attestationOf(receipt, entry));
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f]/g;
+const DETAIL_LIMIT = 72;
+// Anything quoted back from the receipt is input the verifier does not
+// control. It is stripped of the characters that could rewrite a terminal and
+// truncated before it reaches a detail, and it never becomes a check name.
+function safeText(value) {
+    const raw = typeof value === 'string' ? value
+        : value === null ? 'null'
+            : typeof value === 'object' ? (Array.isArray(value) ? 'an array' : 'an object')
+                : typeof value === 'symbol' ? 'a symbol'
+                    : String(value);
+    const stripped = raw.replace(CONTROL_CHARACTERS, '');
+    return stripped.length > DETAIL_LIMIT ? `${stripped.slice(0, DETAIL_LIMIT)}...` : stripped;
+}
+// Nothing here trusts the array to hold objects, or to hold one entry per
+// role. Callers that want a verdict on every entry use verifyReceipt.
+function signatureEntries(receipt) {
+    const value = receipt;
+    if (!isObject(value) || !Array.isArray(value.signatures))
+        return [];
+    return value.signatures;
+}
+function entriesWithRole(receipt, role) {
+    return signatureEntries(receipt).filter((entry) => isObject(entry) && entry.role === role);
+}
+export function agentSignaturesOf(receipt) {
+    return entriesWithRole(receipt, 'agent');
+}
+export function registrySignaturesOf(receipt) {
+    return entriesWithRole(receipt, 'registry');
+}
+// The singular forms below return the FIRST entry of a role and ignore the
+// rest. Taking the first entry and ignoring the rest is precisely how a
+// forged second registry entry once rode along invisibly, so nothing that
+// decides a verdict may use them: use agentSignaturesOf and
+// registrySignaturesOf, and account for every entry. These remain for callers
+// that want a display value from a receipt already verified.
+/** The first agent entry. Never use this to decide a verdict; see the note above. */
+export function agentSignatureOf(receipt) {
+    return agentSignaturesOf(receipt)[0];
+}
+/** The first registry entry. Never use this to decide a verdict; see the note above. */
+export function registrySignatureOf(receipt) {
+    return registrySignaturesOf(receipt)[0];
+}
+// A root belongs to one registry, so a lookup names the registry it means.
+export function registrySignatureFor(receipt, registryId) {
+    return registrySignaturesOf(receipt).find((entry) => entry.signer === registryId);
+}
+const RECEIPT_ID = /^sha256:[0-9a-f]{64}$/;
+function artifactsProblem(value, member) {
+    if (!Array.isArray(value))
+        return `${member} must be an array`;
+    for (let i = 0; i < value.length; i += 1) {
+        const item = value[i];
+        if (!isObject(item) || typeof item.kind !== 'string' || typeof item.digest !== 'string') {
+            return `${member} entry ${i} must be an object with a string kind and digest`;
+        }
+    }
+    return undefined;
+}
+// RFC 8785 serializes numbers the ES6 way, and a first-time implementer
+// reaching for a built-in JSON serializer will not reproduce it: an integral
+// float prints as 100.0 in some languages, and the thresholds and zero
+// padding of exponential notation differ (1e20, 1e-6, 1e-7 all disagree).
+// Every safe integer serializes identically everywhere, so the core carries
+// only those, and a stranger's first verifier is byte correct. A quantity
+// that is not a whole number belongs in a string, or in a smaller unit:
+// milliseconds, cents, basis points.
+export function coreNumberProblem(value, path = '', depth = 0) {
+    if (depth > MAX_DEPTH)
+        return `${safeText(path) || 'the core'} is nested deeper than ${MAX_DEPTH} levels`;
+    if (typeof value === 'number') {
+        if (Number.isSafeInteger(value))
+            return undefined;
+        const where = path === '' ? 'the core' : path;
+        return `${where} ${safeText(value)} must be an integer of magnitude at most ${Number.MAX_SAFE_INTEGER}`;
+    }
+    if (Array.isArray(value)) {
+        for (let i = 0; i < value.length; i += 1) {
+            const problem = coreNumberProblem(value[i], `${path}[${i}]`, depth + 1);
+            if (problem !== undefined)
+                return problem;
+        }
+        return undefined;
+    }
+    if (isObject(value)) {
+        for (const member of Object.keys(value)) {
+            const problem = coreNumberProblem(value[member], path === '' ? member : `${path}.${member}`, depth + 1);
+            if (problem !== undefined)
+                return problem;
+        }
+        return undefined;
+    }
+    return undefined;
+}
+// What a third-party verifier that validates the schema would insist on. ok
+// must never mean less than this, or a receipt this verifier calls verified
+// is one another verifier rejects, which breaks interoperability in the
+// direction that matters most.
+export function receiptShapeProblem(value) {
+    if (!isObject(value))
+        return 'receipt must be an object';
+    if (value.receipt_version !== RECEIPT_VERSION) {
+        return `receipt_version ${safeText(value.receipt_version)} is not ${RECEIPT_VERSION}`;
+    }
+    if (typeof value.agent !== 'string' || thumbprintOfId(value.agent, AGENT_ID_PREFIX) === undefined) {
+        return `agent must be an ${AGENT_ID_PREFIX} id`;
+    }
+    if (typeof value.timestamp !== 'string')
+        return 'timestamp must be a string';
+    if (!isObject(value.task))
+        return 'task must be an object';
+    if (!isObject(value.action) || typeof value.action.type !== 'string')
+        return 'action must be an object with a string type';
+    const inputs = artifactsProblem(value.inputs, 'inputs');
+    if (inputs !== undefined)
+        return inputs;
+    const outputs = artifactsProblem(value.outputs, 'outputs');
+    if (outputs !== undefined)
+        return outputs;
+    if (!isObject(value.environment))
+        return 'environment must be an object';
+    if (value.policy !== null && !isObject(value.policy))
+        return 'policy must be an object or null';
+    if (typeof value.id !== 'string' || !RECEIPT_ID.test(value.id))
+        return 'id must be a sha256: digest';
+    if (!Array.isArray(value.signatures))
+        return 'signatures must be an array';
+    return coreNumberProblem(coreOf(value));
+}
+function assertCore(core, caller) {
+    if (core.receipt_version !== RECEIPT_VERSION) {
+        throw new Error(`${caller}: receipt_version must be ${RECEIPT_VERSION}`);
+    }
+    if (thumbprintOfId(core.agent, AGENT_ID_PREFIX) === undefined) {
+        throw new Error(`${caller}: agent must be an ${AGENT_ID_PREFIX} id`);
+    }
+    if (typeof core.action !== 'object' || core.action === null || typeof core.action.type !== 'string') {
+        throw new Error(`${caller}: action.type is required`);
+    }
+    const numbers = coreNumberProblem(coreOf(core));
+    if (numbers !== undefined)
+        throw new Error(`${caller}: ${numbers}`);
+}
+export function agentSign(core, agentPrivate) {
+    assertCore(core, 'agentSign');
+    const clean = coreOf(core);
+    if (!isPublicJwk(agentPrivate)) {
+        throw new Error('agentSign: the signing key must carry the string members of a public JWK: kty, crv, and x');
+    }
+    const key = bareJwk(toPublicJwk(agentPrivate));
+    const keyProblem = embeddedKeyProblem(key);
+    if (keyProblem !== undefined)
+        throw new Error(`agentSign: ${keyProblem}`);
+    const signer = agentIdOf(key);
+    if (signer !== clean.agent) {
+        throw new Error(`agentSign: core.agent ${clean.agent} is not the id of the signing key ${signer}`);
+    }
+    const signature = signBytes(canonicalBytes(clean), agentPrivate);
+    return { ...clean, id: receiptIdOf(clean), signatures: [{ role: 'agent', signer, alg: 'Ed25519', key, signature }] };
+}
+export function registrySign(receipt, assigned, registryPrivate) {
+    if (receipt.id !== receiptIdOf(receipt))
+        throw new Error('registrySign: receipt id does not match its content');
+    if (!agentSignatureOf(receipt))
+        throw new Error('registrySign: receipt has no agent signature');
+    if (registrySignatureOf(receipt))
+        throw new Error('registrySign: receipt already has a registry signature');
+    if (!Number.isSafeInteger(assigned.sequence) || assigned.sequence < 1) {
+        throw new Error('registrySign: sequence must be a positive integer no greater than Number.MAX_SAFE_INTEGER');
+    }
+    const signer = registryIdOf(bareJwk(toPublicJwk(registryPrivate)));
+    const fields = { sequence: assigned.sequence, registered_at: assigned.registered_at, signer };
+    const signature = signBytes(registrySigningInput(receipt, fields), registryPrivate);
+    const entry = {
+        role: 'registry',
+        signer,
+        alg: 'Ed25519',
+        sequence: assigned.sequence,
+        registered_at: assigned.registered_at,
+        ...(assigned.jwks === undefined ? {} : { jwks: assigned.jwks }),
+        signature,
+    };
+    return { ...receipt, signatures: [...receipt.signatures, entry] };
+}
+const NOT_CHECKED = 'not checked, the receipt is malformed';
+// A check name is rendered by the CLI, so only a plain token out of the
+// receipt is ever allowed to shape one. Everything else is named
+// unknown_signature and says what it saw in the detail instead.
+const ROLE_TOKEN = /^[A-Za-z0-9_-]{1,32}$/;
+const SIGNING_ALGORITHM = 'Ed25519';
+const EMBEDDED_KEY_MEMBERS = ['crv', 'kty', 'x'];
+// A receipt embeds the agent key it was signed with, so that key is signed
+// input that nothing else inspects. It carries the three members RFC 7638
+// hashes and no others, or a member no verifier reads could ride along inside
+// the signature.
+function embeddedKeyProblem(value) {
+    if (!isPublicJwk(value))
+        return 'agent signature carries no public key';
+    const members = Object.keys(value).sort();
+    if (members.length !== EMBEDDED_KEY_MEMBERS.length || members.some((member, i) => member !== EMBEDDED_KEY_MEMBERS[i])) {
+        return `embedded agent key must carry exactly crv, kty, and x, not ${safeText(members.join(', '))}`;
+    }
+    if (value.kty !== 'OKP')
+        return `embedded agent key kty ${safeText(value.kty)} is not OKP`;
+    if (value.crv !== SIGNING_ALGORITHM)
+        return `embedded agent key crv ${safeText(value.crv)} is not ${SIGNING_ALGORITHM}`;
+    return undefined;
+}
+// Every check is always reported, so a reader sees the whole picture even
+// when the first one fails. Every entry in the signature array is judged or
+// reported by name, so no entry can hide behind another with the same role.
+// A receipt is ok when nothing failed; a skipped registry check means an
+// unregistered receipt, which is still a valid one.
+export function verifyReceipt(receipt, options = {}) {
+    const checks = [];
+    const report = (name, status, detail) => {
+        checks.push({ name, status, detail });
+    };
+    const problem = receiptShapeProblem(receipt);
+    if (problem !== undefined) {
+        report('integrity', 'fail', problem);
+        report('agent_signature', 'fail', NOT_CHECKED);
+        report('agent_identity', 'fail', NOT_CHECKED);
+        return { ok: false, checks };
+    }
+    let signingInput;
+    try {
+        signingInput = agentSigningInput(receipt);
+    }
+    catch (error) {
+        report('integrity', 'fail', `the receipt cannot be canonicalized: ${safeText(error instanceof Error ? error.message : error)}`);
+        report('agent_signature', 'fail', NOT_CHECKED);
+        report('agent_identity', 'fail', NOT_CHECKED);
+        return { ok: false, checks };
+    }
+    if (receipt.id === sha256Digest(signingInput))
+        report('integrity', 'pass', receipt.id);
+    else
+        report('integrity', 'fail', 'mismatch');
+    const agents = agentSignaturesOf(receipt);
+    const agent = agents[0];
+    const keyProblem = agent === undefined ? undefined : embeddedKeyProblem(agent.key);
+    if (agents.length !== 1 || !agent) {
+        const detail = agents.length === 0 ? 'no agent signature' : `${agents.length} agent signatures, exactly one is required`;
+        report('agent_signature', 'fail', detail);
+        report('agent_identity', 'fail', detail);
+    }
+    else if (keyProblem !== undefined) {
+        report('agent_signature', 'fail', keyProblem);
+        report('agent_identity', 'fail', keyProblem);
+    }
+    else if (agent.alg !== SIGNING_ALGORITHM) {
+        // The identity still holds: the key is genuine and binds the id. Only the
+        // claim about how it was used is wrong, so only that check fails.
+        report('agent_signature', 'fail', `alg ${safeText(agent.alg)} is not ${SIGNING_ALGORITHM}`);
+        reportAgentIdentity(receipt, agent, report);
+    }
+    else {
+        const signatureOk = typeof agent.signature === 'string' && verifyBytes(signingInput, agent.signature, agent.key);
+        report('agent_signature', signatureOk ? 'pass' : 'fail', signatureOk ? safeText(agent.signer) : 'agent signature does not verify');
+        reportAgentIdentity(receipt, agent, report);
+    }
+    // Zero registry entries is an unregistered receipt. One keeps the name the
+    // CLI already labels. More than one is legitimate once a second registry
+    // countersigns, and every one of them has to verify on its own.
+    const registries = registrySignaturesOf(receipt);
+    if (registries.length === 0) {
+        report('registry_signature', 'skip', 'absent, unregistered receipt');
+    }
+    else {
+        const keys = options.registryKeys instanceof Map ? options.registryKeys : keyMapFromJwks(options.registryKeys ?? []);
+        registries.forEach((entry, position) => {
+            const name = registries.length === 1 ? 'registry_signature' : `registry_signature_${position + 1}`;
+            const [status, detail] = registryVerdict(receipt, entry, keys);
+            report(name, status, detail);
+        });
+    }
+    const entries = signatureEntries(receipt);
+    for (let i = 0; i < entries.length; i += 1) {
+        const entry = entries[i];
+        if (isObject(entry) && (entry.role === 'agent' || entry.role === 'registry'))
+            continue;
+        if (!isObject(entry)) {
+            report('unknown_signature', 'fail', `signature entry ${i} is ${safeText(entry)}, not an object`);
+        }
+        else if (typeof entry.role !== 'string') {
+            report('unknown_signature', 'fail', `signature entry ${i} has a role that is ${safeText(entry.role)}, not a string`);
+        }
+        else if (!ROLE_TOKEN.test(entry.role)) {
+            report('unknown_signature', 'skip', `unknown role ${safeText(entry.role)}, not checked`);
+        }
+        else {
+            report(`${entry.role}_signature`, 'skip', 'unknown role, not checked');
+        }
+    }
+    return { ok: checks.every((check) => check.status !== 'fail'), checks };
+}
+function reportAgentIdentity(receipt, agent, report) {
+    const derived = agentIdOf(agent.key);
+    const identityOk = derived === agent.signer && derived === receipt.agent;
+    report('agent_identity', identityOk ? 'pass' : 'fail', identityOk ? 'key thumbprint matches id'
+        : `key thumbprint gives ${derived}, receipt says ${safeText(receipt.agent)}, signer says ${safeText(agent.signer)}`);
+}
+function registryVerdict(receipt, entry, keys) {
+    if (entry.alg !== SIGNING_ALGORITHM)
+        return ['fail', `alg ${safeText(entry.alg)} is not ${SIGNING_ALGORITHM}`];
+    const jkt = thumbprintOfId(entry.signer, REGISTRY_ID_PREFIX);
+    const key = jkt === undefined ? undefined : keys.get(jkt);
+    if (!key)
+        return ['fail', `registry key ${safeText(entry.signer)} not available`];
+    // A sequence is a signed number, so the safe-integer rule reaches it too.
+    if (!Number.isSafeInteger(entry.sequence) || entry.sequence < 1 || typeof entry.registered_at !== 'string' || typeof entry.signature !== 'string') {
+        return ['fail', 'registry signature entry is malformed'];
+    }
+    if (!verifyBytes(registrySigningInput(receipt, entry), entry.signature, key))
+        return ['fail', 'registry signature does not verify'];
+    return ['pass', `${safeText(entry.signer)}  sequence #${entry.sequence}`];
+}

package/dist/root.d.ts

@@ -0,0 +1,23 @@
+import { type PrivateJwk, type PublicJwk } from './keys.ts';
+import { type InclusionProof } from './merkle.ts';
+import { type Receipt } from './receipt.ts';
+export declare const ROOT_VERSION = "0.1";
+export interface RootDocument {
+    root_version: typeof ROOT_VERSION;
+    registry: string;
+    date: string;
+    sequence_start: number;
+    sequence_end: number;
+    root: string;
+    signature: string;
+}
+export interface RootProof extends InclusionProof {
+    sequence: number;
+}
+export declare function sequenceOf(receipt: Receipt, registryId: string): number;
+export declare function rootLeaves(receipts: Receipt[], registryId: string): Uint8Array[];
+export declare function rootSigningInput(doc: Omit<RootDocument, 'signature'> | RootDocument): Uint8Array;
+export declare function buildRoot(receipts: Receipt[], date: string, registryPrivate: PrivateJwk): RootDocument;
+export declare function proofFor(receipts: Receipt[], receipt: Receipt, registryId: string): RootProof;
+export declare function verifyRoot(doc: RootDocument, keys: PublicJwk[] | Map<string, PublicJwk>): boolean;
+export declare function verifyRootInclusion(receipt: Receipt, proof: RootProof, doc: RootDocument): boolean;

package/dist/root.js

@@ -0,0 +1,124 @@
+import { canonicalBytes } from "./canonical.js";
+import { bareJwk, keyMapFromJwks, toPublicJwk } from "./keys.js";
+import { inclusionProof, merkleRoot, verifyInclusion } from "./merkle.js";
+import { DIGEST_PREFIX, REGISTRY_ID_PREFIX, registryIdOf, registrySignatureFor, thumbprintOfId } from "./receipt.js";
+import { signBytes, verifyBytes } from "./signature.js";
+export const ROOT_VERSION = '0.1';
+// A sequence belongs to a registry, not to a receipt: the same receipt can be
+// registered by two registries at two different numbers, so every question
+// about sequence names the registry it is asking about.
+export function sequenceOf(receipt, registryId) {
+    const entry = registrySignatureFor(receipt, registryId);
+    if (!entry)
+        throw new Error(`receipt is not registered by ${registryId}`);
+    return entry.sequence;
+}
+function bySequence(receipts, registryId) {
+    return [...receipts].sort((a, b) => sequenceOf(a, registryId) - sequenceOf(b, registryId));
+}
+// An inclusion proof derives the tree size and the leaf index from the
+// sequence range alone, so a root over a range with a gap or a repeat is one
+// whose every proof fails. A registry learns that here, not from a verifier.
+function orderedRun(receipts, registryId, caller) {
+    const ordered = bySequence(receipts, registryId);
+    for (let i = 1; i < ordered.length; i += 1) {
+        const previous = sequenceOf(ordered[i - 1], registryId);
+        const current = sequenceOf(ordered[i], registryId);
+        if (current === previous)
+            throw new Error(`${caller}: sequence ${current} appears twice`);
+        if (current !== previous + 1)
+            throw new Error(`${caller}: sequences ${previous} and ${current} are not consecutive`);
+    }
+    return ordered;
+}
+export function rootLeaves(receipts, registryId) {
+    return bySequence(receipts, registryId).map((receipt) => canonicalBytes(receipt));
+}
+export function rootSigningInput(doc) {
+    const { signature, ...rest } = doc;
+    return canonicalBytes(rest);
+}
+export function buildRoot(receipts, date, registryPrivate) {
+    if (receipts.length === 0)
+        throw new Error('buildRoot: no receipts');
+    const registry = registryIdOf(bareJwk(toPublicJwk(registryPrivate)));
+    const ordered = orderedRun(receipts, registry, 'buildRoot');
+    const leaves = ordered.map((receipt) => canonicalBytes(receipt));
+    const unsigned = {
+        root_version: ROOT_VERSION,
+        registry,
+        date,
+        sequence_start: sequenceOf(ordered[0], registry),
+        sequence_end: sequenceOf(ordered[ordered.length - 1], registry),
+        root: `${DIGEST_PREFIX}${merkleRoot(leaves).toString('hex')}`,
+    };
+    return { ...unsigned, signature: signBytes(canonicalBytes(unsigned), registryPrivate) };
+}
+export function proofFor(receipts, receipt, registryId) {
+    const ordered = orderedRun(receipts, registryId, 'proofFor');
+    const index = ordered.findIndex((candidate) => candidate.id === receipt.id);
+    if (index < 0)
+        throw new Error('proofFor: receipt is not among the root leaves');
+    const leaves = ordered.map((candidate) => canonicalBytes(candidate));
+    return { sequence: sequenceOf(receipt, registryId), ...inclusionProof(leaves, index) };
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+// Like the merkle layer below it, this layer answers false for anything it
+// cannot make sense of. A verifier handed a hostile file reports a verdict,
+// never an exception.
+export function verifyRoot(doc, keys) {
+    const value = doc;
+    if (!isObject(value))
+        return false;
+    if (value.root_version !== ROOT_VERSION || typeof value.signature !== 'string')
+        return false;
+    const map = keys instanceof Map ? keys : keyMapFromJwks(keys);
+    const jkt = typeof value.registry === 'string' ? thumbprintOfId(value.registry, REGISTRY_ID_PREFIX) : undefined;
+    const key = jkt === undefined ? undefined : map.get(jkt);
+    if (!key)
+        return false;
+    try {
+        return verifyBytes(rootSigningInput(doc), value.signature, key);
+    }
+    catch {
+        return false;
+    }
+}
+export function verifyRootInclusion(receipt, proof, doc) {
+    const document = doc;
+    const claim = proof;
+    if (!isObject(document) || !isObject(claim) || !isObject(receipt))
+        return false;
+    // Inclusion alone says nothing: a tree the caller has not checked the
+    // signature of, or one built by another registry, would otherwise answer
+    // true on its own. verifyRoot is still required; this binds the two.
+    if (document.root_version !== ROOT_VERSION)
+        return false;
+    if (typeof document.root !== 'string' || !document.root.startsWith(DIGEST_PREFIX))
+        return false;
+    if (typeof document.registry !== 'string')
+        return false;
+    // A sequence starts at 1. Without the lower bound a root claiming to start
+    // at 0 or below shifts every index, and the arithmetic below still lines up.
+    if (!Number.isSafeInteger(document.sequence_start) || !Number.isSafeInteger(document.sequence_end))
+        return false;
+    const start = document.sequence_start;
+    const end = document.sequence_end;
+    if (start < 1 || end < start)
+        return false;
+    const entry = registrySignatureFor(receipt, document.registry);
+    if (!entry || !Number.isInteger(claim.sequence) || entry.sequence !== claim.sequence)
+        return false;
+    if (claim.size !== end - start + 1)
+        return false;
+    if (claim.index !== claim.sequence - start)
+        return false;
+    try {
+        return verifyInclusion(canonicalBytes(receipt), proof, document.root.slice(DIGEST_PREFIX.length));
+    }
+    catch {
+        return false;
+    }
+}

package/dist/signature.d.ts

@@ -0,0 +1,3 @@
+import { type PrivateJwk, type PublicJwk } from './keys.ts';
+export declare function signBytes(data: Uint8Array, privateJwk: PrivateJwk): string;
+export declare function verifyBytes(data: Uint8Array, signature: string, publicJwk: PublicJwk): boolean;

package/dist/signature.js

@@ -0,0 +1,22 @@
+import { sign as cryptoSign, verify as cryptoVerify } from 'node:crypto';
+import { privateKeyFromJwk, publicKeyFromJwk } from "./keys.js";
+export function signBytes(data, privateJwk) {
+    return Buffer.from(cryptoSign(null, data, privateKeyFromJwk(privateJwk))).toString('base64url');
+}
+// An Ed25519 signature is 64 bytes, which is exactly 86 base64url characters
+// with no padding. Buffer.from would also swallow standard base64, padding,
+// and trailing garbage, so one encoding is accepted and no other.
+const SIGNATURE_PATTERN = /^[A-Za-z0-9_-]{86}$/;
+export function verifyBytes(data, signature, publicJwk) {
+    try {
+        if (typeof signature !== 'string' || !SIGNATURE_PATTERN.test(signature))
+            return false;
+        const raw = Buffer.from(signature, 'base64url');
+        if (raw.length !== 64)
+            return false;
+        return cryptoVerify(null, data, publicKeyFromJwk(publicJwk), raw);
+    }
+    catch {
+        return false;
+    }
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@ageprotocol/receipts",
+  "version": "0.1.0",
+  "description": "AGE Protocol v0.1: signed, verifiable receipts for work performed by AI agents",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HS0055/age-protocol.git",
+    "directory": "packages/receipts"
+  },
+  "homepage": "https://github.com/HS0055/age-protocol#readme",
+  "bugs": {
+    "url": "https://github.com/HS0055/age-protocol/issues"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "engines": {
+    "node": ">=22.18"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "age",
+    "age-protocol",
+    "receipts",
+    "ed25519",
+    "rfc8785",
+    "provenance",
+    "ai-agents",
+    "verification"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "test": "node --test test/*.test.ts",
+    "typecheck": "tsc -p tsconfig.json"
+  }
+}