@auctra/sdk 0.6.0 → 0.6.2

package/src/index.ts

@@ -1,1125 +1,10 @@
-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";
-export type Decision = "allowed" | "blocked" | "require_approval";
-export type PolicyType = "spending" | "data_access" | "communication" | "approval";
-export type ActorType = "human" | "agent" | "service" | "tool";
-export type RiskLevel = "low" | "medium" | "high" | "critical";
-export type IntentStatus = "active" | "expired" | "completed" | "revoked" | "suspended";
-
-export type EvaluateActionInput = {
-  agentId: string;
-  actionType: string;
-  payload?: Record<string, unknown>;
-  claimedIntentId?: string;
-  intentAnchorToken?: string;
-  parentActionId?: string;
-  actor?: {
-    id?: string;
-    type?: ActorType;
-    name?: string;
-  };
-  action?: {
-    target?: string;
-    description?: string;
-    riskLevel?: RiskLevel;
-    metadata?: Record<string, unknown>;
-  };
-};
-
-export type EvaluateActionResponse = {
-  decision: Decision;
-  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;
-    intent_status: string;
-    trust_summary?: string;
-  };
-};
-
-export type RequestOptions = {
-  idempotencyKey?: string;
-  signal?: AbortSignal;
-};
-
-export type AuctraClientOptions = {
-  apiKey: string;
-  baseUrl?: string;
-  timeoutMs?: number;
-  maxRetries?: number;
-  fetch?: typeof fetch;
-};
-
-export type Agent = {
-  id: string;
-  identity_id: string;
-  name: string;
-  description: string | null;
-  model_provider: "openai" | "anthropic" | "gemini" | "local";
-  model_name: string;
-  environment: AgentEnvironment;
-  authority_level: AuthorityLevel;
-  status: "active" | "suspended" | "restricted" | "compromised";
-  trust_rating: number;
-  sponsor: { id: string; full_name: string; email: string };
-  created_at: string;
-};
-
-export type CreateAgentInput = {
-  name: string;
-  modelProvider: Agent["model_provider"];
-  modelName: string;
-  description?: string;
-  environment?: AgentEnvironment;
-  authorityLevel?: AuthorityLevel;
-  sponsorUserId?: string;
-};
-
-export type Delegation = {
-  id: string;
-  agent: { id: string; name: string };
-  delegator: { id: string; full_name: string; email: string };
-  scope: { action_types: string[] };
-  limits: {
-    max_amount?: number;
-    max_count?: number;
-    currency?: string;
-    environment?: AgentEnvironment;
-    max_actions_per_window?: {
-      count: number;
-      window_seconds: number;
-      action_type?: string;
-    };
-    max_amount_per_window?: {
-      amount: number;
-      window_seconds: number;
-    };
-  };
-  valid_from: string;
-  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;
-};
-
-export type CreateDelegationInput = {
-  agentId: string;
-  actionTypes: string[];
-  validUntil: string;
-  maxAmount?: number;
-  maxCount?: number;
-  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;
-    actionType?: string;
-  };
-  maxAmountPerWindow?: {
-    amount: number;
-    windowSeconds: number;
-  };
-};
-
-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;
-  action_type: string;
-  action_summary: string;
-  payload: Record<string, unknown>;
-  decision: string;
-  decision_reason: string | null;
-  risk_score: number;
-  delegation_id: string | null;
-  policy_ids: string[];
-  claimed_intent_id: string | null;
-  parent_action_id: string | null;
-  actor_id: string | null;
-  actor_type: ActorType;
-  action_target: string | null;
-  action_description: string | null;
-  action_risk_level: RiskLevel | null;
-  action_metadata: Record<string, unknown>;
-  pending_approval_id: string | null;
-  created_at: string;
-  decided_at: string | null;
-};
-
-export type Intent = {
-  id: string;
-  title: string;
-  description: string | null;
-  intent_type: string | null;
-  status: IntentStatus;
-  risk_level: RiskLevel;
-  max_risk_level: RiskLevel;
-  expires_at: string | null;
-  created_at: string;
-  owner: { id: string; full_name: string; email: string } | null;
-  linked_actions: number;
-};
-
-export type IntentDetail = Omit<Intent, "linked_actions"> & {
-  linked_actions: Array<{
-    action_request_id: string;
-    action_type: string;
-    summary: string;
-    decision: string;
-    alignment_status: string;
-    alignment_score: number | null;
-  }>;
-};
-
-export type CreateAuthorityEdgeInput = {
-  fromActorId: string;
-  fromActorType: ActorType;
-  toActorId: string;
-  toActorType: ActorType;
-  authorityScope: string;
-  conditions?: Record<string, unknown>;
-  maxRiskLevel?: RiskLevel;
-  expiresAt?: string;
-};
-
-export type CreateIntentInput = {
-  title: string;
-  description?: string;
-  intentType?: string;
-  riskLevel?: RiskLevel;
-  maxRiskLevel?: RiskLevel;
-  expiresAt?: string;
-  allowedActionTypes?: string[];
-  targetPattern?: string;
-  resourceAllowlist?: string[];
-};
-
-export type UpdateIntentInput = {
-  status?: Exclude<IntentStatus, "expired">;
-  title?: string;
-  description?: string | null;
-  intentType?: string | null;
-  riskLevel?: RiskLevel;
-  maxRiskLevel?: RiskLevel;
-  expiresAt?: string | null;
-};
-
-export type UpdateAgentStatusInput = {
-  status: Agent["status"];
-  reason?: string;
-  /** Permanently revoke instead of quarantine (default: quarantine on restrict/suspend). */
-  revokeDelegations?: boolean;
-  /** Restore quarantined delegations when reactivating (default: true). */
-  restoreDelegations?: boolean;
-};
-
-export type AuthorityGraph = {
-  nodes: Array<{ id: string; type: ActorType; label: string }>;
-  edges: Array<{
-    id: string;
-    from: string;
-    to: string;
-    fromType: ActorType;
-    toType: ActorType;
-    scope: string;
-    status: string;
-    edgeType: string;
-  }>;
-};
-
-export type ActionEvaluation = {
-  id: string;
-  action_request_id: string;
-  intent_id: string | null;
-  decision: "allowed" | "requires_approval" | "blocked";
-  risk_score: number;
-  authority_valid: boolean;
-  intent_valid: boolean;
-  root_intent_valid: boolean;
-  reasons: string[];
-  created_at: string;
-};
-
-export type RootIntentChain = {
-  valid: boolean;
-  root_human_id: string | null;
-  root_intent_id: string | null;
-  reason: string | null;
-  chain: Array<{
-    actionId?: string;
-    actorId: string;
-    actorType: ActorType;
-    intentId?: string;
-    parentActionId?: string;
-    label?: string;
-  }>;
-};
-
-export type Policy = {
-  id: string;
-  name: string;
-  description: string | null;
-  policy_type: PolicyType;
-  status: "active" | "draft" | "archived";
-  priority: number;
-  conditions: Record<string, unknown>;
-  actions: Record<string, unknown>;
-  created_at: string;
-};
-
-export type CreatePolicyInput = {
-  name: string;
-  description?: string;
-  policyType: PolicyType;
-  status?: "active" | "draft";
-  priority?: number;
-  actionType?: string;
-  amountGreaterThan?: number;
-  resourceSensitivity?: "public" | "internal" | "confidential" | "pii";
-  externalRecipient?: boolean;
-  environment?: AgentEnvironment;
-  decision: "block" | "require_approval";
-  approverRole?: "owner" | "admin" | "reviewer";
-  maxActionsPerWindow?: {
-    count: number;
-    windowSeconds: number;
-    actionType?: string;
-  };
-  maxAmountPerWindow?: {
-    amount: number;
-    windowSeconds: number;
-  };
-};
-
-export type CustomActionType = {
-  id: string;
-  label: string;
-  description: string | null;
-  category: string;
-  policy_type: PolicyType;
-  payload_schema: Record<string, unknown>;
-  source: "builtin" | "custom";
-  template?: boolean;
-  created_at?: string | null;
-};
-
-export type CreateCustomActionTypeInput = {
-  id: string;
-  label: string;
-  description?: string;
-  category?: string;
-  policyType: PolicyType;
-  payloadSchema?: Record<string, unknown>;
-};
-
-export type PolicySimulation = {
-  policy_id: string;
-  policy_name: string;
-  policy_status: string;
-  sample_size: number;
-  changed_count: number;
-  unchanged_count: number;
-  would_block_count: number;
-  replay_source?: "audit_events" | "action_requests" | "mixed";
-  deltas: Array<{
-    action_request_id: string;
-    action_type: string;
-    current_decision: string;
-    simulated_decision: string;
-    changed: boolean;
-  }>;
-};
-
-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;
-  event_summary: string;
-  decision: string | null;
-  decision_reason: string | null;
-  authority_valid_at_action: boolean | null;
-  actor_name: string;
-  approver_name: string | null;
-  policy_applied: string | null;
-  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;
-};
-
-export type ApiKeySummary = {
-  id: string;
-  name: string;
-  key_prefix: string;
-  environment: "development" | "production";
-  permissions: string[];
-  status: "active" | "revoked";
-  last_used_at: string | null;
-  created_at: string;
-};
-
-export class AuctraApiError extends Error {
-  readonly status: number;
-  readonly code?: string;
-  readonly details?: unknown;
-  readonly requestId?: string;
-
-  constructor(
-    message: string,
-    options: { status: number; code?: string; details?: unknown; requestId?: string },
-  ) {
-    super(message);
-    this.name = "AuctraApiError";
-    this.status = options.status;
-    this.code = options.code;
-    this.details = options.details;
-    this.requestId = options.requestId;
-  }
-}
-
-function retryDelay(response: Response | undefined, attempt: number) {
-  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: number, signal?: AbortSignal) {
-  if (signal?.aborted) return Promise.reject(signal.reason);
-  return new Promise<void>((resolve, reject) => {
-    const timeout = setTimeout(resolve, ms);
-    signal?.addEventListener(
-      "abort",
-      () => {
-        clearTimeout(timeout);
-        reject(signal.reason);
-      },
-      { once: true },
-    );
-  });
-}
-
-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;
-  private readonly timeoutMs: number;
-  private readonly maxRetries: number;
-  private readonly fetchImpl: typeof fetch;
-
-  constructor(options: AuctraClientOptions) {
-    if (!options.apiKey.trim()) throw new Error("apiKey is required");
-    if (options.timeoutMs !== undefined && options.timeoutMs <= 0) {
-      throw new Error("timeoutMs must be greater than zero");
-    }
-    if (
-      options.maxRetries !== undefined &&
-      (!Number.isInteger(options.maxRetries) || options.maxRetries < 0)
-    ) {
-      throw new Error("maxRetries must be a non-negative integer");
-    }
-    this.apiKey = options.apiKey;
-    this.baseUrl = (options.baseUrl ?? "https://console.auctra.tech").replace(/\/$/, "");
-    this.timeoutMs = options.timeoutMs ?? 10_000;
-    this.maxRetries = options.maxRetries ?? 2;
-    this.fetchImpl = options.fetch ?? globalThis.fetch;
-    if (!this.fetchImpl) throw new Error("A fetch implementation is required");
-  }
-
-  private async request<T>(
-    method: string,
-    path: string,
-    body?: unknown,
-    options: RequestOptions = {},
-  ): Promise<T> {
-    const retryableRequest = method === "GET" || Boolean(options.idempotencyKey);
-    let lastError: unknown;
-
-    for (let attempt = 0; attempt <= this.maxRetries; attempt += 1) {
-      if (options.signal?.aborted) throw options.signal.reason;
-      const timeoutSignal = AbortSignal.timeout(this.timeoutMs);
-      const signal = options.signal
-        ? AbortSignal.any([options.signal, timeoutSignal])
-        : timeoutSignal;
-      let response: Response | undefined;
-
-      try {
-        response = await this.fetchImpl(`${this.baseUrl}${path}`, {
-          method,
-          signal,
-          headers: {
-            ...(body !== undefined ? { "content-type": "application/json" } : {}),
-            ...(options.idempotencyKey ? { "idempotency-key": options.idempotencyKey } : {}),
-            authorization: `Bearer ${this.apiKey}`,
-            "x-auctra-sdk-version": AUCTRA_SDK_VERSION,
-          },
-          ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
-        });
-
-        const data = (await response.json().catch(() => ({}))) as Record<string, unknown>;
-        if (response.ok) return data as T;
-
-        if (
-          retryableRequest &&
-          (response.status === 429 || response.status >= 500) &&
-          attempt < this.maxRetries
-        ) {
-          await wait(retryDelay(response, attempt), options.signal);
-          continue;
-        }
-
-        throw new AuctraApiError(
-          typeof data.error === "string" ? data.error : `Auctra API error (${response.status})`,
-          {
-            status: response.status,
-            code: typeof data.code === "string" ? data.code : undefined,
-            details: data.details,
-            requestId: response.headers.get("x-request-id") ?? undefined,
-          },
-        );
-      } catch (error) {
-        lastError = error;
-        if (options.signal?.aborted) throw options.signal.reason;
-        if (error instanceof AuctraApiError || !retryableRequest || attempt >= this.maxRetries) {
-          throw error;
-        }
-        await wait(retryDelay(response, attempt), options.signal);
-      }
-    }
-
-    throw lastError;
-  }
-
-  private async executeOrEvaluateAction(
-    input: EvaluateActionInput,
-    options: RequestOptions,
-    mode: "execute" | "evaluate",
-  ): Promise<EvaluateActionResponse> {
-    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,
-              type: input.actor.type,
-              name: input.actor.name,
-            }
-          : undefined,
-        action: input.action
-          ? {
-              target: input.action.target,
-              description: input.action.description,
-              risk_level: input.action.riskLevel,
-              metadata: input.action.metadata,
-            }
-          : undefined,
-      },
-      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");
-  }
-
-  async createIntent(
-    input: CreateIntentInput,
-  ): Promise<{ intent: { id: string; title: string; status: string } }> {
-    return this.request("POST", "/v1/intents", {
-      title: input.title,
-      description: input.description,
-      intent_type: input.intentType,
-      risk_level: input.riskLevel,
-      max_risk_level: input.maxRiskLevel,
-      expires_at: input.expiresAt,
-      allowed_action_types: input.allowedActionTypes,
-      target_pattern: input.targetPattern,
-      resource_allowlist: input.resourceAllowlist,
-    });
-  }
-
-  async getIntent(intentId: string): Promise<{ intent: IntentDetail }> {
-    return this.request("GET", `/v1/intents/${encodeURIComponent(intentId)}`);
-  }
-
-  async updateIntentStatus(
-    intentId: string,
-    status: Exclude<IntentStatus, "expired">,
-  ): Promise<{ intent: { id: string; title: string; status: IntentStatus } }> {
-    return this.updateIntent(intentId, { status });
-  }
-
-  async updateIntent(
-    intentId: string,
-    input: UpdateIntentInput,
-  ): Promise<{
-    intent: {
-      id: string;
-      title: string;
-      status: IntentStatus;
-      description?: string | null;
-      intent_type?: string | null;
-      risk_level?: RiskLevel;
-      max_risk_level?: RiskLevel;
-      expires_at?: string | null;
-    };
-  }> {
-    return this.request("PATCH", `/v1/intents/${encodeURIComponent(intentId)}`, {
-      status: input.status,
-      title: input.title,
-      description: input.description,
-      intent_type: input.intentType,
-      risk_level: input.riskLevel,
-      max_risk_level: input.maxRiskLevel,
-      expires_at: input.expiresAt,
-    });
-  }
-
-  async getAuthorityGraph(): Promise<{ authority_graph: AuthorityGraph }> {
-    return this.request("GET", "/v1/authority/graph");
-  }
-
-  async createAuthorityEdge(input: CreateAuthorityEdgeInput): Promise<{ edge: { id: string } }> {
-    return this.request("POST", "/v1/authority/edges", {
-      from_actor_id: input.fromActorId,
-      from_actor_type: input.fromActorType,
-      to_actor_id: input.toActorId,
-      to_actor_type: input.toActorType,
-      authority_scope: input.authorityScope,
-      conditions: input.conditions,
-      max_risk_level: input.maxRiskLevel,
-      expires_at: input.expiresAt,
-    });
-  }
-
-  async getActionEvaluation(actionRequestId: string): Promise<{ evaluation: ActionEvaluation }> {
-    return this.request(
-      "GET",
-      `/v1/action-requests/${encodeURIComponent(actionRequestId)}/evaluation`,
-    );
-  }
-
-  async getRootIntentChain(
-    actionRequestId: string,
-  ): Promise<{ root_intent_chain: RootIntentChain }> {
-    return this.request(
-      "GET",
-      `/v1/action-requests/${encodeURIComponent(actionRequestId)}/root-intent`,
-    );
-  }
-
-  async listAgents(): Promise<{ agents: Agent[] }> {
-    return this.request("GET", "/v1/agents");
-  }
-
-  async getAgent(agentId: string): Promise<{ agent: Agent }> {
-    return this.request("GET", `/v1/agents/${encodeURIComponent(agentId)}`);
-  }
-
-  async createAgent(input: CreateAgentInput): Promise<{ agent: Agent }> {
-    return this.request("POST", "/v1/agents", {
-      name: input.name,
-      model_provider: input.modelProvider,
-      model_name: input.modelName,
-      description: input.description,
-      environment: input.environment,
-      authority_level: input.authorityLevel,
-      sponsor_user_id: input.sponsorUserId,
-    });
-  }
-
-  async updateAgentStatus(
-    agentId: string,
-    input: UpdateAgentStatusInput,
-  ): Promise<{ agent: { id: string; name: string; status: Agent["status"] } }> {
-    return this.request("PATCH", `/v1/agents/${encodeURIComponent(agentId)}`, {
-      status: input.status,
-      reason: input.reason,
-      revoke_delegations: input.revokeDelegations,
-      restore_delegations: input.restoreDelegations,
-    });
-  }
-
-  async deleteAgent(agentId: string): Promise<{ ok: true }> {
-    return this.request("DELETE", `/v1/agents/${encodeURIComponent(agentId)}`);
-  }
-
-  async listAuthorities(): Promise<{ delegations: Delegation[]; authorities?: AuthoritySummary[] }> {
-    return this.request("GET", "/v1/authorities");
-  }
-
-  async getAuthority(authorityId: string): Promise<{ delegation: Delegation }> {
-    return this.request("GET", `/v1/authorities/${encodeURIComponent(authorityId)}`);
-  }
-
-  async listActionRequests(): Promise<{ action_requests: ActionRequest[] }> {
-    return this.request("GET", "/v1/action-requests");
-  }
-
-  async approveActionRequest(actionRequestId: string, approverUserId: string, reason?: string) {
-    return this.resolveActionRequest(actionRequestId, "approve", approverUserId, reason);
-  }
-
-  async rejectActionRequest(actionRequestId: string, approverUserId: string, reason?: string) {
-    return this.resolveActionRequest(actionRequestId, "reject", approverUserId, reason);
-  }
-
-  async escalateActionRequest(actionRequestId: string, approverUserId: string, reason?: string) {
-    return this.resolveActionRequest(actionRequestId, "escalate", approverUserId, reason);
-  }
-
-  private async resolveActionRequest(
-    actionRequestId: string,
-    action: "approve" | "reject" | "escalate",
-    approverUserId: string,
-    reason?: string,
-  ): Promise<{
-    ok: true;
-    decision: "approved" | "rejected" | "escalated";
-    action_decision: "allowed" | "blocked" | "require_approval";
-    reason: string;
-  }> {
-    return this.request(
-      "POST",
-      `/v1/action-requests/${encodeURIComponent(actionRequestId)}/${action}`,
-      { reason, approver_user_id: approverUserId },
-    );
-  }
-
-  async listPolicies(): Promise<{ policies: Policy[] }> {
-    return this.request("GET", "/v1/policies");
-  }
-
-  async createPolicy(
-    input: CreatePolicyInput,
-  ): Promise<{ policy: Pick<Policy, "id" | "name" | "status" | "created_at"> }> {
-    return this.request("POST", "/v1/policies", {
-      name: input.name,
-      description: input.description,
-      policy_type: input.policyType,
-      status: input.status,
-      priority: input.priority,
-      action_type: input.actionType,
-      amount_greater_than: input.amountGreaterThan,
-      resource_sensitivity: input.resourceSensitivity,
-      external_recipient: input.externalRecipient,
-      environment: input.environment,
-      decision: input.decision,
-      approver_role: input.approverRole,
-      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 simulatePolicy(
-    policyId: string,
-    input: { limit?: number; since?: string } = {},
-  ): Promise<{
-    simulation: PolicySimulation;
-    meta: {
-      simulated_at: string;
-      sample_size: number;
-      changed_count: number;
-      unchanged_count: number;
-    };
-  }> {
-    return this.request("POST", `/v1/policies/${encodeURIComponent(policyId)}/simulate`, input);
-  }
-
-  async publishPolicy(
-    policyId: string,
-    input: { force?: boolean } = {},
-  ): Promise<{ ok: true; policyId: string; simulation: Record<string, unknown> }> {
-    return this.request("POST", `/v1/policies/${encodeURIComponent(policyId)}/publish`, input);
-  }
-
-  async listActionTypes(): Promise<{ action_types: CustomActionType[] }> {
-    return this.listCustomActionTypes();
-  }
-
-  async listCustomActionTypes(): Promise<{ action_types: CustomActionType[] }> {
-    return this.request("GET", "/v1/action-types");
-  }
-
-  async createCustomActionType(input: CreateCustomActionTypeInput): Promise<{
-    action_type: Pick<CustomActionType, "id" | "label" | "policy_type" | "source" | "created_at">;
-  }> {
-    return this.request("POST", "/v1/action-types", {
-      id: input.id,
-      label: input.label,
-      description: input.description,
-      category: input.category,
-      policy_type: input.policyType,
-      payload_schema: input.payloadSchema ?? {},
-    });
-  }
-
-  async listAuditEvents(): Promise<{ audit_events: AuditEvent[] }> {
-    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");
-  }
-}
+/**
+ * @auctra/sdk — Stage 1.0 public surface.
+ *
+ * Modular layout under src/{types,artifacts,client,authority,action,evidence}.ts.
+ * Canonical API: authority.* / action.* / evidence.* — no createDelegation / evaluateAction.
+ */
+export { AUCTRA_SDK_VERSION, DEFAULT_BASE_URL } from "./types.js";
+export type * from "./types.js";
+export { AuctraApiError, verifyMandateArtifact, verifyDecisionArtifact } from "./artifacts.js";
+export { Auctra } from "./client.js";