@auctra/sdk 0.3.5 → 0.6.1

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.6.1
+
+**Stage 1.0 — SDK + Runtime convergence packaging**
+
+- Modularize the client under `authority` / `action` / `evidence` modules (same public API as 0.6.0).
+- Align with Stage 1.0 cloud surface: authorities, `action.evaluate` / `action.execute`, evidence verify.
+- No public API break from 0.6.0.
+
+## 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 +56,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/action.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/artifacts.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuctraApiError = void 0;
+exports.retryDelay = retryDelay;
+exports.wait = wait;
+exports.verifyMandateArtifact = verifyMandateArtifact;
+exports.verifyDecisionArtifact = verifyDecisionArtifact;
+/** @auctra/sdk — Authority Protocol client (Stage 1.0 modular layout). */
+const node_crypto_1 = require("node:crypto");
+class AuctraApiError extends Error {
+    status;
+    code;
+    details;
+    requestId;
+    constructor(message, options) {
+        super(message);
+        this.name = "AuctraApiError";
+        this.status = options.status;
+        this.code = options.code;
+        this.details = options.details;
+        this.requestId = options.requestId;
+    }
+}
+exports.AuctraApiError = AuctraApiError;
+function retryDelay(response, attempt) {
+    const retryAfter = response?.headers.get("retry-after");
+    if (retryAfter) {
+        const seconds = Number(retryAfter);
+        if (Number.isFinite(seconds))
+            return Math.min(30_000, Math.max(0, seconds * 1_000));
+        const dateDelay = Date.parse(retryAfter) - Date.now();
+        if (Number.isFinite(dateDelay))
+            return Math.min(30_000, Math.max(0, dateDelay));
+    }
+    return Math.min(5_000, 150 * 2 ** attempt);
+}
+function wait(ms, signal) {
+    if (signal?.aborted)
+        return Promise.reject(signal.reason);
+    return new Promise((resolve, reject) => {
+        const timeout = setTimeout(resolve, ms);
+        signal?.addEventListener("abort", () => {
+            clearTimeout(timeout);
+            reject(signal.reason);
+        }, { 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 };
+}

package/dist/cjs/authority.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });