@auctra/sdk 0.6.0 → 0.6.2

package/src/client.ts

@@ -0,0 +1,555 @@
+/** @auctra/sdk — Authority Protocol client (Stage 1.0 modular layout). */
+import { AuctraApiError, retryDelay, wait } from "./artifacts.js";
+import type {
+  ActionEvaluation,
+  ActionRequest,
+  ActorType,
+  Agent,
+  ApiKeySummary,
+  ArtifactVerification,
+  AuditChainVerification,
+  AuditEvent,
+  AuthorityGraph,
+  AuthoritySummary,
+  AuctraClientOptions,
+  CreateAgentInput,
+  CreateAuthorityEdgeInput,
+  CreateCustomActionTypeInput,
+  CreateIntentInput,
+  CreatePolicyInput,
+  CustomActionType,
+  DecisionEvidence,
+  DecisionEvidencePayload,
+  DelegateAuthorityInput,
+  Delegation,
+  EvaluateActionInput,
+  EvaluateActionResponse,
+  Intent,
+  IntentDetail,
+  IntentStatus,
+  IssueAuthorityInput,
+  MandateEvidence,
+  MandatePayload,
+  Policy,
+  PolicySimulation,
+  RequestOptions,
+  RiskLevel,
+  RootIntentChain,
+  UpdateAgentStatusInput,
+  UpdateIntentInput,
+} from "./types.js";
+import { AUCTRA_SDK_VERSION, DEFAULT_BASE_URL } from "./types.js";
+
+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 ?? DEFAULT_BASE_URL).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");
+  }
+}

package/src/evidence.ts

@@ -0,0 +1,9 @@
+/** Evidence verification surface. */
+export type {
+  ArtifactVerification,
+  DecisionEvidence,
+  DecisionEvidencePayload,
+  MandateEvidence,
+  MandatePayload,
+} from "./types.js";
+export { verifyDecisionArtifact, verifyMandateArtifact } from "./artifacts.js";