@countersign/api-contract - npm Package Compare versions

Comparing version 0.3.1 to 0.4.0

dist/index.d.ts

@@ -23,15 +23,58 @@ import { z } from 'zod';
  * The declarative policy CONTRACT — the ONE policy shape an operator writes (caps, allow/deny
- * lists, approval threshold, freeze) plus its validators/builders. This is the PUBLIC part of the
- * policy story, so it lives in @countersign/core (the open interface package): the front door can
- * describe and validate a policy WITHOUT the proprietary compiler. The compiler that lowers this
- * shape to each backend's native controls — the IP — lives in @countersign/policy.
+ * lists, approval threshold, freeze, venue rules) plus its validators/builders. This is the PUBLIC
+ * part of the policy story, so it lives in @countersign/core (the open interface package): the
+ * front door can describe and validate a policy WITHOUT the proprietary compiler. The compiler
+ * that lowers this shape to each backend's native controls — the IP — lives in @countersign/policy.
+ *
+ * Two schema generations are accepted on input; the system operates on ONE canonical shape:
+ *   v1 (schemaVersion 1): `venues` is a plain allow-array of venue names.
+ *   v2 (schemaVersion 2): `venues` is a rules block — allow/deny lists, marketplace listing
+ *       allowlist, and per-venue caps (Roadmap v2, Phase 1).
+ * `parsePolicy`/`normalizePolicy` migrate v1 → v2 (a v1 venues array IS a v2 allow list), so the
+ * evaluator, the compiler, and every consumer see only the canonical v2 shape. v1 stays accepted
+ * forever: stored tenant policies and published-SDK callers re-parse on every boot/apply.
  */
 
-/**
- * The ONE declarative policy an operator writes. The compiler lowers it to each backend's
- * native controls; the evaluator (@countersign/policy) 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<{
+/** Schema v2 — `venues` is a rules block (allow/deny, listing allowlist, per-venue caps). */
+declare const UnifiedPolicyV2Schema: z.ZodObject<{
+    venues: z.ZodOptional<z.ZodObject<{
+        allow: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        deny: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        listingAllowlist: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        perVenueCaps: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            perTx: z.ZodOptional<z.ZodString>;
+            dailyRolling: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>;
+    asset: z.ZodString;
+    perTxCap: z.ZodOptional<z.ZodString>;
+    dailyCap: z.ZodOptional<z.ZodString>;
+    allowlist: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    denylist: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    approvalThreshold: z.ZodOptional<z.ZodString>;
+    frozen: z.ZodOptional<z.ZodBoolean>;
+    schemaVersion: z.ZodLiteral<2>;
+}, z.core.$strict>;
+type UnifiedPolicyV2 = z.infer<typeof UnifiedPolicyV2Schema>;
+/** What operators may SUBMIT: either schema generation. */
+declare const UnifiedPolicySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    venues: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    asset: z.ZodString;
+    perTxCap: z.ZodOptional<z.ZodString>;
+    dailyCap: z.ZodOptional<z.ZodString>;
+    allowlist: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    denylist: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    approvalThreshold: z.ZodOptional<z.ZodString>;
+    frozen: z.ZodOptional<z.ZodBoolean>;
     schemaVersion: z.ZodLiteral<1>;
+}, z.core.$strict>, z.ZodObject<{
+    venues: z.ZodOptional<z.ZodObject<{
+        allow: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        deny: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        listingAllowlist: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        perVenueCaps: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            perTx: z.ZodOptional<z.ZodString>;
+            dailyRolling: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>;
     asset: z.ZodString;
@@ -44,5 +87,11 @@ perTxCap: z.ZodOptional<z.ZodString>;
     frozen: z.ZodOptional<z.ZodBoolean>;
-    venues: z.ZodOptional<z.ZodArray<z.ZodString>>;
-}, z.core.$strict>;
-type UnifiedPolicy = z.infer<typeof UnifiedPolicySchema>;
+    schemaVersion: z.ZodLiteral<2>;
+}, z.core.$strict>], "schemaVersion">;
+/** Either accepted input generation. Use this for API/SDK request types. */
+type UnifiedPolicyInput = z.infer<typeof UnifiedPolicySchema>;
+/**
+ * The CANONICAL policy shape the system operates on (v2). Everything past the parse boundary —
+ * evaluator, compiler, providers, stores — sees only this.
+ */
+type UnifiedPolicy = UnifiedPolicyV2;
 
@@ -84,2 +133,4 @@ /**
     venue: Venue;
+    /** Marketplace listing being paid (x402 Bazaar / Agentic.Market pin), when known — for the ledger. */
+    listingId?: string;
     raw?: unknown;
@@ -317,6 +368,15 @@ ts: number;
 }
+/** GET /policies — the tenant's applied policies (canonical v2 shapes). */
+interface PoliciesResponse {
+    policies: {
+        agentId: string;
+        policyId: string;
+        policy: UnifiedPolicy;
+    }[];
+}
 interface ApplyPolicyRequest {
     /** Target a single agent, or omit to apply to every agent on every backend. */
     agentId?: string;
-    policy: UnifiedPolicy;
+    /** Either schema generation is accepted; the Core normalizes to canonical v2 on receipt. */
+    policy: UnifiedPolicyInput;
 }
@@ -357,2 +417,4 @@ interface ApplyPolicyResult {
     venue: string;
+    /** Marketplace listing being paid (x402 Bazaar / Agentic.Market pin), when known. */
+    listingId?: string;
 }
@@ -407,2 +469,33 @@ interface EvaluateResponse {
 }
+/** RFC 6962 audit path (P1.6) — verify offline with `@countersign/verify`. */
+interface MerkleProofDTO {
+    /** 0-based index of the proven row. */
+    index: number;
+    /** Tree size (row count) the proof was computed against. */
+    size: number;
+    /** Audit path, deepest-first; `side` = which side the SIBLING sits on when re-hashing upward. */
+    siblings: {
+        hash: string;
+        side: "left" | "right";
+    }[];
+}
+/** A commitment to the ledger's size, head hash, and Merkle root at a point in time. */
+interface LedgerCheckpointDTO {
+    size: number;
+    headHash: string;
+    /** RFC 6962 Merkle root over rowHashes[0..size). */
+    merkleRoot?: string;
+    ts: number;
+    /** Ed25519 signature over `cs-checkpoint:v2:<size>:<headHash>:<merkleRoot>` (v1 omits the root). */
+    signature?: string;
+    witnessCosignature?: string;
+}
+/** GET /ledger/proof/:index — everything a third party needs to verify one row offline. */
+interface LedgerProofResponse {
+    record: LedgerRecordDTO;
+    proof: MerkleProofDTO;
+    checkpoint: LedgerCheckpointDTO;
+    /** Ledger signing public key (base64 SPKI), when the ledger is signed. */
+    publicKey?: string;
+}
 /** Messages the Core pushes to the client over the websocket. */
@@ -430,2 +523,4 @@ type WsServerMessage = {
     applyPolicy(req: ApplyPolicyRequest): Promise<ApplyPolicyResult>;
+    /** The tenant's applied policies (P1.4 — feeds countersign_list_approved_venues). */
+    policies(): Promise<PoliciesResponse>;
     evaluate(req: EvaluateRequest): Promise<EvaluateResponse>;
@@ -443,2 +538,2 @@ approvals(): Promise<ApprovalsResponse>;
 export { WS_PATH };
-export type { AgentDTO, AgentsResponse, ApplyPolicyRequest, ApplyPolicyResult, ApprovalResolution, ApprovalsResponse, ApproveRequest, CountersignApi, DenyRequest, EnforcementResponse, EvaluateRequest, EvaluateResponse, FieldEnforcement, FreezeRequest, FreezeResponse, HealthResponse, LedgerRecordDTO, LedgerResponse, PendingApprovalDTO, ProviderEnforcement, ProviderHealth, UnfreezeRequest, WsServerMessage };
+export type { AgentDTO, AgentsResponse, ApplyPolicyRequest, ApplyPolicyResult, ApprovalResolution, ApprovalsResponse, ApproveRequest, CountersignApi, DenyRequest, EnforcementResponse, EvaluateRequest, EvaluateResponse, FieldEnforcement, FreezeRequest, FreezeResponse, HealthResponse, LedgerCheckpointDTO, LedgerProofResponse, LedgerRecordDTO, LedgerResponse, MerkleProofDTO, PendingApprovalDTO, PoliciesResponse, ProviderEnforcement, ProviderHealth, UnfreezeRequest, WsServerMessage };

package.json

 {
   "name": "@countersign/api-contract",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Countersign Core API contract — typed REST + ws schema and OpenAPI spec for the cross-vendor agent-spend control plane.",
@@ -5,0 +5,0 @@ "license": "Apache-2.0",

No alert changes

Improved metrics

Total package byte prevSize

42807

11.89%

Lines of code

554

20.7%

No dependency changes