@countersign/api-contract 0.1.0

package/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2026 Simon Crean. All rights reserved.
+
+This software and its source code (the "Software") are proprietary and
+confidential. No license, right, or permission is granted to use, copy, modify,
+merge, publish, distribute, sublicense, or sell copies of the Software, in whole
+or in part, except with the prior written permission of the copyright holder.
+
+Unauthorized copying, distribution, or use of the Software is strictly prohibited.
+
+NOTE (intent): Countersign follows an open-core direction. Specific "front door"
+components — the EnforcementProvider interface, the API contract, the SDK, and
+the MCP server (packages: core interface, api-contract, sdk, mcp) — are expected
+to be re-licensed under a permissive open-source license (e.g. MIT/Apache-2.0) to
+drive adoption, while the control-plane "brain" (policy compiler, ledger, anomaly
+engine, hosted Core) remains proprietary. Until that re-licensing is explicitly
+published, all rights are reserved.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED. IT IS A TESTNET-ONLY PROOF AND HAS NOT BEEN SECURITY-AUDITED. DO NOT USE
+WITH MAINNET FUNDS OR IN PRODUCTION CUSTODY OF REAL ASSETS.

package/dist/index.cjs

@@ -0,0 +1,30 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// index.ts
+var index_exports = {};
+__export(index_exports, {
+  WS_PATH: () => WS_PATH
+});
+module.exports = __toCommonJS(index_exports);
+var WS_PATH = "/events";
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  WS_PATH
+});

package/dist/index.d.ts

@@ -0,0 +1,426 @@
+import { z } from 'zod';
+
+/**
+ * Branded identifier types. Brands prevent accidentally passing an AgentId where a
+ * ProviderId is expected — a real class of bug once three backends are in play.
+ *
+ * These are zero-cost at runtime (just strings); the brand exists only in the type system.
+ */
+type ProviderId = string & {
+    readonly __brand: "ProviderId";
+};
+type AgentId = string & {
+    readonly __brand: "AgentId";
+};
+type SessionId = string & {
+    readonly __brand: "SessionId";
+};
+/** chain / network / venue, e.g. "base-sepolia" */
+type Venue = string;
+
+/**
+ * The ONE declarative policy an operator writes. The compiler lowers it to each backend's
+ * native controls; the evaluator (./evaluate.ts) is its executable semantics. Keep this small
+ * and backend-neutral — every field must mean the same thing on every rail.
+ */
+declare const UnifiedPolicySchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    /** Asset the caps apply to, e.g. "USDC". */
+    asset: z.ZodString;
+    /** Max value of a single spend (base units). Absent = no per-tx cap. */
+    perTxCap: z.ZodOptional<z.ZodString>;
+    /** Max cumulative spend per rolling day (base units). Absent = no daily cap. */
+    dailyCap: z.ZodOptional<z.ZodString>;
+    /**
+     * Counterparty allowlist. ABSENT = any counterparty allowed (subject to other rules).
+     * PRESENT-but-EMPTY ([]) = deny everything (an explicit "allow nobody" sentinel).
+     */
+    allowlist: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /** Counterparty denylist — always wins over the allowlist. */
+    denylist: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /** Spends STRICTLY ABOVE this require human approval before signing (base units). */
+    approvalThreshold: z.ZodOptional<z.ZodString>;
+    /** Hard kill — deny everything regardless of the rest. */
+    frozen: z.ZodOptional<z.ZodBoolean>;
+    /** Allowed venues/chains by name (see ./venues.ts). Absent = any venue. */
+    venues: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strict", z.ZodTypeAny, {
+    schemaVersion: 1;
+    asset: string;
+    perTxCap?: string | undefined;
+    dailyCap?: string | undefined;
+    allowlist?: string[] | undefined;
+    denylist?: string[] | undefined;
+    approvalThreshold?: string | undefined;
+    frozen?: boolean | undefined;
+    venues?: string[] | undefined;
+}, {
+    schemaVersion: 1;
+    asset: string;
+    perTxCap?: string | undefined;
+    dailyCap?: string | undefined;
+    allowlist?: string[] | undefined;
+    denylist?: string[] | undefined;
+    approvalThreshold?: string | undefined;
+    frozen?: boolean | undefined;
+    venues?: string[] | undefined;
+}>;
+type UnifiedPolicy = z.infer<typeof UnifiedPolicySchema>;
+
+/**
+ * Countersign Core — EnforcementProvider
+ * Location in repo: packages/core/src/enforcement-provider.ts
+ *
+ * THE KEYSTONE ABSTRACTION.
+ *
+ * Every wallet backend (Coinbase Agentic Wallets, Turnkey, Openfort, ...) is wrapped
+ * in an adapter that implements this interface. The freeze controller, policy compiler,
+ * ledger, and API depend ONLY on this interface — never on a vendor SDK directly.
+ *
+ * Enforcement is NATIVE to each backend (MPC/TEE policy, session caps, or on-chain rules).
+ * Countersign's job across all of them is the same four verbs:
+ *   1. APPLY a unified policy (each adapter compiles it to the backend's native controls)
+ *   2. FREEZE (revoke/zero/flip — a hard stop)
+ *   3. (optionally) APPROVE inline, for backends that can gate a signature on approval
+ *   4. OBSERVE (stream events into the tamper-evident ledger)
+ *
+ * FAIL-CLOSED CONTRACT (non-negotiable):
+ *   - `freeze()` MUST be idempotent and MUST hard-stop. If an adapter cannot CONFIRM the
+ *     stop, it returns `{ confirmed: false }` (or throws). The controller then treats the
+ *     agent as STILL DANGEROUS and escalates (alert + retry +, if available, on-chain guard).
+ *   - `applyPolicy()` that cannot confirm the new policy is live MUST throw — the caller
+ *     responds by freezing, never by assuming the looser/old policy is fine.
+ *   - No decision / no backend response => the action does NOT execute. Default deny.
+ */
+
+type EnforcementMode = "native-session-caps" | "pre-sign-policy" | "onchain-policy";
+interface ActionRequest {
+    id: string;
+    agentId: AgentId;
+    kind: "transfer" | "contract-call" | "x402-payment";
+    asset: string;
+    amount: string;
+    counterparty?: string;
+    venue: Venue;
+    raw?: unknown;
+    ts: number;
+}
+interface FreezeResult {
+    confirmed: boolean;
+    frozenAgents: AgentId[];
+    mechanism: "session-revoked" | "caps-zeroed" | "onchain-guard" | "policy-deny";
+    at: number;
+}
+
+/**
+ * The canonical Countersign event vocabulary. EVERY one of these is appended, in order, to the
+ * hash-chained ledger — the audit artifact and source of truth (prime directive #5).
+ *
+ * Two origins:
+ *  - provider-origin events (mirror the adapter's ProviderEvent): what each backend did.
+ *  - controller-origin events: the cross-vendor freeze orchestration (the moat made auditable).
+ *
+ * The ledger package stores these generically (payload-agnostic, hash-chained). Core owns the
+ * vocabulary; the ledger owns durability. That split keeps core free of any storage dependency.
+ */
+
+type FreezeMechanism = FreezeResult["mechanism"];
+/** Per-provider outcome of a freeze attempt. unconfirmed AND failed are BOTH "still dangerous". */
+type FreezeOutcome = "confirmed" | "unconfirmed" | "failed";
+type LedgerEvent = {
+    kind: "action_requested";
+    providerId: ProviderId;
+    agentId: AgentId;
+    action: ActionRequest;
+    ts: number;
+} | {
+    kind: "action_allowed";
+    providerId: ProviderId;
+    agentId: AgentId;
+    action: ActionRequest;
+    policyId: string;
+    ts: number;
+} | {
+    kind: "action_blocked";
+    providerId: ProviderId;
+    agentId: AgentId;
+    action: ActionRequest;
+    policyId: string;
+    reason: string;
+    ts: number;
+} | {
+    kind: "policy_applied";
+    providerId: ProviderId;
+    agentId: AgentId;
+    policyId: string;
+    ts: number;
+} | {
+    kind: "session_revoked";
+    providerId: ProviderId;
+    agentId: AgentId;
+    sessionId?: SessionId | undefined;
+    ts: number;
+} | {
+    kind: "needs_approval";
+    providerId: ProviderId;
+    agentId: AgentId;
+    action: ActionRequest;
+    approvalToken: string;
+    reason: string;
+    ts: number;
+} | {
+    kind: "approval_resolved";
+    providerId: ProviderId;
+    agentId: AgentId;
+    approvalToken: string;
+    decision: "approved" | "denied";
+    ts: number;
+} | {
+    kind: "freeze_requested";
+    freezeId: string;
+    targets: ProviderId[];
+    reason: string;
+    ts: number;
+} | {
+    kind: "freeze_result";
+    freezeId: string;
+    providerId: ProviderId;
+    mode: EnforcementMode;
+    outcome: FreezeOutcome;
+    mechanism?: FreezeMechanism | undefined;
+    latencyMs: number;
+    detail?: string | undefined;
+    ts: number;
+} | {
+    kind: "freeze_partial";
+    freezeId: string;
+    confirmed: ProviderId[];
+    dangerous: ProviderId[];
+    ts: number;
+} | {
+    kind: "escalation_revoke_session";
+    freezeId: string;
+    providerId: ProviderId;
+    agentId: AgentId;
+    outcome: "confirmed" | "failed";
+    latencyMs: number;
+    ts: number;
+} | {
+    kind: "freeze_resolved";
+    freezeId: string;
+    providerCount: number;
+    windowMs: number;
+    ts: number;
+} | {
+    kind: "still_dangerous";
+    freezeId: string;
+    dangerous: {
+        providerId: ProviderId;
+        agentId?: AgentId | undefined;
+    }[];
+    windowMs: number;
+    ts: number;
+} | {
+    kind: "anomaly_detected";
+    agentId: AgentId;
+    providerId?: ProviderId | undefined;
+    rule: "velocity" | "blocked_burst" | "new_counterparty" | "cumulative";
+    detail: string;
+    action: "alert" | "freeze";
+    ts: number;
+} | {
+    kind: "error";
+    providerId?: ProviderId | undefined;
+    agentId?: AgentId | undefined;
+    message: string;
+    ts: number;
+} | {
+    kind: "backend_connected";
+    providerId: ProviderId;
+    ts: number;
+} | {
+    kind: "ledger_anchored";
+    index: number;
+    rowHash: string;
+    ref?: string | undefined;
+    ts: number;
+};
+
+/**
+ * The cross-venue freeze controller — the headline capability.
+ *
+ * ONE action fans out a hard stop to every connected backend CONCURRENTLY and returns a
+ * complete, audited verdict in well under a second. This is the one thing no single wallet
+ * vendor can do, because each only governs its own rail.
+ *
+ * Fail-closed contract (prime directive #3):
+ *   - Every provider's verdict is kept (we never drop one because another failed).
+ *   - A freeze that resolves { confirmed: false }, throws, or times out is treated as
+ *     STILL DANGEROUS — never as "probably fine".
+ *   - Unconfirmed providers are escalated to the harder kill (revokeSession per agent).
+ *     If that also fails, the agent is surfaced as still-dangerous in the ledger + report.
+ */
+
+interface PerProviderFreeze {
+    providerId: ProviderId;
+    mode: EnforcementMode;
+    outcome: FreezeOutcome;
+    mechanism?: FreezeMechanism | undefined;
+    /** true if the freeze confirmed OR escalation (revokeSession) succeeded. */
+    stopped: boolean;
+    dangerousAgents: AgentId[];
+    latencyMs: number;
+}
+interface FreezeReport {
+    freezeId: string;
+    requestedAt: number;
+    windowMs: number;
+    allStopped: boolean;
+    providers: PerProviderFreeze[];
+}
+
+/**
+ * @countersign/api-contract — the SINGLE SOURCE OF TRUTH for the Client<->Core wire interface.
+ * The Flutter client is generated from this (openapi.yaml for REST + these types for the ws stream),
+ * so the approve / freeze / ledger contract never drifts between Dart and TS.
+ *
+ * The language boundary (Dart client / TS core) is the trust boundary: a compromised client can
+ * still only call these endpoints — it holds no keys and cannot weaken policy or move funds.
+ */
+
+declare const WS_PATH = "/events";
+interface ProviderHealth {
+    id: string;
+    mode: EnforcementMode;
+    healthy: boolean;
+    detail?: string;
+}
+interface HealthResponse {
+    ok: boolean;
+    providers: ProviderHealth[];
+}
+interface AgentDTO {
+    providerId: string;
+    agentId: string;
+    wallet: string;
+    venue: string;
+    mode: EnforcementMode;
+}
+interface AgentsResponse {
+    agents: AgentDTO[];
+}
+interface ApplyPolicyRequest {
+    /** Target a single agent, or omit to apply to every agent on every backend. */
+    agentId?: string;
+    policy: UnifiedPolicy;
+}
+interface ApplyPolicyResult {
+    applied: {
+        providerId: string;
+        agentId: string;
+        policyId: string;
+    }[];
+    /** Backends that could not confirm the policy — fail-closed: these are NOT live. */
+    failed: {
+        providerId: string;
+        agentId: string;
+        error: string;
+    }[];
+}
+interface FreezeRequest {
+    reason?: string;
+}
+type FreezeResponse = FreezeReport;
+/**
+ * The agent-facing pre-flight guard: an agent asks Countersign "should I make this spend?" BEFORE it
+ * touches the wallet. Countersign answers from the unified policy and records the decision. This is the
+ * call that gets made on every transaction — the data flywheel.
+ */
+interface EvaluateRequest {
+    agentId: string;
+    amount: string;
+    asset: string;
+    counterparty?: string;
+    venue: string;
+}
+interface EvaluateResponse {
+    outcome: "allow" | "deny" | "needs_approval";
+    reason?: string;
+    approvalToken?: string;
+    policyId: string;
+}
+/** A spend held pending human approval (the Turnkey-style consensus path). */
+interface PendingApprovalDTO {
+    approvalToken: string;
+    agentId: string;
+    providerId: string;
+    amount: string;
+    asset: string;
+    counterparty?: string;
+    venue: string;
+    reason: string;
+    ts: number;
+}
+interface ApprovalsResponse {
+    approvals: PendingApprovalDTO[];
+}
+interface ApproveRequest {
+    approvalToken: string;
+}
+interface DenyRequest {
+    approvalToken: string;
+    reason?: string;
+}
+interface ApprovalResolution {
+    outcome: "approved" | "denied";
+    agentId: string;
+    approvalToken: string;
+    reason?: string;
+}
+interface LedgerRecordDTO {
+    index: number;
+    prevHash: string;
+    payloadHash: string;
+    rowHash: string;
+    payload: LedgerEvent;
+}
+interface LedgerResponse {
+    records: LedgerRecordDTO[];
+    /** Result of re-verifying the hash chain (and signatures, if signed) at read time. */
+    verified: boolean;
+    /** Ed25519 public key (base64 SPKI) to independently verify the signed ledger, if signed. */
+    publicKey?: string;
+}
+/** Messages the Core pushes to the client over the websocket. */
+type WsServerMessage = {
+    type: "hello";
+    providers: ProviderHealth[];
+} | {
+    type: "ledger_append";
+    record: LedgerRecordDTO;
+} | {
+    type: "freeze_report";
+    report: FreezeReport;
+};
+/**
+ * The operations the front door exposes — the single abstraction the SDK client, the embedded
+ * in-process Core, the MCP tools, and the x402 guard all program against. `CountersignClient` (HTTP) and
+ * the local adapter both implement this, so callers don't care whether the Core is remote or embedded.
+ */
+interface CountersignApi {
+    health(): Promise<HealthResponse>;
+    agents(): Promise<AgentsResponse>;
+    applyPolicy(req: ApplyPolicyRequest): Promise<ApplyPolicyResult>;
+    evaluate(req: EvaluateRequest): Promise<EvaluateResponse>;
+    approvals(): Promise<ApprovalsResponse>;
+    approve(req: ApproveRequest): Promise<ApprovalResolution>;
+    deny(req: DenyRequest): Promise<ApprovalResolution>;
+    freeze(req?: FreezeRequest): Promise<FreezeResponse>;
+    unfreeze(): Promise<{
+        ok: boolean;
+    }>;
+    ledger(): Promise<LedgerResponse>;
+}
+
+export { WS_PATH };
+export type { AgentDTO, AgentsResponse, ApplyPolicyRequest, ApplyPolicyResult, ApprovalResolution, ApprovalsResponse, ApproveRequest, CountersignApi, DenyRequest, EvaluateRequest, EvaluateResponse, FreezeRequest, FreezeResponse, HealthResponse, LedgerRecordDTO, LedgerResponse, PendingApprovalDTO, ProviderHealth, WsServerMessage };

package/dist/index.js

@@ -0,0 +1,5 @@
+// index.ts
+var WS_PATH = "/events";
+export {
+  WS_PATH
+};

package/openapi.yaml

@@ -0,0 +1,272 @@
+openapi: 3.1.0
+info:
+  title: Countersign Core API
+  version: 0.1.0
+  description: >
+    The neutral control plane the (key-less) Countersign client talks to. The client renders state and
+    fires approve / freeze; all crypto and vendor SDK weight lives behind this API. Source of truth
+    for the generated Dart client. The websocket event stream is typed in index.ts (WsServerMessage).
+servers:
+  - url: http://localhost:8080
+paths:
+  /health:
+    get:
+      summary: Liveness + per-backend health
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/HealthResponse" }
+  /agents:
+    get:
+      summary: List provisioned agents across all backends
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/AgentsResponse" }
+  /policy:
+    post:
+      summary: Compile + apply one unified policy across backends (fail-closed)
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/ApplyPolicyRequest" }
+      responses:
+        "200":
+          description: Per-backend apply results
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/ApplyPolicyResult" }
+  /freeze:
+    post:
+      summary: The kill switch — freeze every agent on every backend, concurrently
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/FreezeRequest" }
+      responses:
+        "200":
+          description: Aggregate freeze report (sub-second, fail-closed)
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/FreezeReport" }
+  /evaluate:
+    post:
+      summary: Pre-flight spend guard — ask Countersign whether a spend is allowed before touching the wallet
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/EvaluateRequest" }
+      responses:
+        "200":
+          description: The decision (allow / deny / needs_approval), also recorded in the ledger
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/EvaluateResponse" }
+  /approvals:
+    get:
+      summary: Spends currently held pending human approval
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/ApprovalsResponse" }
+  /approve:
+    post:
+      summary: Approve a pending spend (rejected if the system is frozen — fail-closed)
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { type: object, required: [approvalToken], properties: { approvalToken: { type: string } } }
+      responses:
+        "200":
+          description: Resolution
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/ApprovalResolution" }
+  /deny:
+    post:
+      summary: Deny a pending spend
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { type: object, required: [approvalToken], properties: { approvalToken: { type: string }, reason: { type: string } } }
+      responses:
+        "200":
+          description: Resolution
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/ApprovalResolution" }
+  /ledger:
+    get:
+      summary: The append-only, hash-chained audit ledger (re-verified at read time)
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/LedgerResponse" }
+components:
+  schemas:
+    ProviderHealth:
+      type: object
+      required: [id, mode, healthy]
+      properties:
+        id: { type: string }
+        mode: { type: string, enum: [native-session-caps, pre-sign-policy, onchain-policy] }
+        healthy: { type: boolean }
+        detail: { type: string }
+    HealthResponse:
+      type: object
+      required: [ok, providers]
+      properties:
+        ok: { type: boolean }
+        providers: { type: array, items: { $ref: "#/components/schemas/ProviderHealth" } }
+    AgentsResponse:
+      type: object
+      required: [agents]
+      properties:
+        agents:
+          type: array
+          items:
+            type: object
+            required: [providerId, agentId, wallet, venue, mode]
+            properties:
+              providerId: { type: string }
+              agentId: { type: string }
+              wallet: { type: string }
+              venue: { type: string }
+              mode: { type: string }
+    UnifiedPolicy:
+      type: object
+      required: [schemaVersion, asset]
+      properties:
+        schemaVersion: { type: integer, enum: [1] }
+        asset: { type: string }
+        perTxCap: { type: string, description: base units }
+        dailyCap: { type: string, description: base units }
+        allowlist: { type: array, items: { type: string } }
+        denylist: { type: array, items: { type: string } }
+        approvalThreshold: { type: string, description: base units }
+        frozen: { type: boolean }
+        venues: { type: array, items: { type: string } }
+    ApplyPolicyRequest:
+      type: object
+      required: [policy]
+      properties:
+        agentId: { type: string }
+        policy: { $ref: "#/components/schemas/UnifiedPolicy" }
+    ApplyPolicyResult:
+      type: object
+      required: [applied, failed]
+      properties:
+        applied:
+          type: array
+          items:
+            type: object
+            properties:
+              providerId: { type: string }
+              agentId: { type: string }
+              policyId: { type: string }
+        failed:
+          type: array
+          items:
+            type: object
+            properties:
+              providerId: { type: string }
+              agentId: { type: string }
+              error: { type: string }
+    FreezeRequest:
+      type: object
+      properties:
+        reason: { type: string }
+    EvaluateRequest:
+      type: object
+      required: [agentId, amount, asset, venue]
+      properties:
+        agentId: { type: string }
+        amount: { type: string, description: base units }
+        asset: { type: string }
+        counterparty: { type: string }
+        venue: { type: string }
+    EvaluateResponse:
+      type: object
+      required: [outcome, policyId]
+      properties:
+        outcome: { type: string, enum: [allow, deny, needs_approval] }
+        reason: { type: string }
+        approvalToken: { type: string }
+        policyId: { type: string }
+    ApprovalsResponse:
+      type: object
+      required: [approvals]
+      properties:
+        approvals:
+          type: array
+          items:
+            type: object
+            required: [approvalToken, agentId, providerId, amount, asset, venue, reason, ts]
+            properties:
+              approvalToken: { type: string }
+              agentId: { type: string }
+              providerId: { type: string }
+              amount: { type: string }
+              asset: { type: string }
+              counterparty: { type: string }
+              venue: { type: string }
+              reason: { type: string }
+              ts: { type: integer }
+    ApprovalResolution:
+      type: object
+      required: [outcome, agentId, approvalToken]
+      properties:
+        outcome: { type: string, enum: [approved, denied] }
+        agentId: { type: string }
+        approvalToken: { type: string }
+        reason: { type: string }
+    FreezeReport:
+      type: object
+      required: [freezeId, requestedAt, windowMs, allStopped, providers]
+      properties:
+        freezeId: { type: string }
+        requestedAt: { type: integer }
+        windowMs: { type: integer }
+        allStopped: { type: boolean }
+        providers:
+          type: array
+          items:
+            type: object
+            properties:
+              providerId: { type: string }
+              mode: { type: string }
+              outcome: { type: string, enum: [confirmed, unconfirmed, failed] }
+              mechanism: { type: string }
+              stopped: { type: boolean }
+              dangerousAgents: { type: array, items: { type: string } }
+              latencyMs: { type: integer }
+    LedgerResponse:
+      type: object
+      required: [records, verified]
+      properties:
+        verified: { type: boolean }
+        publicKey: { type: string, description: Ed25519 public key (base64) to independently verify the signed ledger }
+        records:
+          type: array
+          items:
+            type: object
+            required: [index, prevHash, payloadHash, rowHash, payload]
+            properties:
+              index: { type: integer }
+              prevHash: { type: string }
+              payloadHash: { type: string }
+              rowHash: { type: string }
+              payload: { type: object, additionalProperties: true }

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@countersign/api-contract",
+  "version": "0.1.0",
+  "description": "Countersign Core API contract — typed REST + ws schema and OpenAPI spec for the cross-vendor agent-spend control plane.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./openapi": "./openapi.yaml"
+  },
+  "files": [
+    "dist",
+    "openapi.yaml"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/countersign-network/countersign.git",
+    "directory": "api-contract"
+  },
+  "homepage": "https://countersign.network",
+  "keywords": [
+    "countersign",
+    "ai-agents",
+    "agent-payments",
+    "openapi",
+    "policy",
+    "freeze"
+  ],
+  "dependencies": {
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "@countersign/core": "0.0.0",
+    "@countersign/policy": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p ../tsconfig.dts.json && tsup && rollup -c rollup.dts.config.mjs"
+  },
+  "module": "./dist/index.js"
+}