ccp-core 0.5.0 → 0.5.1

package/dist/runtime.js

@@ -4,7 +4,10 @@ import { signingBytes } from "./signing.js";
 import { keyIdFromPublic, verify } from "./crypto.js";
 import { decide } from "./decision.js";
 import { validate as validateSchema } from "./schema.js";
-import { AUTHORIZED, CONFIRMATION_REQUIRED } from "./errors.js";
+import { AUTHORIZED, CONFIRMATION_REQUIRED, CcpError } from "./errors.js";
+import { createGrant } from "./grants.js";
+import { verifyManifest } from "./consumer.js";
+import { IdentityError, admit, admittedGrant, verifyIdentityDocument, } from "./identity.js";
 import { MemoryAuditLog, MemoryGrantStore, MemoryLimitStore, MemoryManifestStore, MemoryPendingStore, MemoryReplayStore, } from "./stores.js";
 import { utcnow } from "./time.js";
 export { utcnow };
@@ -20,21 +23,169 @@ export class SchemaRegistry {
         return id === undefined ? undefined : this._schemas.get(id);
     }
 }
+/** The only hosts that may be registered without an explicit profile. */
+export const CORE_HOSTS = new Set([
+    "store.read",
+    "files.read",
+    "files.search",
+    "notify",
+    "confirm",
+    "audit.append",
+]);
+const HOST_CLASSES = new Set([
+    "read",
+    "write",
+    "disclose",
+    "control",
+    "compute",
+]);
+const HOST_RISKS = new Set([
+    "read",
+    "write",
+    "disclose",
+    "irreversible",
+]);
+const HOST_PLACEMENTS = new Set([
+    "local",
+    "remote",
+    "delegated",
+]);
+const IDEMPOTENCY = new Set([
+    "pure",
+    "caller_key",
+    "atomic",
+    "none",
+]);
+const CLASS_DEFAULTS = {
+    read: { risk: "read", minConfirmation: "none", idempotency: "pure" },
+    disclose: { risk: "disclose", minConfirmation: "per_action", idempotency: "pure" },
+    write: { risk: "write", minConfirmation: "per_action", idempotency: "caller_key" },
+    control: { risk: "write", minConfirmation: "per_action", idempotency: "none" },
+    compute: { risk: "read", minConfirmation: "per_action", idempotency: "pure" },
+};
+export class HostProfileError extends Error {
+    code = "invalid_request";
+    constructor(message) {
+        super(`invalid_request: ${message}`);
+        this.name = "HostProfileError";
+    }
+}
+/**
+ * Validate and normalize a host profile (§26.4).
+ *
+ * Extension hosts (anything outside the core six) must declare a class; the
+ * rest of the contract follows from it unless explicitly overridden. A
+ * `write`, `control`, or `compute` host can never suppress confirmation, and
+ * an `irreversible` risk cannot either.
+ */
+export function validateHostProfile(name, profile = {}) {
+    if (typeof name !== "string" || name === "") {
+        throw new HostProfileError("host name is required");
+    }
+    const declared = profile.class;
+    if (declared === undefined && !CORE_HOSTS.has(name)) {
+        throw new HostProfileError(`extension host ${name} requires a class`);
+    }
+    if (declared !== undefined && !HOST_CLASSES.has(declared)) {
+        throw new HostProfileError(`unknown host class: ${declared}`);
+    }
+    const hostClass = (declared ?? "read");
+    const defaults = CLASS_DEFAULTS[hostClass];
+    const risk = (profile.risk ?? defaults.risk);
+    if (!HOST_RISKS.has(risk)) {
+        throw new HostProfileError(`unknown host risk: ${risk}`);
+    }
+    const minConfirmation = (profile.minConfirmation ??
+        defaults.minConfirmation);
+    if (minConfirmation !== "none" && minConfirmation !== "per_action") {
+        throw new HostProfileError(`unknown confirmation floor: ${minConfirmation}`);
+    }
+    if (minConfirmation === "none") {
+        if (hostClass !== "read" && hostClass !== "disclose") {
+            throw new HostProfileError(`a ${hostClass} host cannot suppress confirmation`);
+        }
+        if (risk === "irreversible") {
+            throw new HostProfileError("an irreversible host cannot suppress confirmation");
+        }
+    }
+    const idempotency = (profile.idempotency ?? defaults.idempotency);
+    if (!IDEMPOTENCY.has(idempotency)) {
+        throw new HostProfileError(`unknown idempotency: ${idempotency}`);
+    }
+    const network = profile.network === true;
+    if (profile.network !== undefined && typeof profile.network !== "boolean") {
+        throw new HostProfileError("network must be a boolean");
+    }
+    const placement = profile.placement ?? ["local"];
+    if (!Array.isArray(placement) || placement.length === 0) {
+        throw new HostProfileError("placement must be a non-empty array");
+    }
+    const seenPlacement = new Set();
+    for (const entry of placement) {
+        if (typeof entry !== "string" || !HOST_PLACEMENTS.has(entry)) {
+            throw new HostProfileError(`unknown placement: ${entry}`);
+        }
+        if (seenPlacement.has(entry)) {
+            throw new HostProfileError(`duplicate placement: ${entry}`);
+        }
+        seenPlacement.add(entry);
+    }
+    const fields = profile.fields ?? [];
+    if (!Array.isArray(fields)) {
+        throw new HostProfileError("fields must be an array");
+    }
+    const seenFields = new Set();
+    for (const field of fields) {
+        if (typeof field !== "string" || field === "") {
+            throw new HostProfileError("fields must be non-empty strings");
+        }
+        if (seenFields.has(field)) {
+            throw new HostProfileError(`duplicate field: ${field}`);
+        }
+        seenFields.add(field);
+    }
+    if (network && fields.length === 0 && hostClass === "disclose") {
+        throw new HostProfileError("a network disclose host must declare the fields it sends");
+    }
+    return {
+        class: hostClass,
+        risk,
+        minConfirmation,
+        idempotency,
+        network,
+        placement: placement,
+        fields: [...fields],
+    };
+}
 export class HostAccess {
     registry;
+    policy;
     _granted;
-    constructor(registry, granted) {
+    constructor(registry, granted, policy = {
+        network: false,
+        fields: new Set(),
+    }) {
         this.registry = registry;
+        this.policy = policy;
         this._granted = new Set(granted);
     }
     call(name, ...args) {
         if (!this._granted.has(name)) {
             throw new Error(`host function not granted: ${name}`);
         }
-        const fn = this.registry.host(name);
-        if (!fn)
+        const entry = this.registry.hostMeta(name);
+        if (entry === undefined) {
             throw new Error(`host function not installed: ${name}`);
-        return fn(...args);
+        }
+        if (entry.profile.network && !this.policy.network) {
+            throw new Error(`host requires network egress not granted: ${name}`);
+        }
+        for (const field of entry.profile.fields) {
+            if (!this.policy.fields.has(field)) {
+                throw new Error(`host may send an undeclared field: ${name}/${field}`);
+            }
+        }
+        return entry.fn(...args);
     }
     has(name) {
         return this._granted.has(name) && this.registry.hasHost(name);
@@ -43,13 +194,20 @@ export class HostAccess {
 export class HostRegistry {
     _hosts = new Map();
     _intents = new Map();
-    registerHost(name, fn) {
-        this._hosts.set(name, fn);
+    registerHost(name, fn, profile = {}) {
+        this._hosts.set(name, {
+            fn,
+            profile: validateHostProfile(name, profile),
+        });
     }
     registerIntent(name, fn) {
         this._intents.set(name, fn);
     }
     host(name) {
+        return this._hosts.get(name)?.fn;
+    }
+    /** Metadata used to enforce placement, egress, and confirmation (§12). */
+    hostMeta(name) {
         return this._hosts.get(name);
     }
     hasHost(name) {
@@ -61,10 +219,16 @@ export class HostRegistry {
     hasIntent(name) {
         return this._intents.has(name);
     }
-    access(granted) {
-        return new HostAccess(this, granted);
+    access(granted, policy) {
+        return new HostAccess(this, granted, policy);
     }
 }
+/**
+ * Reserved suspension reason for a requester key change (§7.4). A grant
+ * suspended this way cannot be resumed; the consumer re-introduces the
+ * contact and creates a new grant.
+ */
+export const IDENTITY_CHANGED_REASON = "identity_changed";
 export class Runtime {
     grants;
     manifests;
@@ -123,7 +287,7 @@ export class Runtime {
             return this.reject("unauthenticated", signal.request_id, undefined, String(error));
         }
         const signer = keyIdFromPublic(publicKey);
-        const grant = await this.grants.find(signer, signal.grant_digest);
+        const grant = await this.resolveGrant(signer, signal.grant_digest, signal.intent);
         let intentSpec = null;
         let paramsSchema = null;
         if (grant) {
@@ -148,7 +312,7 @@ export class Runtime {
             supportedCcp: this.supportedCcp,
         });
         if (outcome !== AUTHORIZED && outcome !== CONFIRMATION_REQUIRED) {
-            return this.reject(outcome, signal.request_id, grant);
+            return this.reject(outcome, signal.request_id, grant, this.stateDetail(outcome, grant));
         }
         if (!(await this.replay.markIfNew(signal.request_id))) {
             return this.reject("replay_detected", signal.request_id, grant);
@@ -162,7 +326,13 @@ export class Runtime {
             await this.limits.release(grant.id, grant.limits);
             return this.reject("capability_unavailable", signal.request_id, grant, `unavailable: ${unavailable.length > 0 ? unavailable.join(",") : signal.intent}`);
         }
-        if (outcome === CONFIRMATION_REQUIRED) {
+        const deployment = this.deploymentError(grant, intentSpec, required);
+        if (deployment !== undefined) {
+            await this.limits.release(grant.id, grant.limits);
+            return this.reject("capability_unavailable", signal.request_id, grant, deployment);
+        }
+        const requiresConfirmation = outcome === CONFIRMATION_REQUIRED || this.hostFloor(intentSpec);
+        if (requiresConfirmation) {
             const pendingId = randomId();
             await this.pendingStore.put({
                 id: pendingId,
@@ -204,16 +374,206 @@ export class Runtime {
                 state: "cancelled",
             };
         }
-        const stateError = this.grantStateError(pending.grant, this.clock());
+        // The grant may have been revoked or paused while the prompt was open
+        // (§9.4.3); re-read it rather than trusting the snapshot.
+        const current = (await this.grants.get(pending.grant.id)) ?? pending.grant;
+        const stateError = this.grantStateError(current, this.clock());
         if (stateError) {
-            await this.limits.release(pending.grant.id, pending.grant.limits);
-            return this.reject(stateError, pending.signal.request_id, pending.grant);
+            await this.limits.release(current.id, current.limits);
+            return this.reject(stateError, pending.signal.request_id, current, this.stateDetail(stateError, current));
         }
-        return this.execute(pending.signal, pending.grant, pending.intentSpec);
+        return this.execute(pending.signal, current, pending.intentSpec);
     }
     pending(pendingId) {
         return Promise.resolve(this.pendingStore.get(pendingId));
     }
+    /**
+     * Pause one grant (§9.4.1). Configuration, limits, and history are kept.
+     */
+    async pauseGrant(id, reason) {
+        return this.transition(id, "paused", reason);
+    }
+    /**
+     * Suspend one grant (§9.4.2). Used for security events such as a requester
+     * key change; resumption requires an explicit `resumeGrant`.
+     */
+    async suspendGrant(id, reason) {
+        return this.transition(id, "suspended", reason);
+    }
+    /**
+     * Resume a paused or suspended grant (§9.4.3).
+     *
+     * Re-checks revocation, expiry, and the approved manifest before restoring
+     * authority. A revoked or expired grant cannot be resumed.
+     */
+    async resumeGrant(id) {
+        const grant = await this.grants.get(id);
+        if (grant === undefined) {
+            throw new CcpError("no_matching_grant", `unknown grant: ${id}`);
+        }
+        if (grant.state === "revoked") {
+            throw new CcpError("grant_revoked", "a revoked grant cannot be resumed");
+        }
+        if (grant.state === "suspended" &&
+            grant.state_reason === IDENTITY_CHANGED_REASON) {
+            throw new CcpError("grant_suspended", "identity changed; re-introduce the contact and create a new grant");
+        }
+        if (grant.state === "expired" || this.clock() >= grant.expires_at) {
+            throw new CcpError("grant_expired", "an expired grant cannot be resumed");
+        }
+        if (this.manifests.get(grant.manifest_digest) === undefined) {
+            throw new CcpError("capability_unavailable", "the approved manifest is no longer stored");
+        }
+        if (grant.state === "active")
+            return grant;
+        return this.transition(id, "active", undefined);
+    }
+    /**
+     * Revoke one grant by id (§9.4.4). Permanent: the grant is not resumable and
+     * a new approval is required.
+     *
+     * Policy-created grants reuse their deterministic id, so revoking here also
+     * stops an admission rule from re-creating the same access (§25.8.3).
+     */
+    async revokeGrant(id, reason) {
+        return this.transition(id, "revoked", reason);
+    }
+    /**
+     * Suspend every active grant bound to a contact (§7.4, §9.4.2).
+     * Returns the number of grants affected.
+     */
+    async suspendContact(contactId, reason) {
+        const affected = (await this.grants.all()).filter((grant) => grant.contact_id === contactId && grant.state !== "revoked");
+        for (const grant of affected) {
+            await this.setGrantState(grant, "suspended", reason ?? "contact suspended");
+        }
+        return affected.length;
+    }
+    /**
+     * Verify an identity document for a known contact (§7.4, §25.8.4).
+     *
+     * On `identity_changed` — a valid signature from a different key — the
+     * contact's grants are suspended before the error is rethrown. A bad
+     * signature never suspends anything, so an attacker cannot force a
+     * suspension by sending garbage.
+     */
+    async verifyContactIdentity(document, options) {
+        try {
+            return verifyIdentityDocument(document, options);
+        }
+        catch (error) {
+            if (error instanceof IdentityError && error.code === "identity_changed") {
+                const suspended = await this.suspendContact(options.contactId, IDENTITY_CHANGED_REASON);
+                await this.audit.append({
+                    event: "identity_changed",
+                    contact_id: options.contactId,
+                    detail: `${suspended} grant(s) suspended`,
+                });
+            }
+            throw error;
+        }
+    }
+    /**
+     * Admit a request under a reviewed policy (§25.8.3).
+     *
+     * `allow` creates or reuses the grant with the policy's deterministic id,
+     * records the admitting rule in the audit log, and leaves the request to
+     * proceed through `submit` normally. Revoked ids are consulted from the
+     * grant store, so a revocation is never undone here.
+     */
+    async admitRequest(options) {
+        const { policy, request } = options;
+        const manifest = typeof options.manifest === "string"
+            ? verifyManifest(options.manifest)
+            : options.manifest;
+        const revoked = new Set((await this.grants.all())
+            .filter((grant) => grant.state === "revoked")
+            .map((grant) => grant.id));
+        const result = admit(policy, request, { revoked });
+        if (result.decision !== "allow")
+            return { result };
+        const granted = admittedGrant(policy, request, result);
+        if (granted === undefined)
+            return { result };
+        // A policy may never admit an intent whose hosts require a human.
+        const intentSpec = manifest.manifest.intents?.[granted.intent];
+        for (const capability of intentSpec?.required_capabilities ?? []) {
+            const meta = this.hosts.hostMeta(capability);
+            if (meta === undefined) {
+                return { result: { decision: "deny", reason: "capability_unavailable" } };
+            }
+            if (meta.profile.minConfirmation !== "none") {
+                return { result: { decision: "deny", reason: "risk_not_admittable" } };
+            }
+        }
+        const existing = await this.grants.get(granted.id);
+        if (existing !== undefined)
+            return { result, grant: existing };
+        const grant = createGrant({
+            id: granted.id,
+            contactId: request.contactId,
+            requesterKey: request.requesterKey,
+            manifest,
+            intents: [granted.intent],
+            limits: granted.limits,
+            confirmation: options.confirmation ?? { [granted.intent]: "none" },
+            createdAt: this.clock(),
+            expiresAt: granted.expiresAt,
+            admittedBy: result.ruleId,
+        });
+        await this.grants.add(grant);
+        this.manifests.add(manifest);
+        await this.audit.append({
+            event: "admitted",
+            grant_id: grant.id,
+            intent: granted.intent,
+            rule_id: result.ruleId,
+        });
+        return { result, grant };
+    }
+    /**
+     * Resolve the grant for this request.
+     *
+     * A requester may hold several grants over one manifest digest (for
+     * example, a manual grant and a policy-created one). The store lookup is
+     * the fast path; when it lands on a grant that does not enable the intent,
+     * prefer a grant that does. Revocation remains per grant (§25.8.3).
+     */
+    async resolveGrant(requesterKey, manifestDigest, intent) {
+        const found = await this.grants.find(requesterKey, manifestDigest);
+        if (found !== undefined && found.intents.includes(intent))
+            return found;
+        const candidates = (await this.grants.all()).filter((grant) => grant.requester_key === requesterKey &&
+            grant.manifest_digest === manifestDigest &&
+            grant.intents.includes(intent));
+        if (candidates.length === 0)
+            return found;
+        return candidates.find((grant) => grant.state === "active") ?? candidates[0];
+    }
+    async transition(id, state, reason) {
+        const grant = await this.grants.get(id);
+        if (grant === undefined) {
+            throw new CcpError("no_matching_grant", `unknown grant: ${id}`);
+        }
+        if (grant.state === "revoked" && state !== "revoked") {
+            throw new CcpError("grant_revoked", "a revoked grant is final");
+        }
+        return this.setGrantState(grant, state, reason);
+    }
+    async setGrantState(grant, state, reason) {
+        const updated = {
+            ...grant,
+            state,
+            state_reason: state === "active" ? null : reason ?? grant.state_reason ?? null,
+        };
+        await this.grants.add(updated);
+        await this.audit.append({
+            event: state === "active" ? "resumed" : state,
+            grant_id: grant.id,
+            detail: reason,
+        });
+        return updated;
+    }
     async execute(signal, grant, intentSpec) {
         await this.audit.append({
             event: "executing",
@@ -234,7 +594,7 @@ export class Runtime {
         }
         let result;
         try {
-            result = await executor(signal.params, this.hosts.access(grant.capabilities));
+            result = await executor(signal.params, this.hosts.access(grant.capabilities, this.egressPolicy(grant)));
         }
         catch (error) {
             await this.limits.release(grant.id, grant.limits);
@@ -284,6 +644,51 @@ export class Runtime {
             state: "completed",
         };
     }
+    /**
+     * Enforce the grant's placement and egress ceilings before execution (§12).
+     * A host that needs network access cannot run under a grant that denies it.
+     */
+    deploymentError(grant, intentSpec, required) {
+        const placement = typeof intentSpec.placement === "string" ? intentSpec.placement : "local";
+        if (!(grant.placement ?? []).includes(placement)) {
+            return `placement ${placement} is not granted`;
+        }
+        const policy = this.egressPolicy(grant);
+        for (const capability of required) {
+            const meta = this.hosts.hostMeta(capability);
+            if (meta === undefined)
+                return `host ${capability} is not installed`;
+            if (!meta.profile.placement.includes(placement)) {
+                return `host ${capability} cannot run with ${placement} placement`;
+            }
+            if (meta.profile.network && !policy.network) {
+                return `host ${capability} requires network egress not granted`;
+            }
+            for (const field of meta.profile.fields) {
+                if (!policy.fields.has(field)) {
+                    return `host ${capability} may send undeclared field ${field}`;
+                }
+            }
+        }
+        return undefined;
+    }
+    /** True when a required host declares a per-action confirmation floor. */
+    hostFloor(intentSpec) {
+        for (const capability of intentSpec.required_capabilities ?? []) {
+            const meta = this.hosts.hostMeta(capability);
+            if (meta?.profile.minConfirmation === "per_action")
+                return true;
+        }
+        return false;
+    }
+    egressPolicy(grant) {
+        const egress = grant.egress ?? {};
+        const fields = Array.isArray(egress.fields) ? egress.fields : [];
+        return {
+            network: egress.network === true,
+            fields: new Set(fields.filter((field) => typeof field === "string")),
+        };
+    }
     grantStateError(grant, now) {
         if (grant.state === "revoked")
             return "grant_revoked";
@@ -296,6 +701,20 @@ export class Runtime {
         }
         return undefined;
     }
+    /**
+     * Surface a recorded pause/suspend/revoke reason (§9.4.2). The reason is
+     * local and must not contain secrets; hosts choose what to record.
+     */
+    stateDetail(outcome, grant) {
+        if (grant === undefined)
+            return undefined;
+        if (outcome === "grant_revoked" ||
+            outcome === "grant_paused" ||
+            outcome === "grant_suspended") {
+            return grant.state_reason ?? undefined;
+        }
+        return undefined;
+    }
     async reject(code, requestId, grant, detail) {
         await this.audit.append({
             event: "rejected",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccp-core",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/index.js",