/** Kind of party in a delegation: a person, organization, non-agent service, or AI agent. */ export type SubjectType = "NATURAL_PERSON" | "LEGAL_ENTITY" | "SERVICE" | "AGENT"; /** eIDAS 2.0 Person Identification Data attributes */ export interface EidasAttributes { /** Unique, persistent identifier assigned by the Member State (PID anchor) */ unique_id?: string; /** Current surname(s) */ family_name?: string; /** Current first name(s) */ given_name?: string; /** Date of birth (ISO 8601) */ birth_date?: string; /** Nationality (ISO 3166-1 alpha-2) */ nationality?: string; /** PID issuing authority identifier */ pid_issuer?: string; /** ISO 3166-1 alpha-2 issuing country */ issuing_country?: string; /** eIDAS assurance level */ assurance_level?: "LOW" | "SUBSTANTIAL" | "HIGH"; } /** * A party in a delegation — the principal granting authority or the delegate * receiving it. Identified by a stable `subject_id` and optionally enriched with * EUDI Wallet / eIDAS 2.0 verified attributes. */ export interface Subject { /** Subject type discriminator */ type: SubjectType; /** Unique subject identifier (e.g. "oidc|auth0|user123", "eudi:DE/1234...", "agent:example:validate-v2") */ subject_id: string; /** Optional display name */ display_name?: string; /** EUDI Wallet PID (planned for eIDAS 2.0 integration) */ eudi_pid?: string; /** eIDAS 2.0 verified attributes from EUDI Wallet PID */ eidas_attributes?: EidasAttributes; } /** * What a mandate delegates: the taxonomy actions and resource patterns it * covers, whether it grants or denies them, and any fine-grained conditions. */ export interface Scope { /** List of action identifiers from the taxonomy, e.g. ["construction.validation.approve"] */ actions: string[]; /** Resource URI patterns, e.g. ["construction:project:proj_123/*"] */ resources: string[]; /** Whether this scope allows or denies the actions */ effect: "ALLOW" | "DENY"; /** Optional conditions for fine-grained control */ conditions?: Record; } /** Time window bounding when a mandate is valid (not-before, expiry, or duration). */ export interface TimeConstraint { /** ISO 8601 timestamp — mandate becomes active */ not_before?: string; /** ISO 8601 timestamp — mandate expires */ expires_at?: string; /** ISO 8601 duration — alternative to expires_at, e.g. "P30D" */ duration?: string; } /** A monetary ceiling (currency + amount) applied to actions under a mandate. */ export interface TransactionLimit { currency: string; value: number; } /** A rule that escalates — notifies, requires approval, or blocks — when a condition is met. */ export interface EscalationRule { /** Condition that triggers escalation */ condition: string; /** Who to escalate to */ escalate_to: string; /** Escalation method */ method: "NOTIFY" | "APPROVAL_REQUIRED" | "BLOCK"; } /** A cap on how many operations a mandate permits within a rolling time window. */ export interface RateLimit { /** Maximum number of operations */ max_operations: number; /** Time window in seconds */ window_seconds: number; } /** * The boundaries on a mandate. * * **Not every field here is enforced by `POST /verify`.** The ones that are: * `time`, `require_mfa`, and `escalation_rules[].deviation_above_percent`. * Fields marked `@deprecated` below are accepted and stored but evaluated by * nothing on the verify path — the creation response names them in * `unsupported_constraints`, and every verification response reports * `evaluated_constraints` and `unevaluated_constraints`. * * They are deprecated as of 2026-09-10 and will be rejected at creation after * the 90-day deprecation window that applies to Stable endpoints. */ export interface Constraints { /** Enforced. The mandate's validity window. */ time?: TimeConstraint; /** * @deprecated Not enforced by `POST /verify`, which never has. A * Proof-of-Mandate issued by `/verify` lists this under * `unenforced_constraints` rather than in `constraints_snapshot`, so a * relying party is not misled into treating it as checked. * * The execution path (`POST /executions`) reads `max_amount` and * `max_total` in its own shapes, which this type does not describe yet: * money with a decimal-string `value`, and a list of * `{ amount, window }` (see the execution guide). */ transaction_limits?: Record; /** * Partially enforced. `deviation_above_percent` is evaluated by * `POST /verify` when the request supplies `context.deviation_percent`. * `amount_above` is evaluated only by the execution path * (`POST /executions`), in its own shape (see the execution guide). */ escalation_rules?: EscalationRule[]; /** * @deprecated Not enforced by `POST /verify`. For request-rate limiting see * the Rate Limiting guide — those limits are enforced per tenant at the * gateway, not per mandate. * * The execution path (`POST /executions`) reads `max_count`, a list of * `{ count, window }` this type does not describe yet, and refuses a * mandate carrying any other key here (see the execution guide). */ rate_limits?: Record; /** @deprecated Not enforced. Accepted and stored; no code path evaluates it. */ require_human_confirmation?: boolean; /** * When true, verification requires MFA proof in context. * Callers must provide one of: `context.amr` (containing "mfa"), * `context.loa` ("SUBSTANTIAL" or "HIGH"), or `context.mfa_timestamp`. */ require_mfa?: boolean; /** * Custom constraint extensions. * * Accepted and stored verbatim, and evaluated by nothing. Anything set here * appears in `unsupported_constraints` on the creation response. */ custom?: Record; } /** Lifecycle state of a mandate, from pending approval through active to a terminal state. */ export type MandateStatus = "ACTIVE" | "PENDING_APPROVAL" | "SUSPENDED" | "REVOKED" | "EXPIRED"; /** * The core delegation object: a signed, auditable grant of bounded authority * from a principal to a delegate, with a scope, constraints, status, and * cryptographic proof of creation. */ export interface Mandate { /** Unique mandate identifier, e.g. "mnd_abc123def456" */ mandate_id: string; /** Tenant that owns this mandate */ tenant_id: string; /** Who is delegating authority */ principal: Subject; /** Who is receiving authority */ delegate: Subject; /** What is being delegated */ scope: Scope; /** Boundaries on the delegation */ constraints: Constraints; /** Current status */ status: MandateStatus; /** Cryptographic proof of creation */ proof: MandateProof; /** Taxonomy version used for validation */ taxonomy_version?: string; /** ISO 8601 creation timestamp */ created_at: string; /** ISO 8601 last update timestamp */ updated_at: string; /** Optional metadata */ metadata?: Record; /** @experimental Verifiable User Instruction (present if instruction was provided at creation) */ vui?: VerifiableUserInstruction; } /** Cryptographic proof that a mandate was created, including the KMS signature and signer metadata. */ export interface MandateProof { /** Signature algorithm */ algorithm: string; /** KMS key ARN used for signing */ key_id: string; /** Base64-encoded signature */ signature: string; /** ISO 8601 timestamp of signing */ signed_at: string; /** EUDI session ID that authenticated the principal (when proof is from EUDI_WALLET) */ eudi_session_id?: string; /** VP Token compact serialization (audit trail for EUDI_WALLET proofs) */ vp_token_compact?: string; } /** The kind of action recorded in the audit log — mandate lifecycle, verification, or instruction events. */ export type AuditEventType = "MANDATE_CREATED" | "MANDATE_VERIFIED" | "MANDATE_REVOKED" | "MANDATE_SUSPENDED" | "MANDATE_REACTIVATED" | "MANDATE_APPROVED" | "MANDATE_REJECTED" | "MANDATE_EXPIRED" | "VERIFICATION_DENIED" | "INSTRUCTION_RECORDED" | "INSTRUCTION_REVEALED"; /** * A single immutable entry in a mandate's audit log. Events are hash-chained * (each carries the previous event's hash) so the log is tamper-evident. */ export interface AuditEvent { /** Unique event identifier */ event_id: string; /** Mandate this event belongs to */ mandate_id: string; /** Tenant ID */ tenant_id: string; /** Event type */ event_type: AuditEventType; /** Who triggered this event */ actor: Subject; /** Event-specific payload */ payload: Record; /** Hash of the previous event (chain integrity) */ previous_hash: string; /** Hash of this event */ event_hash: string; /** ISO 8601 timestamp */ timestamp: string; /** Algorithm used to compute event_hash (e.g., "SHA_256"). Present from crypto-agility v1. */ hash_algorithm?: string; /** Algorithm used to produce the KMS signature (e.g., "RSASSA_PSS_SHA_256"). Present from crypto-agility v1. */ signing_algorithm?: string; } /** Request body for creating a mandate: the principal, delegate, scope, constraints, and options. */ export interface CreateMandateRequest { principal: Subject; delegate: Subject; scope: Scope; constraints: Constraints; taxonomy_version?: string; metadata?: Record; /** If true, mandate starts in PENDING_APPROVAL state requiring explicit approval */ require_approval?: boolean; /** @experimental Intent declaration for drift detection */ intent?: MandateIntent; /** @experimental Verifiable User Instruction */ vui?: CreateVUIInput; } /** * Request body for a verification call: which delegate wants to perform which * action on which resource, plus optional context for condition evaluation. */ export interface VerifyRequest { /** * Subject ID of the delegate to verify, e.g. "agent:example:validate-v2". * This is the canonical field name. The server also accepts the legacy * alias `agent_id` for backwards compatibility with demo integrations. * If both are provided, `delegate_subject_id` takes precedence. */ delegate_subject_id: string; /** * Legacy alias for `delegate_subject_id`. * @deprecated Use `delegate_subject_id` instead. Will be removed in v2.0.0. */ agent_id?: string; /** Action being attempted */ action: string; /** Resource being accessed */ resource: string; /** Additional context for condition evaluation */ context?: Record; } /** * Result of a verification call: the ALLOW/DENY decision, the matching mandate * (on ALLOW), an audit event ID, and reason codes (on DENY). */ export interface VerifyResponse { /** Verification decision */ decision: "ALLOW" | "DENY"; /** Mandate ID that matched (present on ALLOW, absent on DENY/NO_MATCHING_MANDATE) */ mandate_id?: string; /** Unique verification event ID for audit trail */ event_id: string; /** Reason codes for denial (present on DENY) */ reason_codes?: string[]; /** Remaining constraints snapshot (present on ESCALATION_REQUIRED) */ constraints_remaining?: Record; } /** @experimental Channel through which the instruction was received */ export type InstructionChannel = "chat" | "email" | "voice" | "api"; /** @experimental How the principal confirmed the instruction */ export type ConfirmationMethod = "explicit_approval" | "implicit_delegation"; /** * @experimental Verifiable User Instruction. * Captures the human's original instruction in a machine-readable, * cryptographically signed form that gets embedded into PoM tokens. */ export interface VerifiableUserInstruction { /** Original instruction text (encrypted at rest via KMS envelope encryption) */ instruction_text: string; /** SHA-256 hex digest of the original (plaintext) instruction_text */ instruction_hash: string; /** ISO 8601 timestamp when the instruction was captured */ instruction_timestamp: string; /** Channel through which the instruction was received */ instruction_channel: InstructionChannel; /** How the principal confirmed the instruction */ principal_confirmation: { method: ConfirmationMethod; timestamp: string; /** Reference to evidence (chat log URL, email message-id, etc.) */ evidence_ref?: string; }; /** Constraints derived from the instruction (advisory, not enforced) */ constraints_derived?: { max_amount?: number; allowed_actions?: string[]; time_bound?: string; }; } /** * @experimental Response from GET /mandates/{id}/instruction. * Contains the decrypted instruction text and metadata. * Calling this endpoint creates an INSTRUCTION_REVEALED audit event. */ export interface InstructionResponse { /** Decrypted original instruction text */ instruction_text: string; /** SHA-256 hex digest of the instruction text */ instruction_hash: string; /** ISO 8601 timestamp when the instruction was captured */ instruction_timestamp: string; /** Channel through which the instruction was received */ instruction_channel: InstructionChannel; /** How the principal confirmed the instruction */ principal_confirmation: { method: ConfirmationMethod; timestamp: string; evidence_ref?: string; }; /** Mandate ID this instruction belongs to */ mandate_id: string; } /** @experimental VUI input for mandate creation (instruction_text + metadata) */ export interface CreateVUIInput { /** Original instruction text (max 2048 chars) */ instruction_text: string; /** Channel through which the instruction was received */ instruction_channel: InstructionChannel; /** How the principal confirmed the instruction */ principal_confirmation: { method: ConfirmationMethod; timestamp: string; evidence_ref?: string; }; /** Constraints derived from the instruction (advisory, not enforced) */ constraints_derived?: { max_amount?: number; allowed_actions?: string[]; time_bound?: string; }; } /** @experimental Intent declaration for drift detection */ export interface MandateIntent { /** Human-readable purpose of the mandate */ purpose: string; /** Expected action cluster IDs from the taxonomy's semantic graph */ expected_clusters?: string[]; /** Drift threshold (0.0–1.0). Default: 0.7 */ drift_threshold?: number; } /** @experimental Multi-dimensional drift score */ export interface DriftScore { /** How far actions stray from expected clusters (0.0–1.0) */ semantic_distance: number; /** Workflow order violations (0.0–1.0) */ sequence_deviation: number; /** Unusual action frequency patterns (0.0–1.0) */ frequency_anomaly: number; /** Actions outside declared scope (0.0–1.0) */ scope_expansion: number; /** Weighted aggregate score (0.0–1.0) */ aggregate: number; /** Whether the aggregate exceeds the mandate's drift threshold */ drift_detected: boolean; } /** @experimental Semantic signals returned alongside verification */ export interface SemanticSignals { /** Multi-dimensional drift score for the current session window */ drift_score?: DriftScore; /** Detected conflicts between recent actions */ conflicts?: Array<{ action_a: string; action_b: string; weight: number; rationale?: string; }>; /** Sequence violations in the current session */ sequence_violations?: Array<{ action: string; violation: string; expected: string; }>; /** Cross-mandate aggregate drift score for this delegate */ agent_drift_score?: number; } /** Supported output formats for the Proof-of-Mandate artifact */ export type PomFormat = "sd-jwt-vc"; /** W3C VC claim set embedded in the Proof-of-Mandate SD-JWT */ export interface ProofOfMandateClaims { /** VC type discriminator */ vct: "ProofOfMandate"; /** Verification decision */ decision: "ALLOW" | "DENY"; /** Mandate ID that was evaluated (absent for DENY/NO_MATCHING_MANDATE) */ mandate_id?: string; /** Unique verification event ID */ verification_event_id: string; /** ISO 8601 timestamp of the verification */ verification_timestamp: string; /** Action that was requested */ requested_action: string; /** Resource that was requested */ requested_resource: string; /** Subject ID of the delegate that was verified */ delegate_subject_id: string; /** Subject ID of the principal who granted the mandate (if found) */ principal_subject_id?: string; /** Tenant context (selectively disclosable) */ tenant_id?: string; /** Reason codes for denial (selectively disclosable) */ reason_codes?: string[]; /** Remaining constraints snapshot (selectively disclosable) */ constraints_snapshot?: Record; /** Verification latency in ms (selectively disclosable) */ latency_ms?: number; /** @experimental SHA-256 hex digest of the original user instruction (selectively disclosable) */ instruction_digest?: string; /** @experimental Drift score (selectively disclosable) */ drift_score?: DriftScore; /** @experimental Semantic conflicts (selectively disclosable) */ semantic_conflicts?: Array<{ action_a: string; action_b: string; weight: number; rationale?: string; }>; /** @experimental Cross-mandate agent drift score (selectively disclosable) */ agent_drift_score?: number; /** Issuer DID */ iss: string; /** Subject (delegate_subject_id) */ sub: string; /** Issued-at (Unix timestamp) */ iat: number; /** Expiration (Unix timestamp) */ exp: number; /** Selective-disclosure hash algorithm (e.g., "sha-256", "sha-384") */ _sd_alg: string; } /** The full Proof-of-Mandate VC envelope */ export interface ProofOfMandateVC { /** SD-JWT compact serialization (header.payload.signature~disclosure1~...~) */ compact: string; /** Decoded payload for convenience (not authoritative — the compact form is) */ payload: ProofOfMandateClaims; } /** Extended verify response that includes semantic (drift) signals. */ export interface VerifyResponseWithSemantics extends VerifyResponse { /** @experimental Semantic signals (present when ?drift=true) */ semantic_signals?: SemanticSignals; } /** Extended verify response that optionally includes a Proof-of-Mandate VC. */ export interface VerifyResponseWithPoM extends VerifyResponse { /** Proof-of-Mandate Verifiable Credential (present when ?pom=sd-jwt-vc) */ proof_of_mandate?: ProofOfMandateVC; /** * Legacy alias for `proof_of_mandate.compact`. * Provided for backwards compatibility with demo integrations. * @deprecated Use `proof_of_mandate.compact` instead. Will be removed in v2.0.0. */ proof_token?: string; } /** Options for a verify call: request a Proof-of-Mandate VC and/or drift-detection signals. */ export interface VerifyOptions { /** Request a Proof-of-Mandate VC in the specified format */ pom?: PomFormat; /** @experimental Request drift detection signals */ drift?: boolean; } /** A single page of results from a list endpoint, with an opaque cursor for the next page. */ export interface PaginatedResponse { items: T[]; /** Cursor for next page (undefined = last page) */ next_cursor?: string; /** Total count (only if requested) */ total_count?: number; } /** Lifecycle state of a tenant account. */ export type TenantStatus = "PENDING" | "ACTIVE" | "SUSPENDED" | "DEACTIVATED"; /** A tenant (customer organization) that owns mandates and API credentials. */ export interface Tenant { tenant_id: string; name: string; contact_email: string; status: TenantStatus; api_key_hash: string; created_at: string; updated_at: string; } /** A prospective customer's request for platform access, tracked through review to tenant provisioning. */ export interface AccessRequest { request_id: string; company_name: string; contact_name?: string; contact_email: string; use_case: string; website?: string; industry?: string; lead_source?: string; beta_track?: "default" | "healthcare" | "construction"; asset?: string; status: "PENDING" | "APPROVED" | "REJECTED"; submitted_at: string; reviewed_at?: string; reviewer_notes?: string; reviewed_by?: string; tenant_id?: string; } /** * A court-ready evidence bundle for a mandate: the mandate snapshot, its * hash-chained event log, proof tokens, a case-log hash, and the issuer DID * reference needed to verify everything independently. */ export interface EvidencePack { /** Schema version for forward compatibility */ schema_version: string; /** ISO 8601 timestamp of the export */ export_timestamp: string; /** Tenant context */ tenant_id: string; /** Mandate this evidence pack covers */ mandate_id: string; /** Full mandate snapshot at export time */ mandate_snapshot: Record; /** Hash-chained audit event log */ event_chain: Record[]; /** Number of events in the chain */ event_count: number; /** SHA-256 hash over the canonical event chain (court-ready fingerprint) */ case_log_hash: string; /** Chain integrity metadata */ chain_integrity: { first_event_hash: string; last_event_hash: string; genesis_verified: boolean; }; /** Issuer DID and verification endpoint */ issuer: { did: string; did_document_url: string; }; /** SD-JWT proof tokens from verification events */ proof_tokens: string[]; /** Export metadata */ metadata: { mandate_created_at: string; mandate_status: string; export_requested_by: string; event_id_filter?: string; }; } /** A newly created EUDI Wallet verification session, with QR-code and deep-link URIs for the wallet flow. */ export interface EudiSessionResponse { session_id: string; status: "PENDING"; request_uri: string; qr_code_uri: string; deep_link_uri: string; expires_at: string; } /** Current state of an EUDI Wallet verification session, including the resolved identity once completed. */ export interface EudiSessionStatus { session_id: string; status: "PENDING" | "COMPLETED" | "FAILED" | "EXPIRED"; created_at: string; presentation_definition_id: string; resolved_identity?: { subject_id: string; subject_type: string; provider: string; display_name?: string; assurance_level: string; eidas_attributes?: EidasAttributes; }; verified_at?: string; issuer?: string; errors?: string[]; } /** Request body for the tenant kill-switch, which revokes all of a tenant's active mandates at once. */ export interface KillSwitchRequest { reason: string; } /** * Accepted response of the tenant kill-switch. The revocation runs * asynchronously: poll `status_path` (a `KillSwitchExecution`) until its * status is COMPLETED or FAILED. */ export interface KillSwitchResponse { tenant_id: string; execution_id: string; status: "QUEUED"; /** Path of the execution status resource, relative to the API base URL. */ status_path: string; requested_at: string; /** Platform admin who triggered the kill-switch. */ requested_by: string; } export type KillSwitchExecutionStatus = "QUEUED" | "RUNNING" | "COMPLETED" | "FAILED"; /** A tool the kill switch disabled: what the tenant enables again once the incident is over. */ export interface KillSwitchDisabledTool { tool_id: string; version: number; /** The environment it was enabled in. Absent on records made before environments, all in `default`. */ environment?: string; connector_id: string; } /** * Progress record of one kill-switch execution. Counts add up page by page * while RUNNING and are final once COMPLETED or FAILED. The worker disables * the tenant's tools, stops its executions not yet dispatched, then revokes * its mandates; the fields on tools and executions are absent on an * execution recorded before it did. */ export interface KillSwitchExecution { execution_id: string; tenant_id: string; status: KillSwitchExecutionStatus; reason: string; requested_by: string; requested_at: string; started_at?: string; finished_at?: string; updated_at: string; /** What the worker is doing, in this order. */ phase?: "TOOLS" | "EXECUTIONS" | "MANDATES"; /** The tools it disabled. */ tools_disabled?: KillSwitchDisabledTool[]; /** Executions it stopped before they were dispatched, each DENIED with KILL_SWITCH. */ executions_cancelled?: number; /** Executions already dispatched (EXECUTING, UNKNOWN): they finish, and nothing recalls them. */ executions_in_flight?: number; /** Executions another writer held when it reached them; each ends refused, its tool no longer enabled. */ executions_busy?: number; /** Executions whose denial could not be recorded; each is refused by the same check. */ executions_failed?: number; /** Mandates this execution moved to REVOKED. */ revoked_count: number; /** Mandates that needed nothing: already REVOKED or EXPIRED, never submitted, or changed meanwhile. */ skipped_count: number; /** Mandates whose status write failed; still ACTIVE, SUSPENDED or PENDING_APPROVAL. */ failed_count: number; /** Revoked mandates whose MANDATE_REVOKED audit event could not be written. */ audit_event_failures: number; pages_processed: number; /** Worker invocations after the first, for a run that outgrew one invocation. */ continuations: number; /** Delivery attempts of the current queue message. */ attempts: number; last_error?: string; } /** Identity provider a tenant can enable for authenticating principals (API key, Cognito, EUDI Wallet, OIDC providers, …). */ export type IdentityProviderType = "API_KEY" | "COGNITO" | "EUDI_WALLET" | "AUTH0" | "OKTA" | "ENTRA_ID" | "GOOGLE" | "AWS_IAM_IDC" | "GENERIC_OIDC"; /** A tenant's current identity-provider configuration as returned by the API. */ export interface TenantIdpConfig { tenant_id: string; identity_providers: { enabled_providers: IdentityProviderType[]; auth0?: { domain: string; audience: string; client_id: string; }; okta?: { issuer: string; audience: string; }; entra?: { tenant_id: string; client_id: string; }; eudi?: { rp_id: string; presentation_policies: string[]; }; }; } /** Request body for updating a tenant's identity-provider configuration. */ export interface TenantIdpConfigUpdate { enabled_providers: IdentityProviderType[]; auth0?: { domain: string; audience: string; client_id: string; }; okta?: { issuer: string; audience: string; }; entra?: { tenant_id: string; client_id: string; }; eudi?: { rp_id: string; presentation_policies: string[]; }; google?: { client_id: string; hosted_domain?: string; }; aws_iam_idc?: { issuer: string; audience: string; }; generic_oidc?: { name: string; issuer: string; audience: string; subject_prefix: string; }; } //# sourceMappingURL=types.d.ts.map