attention-manifest-protocol 0.4.0 → 0.4.2

package/lib/manifest/cardSign.js

@@ -0,0 +1,70 @@
+import { canonical } from "../semantic/canonical.js";
+const encoder = new TextEncoder();
+function toBase64Url(bytes) {
+    const view = new Uint8Array(bytes);
+    let binary = "";
+    for (const byte of view) {
+        binary += String.fromCharCode(byte);
+    }
+    return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function fromBase64Url(text) {
+    const padded = text.replace(/-/g, "+").replace(/_/g, "/");
+    const pad = padded.length % 4 ? "=".repeat(4 - (padded.length % 4)) : "";
+    const binary = atob(padded + pad);
+    return Uint8Array.from(binary, (char) => char.charCodeAt(0));
+}
+function payloadOf(card) {
+    const { ...rest } = card;
+    delete rest.signatures;
+    return encoder.encode(canonical(rest));
+}
+function signingInput(protectedHeader, payload) {
+    const encoded = toBase64Url(payload);
+    return encoder.encode(`${protectedHeader}.${encoded}`);
+}
+export async function signCard(card, key) {
+    const protectedHeader = toBase64Url(encoder.encode(JSON.stringify({ alg: "EdDSA", kid: key.kid })));
+    const payload = payloadOf(card);
+    const signature = await crypto.subtle.sign("Ed25519", key.privateKey, signingInput(protectedHeader, payload));
+    return { protected: protectedHeader, signature: toBase64Url(signature) };
+}
+export async function verifyCardSignature(card, signature, publicKey) {
+    const reasons = [];
+    let header;
+    try {
+        header = JSON.parse(new TextDecoder().decode(fromBase64Url(signature.protected)));
+    }
+    catch {
+        return { ok: false, reasons: ["protected header is not base64url JSON"] };
+    }
+    if (header.alg !== "EdDSA") {
+        reasons.push(`unsupported alg ${`${header.alg}`}`);
+    }
+    const valid = await crypto.subtle.verify("Ed25519", publicKey, fromBase64Url(signature.signature), signingInput(signature.protected, payloadOf(card)));
+    if (!valid) {
+        reasons.push("card signature does not verify");
+    }
+    return { ok: reasons.length === 0, reasons };
+}
+/**
+ * Resolves the signing key from a trust registry (which Federation bundles can
+ * populate) instead of trusting a key embedded in the card itself.
+ */
+export async function verifyCardWithRegistry(card, signature, registry) {
+    let header;
+    try {
+        header = JSON.parse(new TextDecoder().decode(fromBase64Url(signature.protected)));
+    }
+    catch {
+        return { ok: false, reasons: ["protected header is not base64url JSON"] };
+    }
+    if (!header.kid) {
+        return { ok: false, reasons: ["signature carries no kid"] };
+    }
+    const key = registry.get(header.kid);
+    if (!key) {
+        return { ok: false, reasons: [`unknown or revoked key: ${header.kid}`] };
+    }
+    return verifyCardSignature(card, signature, key);
+}

package/lib/manifest/federation.d.ts

@@ -0,0 +1,64 @@
+import type { Digest, Id, Ref, Timestamp } from "../types/common.js";
+import type { Attestation, ManifestBundle } from "./federationTypes.js";
+import type { Manifest } from "./manifest.js";
+import { KeyRegistry } from "./sign.js";
+import type { KeyPair } from "./sign.js";
+/**
+ * Digest covers manifest + keys + revocation + validity window.
+ */
+export declare function bundleDigest(bundle: Omit<ManifestBundle, "digest" | "attestations">): Digest;
+export declare function exportBundle(manifest: Manifest, key: KeyPair, options: {
+    issued: Timestamp;
+    expires: Timestamp;
+    revoked?: string[];
+    attestations?: Attestation[];
+}): Promise<ManifestBundle>;
+export interface ImportResult {
+    ok: boolean;
+    reasons: string[];
+    manifest?: Manifest;
+    /**
+     * True only when an endorsement's subject binds to the manifest digest AND
+     * its Ed25519 signature verifies against a caller-supplied issuer key.
+     * Without `issuerKeys`, no attestation can be endorsed.
+     */
+    attested: boolean;
+    attestations: Id[];
+}
+/**
+ * Fails closed. Every check must pass before the manifest is used;
+ * the only permitted degradation is "not endorsed", never "less verified".
+ *
+ * `issuerKeys` is the caller's trust root for third-party attestations. The
+ * bundle carries the manifest signer's keys, not the issuer's, so an
+ * attestation is never trusted just because it is inside the bundle.
+ */
+export declare function importBundle(bundle: ManifestBundle, options: {
+    now: Timestamp;
+    revoked?: string[];
+    issuerKeys?: KeyRegistry;
+}): Promise<ImportResult>;
+/**
+ * Imports a bundle's keys into a registry; revoked kids stay revoked.
+ */
+export declare function registryFromBundle(bundle: ManifestBundle): Promise<KeyRegistry>;
+export declare function attest(input: {
+    id: Id;
+    issuer: Ref;
+    manifest: Manifest;
+    scope: string[];
+    issued: Timestamp;
+    expires: Timestamp;
+    key: KeyPair;
+}): Promise<Attestation>;
+export declare function verifyAttestation(attestation: Attestation, issuerKey: KeyPair): Promise<{
+    ok: boolean;
+    reasons: string[];
+}>;
+/**
+ * Public-key variant so a verifier does not need the issuer's private key.
+ */
+export declare function verifyAttestationWithKey(attestation: Attestation, publicKey: CryptoKey): Promise<{
+    ok: boolean;
+    reasons: string[];
+}>;

package/lib/manifest/federation.js

@@ -0,0 +1,187 @@
+import { canonical, digestOf } from "../semantic/canonical.js";
+import { KeyRegistry } from "./sign.js";
+import { verifyManifest } from "./sign.js";
+import { checkManifestWindow } from "./keys.js";
+const encoder = new TextEncoder();
+const SKEW_MS = 5 * 60_000;
+function toBase64Url(bytes) {
+    const view = new Uint8Array(bytes);
+    let binary = "";
+    for (const byte of view) {
+        binary += String.fromCharCode(byte);
+    }
+    return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function fromBase64Url(text) {
+    const padded = text.replace(/-/g, "+").replace(/_/g, "/");
+    const pad = padded.length % 4 ? "=".repeat(4 - (padded.length % 4)) : "";
+    const binary = atob(padded + pad);
+    return Uint8Array.from(binary, (char) => char.charCodeAt(0));
+}
+async function exportKeyMaterial(key) {
+    const raw = await crypto.subtle.exportKey("raw", key.publicKey);
+    return { kid: key.kid, alg: "ed25519", publicKey: toBase64Url(raw) };
+}
+async function importPublicKey(material) {
+    return crypto.subtle.importKey("raw", fromBase64Url(material.publicKey), { name: "Ed25519" }, true, ["verify"]);
+}
+/* ------------------------------- bundle ------------------------------- */
+/**
+ * Digest covers manifest + keys + revocation + validity window.
+ */
+export function bundleDigest(bundle) {
+    return digestOf({
+        manifest: bundle.manifest,
+        keys: bundle.keys,
+        revoked: bundle.revoked ?? [],
+        issued: bundle.issued,
+        expires: bundle.expires,
+    });
+}
+export async function exportBundle(manifest, key, options) {
+    const base = {
+        amp: "0.1",
+        kind: "bundle",
+        manifest,
+        keys: [await exportKeyMaterial(key)],
+        revoked: options.revoked ?? [],
+        issued: options.issued,
+        expires: options.expires,
+    };
+    return { ...base, digest: bundleDigest(base), attestations: options.attestations };
+}
+/**
+ * Fails closed. Every check must pass before the manifest is used;
+ * the only permitted degradation is "not endorsed", never "less verified".
+ *
+ * `issuerKeys` is the caller's trust root for third-party attestations. The
+ * bundle carries the manifest signer's keys, not the issuer's, so an
+ * attestation is never trusted just because it is inside the bundle.
+ */
+export async function importBundle(bundle, options) {
+    const reasons = [];
+    const { digest, attestations, ...rest } = bundle;
+    if (bundleDigest(rest) !== digest) {
+        reasons.push("bundle digest does not cover its content");
+    }
+    const now = Date.parse(options.now);
+    if (!Number.isFinite(now)) {
+        reasons.push("now is not a valid timestamp");
+    }
+    if (Date.parse(bundle.expires) + SKEW_MS < now) {
+        reasons.push("bundle expired");
+    }
+    if (Date.parse(bundle.issued) - SKEW_MS > now) {
+        reasons.push("bundle issued in the future");
+    }
+    const window = checkManifestWindow(bundle.manifest, options.now, SKEW_MS);
+    for (const reason of window.reasons) {
+        reasons.push(`manifest ${reason}`);
+    }
+    const signature = bundle.manifest.signatures.find((entry) => entry.role === "self");
+    if (!signature) {
+        reasons.push("manifest has no self signature");
+    }
+    const key = signature ? bundle.keys.find((material) => material.kid === signature.kid) : undefined;
+    if (signature && !key) {
+        reasons.push(`missing key for kid ${signature.kid}`);
+    }
+    const revoked = new Set([...(bundle.revoked ?? []), ...(options.revoked ?? [])]);
+    if (signature && revoked.has(signature.kid)) {
+        reasons.push(`key revoked: ${signature.kid}`);
+    }
+    if (signature && key) {
+        try {
+            const publicKey = await importPublicKey(key);
+            const verification = await verifyManifest(bundle.manifest, publicKey);
+            for (const reason of verification.reasons) {
+                reasons.push(reason);
+            }
+        }
+        catch {
+            reasons.push("public key cannot be imported");
+        }
+    }
+    const endorsed = [];
+    for (const attestation of attestations ?? []) {
+        if (attestation.subject.digest !== bundle.manifest.digest) {
+            continue;
+        }
+        if (!Number.isFinite(Date.parse(attestation.expires))) {
+            continue;
+        }
+        if (Date.parse(attestation.expires) + SKEW_MS < now) {
+            continue;
+        }
+        if (Date.parse(attestation.issued) - SKEW_MS > now) {
+            continue;
+        }
+        const issuerKid = attestation.signatures[0]?.kid;
+        const issuerKey = issuerKid ? options.issuerKeys?.get(issuerKid) : undefined;
+        if (!issuerKey) {
+            continue;
+        }
+        const verdict = await verifyAttestationWithKey(attestation, issuerKey);
+        if (!verdict.ok) {
+            continue;
+        }
+        endorsed.push(attestation.id);
+    }
+    return {
+        ok: reasons.length === 0,
+        reasons,
+        manifest: reasons.length === 0 ? bundle.manifest : undefined,
+        attested: endorsed.length > 0,
+        attestations: endorsed,
+    };
+}
+/**
+ * Imports a bundle's keys into a registry; revoked kids stay revoked.
+ */
+export async function registryFromBundle(bundle) {
+    const registry = new KeyRegistry();
+    for (const material of bundle.keys) {
+        registry.add(material.kid, await importPublicKey(material));
+    }
+    for (const kid of bundle.revoked ?? []) {
+        registry.revoke(kid);
+    }
+    return registry;
+}
+/* ----------------------------- attestation ---------------------------- */
+export async function attest(input) {
+    const body = {
+        amp: "0.1",
+        kind: "attestation",
+        id: input.id,
+        issuer: input.issuer,
+        subject: {
+            kind: "manifest",
+            id: input.manifest.agent.id,
+            digest: input.manifest.digest,
+        },
+        scope: input.scope,
+        issued: input.issued,
+        expires: input.expires,
+    };
+    const signature = await crypto.subtle.sign("Ed25519", input.key.privateKey, encoder.encode(canonical(body)));
+    return {
+        ...body,
+        signatures: [{ role: "org", alg: "ed25519", kid: input.key.kid, sig: toBase64Url(signature) }],
+    };
+}
+export async function verifyAttestation(attestation, issuerKey) {
+    return verifyAttestationWithKey(attestation, issuerKey.publicKey);
+}
+/**
+ * Public-key variant so a verifier does not need the issuer's private key.
+ */
+export async function verifyAttestationWithKey(attestation, publicKey) {
+    const { signatures, ...body } = attestation;
+    const signature = signatures[0];
+    if (!signature) {
+        return { ok: false, reasons: ["attestation has no signature"] };
+    }
+    const valid = await crypto.subtle.verify("Ed25519", publicKey, fromBase64Url(signature.sig), encoder.encode(canonical(body)));
+    return { ok: valid, reasons: valid ? [] : ["attestation signature does not verify"] };
+}

package/lib/manifest/federationTypes.d.ts

@@ -0,0 +1,51 @@
+/**
+ * AMP v0.1 — Federation Profile: bundles and third-party attestations.
+ * Mirrors docs/schemas/federation.schema.json.
+ */
+import type { Digest, Id, Ref, Signature, Timestamp } from "../types/common.js";
+import type { Manifest } from "./manifest.js";
+export interface KeyMaterial {
+    kid: string;
+    alg: "ed25519";
+    /**
+     * base64url raw public key.
+     */
+    publicKey: string;
+}
+/**
+ * A bundle is a transport shape, not a new trust root: the manifest inside is
+ * already signed, and the keys are the minimum needed to check it.
+ */
+export interface ManifestBundle {
+    amp: "0.1";
+    kind: "bundle";
+    manifest: Manifest;
+    keys: KeyMaterial[];
+    /**
+     * Keys the issuing domain has revoked; the receiver still merges its own list.
+     */
+    revoked?: string[];
+    issued: Timestamp;
+    expires: Timestamp;
+    digest: Digest;
+    attestations?: Attestation[];
+}
+export interface AttestationSubject {
+    kind: "manifest";
+    id: Id;
+    /**
+     * Bound to bytes, not to a name or version.
+     */
+    digest: Digest;
+}
+export interface Attestation {
+    amp: "0.1";
+    kind: "attestation";
+    id: Id;
+    issuer: Ref;
+    subject: AttestationSubject;
+    scope: string[];
+    issued: Timestamp;
+    expires: Timestamp;
+    signatures: Signature[];
+}

package/lib/manifest/federationTypes.js

@@ -0,0 +1 @@
+export {};

package/lib/manifest/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./agentCard.js";
+export * from "./cardSign.js";
+export * from "./federation.js";
+export * from "./federationTypes.js";
+export * from "./keys.js";
+export * from "./manifest.js";
+export * from "./sign.js";
+export * from "./trust.js";

package/lib/manifest/index.js

@@ -0,0 +1,8 @@
+export * from "./agentCard.js";
+export * from "./cardSign.js";
+export * from "./federation.js";
+export * from "./federationTypes.js";
+export * from "./keys.js";
+export * from "./manifest.js";
+export * from "./sign.js";
+export * from "./trust.js";

package/lib/manifest/keys.d.ts

@@ -0,0 +1,221 @@
+/**
+ * AMP v0.1 — key lifecycle: validity windows, rotation, retirement and
+ * revocation.
+ *
+ * This layer is deliberately independent of the envelope and federation
+ * formats. It stores public keys and lifecycle metadata only; it never signs
+ * or verifies a revocation list. A caller must authenticate a list's
+ * `issuer` signature against its own trust root before merging it or acting
+ * on its entries.
+ */
+import type { Id, Timestamp } from "../types/common.js";
+import type { Manifest } from "./manifest.js";
+/**
+ * Lifecycle state: active keys are current, retired keys only verify history.
+ */
+export type KeyStatus = "active" | "retired" | "revoked";
+/**
+ * A public key plus the lifecycle metadata needed to judge it at a time.
+ */
+export interface KeyRecord {
+    kid: Id;
+    publicKey: CryptoKey;
+    status: KeyStatus;
+    validFrom: Timestamp;
+    validTo?: Timestamp;
+    /**
+     * Kid this key replaced, when it was introduced by a rotation.
+     */
+    supersedes?: Id;
+    /**
+     * Free-form audit note; this module never interprets it.
+     */
+    note?: string;
+}
+/**
+ * One kid revoked by an issuer, at a time and for an optional reason.
+ */
+export interface RevocationEntry {
+    kid: Id;
+    revokedAt: Timestamp;
+    reason?: string;
+}
+/**
+ * A signed-by-the-caller revocation snapshot. This module only compares and
+ * merges the data; it does not verify the `issuer` signature.
+ */
+export interface RevocationList {
+    issuer: string;
+    issued: Timestamp;
+    nextUpdate: Timestamp;
+    revoked: RevocationEntry[];
+}
+/**
+ * Optional clock and skew policy for a `Keyring`.
+ */
+export interface KeyringOptions {
+    /**
+     * Clock used when an operation is not given an explicit timestamp.
+     */
+    now?: () => Timestamp;
+    /**
+     * Symmetric tolerance around validity windows, in milliseconds. Defaults
+     * to 0 so a key is only usable inside the window its issuer declared.
+     */
+    clockSkewMs?: number;
+}
+/**
+ * Successor key supplied to `Keyring.rotate()`.
+ */
+type KeyRotation = {
+    kid: Id;
+    publicKey: CryptoKey;
+    validFrom?: Timestamp;
+    overlapMs?: number;
+};
+/**
+ * Validity verdict: `ok` plus one human-readable reason per failed check.
+ */
+type WindowVerdict = {
+    ok: boolean;
+    reasons: string[];
+};
+/**
+ * In-memory public-key lifecycle store.
+ *
+ * A record is usable while its status is `active` or `retired` and `at` lies
+ * inside its validity window. Revocation is permanent and wins over every
+ * window: a historical timestamp cannot resurrect a revoked key. Retired
+ * records are retained so signatures made before rotation stay verifiable.
+ */
+export declare class Keyring {
+    private readonly records;
+    private readonly revocationByKid;
+    private readonly clock;
+    private readonly clockSkewMs;
+    constructor(options?: KeyringOptions);
+    /**
+     * Adds a key record. Throws on a duplicate kid, a malformed timestamp, or
+     * a window whose `validTo` is not strictly after `validFrom`.
+     *
+     * A record supplied already `revoked` is registered as revoked at its
+     * `validFrom` (using the note as the reason), so it is never usable. Use
+     * `revoke()` to record a later revocation time.
+     */
+    add(record: KeyRecord): void;
+    /**
+     * Rotates from `currentKid` to `next`.
+     *
+     * The current record becomes `retired` and remains available for historical
+     * timestamps. It stops being usable after the overlap, which ends at
+     * `now + overlapMs` (or at `now` when omitted), capped by the current key's
+     * existing `validTo` so rotation never extends a lifetime the issuer
+     * already bounded. The successor starts at `next.validFrom` (default now)
+     * and records `supersedes: currentKid`.
+     *
+     * Throws for an unknown, retired or revoked current key, a duplicate next
+     * kid, or a negative/non-finite overlap.
+     */
+    rotate(currentKid: Id, next: KeyRotation): KeyRecord;
+    /**
+     * Revokes a key permanently, returning `false` when the kid is unknown or
+     * was already revoked. The record is kept for audit, and the revocation
+     * takes precedence over every validity window and overlap.
+     */
+    revoke(kid: Id, at?: Timestamp, reason?: string): boolean;
+    /**
+     * Retires an active key at `at` (default now), returning `false` when the
+     * key is unknown, already retired or revoked. The key remains usable for
+     * timestamps before `at` but not after it. Retirement never extends an
+     * existing `validTo`.
+     */
+    retire(kid: Id, at?: Timestamp): boolean;
+    /**
+     * Returns the public key usable at `at` (default now). Revoked keys always
+     * return `undefined`; active and retired keys return `undefined` outside
+     * their validity window. A non-zero `clockSkewMs` widens both edges.
+     */
+    get(kid: Id, at?: Timestamp): CryptoKey | undefined;
+    /**
+     * Returns a copy of the lifecycle record, including retired/revoked history.
+     */
+    record(kid: Id): KeyRecord | undefined;
+    /**
+     * Lists active (not retired or revoked) records usable at `at` (default now).
+     */
+    active(at?: Timestamp): KeyRecord[];
+    /**
+     * True when the kid was revoked; unknown kids are not revoked.
+     */
+    isRevoked(kid: Id): boolean;
+    /**
+     * Explains whether `at` is inside the key's usable window. Missing,
+     * revoked, not-yet-valid and expired keys produce `ok: false` with reasons.
+     */
+    verifyWindow(kid: Id, at: Timestamp): WindowVerdict;
+    /**
+     * Revocations in deterministic order (earliest first, then kid). Entries
+     * are copies; mutating the result does not change the keyring.
+     */
+    revocations(): ReadonlyArray<RevocationEntry>;
+    private contains;
+}
+/**
+ * Thrown by `requireFresh()` when a revocation list cannot be trusted as current.
+ */
+export declare class RevocationError extends Error {
+    /**
+     * Machine-readable reasons the list was rejected.
+     */
+    readonly reasons: string[];
+    constructor(message: string, reasons?: string[]);
+}
+/**
+ * Shape of the revocation freshness checks.
+ */
+type RevocationFreshnessCheck<T> = (list: RevocationList, now: Timestamp, maxStalenessMs: number) => T;
+/**
+ * Freshness verdict for a revocation list.
+ *
+ * Returns `false` for malformed top-level or entry timestamps, a list whose
+ * `nextUpdate` precedes `issued`, an `issued` timestamp in the future, or a
+ * list older than `nextUpdate + maxStalenessMs`. There is no skew parameter:
+ * a verifier should pass a clock reading it is willing to defend.
+ */
+export declare const isRevocationFresh: RevocationFreshnessCheck<boolean>;
+/**
+ * Returns `list` when fresh; otherwise throws a `RevocationError` with reasons.
+ */
+export declare const requireFresh: RevocationFreshnessCheck<RevocationList>;
+/**
+ * The manifest window judged by `checkManifestWindow()`.
+ */
+type ManifestWindow = Pick<Manifest, "issued" | "expires">;
+/**
+ * Shape of `checkManifestWindow()`.
+ */
+type ManifestWindowCheck = (manifest: ManifestWindow, now: Timestamp, skewMs?: number) => WindowVerdict;
+/**
+ * Checks a manifest's own validity window. `issued` may be up to `skewMs`
+ * ahead of `now`, and `expires` up to `skewMs` behind it; the default
+ * tolerance is five minutes, matching federation import. Malformed dates and
+ * `expires <= issued` are rejected.
+ */
+export declare const checkManifestWindow: ManifestWindowCheck;
+/**
+ * Shape of `mergeRevocations()`.
+ */
+type RevocationMerger = (local: RevocationList, remote: RevocationList) => RevocationList;
+/**
+ * Merges two authenticated revocation lists from the same issuer.
+ *
+ * The union keeps the earliest `revokedAt` per kid, chooses the latest
+ * `issued` and `nextUpdate`, and sorts by `revokedAt` then kid, so the result
+ * does not depend on argument order or on repeated merges. Different issuers
+ * throw: a single list must answer to one signature.
+ *
+ * This function performs no signature verification. Authenticate both lists
+ * (and their issuer) first; never merge untrusted snapshots.
+ */
+export declare const mergeRevocations: RevocationMerger;
+export {};