@auctra/sdk 0.3.5 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.6.0
+
+**Breaking — Authority Protocol public API (clean break, no legacy aliases)**
+
+- Removed public `createDelegation()` and `evaluateAction()`.
+- Canonical surface:
+  - `auctra.authority.issue()` / `verify()` / `delegate()` / `revoke()`
+  - `auctra.action.evaluate()` (dry-run) / `auctra.action.execute()` (enforce + evidence)
+  - `auctra.evidence.verify()`
+- REST: prefer `/v1/authorities` and `/v1/actions/{evaluate,execute}`.
+- `listAuthorities()` / `getAuthority()` replace `listDelegations()` / `getDelegation()`.
+
+## 0.5.0
+
+- Introduced Authority Protocol compatibility wrappers (`authority.*`) alongside legacy methods.
+
 ## 0.3.5
 
 - Align `AUCTRA_SDK_VERSION` and the `x-auctra-sdk-version` request header with the published package version.
@@ -32,17 +48,14 @@
 
 ## 0.3.0
 
-- Extend `evaluateAction` with trust infrastructure fields: `claimedIntentId`, `parentActionId`, `actor`, and `action` (target, description, riskLevel, metadata).
+- Extend action execution with trust infrastructure fields: `claimedIntentId`, `parentActionId`, `actor`, and `action` (target, description, riskLevel, metadata).
 - Return intelligence metadata on evaluation: authority validity, root intent validity, intent status, trust summary.
 - Add `listIntents`, `createIntent`, `getIntent`, `getAuthorityGraph`, `getActionEvaluation`, and `getRootIntentChain`.
 
 ## 0.2.1
 
 - Add complete response types for agents, delegations, action requests, policies, audit events, and API keys.
-- Add `getDelegation`, `createPolicy`, and `listApiKeys`.
 - Honor `Retry-After`, preserve caller cancellation, and validate client options.
-- Correct the REST example to use the API's snake_case contract.
-- Add package-level integration tests and npm provenance metadata.
 - Ship tested ESM and CommonJS entry points.
 
 ## 0.2.0

package/README.md

@@ -2,9 +2,7 @@
 
 [![npm version](https://img.shields.io/npm/v/@auctra/sdk.svg)](https://www.npmjs.com/package/@auctra/sdk)
 
-Official TypeScript SDK for [Auctra](https://auctra.tech) — authority infrastructure for AI agents.
-
-Evaluate every agent action against delegated authority and org policies **before** execution.
+Official TypeScript SDK for [Auctra](https://auctra.tech) — **Authority Protocol** for autonomous actors.
 
 | Resource                   | URL                                                           |
 | -------------------------- | ------------------------------------------------------------- |
@@ -20,11 +18,23 @@ Evaluate every agent action against delegated authority and org policies **befor
 npm install @auctra/sdk
 ```
 
-Both ESM (`import`) and CommonJS (`require`) entry points are included.
+## Canonical API (v0.6+)
+
+```text
+auctra.authority.issue()
+auctra.authority.verify()
+auctra.authority.delegate()
+auctra.authority.revoke()
 
-## Quick start — evaluateAction
+auctra.action.evaluate()   # dry-run Decision
+auctra.action.execute()    # enforce + Evidence
+
+auctra.evidence.verify()
+```
 
-Copy-paste this before any consequential agent side effect (payments, refunds, prod changes, CRM writes):
+There is **no** public `createDelegation()` or `evaluateAction()`.
+
+## Quick start
 
 ```typescript
 import { Auctra } from "@auctra/sdk";
@@ -35,129 +45,56 @@ const auctra = new Auctra({
   maxRetries: 2,
 });
 
-const decision = await auctra.evaluateAction(
+const agentId = "your-agent-uuid";
+const expiresAt = new Date(Date.now() + 30 * 864e5).toISOString();
+
+const { authority } = await auctra.authority.issue({
+  subject: agentId,
+  capabilities: ["send_payment"],
+  constraints: { maxAmount: 1200, currency: "USD" },
+  expiresAt,
+});
+
+// Dry-run
+await auctra.action.evaluate({
+  agentId,
+  actionType: "send_payment",
+  payload: { amount: 500, currency: "USD" },
+});
+
+// Production enforcement path
+const decision = await auctra.action.execute(
   {
-    agentId: "your-agent-uuid",
+    agentId,
     actionType: "send_payment",
-    payload: { amount: 1200, currency: "USD" },
+    payload: { amount: 500, currency: "USD" },
   },
   { idempotencyKey: crypto.randomUUID() },
 );
 
 if (decision.decision === "allowed") {
-  // proceed with action
+  // proceed
 } else if (decision.decision === "require_approval") {
-  // pause for human review in console.auctra.tech/console/reviews
   console.log(decision.reason, decision.action_request_id);
 } else {
   throw new Error(decision.reason);
 }
 ```
 
-### Trust infrastructure (0.3.5+)
-
-Declare why an action is happening and trace it back to human-approved intent:
+### Delegate (Child ⊆ Parent)
 
 ```typescript
-const intent = await auctra.createIntent({
-  title: "Renew SaaS contracts under $500/month for Q3",
-  description: "Procurement agent may renew eligible vendor subscriptions.",
+const child = await auctra.authority.delegate({
+  parent: authority.id,
+  subject: "logistics-agent-uuid",
+  capabilities: ["send_payment"],
+  constraints: { maxAmount: 300, currency: "USD" },
+  expiresAt,
 });
-
-const decision = await auctra.evaluateAction({
-  agentId: "your-agent-uuid",
-  actionType: "send_payment",
-  claimedIntentId: intent.intent.id,
-  intentAnchorToken: intent.intent.anchor_token,
-  action: {
-    target: "vendor:slack",
-    description: "Renew Slack Team plan",
-    riskLevel: "medium",
-  },
-  payload: { amount: 420, currency: "USD" },
-});
-
-console.log(decision.intelligence?.trust_summary);
-```
-
-### Production control behavior
-
-- Anchored intents require the matching `intentAnchorToken`; token possession never bypasses expiry, risk, action-type, target, or resource bounds.
-- Count and monetary velocity limits are reserved atomically before a decision. Reuse the same idempotency key for retries of the same business action.
-- Custom action types use lowercase namespaced IDs such as `healthcare.ehr.modify_prescription` and recursively validated JSON payload schemas. Breaking schemas should use a new namespaced action ID.
-- Proposed policies can be replayed against up to 10,000 recorded actions in the console before publication.
-- Restricting an agent quarantines its delegations; reactivation can restore only those quarantined grants. Emergency fleet control is available in the console.
-
-## Get an API key
-
-1. [Sign up](https://console.auctra.tech/auth/signup) and create an organization
-2. Register an agent and delegate scoped authority
-3. Open [API Keys](https://console.auctra.tech/console/api-keys) → **Create API key**
-4. Use a key with `write` permission for `evaluateAction`
-
-## API
-
-| Method                                      | Description                                                     |
-| ------------------------------------------- | --------------------------------------------------------------- |
-| `evaluateAction(input, options)`            | Idempotently check authority + trust trace before an agent acts |
-| `listIntents()`                             | List human-approved intents                                     |
-| `createIntent(input)`                       | Declare a new intent                                            |
-| `updateIntent(id, input)`                   | Update intent metadata or lifecycle status                      |
-| `updateIntentStatus(id, status)`            | Change intent lifecycle status                                  |
-| `getIntent(id)`                             | Get intent detail and linked actions                            |
-| `getAuthorityGraph()`                       | Fetch authority graph nodes and edges                           |
-| `createAuthorityEdge(input)`                | Add a validated authority edge                                  |
-| `getActionEvaluation(actionRequestId)`      | Get decision record for an action                               |
-| `getRootIntentChain(actionRequestId)`       | Get root human intent chain (trust trace)                       |
-| `listAgents()`                              | List registered agents                                          |
-| `createAgent(input)`                        | Register a new agent                                            |
-| `updateAgentStatus(id, input)`              | Restrict, suspend, reactivate, or mark an agent compromised     |
-| `deleteAgent(id)`                           | Remove an agent with no evaluated actions                       |
-| `getAgent(id)`                              | Get one registered agent                                        |
-| `listDelegations()`                         | List authority delegations                                      |
-| `getDelegation(id)`                         | Get one authority delegation                                    |
-| `createDelegation(input)`                   | Grant bounded authority                                         |
-| `revokeDelegation(id)`                      | Revoke a delegation                                             |
-| `listActionRequests()`                      | List recent evaluations                                         |
-| `approveActionRequest(id, approverUserId)`  | Approve as an accountable reviewer                              |
-| `rejectActionRequest(id, approverUserId)`   | Reject as an accountable reviewer                               |
-| `escalateActionRequest(id, approverUserId)` | Escalate as an accountable reviewer                             |
-| `listPolicies()`                            | List org policies                                               |
-| `createPolicy(input)`                       | Create an org policy                                            |
-| `listAuditEvents()`                         | List audit ledger events                                        |
-| `listApiKeys()`                             | List API key metadata                                           |
-
-## REST API (curl)
-
-```bash
-curl -X POST https://console.auctra.tech/v1/action-requests/evaluate \
-  -H "Authorization: Bearer YOUR_API_KEY" \
-  -H "Idempotency-Key: $(uuidgen)" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "agent_id": "your-agent-uuid",
-    "action_type": "send_payment",
-    "payload": { "amount": 100, "currency": "USD" }
-  }'
 ```
 
-The SDK applies bounded retries only to reads and idempotent evaluations. API failures throw
-`AuctraApiError` with `status`, optional structured `details`, and the server `requestId`.
-
-The machine-readable OpenAPI 3.1 contract is available at
-`https://console.auctra.tech/v1/openapi.json`.
-
-## Integration guides (blog)
-
-Stack-specific walkthroughs with console steps:
-
-| Stack             | Guide                                                            |
-| ----------------- | ---------------------------------------------------------------- |
-| LangChain + MCP   | https://auctra.tech/blog/langchain-mcp-authority-integration     |
-| OpenAI Agents SDK | https://auctra.tech/blog/openai-agents-sdk-authority-integration |
-| Vercel AI SDK     | https://auctra.tech/blog/vercel-ai-sdk-evaluate-action-hook      |
-| Stripe payments   | https://auctra.tech/blog/stripe-agent-payments-authority-layer   |
+Scope escalation is rejected by the protocol/runtime.
 
-## License
+## Docs
 
-MIT
+See https://auctra.tech/docs and `docs/AUTHORITY_PROTOCOL_ARCHITECTURE.md`.

package/dist/cjs/index.js

@@ -1,7 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Auctra = exports.AuctraApiError = exports.AUCTRA_SDK_VERSION = void 0;
-exports.AUCTRA_SDK_VERSION = "0.3.5";
+exports.verifyMandateArtifact = verifyMandateArtifact;
+exports.verifyDecisionArtifact = verifyDecisionArtifact;
+const node_crypto_1 = require("node:crypto");
+exports.AUCTRA_SDK_VERSION = "0.6.0";
 class AuctraApiError extends Error {
     status;
     code;
@@ -40,6 +43,69 @@ function wait(ms, signal) {
         }, { once: true });
     });
 }
+function canonicalizeJson(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalizeJson);
+    if (value && typeof value === "object" && !(value instanceof Date)) {
+        return Object.fromEntries(Object.entries(value)
+            .filter(([, child]) => child !== undefined)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, child]) => [key, canonicalizeJson(child)]));
+    }
+    if (value instanceof Date)
+        return value.toISOString();
+    return value;
+}
+function hashJson(value) {
+    return (0, node_crypto_1.createHash)("sha256")
+        .update(JSON.stringify(canonicalizeJson(value)))
+        .digest("hex");
+}
+function verifyEd25519(input) {
+    if (!input.publicKeyPem)
+        return false;
+    if (input.signature.alg !== "Ed25519")
+        return false;
+    return (0, node_crypto_1.verify)(null, Buffer.from(JSON.stringify(canonicalizeJson(input.payload))), typeof input.publicKeyPem === "string"
+        ? (0, node_crypto_1.createPublicKey)(input.publicKeyPem)
+        : input.publicKeyPem, Buffer.from(input.signature.value, "base64url"));
+}
+function verifyMandateArtifact(input) {
+    const expectedHash = hashJson(input.payload);
+    if (input.evidence.format !== "auctra-mandate.v0.1") {
+        return { valid: false, hashValid: false, signatureValid: false };
+    }
+    if (!input.evidence.signed) {
+        const hashValid = input.evidence.payload_hash === expectedHash;
+        return { valid: hashValid, hashValid, signatureValid: false };
+    }
+    const hashValid = input.evidence.payload_hash === expectedHash;
+    const signatureValid = hashValid &&
+        verifyEd25519({
+            payload: input.payload,
+            signature: input.evidence.signature,
+            publicKeyPem: input.publicKeyPem,
+        });
+    return { valid: hashValid && signatureValid, hashValid, signatureValid };
+}
+function verifyDecisionArtifact(input) {
+    const expectedHash = hashJson(input.payload);
+    if (input.evidence.format !== "auctra-evidence.v0.1") {
+        return { valid: false, hashValid: false, signatureValid: false };
+    }
+    if (!input.evidence.signed) {
+        const hashValid = input.evidence.payload_hash === expectedHash;
+        return { valid: hashValid, hashValid, signatureValid: false };
+    }
+    const hashValid = input.evidence.payload_hash === expectedHash;
+    const signatureValid = hashValid &&
+        verifyEd25519({
+            payload: input.payload,
+            signature: input.evidence.signature,
+            publicKeyPem: input.publicKeyPem,
+        });
+    return { valid: hashValid && signatureValid, hashValid, signatureValid };
+}
 class Auctra {
     apiKey;
     baseUrl;
@@ -115,15 +181,17 @@ class Auctra {
         }
         throw lastError;
     }
-    async evaluateAction(input, options = {}) {
-        const idempotencyKey = options.idempotencyKey ?? crypto.randomUUID();
-        return this.request("POST", "/v1/action-requests/evaluate", {
+    async executeOrEvaluateAction(input, options, mode) {
+        const idempotencyKey = mode === "execute" ? (options.idempotencyKey ?? crypto.randomUUID()) : options.idempotencyKey;
+        const path = mode === "execute" ? "/v1/actions/execute" : "/v1/actions/evaluate";
+        return this.request("POST", path, {
             agent_id: input.agentId,
             action_type: input.actionType,
             payload: input.payload ?? {},
             claimed_intent_id: input.claimedIntentId,
             intent_anchor_token: input.intentAnchorToken,
             parent_action_id: input.parentActionId,
+            dry_run: mode === "evaluate",
             actor: input.actor
                 ? {
                     id: input.actor.id,
@@ -139,7 +207,82 @@ class Auctra {
                     metadata: input.action.metadata,
                 }
                 : undefined,
-        }, { ...options, idempotencyKey });
+        }, mode === "execute" ? { ...options, idempotencyKey } : options);
+    }
+    async issueAuthorityRequest(input) {
+        const response = await this.request("POST", "/v1/authorities", {
+            agent_id: input.subject,
+            action_types: input.capabilities,
+            valid_until: input.expiresAt,
+            max_amount: input.constraints?.maxAmount,
+            max_count: input.constraints?.maxCount,
+            environment: input.constraints?.environment,
+            currency: input.constraints?.currency,
+            delegator_user_id: input.delegatorUserId ?? input.issuer,
+            parent_authority_id: input.parentAuthorityId,
+            max_delegation_depth: input.delegation?.maxDepth,
+            max_actions_per_window: input.maxActionsPerWindow
+                ? {
+                    count: input.maxActionsPerWindow.count,
+                    window_seconds: input.maxActionsPerWindow.windowSeconds,
+                    action_type: input.maxActionsPerWindow.actionType,
+                }
+                : undefined,
+            max_amount_per_window: input.maxAmountPerWindow
+                ? {
+                    amount: input.maxAmountPerWindow.amount,
+                    window_seconds: input.maxAmountPerWindow.windowSeconds,
+                }
+                : undefined,
+        });
+        const authorityId = response.authority_id ?? response.delegation.id;
+        const authority = response.authority ?? {
+            id: authorityId,
+            protocol_version: "0.1",
+            status: response.delegation.status,
+            payload_hash: "",
+            signed: false,
+            parent_authority_id: input.parentAuthorityId ?? null,
+            capabilities: input.capabilities,
+        };
+        return {
+            authority,
+            authority_id: authorityId,
+            delegation: response.delegation,
+        };
+    }
+    /**
+     * Authority Protocol — issue, verify, delegate (subset), revoke.
+     * There is no legacy createDelegation() surface.
+     */
+    get authority() {
+        return {
+            issue: (input) => this.issueAuthorityRequest(input),
+            verify: (payload, artifact) => this.request("POST", "/v1/authorities/verify", { payload, artifact }),
+            delegate: (input) => this.issueAuthorityRequest({
+                ...input,
+                parentAuthorityId: input.parent,
+            }),
+            revoke: (authorityId) => this.request("POST", `/v1/authorities/${encodeURIComponent(authorityId)}/revoke`, {}),
+        };
+    }
+    /**
+     * Action Protocol — evaluate (dry-run) vs execute (enforce + evidence).
+     * There is no legacy evaluateAction() surface.
+     */
+    get action() {
+        return {
+            evaluate: (input, options = {}) => this.executeOrEvaluateAction(input, options, "evaluate"),
+            execute: (input, options = {}) => this.executeOrEvaluateAction(input, options, "execute"),
+        };
+    }
+    get evidence() {
+        return {
+            verify: (payload, evidence) => this.request("POST", "/v1/evidence/verify", { payload, evidence }),
+        };
+    }
+    async verifyMandate(payload, evidence) {
+        return this.request("POST", "/v1/mandates/verify", { payload, evidence });
     }
     async listIntents() {
         return this.request("GET", "/v1/intents");
@@ -223,39 +366,11 @@ class Auctra {
     async deleteAgent(agentId) {
         return this.request("DELETE", `/v1/agents/${encodeURIComponent(agentId)}`);
     }
-    async listDelegations() {
-        return this.request("GET", "/v1/delegations");
+    async listAuthorities() {
+        return this.request("GET", "/v1/authorities");
     }
-    async getDelegation(delegationId) {
-        return this.request("GET", `/v1/delegations/${encodeURIComponent(delegationId)}`);
-    }
-    async createDelegation(input) {
-        return this.request("POST", "/v1/delegations", {
-            agent_id: input.agentId,
-            action_types: input.actionTypes,
-            valid_until: input.validUntil,
-            max_amount: input.maxAmount,
-            max_count: input.maxCount,
-            environment: input.environment,
-            currency: input.currency,
-            delegator_user_id: input.delegatorUserId,
-            max_actions_per_window: input.maxActionsPerWindow
-                ? {
-                    count: input.maxActionsPerWindow.count,
-                    window_seconds: input.maxActionsPerWindow.windowSeconds,
-                    action_type: input.maxActionsPerWindow.actionType,
-                }
-                : undefined,
-            max_amount_per_window: input.maxAmountPerWindow
-                ? {
-                    amount: input.maxAmountPerWindow.amount,
-                    window_seconds: input.maxAmountPerWindow.windowSeconds,
-                }
-                : undefined,
-        });
-    }
-    async revokeDelegation(delegationId) {
-        return this.request("POST", `/v1/delegations/${encodeURIComponent(delegationId)}/revoke`, {});
+    async getAuthority(authorityId) {
+        return this.request("GET", `/v1/authorities/${encodeURIComponent(authorityId)}`);
     }
     async listActionRequests() {
         return this.request("GET", "/v1/action-requests");
@@ -329,6 +444,12 @@ class Auctra {
     async listAuditEvents() {
         return this.request("GET", "/v1/audit-events");
     }
+    async getAuditEvent(auditEventId) {
+        return this.request("GET", `/v1/audit-events/${encodeURIComponent(auditEventId)}`);
+    }
+    async verifyAuditChain() {
+        return this.request("GET", "/v1/audit-events/verify");
+    }
     async listApiKeys() {
         return this.request("GET", "/v1/api-keys");
     }