attention-manifest-protocol 0.4.2 → 0.4.3

package/lib/hook/types.js

@@ -0,0 +1,407 @@
+/**
+ * Hook layer contracts for the agent workspace.
+ *
+ * A hook is the composition layer between a host/UI and one bound filesystem
+ * session. It owns three things that a raw service call does not:
+ *
+ * - a small observable state machine (`idle`/`loading`/`ready`/`error`) so a
+ *   caller can render progress without inventing its own flags;
+ * - a run journal (`HookRunEntry`) that is persisted through an injected
+ *   `HookRecorder`, which is how the SQLite `hook_runs` table is fed;
+ * - an optional bounded cache keyed by the canonical request, so a read whose
+ *   request is unchanged can avoid repeating the work.
+ *
+ * The layer is deliberately read-heavy: every hook except `useWrite` delegates
+ * to a read-only session method. `useWrite` is the single mutating hook and it
+ * forwards one `WriteRequest` to `FilesystemSession.write`; it never writes on
+ * its own and it disables the cache, because replaying a mutation from cache
+ * would make "write once" indistinguishable from "do nothing".
+ */
+import { Buffer } from "node:buffer";
+import { createHash } from "node:crypto";
+import { isFilesystemError } from "../file/errors.js";
+import { canonical, digestOf } from "../semantic/canonical.js";
+import { isSessionError } from "../session/errors.js";
+import { LRUOrderedMap } from "../structure/lru.js";
+/**
+ * Default cache capacity and its hard ceiling. A hook result can be a whole
+ * outline, so the default is intentionally small.
+ */
+const DefaultCacheEntries = 32;
+const MaxCacheEntries = 256;
+/**
+ * Convert an arbitrary request/output into a value `digestOf` can canonicalise.
+ *
+ * `canonical` rejects `bigint`, `Uint8Array` and `undefined`, all of which
+ * occur in filesystem results and write requests. The conversion is for audit
+ * only: it must be deterministic, not reversible.
+ */
+const digestable = (value) => {
+    if (value === null) {
+        return null;
+    }
+    const kind = typeof (value);
+    if (kind === "string" || kind === "number" || kind === "boolean") {
+        return value;
+    }
+    if (kind === "bigint") {
+        return `${value}`;
+    }
+    if (value === (void 0)) {
+        return null;
+    }
+    if (value instanceof Uint8Array) {
+        return { encoding: "base64", bytes: Buffer.from(value).toString("base64") };
+    }
+    if (Array.isArray(value)) {
+        return value.map((entry) => digestable(entry));
+    }
+    if (kind === "object") {
+        const source = value;
+        const target = {};
+        const keys = Object.keys(source);
+        for (let index = 0; index < keys.length; index += 1) {
+            const key = keys[index];
+            const entry = source[key];
+            if (entry === (void 0)) {
+                continue;
+            }
+            target[key] = digestable(entry);
+        }
+        return target;
+    }
+    return "<unsupported>";
+};
+/**
+ * Digest of an arbitrary value, falling back to a constant when a caller passes
+ * something canonical JSON cannot express. The fallback keeps the run entry
+ * well-formed instead of failing the operation it is supposed to audit.
+ */
+const safeDigest = (value) => {
+    try {
+        return digestOf(digestable(value));
+    }
+    catch {
+        return digestOf({ digest: "unavailable" });
+    }
+};
+/**
+ * SHA-256 of the canonical request, used as the cache key. An uncanonicalisable
+ * request yields an empty key, which the runtime treats as "do not cache".
+ */
+const cacheKeyOf = (request) => {
+    try {
+        const text = canonical(digestable(request));
+        return createHash("sha256").update(text, "utf8").digest("hex");
+    }
+    catch {
+        return "";
+    }
+};
+/**
+ * Translate an unknown thrown value into the closed hook error surface.
+ */
+const mapHookError = (error) => {
+    if (isFilesystemError(error)) {
+        return error.code;
+    }
+    if (isSessionError(error)) {
+        if (error.code === "invalid_arguments") {
+            return "invalid_arguments";
+        }
+        if (error.code === "invalid_identity" || error.code === "session_forbidden") {
+            return "permission_denied";
+        }
+        return "session_unavailable";
+    }
+    if (error instanceof TypeError || error instanceof RangeError) {
+        return "invalid_arguments";
+    }
+    return "internal_error";
+};
+/**
+ * Clamp `maxCacheEntries` into a positive bound.
+ */
+const cacheCapacity = (value) => {
+    if (value === (void 0) || !Number.isSafeInteger(value) || value < 1) {
+        return DefaultCacheEntries;
+    }
+    return Math.min(value, MaxCacheEntries);
+};
+/**
+ * Concrete hook runtime. Kept private so the public surface is the `Hook`
+ * interface and the `createHook` factory.
+ *
+ * @typeParam TRequest - Request accepted by `run`.
+ * @typeParam TResult - Value produced by a successful run.
+ */
+class HookRuntime {
+    definition;
+    recorder;
+    cache;
+    listeners = new Set();
+    current;
+    generation = 0;
+    /**
+     * Create one runtime from a definition.
+     *
+     * @param definition - Name, session, executor and options.
+     */
+    constructor(definition) {
+        const options = definition.options ?? {};
+        this.definition = definition;
+        this.recorder = options.recorder;
+        this.cache =
+            options.cache === true
+                ? new LRUOrderedMap(cacheCapacity(options.maxCacheEntries))
+                : (void 0);
+        this.current = Object.freeze({ status: "idle", revision: "" });
+    }
+    /**
+     * Current observable state.
+     */
+    get state() {
+        return this.current;
+    }
+    /**
+     * Run one request. The state moves to `loading` synchronously and the
+     * executor starts on the next microtask, so a caller that renders after
+     * calling `run` can observe the loading state even for a synchronous
+     * service method.
+     *
+     * A newer run (or a `reset`) increments the generation; an older run that
+     * finishes later still records and returns its own state but does not
+     * overwrite the newer observable state.
+     *
+     * @param request - Hook request.
+     * @returns The state produced by this run.
+     */
+    async run(request) {
+        const started = new Date();
+        const generation = this.generation + 1;
+        this.generation = generation;
+        this.update({ status: "loading", revision: this.current.revision });
+        const inputDigest = safeDigest(request);
+        const path = this.pathOf(request);
+        const cacheKey = this.cache === (void 0) ? "" : cacheKeyOf(request);
+        const cached = this.cachedFor(cacheKey);
+        await Promise.resolve();
+        if (cached !== (void 0)) {
+            const next = { status: "ready", value: cached.value, revision: cached.revision };
+            if (generation === this.generation) {
+                this.update(next);
+            }
+            this.emit({
+                hook: this.definition.name,
+                sessionId: this.definition.session.sessionId,
+                ...(path === (void 0) ? {} : { path }),
+                status: "ready",
+                revision: next.revision,
+                startedAt: started.toISOString(),
+                durationMs: Date.now() - started.getTime(),
+                inputDigest,
+                outputDigest: safeDigest(cached.value),
+            });
+            return next;
+        }
+        try {
+            const value = await this.definition.execute(request);
+            const revision = this.revisionFor(value);
+            const next = { status: "ready", value, revision };
+            if (generation === this.generation) {
+                if (this.cache !== (void 0) && cacheKey.length > 0) {
+                    this.cache.set(cacheKey, { value, revision });
+                }
+                this.update(next);
+            }
+            this.emit({
+                hook: this.definition.name,
+                sessionId: this.definition.session.sessionId,
+                ...(path === (void 0) ? {} : { path }),
+                status: "ready",
+                revision,
+                startedAt: started.toISOString(),
+                durationMs: Date.now() - started.getTime(),
+                inputDigest,
+                outputDigest: safeDigest(value),
+            });
+            return next;
+        }
+        catch (error) {
+            const code = mapHookError(error);
+            const revision = this.currentRevision();
+            const next = { status: "error", error: code, revision };
+            if (generation === this.generation) {
+                this.update(next);
+            }
+            this.emit({
+                hook: this.definition.name,
+                sessionId: this.definition.session.sessionId,
+                ...(path === (void 0) ? {} : { path }),
+                status: "error",
+                error: code,
+                revision,
+                startedAt: started.toISOString(),
+                durationMs: Date.now() - started.getTime(),
+                inputDigest,
+                outputDigest: "",
+            });
+            return next;
+        }
+    }
+    /**
+     * Subscribe to state changes. The listener is not invoked immediately; it
+     * receives every subsequent `loading`, `ready`, `error` and reset state.
+     *
+     * @param listener - Callback invoked with each new state.
+     * @returns Unsubscribe function.
+     */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    /**
+     * Return to `idle` and drop cached values. The last revision is retained so
+     * a view that resets does not lose its workspace coordinate. In-flight runs
+     * are invalidated so they cannot overwrite the idle state.
+     */
+    reset() {
+        this.generation += 1;
+        if (this.cache !== (void 0)) {
+            this.cache.clear();
+        }
+        this.update({ status: "idle", revision: this.current.revision });
+    }
+    /**
+     * Read a cached result only when it was produced at the current workspace
+     * revision. The request-only cache key cannot see a file change by itself,
+     * so the revision is the freshness check that makes `cache: true` safe for
+     * read hooks.
+     *
+     * @param cacheKey - Canonical request key.
+     * @returns Cached result, or `undefined` when absent or stale.
+     */
+    cachedFor(cacheKey) {
+        if (this.cache === (void 0) || cacheKey.length === 0) {
+            return (void 0);
+        }
+        const entry = this.cache.peek(cacheKey);
+        if (entry === (void 0)) {
+            return (void 0);
+        }
+        const revision = this.sessionRevision();
+        if (revision === (void 0) || revision.length === 0 || entry.revision !== revision) {
+            this.cache.delete(cacheKey);
+            return (void 0);
+        }
+        return this.cache.get(cacheKey);
+    }
+    /**
+     * Revision reported by the bound session, or `undefined` when the session
+     * cannot answer (revoked, expired, store failure). A cache hit is never
+     * trusted without this value.
+     *
+     * @returns Current workspace revision, or `undefined`.
+     */
+    sessionRevision() {
+        try {
+            return this.definition.session.revision();
+        }
+        catch {
+            return (void 0);
+        }
+    }
+    /**
+     * Last known revision from the bound session, falling back to the state.
+     */
+    currentRevision() {
+        const revision = this.sessionRevision();
+        return revision === (void 0) || revision.length === 0 ? this.current.revision : revision;
+    }
+    /**
+     * Revision reported for a successful value.
+     *
+     * @param value - Successful hook output.
+     * @returns Result revision or the session revision.
+     */
+    revisionFor(value) {
+        const revisionOf = this.definition.revisionOf;
+        if (revisionOf === (void 0)) {
+            return this.currentRevision();
+        }
+        try {
+            return revisionOf(value);
+        }
+        catch {
+            return this.currentRevision();
+        }
+    }
+    /**
+     * Optional request path for the run journal.
+     *
+     * @param request - Hook request.
+     * @returns Path, or `undefined` when the request has none.
+     */
+    pathOf(request) {
+        const pathOf = this.definition.pathOf;
+        if (pathOf === (void 0)) {
+            return (void 0);
+        }
+        try {
+            return pathOf(request);
+        }
+        catch {
+            return (void 0);
+        }
+    }
+    /**
+     * Publish one state to every subscriber. A listener that throws is skipped
+     * so one broken view cannot stop the others from updating.
+     *
+     * @param next - New state.
+     */
+    update(next) {
+        const frozen = Object.freeze(next);
+        this.current = frozen;
+        const listeners = [...this.listeners];
+        for (let index = 0; index < listeners.length; index += 1) {
+            try {
+                listeners[index](frozen);
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    /**
+     * Forward one entry to the recorder; an audit failure is swallowed by
+     * contract and never changes the hook result.
+     *
+     * @param entry - Run entry.
+     */
+    emit(entry) {
+        const recorder = this.recorder;
+        if (recorder === (void 0)) {
+            return;
+        }
+        try {
+            recorder.record(entry);
+        }
+        catch {
+            return;
+        }
+    }
+}
+/**
+ * Create one observable hook from a definition. This is the shared factory the
+ * concrete `use*` hooks are built on.
+ *
+ * @typeParam TRequest - Request accepted by `run`.
+ * @typeParam TResult - Value produced by a successful run.
+ * @param definition - Name, session, executor, optional revision/path mapping
+ * and options.
+ * @returns A hook with state, subscription, reset and bounded caching.
+ */
+export const createHook = (definition) => new HookRuntime(definition);

package/lib/index.d.ts

@@ -3,7 +3,16 @@
  * subpaths, for example `attention-manifest-protocol/governance`.
  */
 export * from "./attention/index.js";
+export * from "./assignment/index.js";
 export * from "./context/index.js";
+export * from "./discover/index.js";
+export * as file from "./file/index.js";
+export * as filesystem from "./file/index.js";
+export * as syntax from "./syntax/index.js";
+export * as outline from "./outline/index.js";
+export * as global from "./global/index.js";
+export * as hook from "./hook/index.js";
+export * as session from "./session/index.js";
 export * from "./frame/index.js";
 export * from "./ledger/index.js";
 export * from "./manifest/index.js";

package/lib/index.js

@@ -3,7 +3,16 @@
  * subpaths, for example `attention-manifest-protocol/governance`.
  */
 export * from "./attention/index.js";
+export * from "./assignment/index.js";
 export * from "./context/index.js";
+export * from "./discover/index.js";
+export * as file from "./file/index.js";
+export * as filesystem from "./file/index.js";
+export * as syntax from "./syntax/index.js";
+export * as outline from "./outline/index.js";
+export * as global from "./global/index.js";
+export * as hook from "./hook/index.js";
+export * as session from "./session/index.js";
 export * from "./frame/index.js";
 export * from "./ledger/index.js";
 export * from "./manifest/index.js";

package/lib/lock/lease.js

@@ -5,7 +5,25 @@ const toRecord = (row) => ({
     acquiredAt: row.acquired_at,
     expiresAt: row.expires_at,
 });
-const expiry = (at, ttlMs) => new Date(Date.parse(at) + ttlMs).toISOString();
+const expiry = (at, ttlMs) => {
+    const timestamp = Date.parse(at);
+    if (!Number.isFinite(timestamp)) {
+        throw new RangeError("at must be a valid timestamp");
+    }
+    if (!Number.isSafeInteger(ttlMs) || ttlMs <= 0) {
+        throw new RangeError("ttlMs must be a positive safe integer");
+    }
+    const expires = timestamp + ttlMs;
+    if (!Number.isFinite(expires) || Math.abs(expires) > 8.64e15) {
+        throw new RangeError("lease expiry is outside the supported date range");
+    }
+    return new Date(expires).toISOString();
+};
+const assertLeaseIdentity = (name, holder) => {
+    if (name.trim().length === 0 || holder.trim().length === 0) {
+        throw new TypeError("lock name and holder must not be empty");
+    }
+};
 export const getLock = (db, name) => {
     const row = db.prepare("SELECT * FROM resource_locks WHERE name = ?").get(name);
     return row === (void 0) ? undefined : toRecord(row);
@@ -15,6 +33,8 @@ export const getLock = (db, name) => {
  * Returns `undefined` when another holder owns a live lease.
  */
 export const acquireLock = (db, name, holder, at, ttlMs = 15_000) => {
+    assertLeaseIdentity(name, holder);
+    const expiresAt = expiry(at, ttlMs);
     const result = db
         .prepare(`INSERT INTO resource_locks (name, holder, fencing, acquired_at, expires_at)
              VALUES (?, ?, 1, ?, ?)
@@ -24,16 +44,21 @@ export const acquireLock = (db, name, holder, at, ttlMs = 15_000) => {
                acquired_at = excluded.acquired_at,
                expires_at = excluded.expires_at
              WHERE resource_locks.expires_at <= ? OR resource_locks.holder = ?`)
-        .run(name, holder, at, expiry(at, ttlMs), at, holder);
+        .run(name, holder, at, expiresAt, at, holder);
     if (Number(result.changes) !== 1) {
         return undefined;
     }
     return getLock(db, name);
 };
 export const renewLock = (db, name, holder, fencing, at, ttlMs = 15_000) => {
+    assertLeaseIdentity(name, holder);
+    if (!Number.isSafeInteger(fencing) || fencing <= 0) {
+        throw new RangeError("fencing must be a positive safe integer");
+    }
+    const expiresAt = expiry(at, ttlMs);
     const result = db
         .prepare("UPDATE resource_locks SET expires_at = ? WHERE name = ? AND holder = ? AND fencing = ?")
-        .run(expiry(at, ttlMs), name, holder, fencing);
+        .run(expiresAt, name, holder, fencing);
     return Number(result.changes) === 1;
 };
 export const releaseLock = (db, name, holder, fencing) => {

package/lib/manifest/cardSign.d.ts

@@ -19,7 +19,7 @@ export declare function verifyCardSignature(card: AgentCard, signature: CardSign
  * Resolves the signing key from a trust registry (which Federation bundles can
  * populate) instead of trusting a key embedded in the card itself.
  */
-export declare function verifyCardWithRegistry(card: AgentCard, signature: CardSignature, registry: KeyRegistry): Promise<{
+export declare function verifyCardWithRegistry(card: AgentCard, signature: CardSignature, registry: KeyRegistry, expectedKid?: string): Promise<{
     ok: boolean;
     reasons: string[];
 }>;

package/lib/manifest/cardSign.js

@@ -9,6 +9,9 @@ function toBase64Url(bytes) {
     return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 }
 function fromBase64Url(text) {
+    if (!/^[A-Za-z0-9_-]*$/.test(text) || text.length % 4 === 1) {
+        throw new Error("invalid base64url");
+    }
     const padded = text.replace(/-/g, "+").replace(/_/g, "/");
     const pad = padded.length % 4 ? "=".repeat(4 - (padded.length % 4)) : "";
     const binary = atob(padded + pad);
@@ -30,10 +33,18 @@ export async function signCard(card, key) {
     return { protected: protectedHeader, signature: toBase64Url(signature) };
 }
 export async function verifyCardSignature(card, signature, publicKey) {
+    if (typeof signature?.protected !== "string" || typeof signature.signature !== "string") {
+        return { ok: false, reasons: ["signature must contain protected and signature strings"] };
+    }
     const reasons = [];
     let header;
     try {
-        header = JSON.parse(new TextDecoder().decode(fromBase64Url(signature.protected)));
+        const decoded = new TextDecoder("utf-8", { fatal: true }).decode(fromBase64Url(signature.protected));
+        const parsed = JSON.parse(decoded);
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            return { ok: false, reasons: ["protected header must be a JSON object"] };
+        }
+        header = parsed;
     }
     catch {
         return { ok: false, reasons: ["protected header is not base64url JSON"] };
@@ -41,9 +52,17 @@ export async function verifyCardSignature(card, signature, publicKey) {
     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");
+    if (typeof header.kid !== "string" || header.kid.length === 0) {
+        reasons.push("protected header has no kid");
+    }
+    try {
+        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");
+        }
+    }
+    catch {
+        reasons.push("card signature is malformed");
     }
     return { ok: reasons.length === 0, reasons };
 }
@@ -51,17 +70,28 @@ export async function verifyCardSignature(card, signature, publicKey) {
  * 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) {
+export async function verifyCardWithRegistry(card, signature, registry, expectedKid) {
+    if (typeof signature?.protected !== "string") {
+        return { ok: false, reasons: ["signature must contain a protected header"] };
+    }
     let header;
     try {
-        header = JSON.parse(new TextDecoder().decode(fromBase64Url(signature.protected)));
+        const decoded = new TextDecoder("utf-8", { fatal: true }).decode(fromBase64Url(signature.protected));
+        const parsed = JSON.parse(decoded);
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            return { ok: false, reasons: ["protected header must be a JSON object"] };
+        }
+        header = parsed;
     }
     catch {
         return { ok: false, reasons: ["protected header is not base64url JSON"] };
     }
-    if (!header.kid) {
+    if (typeof header.kid !== "string" || header.kid.length === 0) {
         return { ok: false, reasons: ["signature carries no kid"] };
     }
+    if (expectedKid !== undefined && header.kid !== expectedKid) {
+        return { ok: false, reasons: [`card signer ${header.kid} does not match manifest signer ${expectedKid}`] };
+    }
     const key = registry.get(header.kid);
     if (!key) {
         return { ok: false, reasons: [`unknown or revoked key: ${header.kid}`] };

package/lib/manifest/federation.js

@@ -31,6 +31,8 @@ async function importPublicKey(material) {
  */
 export function bundleDigest(bundle) {
     return digestOf({
+        amp: bundle.amp,
+        kind: bundle.kind,
         manifest: bundle.manifest,
         keys: bundle.keys,
         revoked: bundle.revoked ?? [],
@@ -177,11 +179,16 @@ export async function verifyAttestation(attestation, issuerKey) {
  * 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"] };
+    try {
+        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"] };
+    }
+    catch {
+        return { ok: false, reasons: ["attestation signature is malformed"] };
     }
-    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/trust.d.ts

@@ -21,6 +21,7 @@ interface TrustCardInput {
     bundle: ManifestBundle;
     policy: TrustPolicy;
     issuerKeys?: KeyRegistry;
+    revoked?: string[];
     /**
      * Verification time. Defaults to the real clock.
      */
@@ -30,6 +31,7 @@ interface FetchTrustedOptions {
     bundle: ManifestBundle;
     policy: TrustPolicy;
     issuerKeys?: KeyRegistry;
+    revoked?: string[];
     timeoutMs?: number;
     /**
      * Verification time. Defaults to the real clock.