ccp-core 0.4.0 → 0.5.1

package/README.md

@@ -2,7 +2,7 @@
 
 The TypeScript implementation of the Capability Contacts Protocol (draft
 v0.4), shaped by role: **Requester**, **Consumer**, **Runtime**, **Agent**.
-It reproduces all 51 frozen vectors in `../../test-vectors/`.
+It reproduces the frozen v1, v2, and v3 vectors in `../../test-vectors/`.
 
 Runs in browsers and Node (no Node-only APIs in `src/`).
 
@@ -122,6 +122,53 @@ limits never exceed `suggested_limits`, confirmation is never relaxed,
 capabilities come from the enabled intents, and placement/egress are
 derived from them.
 
+## Identity and admission (§25.8)
+
+Publish a signed identity document, verify one for a known contact, and
+let a reviewed policy answer matching requests without a click.
+
+```ts
+import {
+  buildAdmissionPolicy,
+  buildIdentityDocument,
+  verifyAdmissionPolicy,
+  verifyIdentityDocument,
+} from "ccp-core";
+
+const identity = buildIdentityDocument(
+  { name: "Example Service", manifestDigest: manifest.digest,
+    issuedAt: "2026-10-22T00:00:00Z", expiresAt: "2027-10-22T00:00:00Z" },
+  seed
+);
+
+const peer = verifyIdentityDocument(identity, {
+  expectedIdentity: knownContactKey,
+  manifestDigest: manifest.digest,
+});
+
+const policy = verifyAdmissionPolicy(
+  buildAdmissionPolicy(
+    { version: 1, default: "confirm", rules, issuedAt, expiresAt },
+    hostSeed
+  ),
+  { expectedHost: hostKey }
+);
+
+const { result, grant } = await runtime.admitRequest({
+  policy,
+  request: { requesterKey, contactId, intent, risk, now },
+  manifest,
+});
+// result.decision is allow | confirm | deny; grant is set on allow.
+```
+
+Accepting an invitation creates a contact, never a grant. `default` must
+be `confirm` or `deny`, and only `read`/`disclose` intents can be
+admitted. Policy grants use a deterministic id, so a revocation is not
+undone by the next matching request. See
+[`docs/guides/identity.md`](../../docs/guides/identity.md) and
+[`docs/consistency-audit.md`](../../docs/consistency-audit.md).
+
 ## Durable stores
 
 `Runtime` accepts pluggable stores. The interfaces are `GrantStore`,
@@ -282,6 +329,6 @@ Runnable examples: `examples/provider-node/` (HTTP provider) and
 ## Tests
 
 ```sh
-npx vitest run        # 51 frozen vectors + role unit tests
+npx vitest run        # v1/v2/v3 vectors + role unit tests
 npx tsc --noEmit      # typecheck
 ```

package/dist/decision.d.ts

@@ -7,8 +7,9 @@ export interface DecisionContext {
     counters: Record<string, number>;
     intentSpec: any | null;
     paramsSchema: any | null;
-    supportedCcp?: string;
+    supportedCcp?: string | readonly string[];
 }
+export declare const DEFAULT_SUPPORTED_CCP: readonly ["0.5-draft", "0.4-draft"];
 /**
  * The pure §10.3 decision. Returns `authorized`,
  * `confirmation_required`, or a rejection code.

package/dist/decision.js

@@ -1,12 +1,17 @@
 import { isValid } from "./schema.js";
+export const DEFAULT_SUPPORTED_CCP = ["0.5-draft", "0.4-draft"];
+function isSupported(value, supported) {
+    const labels = typeof supported === "string" ? [supported] : supported;
+    return typeof value === "string" && labels.includes(value);
+}
 /**
  * The pure §10.3 decision. Returns `authorized`,
  * `confirmation_required`, or a rejection code.
  */
 export function decide(ctx) {
     const { grant, signal, signer, now, seen, counters } = ctx;
-    const supported = ctx.supportedCcp ?? "0.4-draft";
-    if (signal.ccp !== supported)
+    const supported = ctx.supportedCcp ?? DEFAULT_SUPPORTED_CCP;
+    if (!isSupported(signal.ccp, supported))
         return "invalid_request";
     if (grant === null || grant === undefined)
         return "no_matching_grant";

package/dist/grants.d.ts

@@ -40,6 +40,12 @@ export interface CreateGrantOptions {
     expiresAt: string;
     state?: GrantState;
     stateReason?: string | null;
+    /**
+     * Rule id that admitted this grant under an admission policy (§25.8.3).
+     * Suppressing per-action confirmation requires this, because the policy is
+     * the consumer's explicit automation decision (§9.5, §26.2).
+     */
+    admittedBy?: string;
 }
 /**
  * Build a least-authority grant from an approved manifest and intent list.

package/dist/grants.js

@@ -49,7 +49,7 @@ export function createGrant(options) {
         throw new CcpError("invalid_request", "expiresAt must be after createdAt");
     }
     const limits = resolveLimits(definitions, options.limits);
-    const confirmation = resolveConfirmation(intents, definitions, options.confirmation);
+    const confirmation = resolveConfirmation(intents, definitions, options.confirmation, options.admittedBy);
     const capabilities = resolveCapabilities(definitions, options.capabilities);
     const placement = resolvePlacement(definitions, options.placement);
     const egress = resolveEgress(definitions, options.egress ?? {});
@@ -98,7 +98,7 @@ function resolveLimits(definitions, requested) {
     }
     return limits;
 }
-function resolveConfirmation(intents, definitions, requested) {
+function resolveConfirmation(intents, definitions, requested, admittedBy) {
     const overrides = requested ?? {};
     for (const intent of Object.keys(overrides)) {
         if (!intents.includes(intent)) {
@@ -119,7 +119,7 @@ function resolveConfirmation(intents, definitions, requested) {
         if (!CONFIRMATION_POLICIES.has(override)) {
             throw new CcpError("invalid_request", `unknown confirmation policy: ${override}`);
         }
-        if (base === "per_action" && override === "none") {
+        if (base === "per_action" && override === "none" && admittedBy === undefined) {
             throw new CcpError("invalid_request", `confirmation for ${intent} cannot be relaxed to none`);
         }
         confirmation[intent] = override;

package/dist/identity.d.ts

@@ -0,0 +1,150 @@
+/** Wire type of an identity document (§25.8.1). */
+export declare const IDENTITY_TYPE = "ccp.identity.v1";
+/** Wire type of an admission policy (§25.8.3). */
+export declare const POLICY_TYPE = "ccp.admission-policy.v1";
+/** Tolerated clock skew for validity windows (§25.8.1). */
+export declare const IDENTITY_CLOCK_SKEW_SECONDS = 120;
+export type RiskClass = "read" | "disclose" | "write" | "irreversible";
+/**
+ * Identity-layer results (§25.8). These are intentionally separate from the
+ * §10.4 decision codes: they occur while establishing a contact, before any
+ * signal exists, and must never be returned as a signal outcome.
+ */
+export type IdentityErrorCode = "invalid_request" | "unauthenticated" | "identity_expired" | "identity_changed" | "manifest_mismatch" | "policy_mismatch" | "policy_expired";
+export declare class IdentityError extends Error {
+    readonly code: IdentityErrorCode;
+    constructor(code: IdentityErrorCode, message?: string);
+}
+export interface Endpoint {
+    transport: string;
+    manifest?: string;
+    signal?: string;
+}
+export interface IdentityInput {
+    name?: string;
+    roles?: string[];
+    endpoints?: Endpoint[];
+    manifestDigest?: string;
+    policyDigest?: string;
+    issuedAt: string;
+    expiresAt: string;
+    ccp?: string;
+}
+export interface VerifiedIdentity {
+    document: string;
+    identity: string;
+    name?: string;
+    roles: string[];
+    endpoints: Endpoint[];
+    manifestDigest?: string;
+    policyDigest?: string;
+    issuedAt: string;
+    expiresAt: string;
+}
+export interface VerifyIdentityOptions {
+    now?: string;
+    expectedIdentity?: string;
+    manifestDigest?: string;
+    policyDigest?: string;
+}
+/** `sha256:<hex>` over the signing bytes of an identity document. */
+export declare function identityDigest(document: string): string;
+/** Build and sign an identity document; the identity is derived from `seed`. */
+export declare function buildIdentityDocument(input: IdentityInput, seed: Uint8Array): string;
+/**
+ * Parse and verify an identity document (§25.8.1).
+ *
+ * `expectedIdentity` is the key the caller already knows for this contact.
+ * A different key is `identity_changed`, not `unauthenticated`, because the
+ * consequence differs: affected grants must be suspended (§7.4).
+ */
+export declare function verifyIdentityDocument(document: string, options?: VerifyIdentityOptions): VerifiedIdentity;
+export interface PolicyRule {
+    id: string;
+    intents: string[];
+    risk: "read" | "disclose";
+    contacts?: string[];
+    requesters?: string[];
+    destinations?: string[];
+    limits?: Record<string, number>;
+    confirmation: "none";
+    expires_at: string;
+}
+export interface AdmissionPolicyInput {
+    version: number;
+    default: "confirm" | "deny";
+    rules: PolicyRule[];
+    issuedAt: string;
+    expiresAt: string;
+    ccp?: string;
+}
+export interface VerifiedPolicy {
+    document: string;
+    host: string;
+    version: number;
+    default: "confirm" | "deny";
+    rules: PolicyRule[];
+    issuedAt: string;
+    expiresAt: string;
+    digest: string;
+}
+export interface VerifyPolicyOptions {
+    now?: string;
+    expectedHost?: string;
+}
+export interface AdmissionRequest {
+    requesterKey: string;
+    contactId: string;
+    intent: string;
+    risk: RiskClass;
+    destination?: string;
+    now: string;
+}
+export interface AdmissionResult {
+    decision: "allow" | "confirm" | "deny";
+    reason: string;
+    ruleId?: string;
+}
+export interface AdmissionOptions {
+    /**
+     * Ids of grants the consumer has revoked. A match whose deterministic id is
+     * in this set is refused with `grant_revoked`; the policy cannot resurrect
+     * it (§25.8.3).
+     */
+    revoked?: ReadonlySet<string>;
+}
+/** The grant a matched rule may create. `allow` still needs its own record. */
+export interface AdmittedGrant {
+    /** Deterministic id; reused on every admission of this rule. */
+    id: string;
+    intent: string;
+    limits: Record<string, number>;
+    expiresAt: string;
+}
+/**
+ * Deterministic grant id for a policy rule and requester (§25.8.3).
+ *
+ * Reusing the id is what makes revocation durable: the host stores one
+ * record, the consumer revokes it, and every later admission of the same
+ * rule resolves to that revoked record.
+ */
+export declare function admittedGrantId(policy: VerifiedPolicy, ruleId: string, request: AdmissionRequest): string;
+/** `sha256:<hex>` over the signing bytes of an admission policy. */
+export declare function policyDigest(document: string): string;
+/** Build and sign an admission policy; `host` is derived from `seed`. */
+export declare function buildAdmissionPolicy(input: AdmissionPolicyInput, seed: Uint8Array): string;
+/** Parse and verify an admission policy (§25.8.3). */
+export declare function verifyAdmissionPolicy(document: string, options?: VerifyPolicyOptions): VerifiedPolicy;
+/**
+ * Evaluate a verified policy against one request (§25.8.3).
+ *
+ * `allow` is not an execution: use `admittedGrant` to create the record and
+ * then proceed through §10.3.
+ */
+export declare function admit(policy: VerifiedPolicy, request: AdmissionRequest, options?: AdmissionOptions): AdmissionResult;
+/**
+ * The grant record a match may create: exactly the requested intent, the
+ * rule's limits, and the earlier of the rule and policy expiries.
+ * Returns `undefined` unless the decision was `allow`.
+ */
+export declare function admittedGrant(policy: VerifiedPolicy, request: AdmissionRequest, result: AdmissionResult): AdmittedGrant | undefined;