@auctra/sdk 0.3.4 → 0.6.0

package/src/index.ts

@@ -1,4 +1,6 @@
-export const AUCTRA_SDK_VERSION = "0.3.3";
+import { createHash, createPublicKey, verify as cryptoVerify, type KeyObject } from "node:crypto";
+
+export const AUCTRA_SDK_VERSION = "0.6.0";
 
 export type AgentEnvironment = "dev" | "staging" | "production";
 export type AuthorityLevel = "low" | "medium" | "high" | "critical";
@@ -33,10 +35,18 @@ export type EvaluateActionResponse = {
   risk_score: number;
   reason: string;
   delegation_id: string | null;
+  authority_id: string | null;
   delegator: string | null;
   sponsor: string;
   matched_policies: string[];
   action_request_id: string;
+  evidence: DecisionEvidence;
+  evidence_payload: DecisionEvidencePayload;
+  protocol?: {
+    version: string;
+    action?: Record<string, unknown>;
+    decision?: Record<string, unknown>;
+  };
   intelligence?: {
     authority_valid: boolean;
     root_intent_valid: boolean;
@@ -107,6 +117,10 @@ export type Delegation = {
   valid_until: string;
   status: "active" | "revoked" | "expired";
   is_active: boolean;
+  mandate?: MandateEvidence | null;
+  mandate_payload?: MandatePayload | null;
+  evidence?: DecisionEvidence | null;
+  evidence_payload?: DecisionEvidencePayload | null;
   created_at: string;
 };
 
@@ -119,6 +133,10 @@ export type CreateDelegationInput = {
   environment?: AgentEnvironment;
   currency?: string;
   delegatorUserId?: string;
+  /** Parent authority/delegation id for subset-constrained delegation chains. */
+  parentAuthorityId?: string;
+  parentDelegationId?: string;
+  maxDelegationDepth?: number;
   maxActionsPerWindow?: {
     count: number;
     windowSeconds: number;
@@ -130,6 +148,49 @@ export type CreateDelegationInput = {
   };
 };
 
+export type AuthoritySummary = {
+  id: string;
+  protocol_version: string;
+  status: string;
+  payload_hash: string;
+  signed: boolean;
+  parent_authority_id: string | null;
+  capabilities: unknown;
+};
+
+export type IssueAuthorityInput = {
+  /** Subject agent id */
+  subject: string;
+  capabilities: string[];
+  expiresAt: string;
+  constraints?: {
+    maxAmount?: number;
+    currency?: string;
+    maxCount?: number;
+    environment?: AgentEnvironment;
+  };
+  delegation?: {
+    allowed?: boolean;
+    maxDepth?: number;
+  };
+  issuer?: string;
+  delegatorUserId?: string;
+  maxActionsPerWindow?: {
+    count: number;
+    windowSeconds: number;
+    actionType?: string;
+  };
+  maxAmountPerWindow?: {
+    amount: number;
+    windowSeconds: number;
+  };
+};
+
+export type DelegateAuthorityInput = IssueAuthorityInput & {
+  /** Parent authority id — child must be a subset of parent */
+  parent: string;
+};
+
 export type ActionRequest = {
   id: string;
   agent_name: string;
@@ -338,6 +399,59 @@ export type PolicySimulation = {
   }>;
 };
 
+export type MandateEvidence =
+  | {
+      format: "auctra-mandate.v0.1";
+      payload_hash: string;
+      signed: false;
+    }
+  | {
+      format: "auctra-mandate.v0.1";
+      signed: true;
+      payload_hash: string;
+      payload: Record<string, unknown>;
+      signature: { alg: "Ed25519"; key_id: string; value: string };
+    };
+
+export type MandatePayload = Record<string, unknown>;
+
+export type DecisionEvidencePayload = Record<string, unknown>;
+
+export type DecisionEvidence =
+  | {
+      format: "auctra-evidence.v0.1";
+      payload_hash: string;
+      signed: false;
+    }
+  | {
+      format: "auctra-evidence.v0.1";
+      signed: true;
+      payload_hash: string;
+      payload: Record<string, unknown>;
+      signature: { alg: "Ed25519"; key_id: string; value: string };
+    };
+
+export type AuditChainVerification = {
+  valid: boolean;
+  total: number;
+  sealed_total: number;
+  legacy_unsealed_total: number;
+  events: Array<{
+    id: string;
+    hashValid: boolean;
+    linkValid: boolean;
+    sequenceValid: boolean;
+    valid: boolean;
+    legacy: boolean;
+  }>;
+};
+
+export type ArtifactVerification = {
+  valid: boolean;
+  hashValid: boolean;
+  signatureValid: boolean;
+};
+
 export type AuditEvent = {
   id: string;
   event_type: string;
@@ -351,6 +465,10 @@ export type AuditEvent = {
   delegation_id: string | null;
   hash: string | null;
   previous_hash: string | null;
+  chain_index?: number;
+  mandate?: MandateEvidence | null;
+  evidence?: DecisionEvidence | null;
+  payload?: Record<string, unknown>;
   created_at: string;
 };
 
@@ -410,6 +528,91 @@ function wait(ms: number, signal?: AbortSignal) {
   });
 }
 
+function canonicalizeJson(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(canonicalizeJson);
+  if (value && typeof value === "object" && !(value instanceof Date)) {
+    return Object.fromEntries(
+      Object.entries(value as Record<string, unknown>)
+        .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: unknown) {
+  return createHash("sha256")
+    .update(JSON.stringify(canonicalizeJson(value)))
+    .digest("hex");
+}
+
+function verifyEd25519(input: {
+  payload: unknown;
+  signature: { alg: "Ed25519"; value: string };
+  publicKeyPem?: string | KeyObject;
+}) {
+  if (!input.publicKeyPem) return false;
+  if (input.signature.alg !== "Ed25519") return false;
+  return cryptoVerify(
+    null,
+    Buffer.from(JSON.stringify(canonicalizeJson(input.payload))),
+    typeof input.publicKeyPem === "string"
+      ? createPublicKey(input.publicKeyPem)
+      : input.publicKeyPem,
+    Buffer.from(input.signature.value, "base64url"),
+  );
+}
+
+export function verifyMandateArtifact(input: {
+  payload: MandatePayload;
+  evidence: MandateEvidence;
+  publicKeyPem?: string | KeyObject;
+}): ArtifactVerification {
+  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 };
+}
+
+export function verifyDecisionArtifact(input: {
+  payload: DecisionEvidencePayload;
+  evidence: DecisionEvidence;
+  publicKeyPem?: string | KeyObject;
+}): ArtifactVerification {
+  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 };
+}
+
 export class Auctra {
   private readonly apiKey: string;
   private readonly baseUrl: string;
@@ -500,14 +703,17 @@ export class Auctra {
     throw lastError;
   }
 
-  async evaluateAction(
+  private async executeOrEvaluateAction(
     input: EvaluateActionInput,
-    options: RequestOptions = {},
+    options: RequestOptions,
+    mode: "execute" | "evaluate",
   ): Promise<EvaluateActionResponse> {
-    const idempotencyKey = options.idempotencyKey ?? crypto.randomUUID();
+    const idempotencyKey =
+      mode === "execute" ? (options.idempotencyKey ?? crypto.randomUUID()) : options.idempotencyKey;
+    const path = mode === "execute" ? "/v1/actions/execute" : "/v1/actions/evaluate";
     return this.request(
       "POST",
-      "/v1/action-requests/evaluate",
+      path,
       {
         agent_id: input.agentId,
         action_type: input.actionType,
@@ -515,6 +721,7 @@ export class Auctra {
         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,
@@ -531,10 +738,128 @@ export class Auctra {
             }
           : undefined,
       },
-      { ...options, idempotencyKey },
+      mode === "execute" ? { ...options, idempotencyKey } : options,
     );
   }
 
+  private async issueAuthorityRequest(
+    input: IssueAuthorityInput & { parentAuthorityId?: string },
+  ): Promise<{
+    authority: AuthoritySummary;
+    authority_id: string;
+    delegation: Delegation;
+  }> {
+    const response = await this.request<{
+      delegation: Delegation;
+      authority_id?: string;
+      authority?: AuthoritySummary;
+    }>("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: AuthoritySummary = 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: IssueAuthorityInput) => this.issueAuthorityRequest(input),
+      verify: (
+        payload: Record<string, unknown>,
+        artifact: Record<string, unknown>,
+      ): Promise<{
+        valid: boolean;
+        hashValid: boolean;
+        signatureValid: boolean;
+        expired: boolean;
+        status: string;
+        issuer: string;
+        subject: string;
+        capabilities: string[];
+        constraints: Record<string, unknown>;
+        expiresAt: string;
+        protocolVersion: string;
+      }> => this.request("POST", "/v1/authorities/verify", { payload, artifact }),
+      delegate: (input: DelegateAuthorityInput) =>
+        this.issueAuthorityRequest({
+          ...input,
+          parentAuthorityId: input.parent,
+        }),
+      revoke: (authorityId: string): Promise<{ ok: true }> =>
+        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: EvaluateActionInput, options: RequestOptions = {}) =>
+        this.executeOrEvaluateAction(input, options, "evaluate"),
+      execute: (input: EvaluateActionInput, options: RequestOptions = {}) =>
+        this.executeOrEvaluateAction(input, options, "execute"),
+    };
+  }
+
+  get evidence() {
+    return {
+      verify: (
+        payload: DecisionEvidencePayload,
+        evidence: DecisionEvidence,
+      ): Promise<ArtifactVerification> =>
+        this.request("POST", "/v1/evidence/verify", { payload, evidence }),
+    };
+  }
+
+  async verifyMandate(
+    payload: MandatePayload,
+    evidence: MandateEvidence,
+  ): Promise<ArtifactVerification> {
+    return this.request("POST", "/v1/mandates/verify", { payload, evidence });
+  }
+
   async listIntents(): Promise<{ intents: Intent[] }> {
     return this.request("GET", "/v1/intents");
   }
@@ -661,42 +986,12 @@ export class Auctra {
     return this.request("DELETE", `/v1/agents/${encodeURIComponent(agentId)}`);
   }
 
-  async listDelegations(): Promise<{ delegations: Delegation[] }> {
-    return this.request("GET", "/v1/delegations");
-  }
-
-  async getDelegation(delegationId: string): Promise<{ delegation: Delegation }> {
-    return this.request("GET", `/v1/delegations/${encodeURIComponent(delegationId)}`);
-  }
-
-  async createDelegation(input: CreateDelegationInput): Promise<{ delegation: Delegation }> {
-    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 listAuthorities(): Promise<{ delegations: Delegation[]; authorities?: AuthoritySummary[] }> {
+    return this.request("GET", "/v1/authorities");
   }
 
-  async revokeDelegation(delegationId: string): Promise<{ ok: true }> {
-    return this.request("POST", `/v1/delegations/${encodeURIComponent(delegationId)}/revoke`, {});
+  async getAuthority(authorityId: string): Promise<{ delegation: Delegation }> {
+    return this.request("GET", `/v1/authorities/${encodeURIComponent(authorityId)}`);
   }
 
   async listActionRequests(): Promise<{ action_requests: ActionRequest[] }> {
@@ -816,6 +1111,14 @@ export class Auctra {
     return this.request("GET", "/v1/audit-events");
   }
 
+  async getAuditEvent(auditEventId: string): Promise<{ audit_event: AuditEvent }> {
+    return this.request("GET", `/v1/audit-events/${encodeURIComponent(auditEventId)}`);
+  }
+
+  async verifyAuditChain(): Promise<AuditChainVerification> {
+    return this.request("GET", "/v1/audit-events/verify");
+  }
+
   async listApiKeys(): Promise<{ api_keys: ApiKeySummary[] }> {
     return this.request("GET", "/v1/api-keys");
   }