ccp-core 0.0.0-stage → 0.4.0

package/README.md

@@ -1,3 +1,287 @@
-# Temporary Holding Version
+# ccp-core — CCP TypeScript SDK
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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/`.
+
+Runs in browsers and Node (no Node-only APIs in `src/`).
+
+## Install
+
+```sh
+npm install ccp-core
+```
+
+## Requester — sign a manifest and a signal
+
+```ts
+import { Requester, publicFromSeed } from "ccp-core";
+
+const seed = crypto.getRandomValues(new Uint8Array(32));
+const requester = new Requester(seed);
+
+const manifest = requester.manifest({
+  provider: { id: requester.keyId, name: "Example Service" },
+  version: 1,
+  intents: {
+    "example.lookup": {
+      params_schema: "schema:example.lookup.params.v1",
+      result_schema: "schema:example.lookup.result.v1",
+      required_capabilities: ["store.read"],
+      placement: "local",
+      data_egress: { network: false, fields: [] },
+      confirmation: "grant-policy",
+    },
+  },
+});
+
+const signal = requester.signal({
+  requestId: "req-1",
+  grantDigest: "sha256:…", // the grant's manifest_digest
+  intent: "example.lookup",
+  params: { item_id: "item-123" },
+  issuedAt: "2026-10-22T12:00:00Z",
+  expiresAt: "2026-10-22T12:01:00Z",
+});
+```
+
+## Consumer — verify and render a permission card
+
+```ts
+import { verifyManifest, verifySignal, permissionCard } from "ccp-core";
+
+const verified = verifyManifest(manifest); // throws CcpError on failure
+const card = permissionCard(verified.manifest, "example.lookup", {
+  providerName: "Example Service",
+});
+// card.who / card.what / card.dataRead / card.where / card.egress /
+// card.effects / card.recurrence / card.revoke
+
+const inbox = verifySignal(signal, senderPublicKey);
+```
+
+## Runtime — enforce a grant
+
+```ts
+import {
+  HostRegistry,
+  MemoryAuditLog,
+  MemoryGrantStore,
+  MemoryManifestStore,
+  Runtime,
+  SchemaRegistry,
+  createGrant,
+  verifyManifest,
+} from "ccp-core";
+
+const manifest = verifyManifest(manifestWire);
+
+const grant = createGrant({
+  requesterKey: requester.keyId,
+  contactId: "c-1",
+  manifest,
+  intents: ["example.lookup"],
+  // Defaults to the manifest's suggested_limits. Values above the
+  // suggestion are rejected (§9.2).
+  limits: { calls_per_hour: 5 },
+  // Defaults to the manifest policy. Confirmation can be tightened but
+  // never relaxed to "none".
+  expiresAt: "2026-10-22T23:00:00Z",
+});
+
+const hosts = new HostRegistry();
+hosts.registerHost("store.read", (id: string) => ({ item_id: id }));
+hosts.registerIntent("example.lookup", (params, access) =>
+  access.call("store.read", params.item_id)
+);
+
+const runtime = new Runtime({
+  grants: new MemoryGrantStore([grant]),
+  manifests: new MemoryManifestStore([manifest]),
+  schemas: new SchemaRegistry({
+    "schema:example.lookup.params.v1": {
+      type: "object",
+      properties: { item_id: { type: "string" } },
+      required: ["item_id"],
+      additionalProperties: false,
+    },
+  }),
+  hosts,
+  audit: new MemoryAuditLog(),
+});
+
+const decision = await runtime.submit(signal, requesterPublicKey);
+if (decision.outcome === "confirmation_required") {
+  await runtime.confirm(decision.pending_id!, true); // trusted UI decision
+}
+```
+
+`decision.outcome` is `authorized`, `confirmation_required`, or a §10.4
+rejection code. `createGrant` only narrows what the manifest declares:
+limits never exceed `suggested_limits`, confirmation is never relaxed,
+capabilities come from the enabled intents, and placement/egress are
+derived from them.
+
+## Durable stores
+
+`Runtime` accepts pluggable stores. The interfaces are `GrantStore`,
+`ManifestStore`, `ReplayStore`, `LimitStore`, `PendingStore`, and
+`AuditStore`; the in-memory implementations are prefixed with `Memory`.
+Authorization-state methods may be synchronous (the defaults, or a
+synchronous SQLite driver) or asynchronous (Postgres, a remote store);
+the runtime awaits them. `ManifestStore` stays synchronous because
+verified manifests are immutable and can be loaded at startup.
+
+Three methods carry atomicity requirements:
+
+- `LimitStore.tryReserve` reserves one unit against every limit or none,
+  in one transaction.
+- `ReplayStore.markIfNew` inserts atomically and returns `false` when the
+  request id already exists.
+- `PendingStore.take` removes and returns a confirmation atomically, so it
+  can be resolved at most once across processes.
+
+```ts
+const runtime = new Runtime({
+  grants: postgresGrants,
+  manifests: new MemoryManifestStore([manifest]), // immutable; load at startup
+  replay: postgresReplay,
+  limits: postgresLimits,
+  pending: postgresPending,
+  audit: postgresAudit,
+  schemas,
+  hosts,
+});
+```
+
+See `docs/guides/persistence.md` for the SQL shape and the full contract.
+
+### Node (SQLite)
+
+The package ships a durable implementation on the built-in `node:sqlite`
+module, with no extra dependency. It is Node-only and never imported by the
+browser-safe core:
+
+```ts
+import { Runtime } from "ccp-core";
+import { SqliteStores } from "ccp-core/node";
+
+const stores = new SqliteStores("ccp.db"); // or ":memory:"
+const runtime = new Runtime({ ...stores, schemas, hosts });
+// ...
+stores.close();
+```
+
+`node:sqlite` requires Node 22.5+ (available without a flag in Node 24, where
+it is still marked experimental).
+
+## Agent — wrap a tool call
+
+```ts
+import { Agent, attenuates } from "ccp-core";
+
+const agent = new Agent(agentSeed);
+const wire = agent.signalFor(
+  { intent: "example.lookup", params: { item_id: "item-123" } },
+  grant,
+  { requestId: "req-2", issuedAt: "…", expiresAt: "…" }
+);
+
+// Delegation must be no broader than the parent grant (§15.1).
+attenuates(parentGrant, childGrant);
+```
+
+## Adapters — meet each framework in place
+
+Adapters are subpath exports, so the core bundle stays free of Express and
+React. They never decide authorization themselves; they parse the request,
+resolve the sender key, and call the runtime.
+
+### Express provider
+
+```ts
+import express from "express";
+import { providerMiddleware } from "ccp-core/express";
+
+const app = express();
+app.use(express.json());
+app.post(
+  "/ccp",
+  providerMiddleware({
+    runtime,
+    // Resolve from your authenticated channel, not from the signal.
+    keyResolver: (req) => publicKeys.get(req.header("x-contact")),
+  })
+);
+```
+
+The middleware reads `{ "signal": "<canonical json>" }` and forwards the
+string untouched. It answers 200 for `authorized`/`confirmation_required`,
+400 for `invalid_request`, 401 when the sender is unknown, 403 for
+`unauthenticated`/`no_matching_grant`, and 409 for other refusals.
+
+### Next.js / Web routes
+
+```ts
+import { createManifestHandler, createSignalHandler } from "ccp-core/next";
+
+export const GET = createManifestHandler({ manifest: manifestWire });
+export const POST = createSignalHandler({ runtime, keyResolver });
+```
+
+The signal handler takes the raw canonical JSON as the body and returns a
+standard `Response`; it has no Next.js dependency and also works in any
+`Request`/`Response` runtime. The manifest handler serves the signed wire
+verbatim.
+
+### React permission card
+
+```tsx
+import { usePermissionCard } from "ccp-core/react";
+
+const { status, card, decision, approve, deny } = usePermissionCard({
+  runtime,
+  signal,
+  publicKey,
+  card: permissionCardModel,
+});
+```
+
+Headless: render `card` however you like. `status` is `loading`,
+`authorized`, `confirmation_required`, `rejected`, or `cancelled`; calling
+`approve()` / `deny()` resolves a pending confirmation. The hook submits once
+per signal.
+
+### MCP agent bridge
+
+```ts
+import { createMcpServer } from "ccp-core/mcp";
+
+const bridge = createMcpServer({
+  runtime,
+  agent, // Agent key the grant is bound to
+  grant,
+  // Trusted host decision. Omit to surface confirmation_required instead.
+  confirm: async ({ params, card }) => askUser(card, params),
+});
+
+registerToolsOnYourMcpServer(bridge.tools);
+const result = await bridge.callTool("example.lookup", {
+  item_id: "item-123",
+});
+```
+
+One bridge serves one grant; tool names are the granted intent names. The
+adapter signs every call and lets the runtime decide. It never auto-approves:
+without `confirm`, a `confirmation_required` outcome is returned with the
+pending id and the §11.4 card. Tool results are data, not instructions.
+
+Runnable examples: `examples/provider-node/` (HTTP provider) and
+`examples/agent-mcp/` (MCP; `npm run mcp:demo`).
+
+## Tests
+
+```sh
+npx vitest run        # 51 frozen vectors + role unit tests
+npx tsc --noEmit      # typecheck
+```

package/dist/adapters/express.d.ts

@@ -0,0 +1,16 @@
+import type { Request, RequestHandler } from "express";
+import type { Runtime } from "../runtime.js";
+/** Resolve the requester's Ed25519 public key, or `undefined` if unknown. */
+export type ExpressKeyResolver = (request: Request) => Uint8Array | undefined | Promise<Uint8Array | undefined>;
+export interface ProviderMiddlewareOptions {
+    /** Runtime that owns grants, replay protection, limits, and executors. */
+    runtime: Runtime;
+    /** Key for the sender of this request; `undefined` rejects with 401. */
+    keyResolver: ExpressKeyResolver;
+}
+/**
+ * Provider-side Express middleware. It reads `{ "signal": "<json>" }` (or a
+ * raw text body), resolves the sender key, and lets the runtime decide.
+ * Authorization never happens here.
+ */
+export declare function providerMiddleware(options: ProviderMiddlewareOptions): RequestHandler;

package/dist/adapters/express.js

@@ -0,0 +1,49 @@
+import { httpStatusFor } from "./status.js";
+/**
+ * Provider-side Express middleware. It reads `{ "signal": "<json>" }` (or a
+ * raw text body), resolves the sender key, and lets the runtime decide.
+ * Authorization never happens here.
+ */
+export function providerMiddleware(options) {
+    const { runtime, keyResolver } = options;
+    return async (request, response) => {
+        const signal = extractSignal(request.body);
+        if (signal === undefined) {
+            response
+                .status(400)
+                .json({ outcome: "invalid_request", error: "invalid_request" });
+            return;
+        }
+        let publicKey;
+        try {
+            publicKey = await keyResolver(request);
+        }
+        catch {
+            publicKey = undefined;
+        }
+        if (publicKey === undefined) {
+            response
+                .status(401)
+                .json({ outcome: "unauthenticated", error: "unauthenticated" });
+            return;
+        }
+        try {
+            const decision = await runtime.submit(signal, publicKey);
+            response.status(httpStatusFor(decision)).json(decision);
+        }
+        catch {
+            response
+                .status(500)
+                .json({ outcome: "outcome_unknown", error: "outcome_unknown" });
+        }
+    };
+}
+function extractSignal(body) {
+    if (typeof body === "string")
+        return body;
+    if (body === null || typeof body !== "object" || Array.isArray(body)) {
+        return undefined;
+    }
+    const value = body.signal;
+    return typeof value === "string" ? value : undefined;
+}

package/dist/adapters/mcp.d.ts

@@ -0,0 +1,57 @@
+import type { Agent } from "../agent.js";
+import type { PermissionCard, VerifiedManifest } from "../consumer.js";
+import type { JsonValue } from "../json.js";
+import type { Runtime } from "../runtime.js";
+import type { Grant } from "../stores.js";
+export interface McpTool {
+    /** Intent name, used verbatim as the MCP tool name. */
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+}
+export interface McpTextContent {
+    type: "text";
+    text: string;
+}
+export interface McpToolResult {
+    content: McpTextContent[];
+    structuredContent?: Record<string, unknown>;
+    isError?: boolean;
+}
+/** The exact action a trusted host is asked to approve (§11.4). */
+export interface ConfirmationRequest {
+    pendingId: string;
+    requestId: string;
+    intent: string;
+    params: Record<string, JsonValue>;
+    card: PermissionCard;
+}
+export interface McpServerOptions {
+    /** Runtime that owns grants, limits, replay protection, and executors. */
+    runtime: Runtime;
+    /** Agent key that signs each tool call and that the grant is bound to. */
+    agent: Agent;
+    /** The agent's whole authority. Create one bridge per grant. */
+    grant: Grant;
+    /** Defaults to the runtime's verified manifest for this grant. */
+    manifest?: VerifiedManifest;
+    /**
+     * Trusted host decision. Omit to surface `confirmation_required` to the
+     * caller instead. The adapter never approves on its own.
+     */
+    confirm?: (request: ConfirmationRequest) => boolean | Promise<boolean>;
+    /** Lifetime of each signed signal, in seconds. Default 60. */
+    requestTtlSeconds?: number;
+    /** Defaults to `runtime.clock`. */
+    now?: () => string;
+}
+export interface McpServer {
+    readonly tools: readonly McpTool[];
+    callTool(name: string, args: unknown): Promise<McpToolResult>;
+}
+/**
+ * Transport-neutral MCP bridge. Expose `tools` through an MCP host and route
+ * `tools/call` to `callTool`; the runtime makes every authorization decision.
+ */
+export declare function createMcpServer(options: McpServerOptions): McpServer;

package/dist/adapters/mcp.js

@@ -0,0 +1,145 @@
+import { permissionCard } from "../consumer.js";
+import { confirmationPolicy } from "../decision.js";
+import { AUTHORIZED, CONFIRMATION_REQUIRED, ERROR_CODES } from "../errors.js";
+import { randomId } from "../ids.js";
+/**
+ * Transport-neutral MCP bridge. Expose `tools` through an MCP host and route
+ * `tools/call` to `callTool`; the runtime makes every authorization decision.
+ */
+export function createMcpServer(options) {
+    const { runtime, agent, grant } = options;
+    const manifest = options.manifest ?? runtime.manifests.get(grant.manifest_digest);
+    if (manifest === undefined) {
+        throw new Error(`manifest not found for grant ${grant.id}`);
+    }
+    const verified = manifest;
+    if (grant.requester_key !== agent.keyId) {
+        throw new Error(`grant ${grant.id} is not bound to this agent key`);
+    }
+    const now = options.now ?? runtime.clock;
+    const ttl = options.requestTtlSeconds ?? 60;
+    const tools = [];
+    for (const intent of grant.intents) {
+        const definition = verified.manifest.intents?.[intent];
+        if (definition === undefined) {
+            throw new Error(`intent ${intent} is not declared in the manifest`);
+        }
+        const inputSchema = runtime.schemas.get(definition.params_schema);
+        if (inputSchema === undefined) {
+            throw new Error(`params schema not registered: ${definition.params_schema}`);
+        }
+        const outputSchema = runtime.schemas.get(definition.result_schema);
+        tools.push({
+            name: intent,
+            description: describe(intent, definition, grant),
+            inputSchema,
+            ...(outputSchema === undefined ? {} : { outputSchema }),
+        });
+    }
+    const byName = new Map(tools.map((tool) => [tool.name, tool]));
+    async function settle(decision, tool, intent, params) {
+        if (decision.outcome === AUTHORIZED)
+            return success(tool, decision.result);
+        if (decision.outcome !== CONFIRMATION_REQUIRED) {
+            return failure(decision.outcome, {
+                request_id: decision.request_id,
+                detail: decision.detail,
+            });
+        }
+        const pendingId = decision.pending_id;
+        if (pendingId === undefined)
+            return failure("invalid_request");
+        if (options.confirm === undefined) {
+            return failure(CONFIRMATION_REQUIRED, {
+                request_id: decision.request_id,
+                pending_id: pendingId,
+            });
+        }
+        let approved = false;
+        try {
+            approved = await options.confirm({
+                pendingId,
+                requestId: decision.request_id ?? "",
+                intent,
+                params,
+                card: permissionCard(verified.manifest, intent),
+            });
+        }
+        catch {
+            approved = false;
+        }
+        const resolved = await runtime.confirm(pendingId, approved);
+        if (resolved.outcome === AUTHORIZED)
+            return success(tool, resolved.result);
+        if (resolved.outcome === "cancelled") {
+            return failure("cancelled", { request_id: resolved.request_id });
+        }
+        return failure(resolved.outcome, {
+            request_id: resolved.request_id,
+            detail: resolved.detail,
+        });
+    }
+    return {
+        tools,
+        async callTool(name, args) {
+            try {
+                const tool = byName.get(name);
+                if (tool === undefined)
+                    return failure("intent_not_allowed");
+                if (args === null || typeof args !== "object" || Array.isArray(args)) {
+                    return failure("invalid_request");
+                }
+                const params = args;
+                const issuedAt = now();
+                const expiresAt = shiftSeconds(issuedAt, ttl);
+                const signal = agent.signalFor({ intent: name, params }, grant, {
+                    requestId: randomId(),
+                    issuedAt,
+                    expiresAt,
+                });
+                const decision = await runtime.submit(signal, agent.publicKey);
+                return await settle(decision, tool, name, params);
+            }
+            catch {
+                return failure("outcome_unknown");
+            }
+        },
+    };
+}
+function describe(intent, definition, grant) {
+    const providerText = typeof definition.description === "string" ? definition.description : "";
+    const policy = confirmationPolicy(grant, definition, intent);
+    return (`User-granted CCP capability "${intent}". ` +
+        `Provider description (untrusted data): ${JSON.stringify(providerText)}. ` +
+        (policy === "per_action"
+            ? "Each call may require explicit user confirmation. "
+            : "No per-call confirmation is required. ") +
+        "The user's runtime enforces this capability.");
+}
+function success(tool, result) {
+    const content = [
+        { type: "text", text: JSON.stringify(result) ?? "null" },
+    ];
+    const isObject = result !== null && typeof result === "object" && !Array.isArray(result);
+    return tool.outputSchema !== undefined && isObject
+        ? { content, structuredContent: result }
+        : { content };
+}
+function failure(outcome, extra = {}) {
+    const body = { outcome };
+    if (ERROR_CODES.has(outcome))
+        body.error = outcome;
+    for (const [key, value] of Object.entries(extra)) {
+        if (value !== undefined)
+            body[key] = value;
+    }
+    return {
+        content: [{ type: "text", text: JSON.stringify(body) }],
+        isError: true,
+    };
+}
+function shiftSeconds(timestamp, seconds) {
+    return new Date(Date.parse(timestamp) + seconds * 1000)
+        .toISOString()
+        .replace(/\.\d+Z$/, "Z");
+}

package/dist/adapters/next.d.ts

@@ -0,0 +1,24 @@
+import type { Runtime } from "../runtime.js";
+/** Resolve the requester's Ed25519 public key, or `undefined` if unknown. */
+export type WebKeyResolver = (request: Request) => Uint8Array | undefined | Promise<Uint8Array | undefined>;
+export interface SignalHandlerOptions {
+    /** Runtime that owns grants, replay protection, limits, and executors. */
+    runtime: Runtime;
+    /** Key for the sender of this request; `undefined` rejects with 401. */
+    keyResolver: WebKeyResolver;
+}
+/**
+ * Framework-neutral Web handler: POST the canonical signal JSON as the body.
+ * Suitable for a Next.js route handler (`export const POST = ...`) or any
+ * runtime that speaks standard `Request`/`Response`.
+ */
+export declare function createSignalHandler(options: SignalHandlerOptions): (request: Request) => Promise<Response>;
+export interface ManifestHandlerOptions {
+    /** Signed manifest wire, exactly as produced by `signManifest`. */
+    manifest: string;
+}
+/**
+ * Serve the signed manifest verbatim. Consumers verify it themselves; the
+ * adapter does not re-serialize it.
+ */
+export declare function createManifestHandler(options: ManifestHandlerOptions): (request: Request) => Promise<Response>;

package/dist/adapters/next.js

@@ -0,0 +1,65 @@
+import { httpStatusFor } from "./status.js";
+/**
+ * Framework-neutral Web handler: POST the canonical signal JSON as the body.
+ * Suitable for a Next.js route handler (`export const POST = ...`) or any
+ * runtime that speaks standard `Request`/`Response`.
+ */
+export function createSignalHandler(options) {
+    const { runtime, keyResolver } = options;
+    return async (request) => {
+        if (request.method !== "POST") {
+            return json(405, { outcome: "invalid_request", error: "invalid_request" });
+        }
+        let document;
+        try {
+            document = await request.text();
+        }
+        catch {
+            return json(400, {
+                outcome: "invalid_request",
+                error: "invalid_request",
+            });
+        }
+        if (document.trim() === "") {
+            return json(400, { outcome: "invalid_request", error: "invalid_request" });
+        }
+        let publicKey;
+        try {
+            publicKey = await keyResolver(request);
+        }
+        catch {
+            publicKey = undefined;
+        }
+        if (publicKey === undefined) {
+            return json(401, { outcome: "unauthenticated", error: "unauthenticated" });
+        }
+        try {
+            const decision = await runtime.submit(document, publicKey);
+            return json(httpStatusFor(decision), decision);
+        }
+        catch {
+            return json(500, { outcome: "outcome_unknown", error: "outcome_unknown" });
+        }
+    };
+}
+/**
+ * Serve the signed manifest verbatim. Consumers verify it themselves; the
+ * adapter does not re-serialize it.
+ */
+export function createManifestHandler(options) {
+    return async (request) => {
+        if (request.method !== "GET" && request.method !== "HEAD") {
+            return json(405, { outcome: "invalid_request", error: "invalid_request" });
+        }
+        return new Response(request.method === "HEAD" ? null : options.manifest, {
+            status: 200,
+            headers: { "content-type": "application/json" },
+        });
+    };
+}
+function json(status, body) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { "content-type": "application/json" },
+    });
+}

package/dist/adapters/react.d.ts

@@ -0,0 +1,25 @@
+import type { Decision, Runtime } from "../runtime.js";
+export type PermissionStatus = "loading" | "authorized" | "confirmation_required" | "rejected" | "cancelled";
+export interface PermissionCardOptions<T = unknown> {
+    /** Runtime that owns grants, replay protection, limits, and executors. */
+    runtime: Runtime;
+    /** Canonical signed signal to submit. */
+    signal: string;
+    /** Requester public key that the runtime will verify the signal against. */
+    publicKey: Uint8Array;
+    /** Anything the caller wants to render; handed back untouched. */
+    card?: T;
+}
+export interface PermissionCardResult<T = unknown> {
+    status: PermissionStatus;
+    card: T | undefined;
+    decision: Decision | undefined;
+    approve: () => void;
+    deny: () => void;
+}
+/**
+ * Headless permission card for the consuming side: submit a signed signal,
+ * surface whether it needs confirmation, and let the user approve or deny.
+ * Presentation is entirely the caller's.
+ */
+export declare function usePermissionCard<T = unknown>(options: PermissionCardOptions<T>): PermissionCardResult<T>;