@auctra/sdk 0.6.0 → 0.6.2

package/src/types.ts

@@ -0,0 +1,488 @@
+/** @auctra/sdk — Authority Protocol client (Stage 1.0 modular layout). */
+
+export const AUCTRA_SDK_VERSION = "0.6.2";
+
+/** Production API + console host (Architecture A: colocated on app.auctra.tech). */
+export const DEFAULT_BASE_URL = "https://app.auctra.tech";
+
+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;
+  /** Defaults to {@link DEFAULT_BASE_URL}. Override for staging/local. */
+  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;
+};