@emilia-protocol/sdk 0.9.0 → 0.11.0

package/src/types.ts

@@ -425,6 +425,234 @@ export interface InstallPreflightResult {
   score: number;
 }
 
+// ----------------------------------------------------------------------------
+// v1 Trust Receipt enforcement types
+// ----------------------------------------------------------------------------
+
+export type GuardActionType =
+  | 'benefit_bank_account_change'
+  | 'benefit_address_change'
+  | 'caseworker_override'
+  | 'gov.vendor_payment_destination_change'
+  | 'gov.disbursement_release'
+  | 'gov.grant_disbursement'
+  | 'gov.provider_enrollment_change'
+  | 'gov.eligibility_override'
+  | 'vendor_bank_account_change'
+  | 'beneficiary_creation'
+  | 'large_payment_release'
+  | 'ai_agent_payment_action'
+  | 'policy_rollout';
+
+export type GuardDecision = 'allow' | 'observe' | 'allow_with_signoff' | 'deny';
+export type GuardEnforcementMode = 'observe' | 'warn' | 'enforce';
+export type ReceiptStatus =
+  | 'issued'
+  | 'pending_signoff'
+  | 'approved_pending_consume'
+  | 'rejected'
+  | 'consumed'
+  | 'denied';
+
+export interface GuardQuorumApprover {
+  role: string;
+  approver: string;
+}
+
+export interface GuardQuorumPolicy {
+  mode?: 'threshold' | 'ordered';
+  required: number;
+  approvers: GuardQuorumApprover[];
+}
+
+export interface CreateTrustReceiptParams {
+  /** Optional cross-check; the API derives the authorized organization from the authenticated key. */
+  organizationId?: string;
+  actionType: GuardActionType;
+  targetResourceId: string;
+  policyId?: string;
+  enforcementMode?: GuardEnforcementMode;
+  beforeState?: Record<string, unknown>;
+  afterState?: Record<string, unknown>;
+  targetChangedFields?: string[];
+  amount?: number;
+  currency?: string;
+  riskFlags?: string[];
+  actorRole?: string;
+  actorDepartment?: string;
+  businessHours?: boolean;
+  velocitySameActor24h?: number;
+  priorDenialsActor30d?: number;
+  priorChangesTarget30d?: number;
+  destinationAgeDays?: number;
+  quorumPolicy?: GuardQuorumPolicy;
+  metadata?: Record<string, unknown>;
+}
+
+export interface TrustReceipt {
+  receipt_id: string;
+  decision: GuardDecision;
+  observed_decision?: GuardDecision | null;
+  policy_id: string;
+  policy_hash: string;
+  action_hash: string;
+  before_state_hash?: string | null;
+  after_state_hash?: string | null;
+  nonce: string;
+  expires_at: string;
+  signoff_required: boolean;
+  signoff_request_id?: string | null;
+  risk_flags?: string[];
+  receipt_status: ReceiptStatus | string;
+  enforcement_mode: GuardEnforcementMode | string;
+  reasons?: string[];
+  canonical_action: Record<string, unknown>;
+}
+
+export interface TrustReceiptState {
+  receipt_id: string;
+  organization_id: string;
+  action_type: string;
+  decision: GuardDecision;
+  enforcement_mode: GuardEnforcementMode | string;
+  policy_id: string;
+  policy_hash: string;
+  action_hash: string;
+  before_state_hash?: string | null;
+  after_state_hash?: string | null;
+  expires_at: string;
+  signoff_required: boolean;
+  receipt_status: ReceiptStatus | string;
+  signoff_key_class?: 'A' | 'B' | 'C' | string | null;
+  timeline_event_count: number;
+}
+
+export interface RequestSignoffParams {
+  receiptId: string;
+  approverId?: string;
+  expiresInMinutes?: number;
+  comment?: string;
+}
+
+export interface SignoffRequest {
+  signoff_id?: string;
+  receipt_id: string;
+  action_hash: string;
+  initiator_id: string;
+  approver_id?: string;
+  expires_at: string;
+  status: 'pending' | string;
+  quorum?: { mode: string; required: number; count: number };
+  signoffs?: Array<{ signoff_id: string; role?: string; approver_id: string }>;
+}
+
+export interface ConsumeTrustReceiptParams {
+  actionHash: string;
+  executingSystem: string;
+  executionReferenceId?: string;
+}
+
+export interface ConsumeTrustReceiptResult {
+  receipt_id: string;
+  status: 'consumed' | string;
+  consumed_at: string;
+  consumed_by_system: string;
+  execution_reference_id?: string | null;
+}
+
+export interface AttestExecutionParams {
+  executedAction: Record<string, unknown>;
+  observedAction: Record<string, unknown>;
+  executingSystem: string;
+  executionId?: string;
+  executedAt?: string;
+}
+
+export interface ExecutionAttestation {
+  receipt_id: string;
+  status: 'executed' | string;
+  binding_status: 'match' | 'drift' | string;
+  executed_action_hash: string;
+  approved_action_hash: string;
+  execution_integrity: Record<string, unknown>;
+}
+
+export interface TrustReceiptEvidence {
+  document: Record<string, unknown> | null;
+  public_key: string | null;
+  signed: boolean;
+  verify_with: string;
+  receipt_id: string;
+  organization_id: string;
+  action: {
+    type: string;
+    action_hash: string;
+    before_state_hash?: string | null;
+    after_state_hash?: string | null;
+  };
+  policy: {
+    id: string;
+    hash: string;
+    decision: string;
+    enforcement_mode: string;
+  };
+  signoff: {
+    required: boolean;
+    approver_id?: string | null;
+    approved_at?: string | null;
+    rejected_at?: string | null;
+    events: Array<{ event_type: string; actor_id: string; at: string }>;
+  };
+  consume: {
+    consumed_at?: string | null;
+    consumed_by_system?: string | null;
+    execution_reference_id?: string | null;
+  };
+  issued_at: string;
+  expires_at: string;
+  schema_version: string;
+  [key: string]: unknown;
+}
+
+export interface SignoffRequiredContext {
+  client: unknown;
+  receipt: TrustReceipt;
+  signoff?: SignoffRequest;
+}
+
+export interface RequireReceiptParams extends CreateTrustReceiptParams {
+  executingSystem: string;
+  executionReferenceId?: string;
+  approverId?: string;
+  signoffComment?: string;
+  signoffExpiresInMinutes?: number;
+  /**
+   * Called after a signoff request is created. Complete approval externally
+   * (for example a passkey/WebAuthn ceremony or operator workflow) before
+   * returning. If omitted, the SDK fails closed and does not run the mutation.
+   */
+  onSignoffRequired?: (ctx: SignoffRequiredContext) => Promise<void | boolean | { approved?: boolean }>;
+  /** Legacy explicit execution report. Prefer observedAction for new integrations. */
+  executedAction?: Record<string, unknown> | ((ctx: { receipt: TrustReceipt; result: unknown }) => Record<string, unknown>);
+  /**
+   * Action fields independently observed by the executor after mutation. If
+   * omitted, no execution attestation is emitted.
+   */
+  observedAction?: Record<string, unknown> | ((ctx: { receipt: TrustReceipt; result: unknown }) => Record<string, unknown>);
+  executionId?: string | ((result: unknown) => string | undefined);
+  fetchEvidence?: boolean;
+}
+
+export interface RequireReceiptResult<T> {
+  result: T;
+  receipt: TrustReceipt;
+  signoff?: SignoffRequest;
+  consume: ConsumeTrustReceiptResult;
+  execution?: ExecutionAttestation;
+  executionStatus: 'attested' | 'unobserved';
+  evidence?: TrustReceiptEvidence;
+}
+
 /** A principal — the enduring actor behind one or more entities. */
 export interface Principal {
   principal_id: string;
@@ -472,16 +700,6 @@ export interface LineageResult {
   }>;
 }
 
-/** Result of a batch receipt submission. */
-export interface BatchReceiptResult {
-  results: Array<{
-    entity_id: string;
-    success: boolean;
-    receipt_id?: string;
-    error?: string;
-  }>;
-}
-
 /** Result of a bilateral receipt confirmation. */
 export interface ConfirmReceiptResult {
   receipt_id: string;
@@ -497,7 +715,7 @@ export interface TrustPolicyDefinition {
   min_confidence?: ConfidenceTier;
 }
 
-/** Public proof metrics from /api/stats. */
+/** Authenticated operator metrics from /api/stats. */
 export interface EPStats {
   total_entities: number;
   trust_surfaces: number;