{ "openapi": "3.1.0", "info": { "title": "FARIGATE Gate API", "description": "Regulated-finance evidence infrastructure.\n\n`POST /gate` (and the bank-facing alias `POST /v1/activations`) submits a governance action for a decision and returns a signed receipt plus a self-contained evidence pack. The gate fails closed on unsupported regulated action types, stale or unverifiable source state, and missing required evidence context.\n\nSupported regulated action types and their required structured contexts: `regulated_product_activation`, `regulated_client_entitlement`, `regulated_platform_change`, `regulated_monitoring_coverage`, and `agent_payment`. The `agent_payment` action implements the AP2 v0.2.0 mandate profile (checkout + payment mandate SD-JWTs verified against operator-supplied trust material). This is a statement of implemented behavior, not an endorsement, certification, or compliance approval by any payment network, standards body, or regulator.\n\nFARIGATE is evidence infrastructure: a decision and its evidence pack prove what the gate decided and verified — they do not guarantee that an enforcement action cannot happen elsewhere.", "license": { "name": "Proprietary", "identifier": "Proprietary" }, "version": "0.6.0" }, "paths": { "/gate": { "post": { "tags": [ "gate" ], "summary": "POST /gate — Submit a governance action for a decision.", "description": "This handler:\n1. Validates the request body\n2. Enforces actor binding (in strict mode)\n3. Handles idempotency and deduplication via the durable intake journal\n4. Returns a decision response with a signed receipt\n\nNote: Full receipt signing and sequencing is handled by the evidence plane.\nThis ingestion plane handler focuses on admission control, validation, and\ndurable journaling.", "operationId": "submit_gate_decision", "requestBody": { "description": "Governance action to gate. Regulated action types (`regulated_product_activation`, `regulated_client_entitlement`, `regulated_platform_change`, `regulated_monitoring_coverage`, `agent_payment`) require their matching structured context field; unsupported regulated action types fail closed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateRequest" } } }, "required": true }, "responses": { "200": { "description": "Decision issued: signed receipt and self-contained evidence pack (also returned when replaying a completed idempotent request)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateResponse" } } } }, "202": { "description": "Request journaled; evidence-plane completion pending or a request with the same idempotency key is in flight. Replay with the same idempotency key to retrieve the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateErrorResponse" } } } }, "400": { "description": "Fail-closed validation rejection: unsupported regulated action_type, action-digest mismatch, missing or invalid required regulated context (including AP2 mandate context for agent_payment), reserved context keys, or invalid idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateErrorResponse" } } } }, "401": { "description": "Missing, invalid, or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateErrorResponse" } } } }, "403": { "description": "Actor binding rejected: the authenticated key is not authorized to submit for the claimed actor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateErrorResponse" } } } }, "409": { "description": "Idempotency conflict: the idempotency key was already used with a different request payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateErrorResponse" } } } }, "422": { "description": "Malformed JSON request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateErrorResponse" } } } }, "503": { "description": "Service unavailable: shutting down, database not configured, or verified governance bundle unavailable (fail closed)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateErrorResponse" } } } } }, "security": [ { "bearer_api_key": [] } ] } }, "/gate/settle": { "post": { "tags": [ "gate" ], "summary": "POST /gate/settle — Bind a rail-confirmation (settlement) layer to a\ncommitted `agent_payment` decision.", "operationId": "settle_gate_decision", "requestBody": { "description": "The committed decision's request_key plus the rail's settlement result (RailConfirmation). The settlement is cross-checked against the authorized mandate amount/currency and the decision receipt digest; you can only settle what was authorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettleRequest" } } }, "required": true }, "responses": { "200": { "description": "Settlement bound (or replayed): the signed rail-confirmation binding and the updated evidence pack carrying the additive rail layer. A byte-identical re-settle replays the existing binding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettleResponse" } } } }, "400": { "description": "Fail-closed rejection: not an agent_payment decision, receipt-digest mismatch, amount/currency divergence from the authorized mandate, or malformed rail confirmation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateErrorResponse" } } } }, "401": { "description": "Missing, invalid, or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateErrorResponse" } } } }, "403": { "description": "Actor binding rejected: the authenticated key is not the actor that made the decision", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateErrorResponse" } } } }, "404": { "description": "No committed decision found for this request_key in the caller's tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateErrorResponse" } } } }, "409": { "description": "Settlement conflict: the decision is already settled with a different rail confirmation (a decision settles once)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateErrorResponse" } } } }, "422": { "description": "Malformed JSON request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateErrorResponse" } } } }, "503": { "description": "Service unavailable: database not configured or receipt signer unavailable (fail closed)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateErrorResponse" } } } } }, "security": [ { "bearer_api_key": [] } ] } }, "/openapi.json": { "get": { "tags": [ "meta" ], "summary": "GET /openapi.json — the OpenAPI document for this API.", "description": "Plain JSON document route (no UI); unauthenticated.", "operationId": "get_openapi_document", "responses": { "200": { "description": "OpenAPI document for the gate API" } } } }, "/v1/activations": { "post": { "tags": [ "gate" ], "summary": "POST /v1/activations — Bank-facing alias over the existing gate pipeline.", "operationId": "submit_activation", "requestBody": { "description": "Bank-facing activation request; mapped onto the same gate decision pipeline as POST /gate (the alias accepts the four structured regulated contexts but not `agent_payment`, which is a /gate context).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivationRequest" } } }, "required": true }, "responses": { "200": { "description": "Decision issued: signed receipt and self-contained evidence pack", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateResponse" } } } }, "202": { "description": "Request journaled; evidence-plane completion pending or a request with the same idempotency key is in flight", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateErrorResponse" } } } }, "400": { "description": "Fail-closed validation rejection (see POST /gate)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateErrorResponse" } } } }, "401": { "description": "Missing, invalid, or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateErrorResponse" } } } }, "403": { "description": "Actor binding rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateErrorResponse" } } } }, "409": { "description": "Idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateErrorResponse" } } } }, "422": { "description": "Malformed JSON request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateErrorResponse" } } } }, "503": { "description": "Service unavailable (fail closed)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateErrorResponse" } } } } }, "security": [ { "bearer_api_key": [] } ] } } }, "components": { "schemas": { "ActionEvidencePack": { "type": "object", "required": [ "format", "summary", "chain", "governance", "verifier", "included_artifacts", "artifact_class" ], "properties": { "artifact_class": { "$ref": "#/components/schemas/ArtifactClass", "description": "Artifact class identifying this as a combined evidence package.\nThe evidence pack contains both decision receipt and governance materials." }, "binding": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EvidencePackBinding" } ] }, "chain": { "$ref": "#/components/schemas/EvidencePackChain" }, "checkpoint": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EvidencePackCheckpoint" } ] }, "evidence_contract": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EvidenceContract" } ] }, "format": { "type": "string" }, "governance": { "$ref": "#/components/schemas/EvidencePackGovernance" }, "included_artifacts": { "type": "array", "items": { "$ref": "#/components/schemas/EvidencePackArtifact" } }, "manifest": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EvidencePackManifest" } ] }, "rail_confirmation_binding": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EvidencePackRailConfirmationBinding", "description": "Additive, separately-signed rail-confirmation layer. Present only after\na settlement has been bound via `/gate/settle`. The rail-confirmation\nartifact itself rides in `included_artifacts`/`manifest` with role\n[`RAIL_CONFIRMATION_ARTIFACT_ROLE`]; this field carries the signed\nbinding over it. `None` for decision-time packs (back-compat)." } ] }, "receipt": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EvidencePackReceipt" } ] }, "summary": { "$ref": "#/components/schemas/EvidencePackSummary" }, "verifier": { "$ref": "#/components/schemas/EvidencePackVerifier" } } }, "ActivationEvidenceRef": { "type": "object", "required": [ "ref_id" ], "properties": { "collected_at": { "type": [ "string", "null" ] }, "jurisdiction": { "type": [ "string", "null" ] }, "ref_id": { "type": "string" } } }, "ActivationRequest": { "type": "object", "description": "The public `/v1/activations` request payload.\nDomain-agnostic within the supported appliance, but not the canonical\nlong-term Farigate evidence-event model.", "required": [ "action_type", "action_digest", "actor", "subject" ], "properties": { "action_digest": { "type": "string", "description": "SHA-256 hash of the underlying document/artifact being reviewed.\nFormat: \"sha256:\" (64 hex chars after prefix).\nThis is the cryptographic anchor to the actual content.\nThe client computes this on their side — Farigate never sees the raw document." }, "action_type": { "type": "string", "description": "What kind of governance action is being gated.\nExamples: \"document_approval\", \"model_deploy\", \"kyc_decision\"" }, "actor": { "$ref": "#/components/schemas/Actor", "description": "Identity of the actor requesting the activation." }, "context": { "description": "Additional context. Farigate does NOT inspect or store the contents.\nWARNING: Do not include PII. This value is hashed into the receipt's\ncomposite request digest." }, "regulated_client_entitlement": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/RegulatedClientEntitlement", "description": "Structured regulated client entitlement payload for the v0 client\nentitlement control flow. Optional for backward compatibility, but\nrequired when `action_type` is `regulated_client_entitlement`." } ] }, "regulated_monitoring_coverage": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/RegulatedMonitoringCoverage", "description": "Structured population coverage proof payload for the v0 monitoring\ncoverage control flow. Optional for backward compatibility, but\nrequired when `action_type` is `regulated_monitoring_coverage`." } ] }, "regulated_platform_change": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/RegulatedPlatformChange", "description": "Structured regulated platform change payload for the v0 platform-state\ncontrol flow. Optional for backward compatibility, but required when\n`action_type` is `regulated_platform_change`." } ] }, "regulated_product_activation": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/RegulatedProductActivation", "description": "Structured regulated product activation payload for the v0 activation\ncontrol flow. Optional for backward compatibility, but required when\n`action_type` is `regulated_product_activation`." } ] }, "subject": { "$ref": "#/components/schemas/Subject", "description": "The thing being reviewed/approved/denied." } } }, "Actor": { "type": "object", "required": [ "id", "role" ], "properties": { "id": { "type": "string" }, "institution": { "type": [ "string", "null" ] }, "role": { "type": "string" } } }, "AgentPaymentContext": { "type": "object", "description": "Structured AP2 mandate context for the `agent_payment` regulated action.\n\nCarries the checkout + payment mandate SD-JWT compact serializations\n(AP2 v0.2 per ADR-003) plus the key-binding expectations for delegated\n(human-not-present) chains. The mandate signatures are verified by the\ngate against the agent-mandate trust directory; intake only enforces\nstructural bounds and the action-digest binding.", "required": [ "checkout_mandate", "payment_mandate" ], "properties": { "checkout_mandate": { "type": "string", "description": "Checkout Mandate token (single SD-JWT or `~~`-joined chain)." }, "checkout_nonce": { "type": [ "string", "null" ], "description": "Expected `nonce` on checkout-chain KB hops." }, "expected_aud": { "type": [ "string", "null" ], "description": "Expected `aud` on KB hops (enforced on every hop when set)." }, "payment_mandate": { "type": "string", "description": "Payment Mandate token (single SD-JWT or `~~`-joined chain)." }, "payment_nonce": { "type": [ "string", "null" ], "description": "Expected `nonce` on payment-chain KB hops." } } }, "ArtifactClass": { "type": "string", "description": "Artifact class identifies the semantic role of an artifact in the evidence system.\nThis allows operators to distinguish between decision receipts, governance bundles,\nand combined evidence packages.", "enum": [ "decision_receipt", "governance_bundle", "combined_evidence_package", "public_key" ] }, "EvidenceContract": { "type": "object", "required": [ "format", "id", "action_class", "required_source_classes", "required_approval_context", "required_policy_context", "required_trace_outcomes", "required_artifacts", "required_verifier_profile", "fail_closed_cases", "caveats", "non_claims" ], "properties": { "action_class": { "type": "string" }, "caveats": { "type": "array", "items": { "type": "string" } }, "fail_closed_cases": { "type": "array", "items": { "type": "string" } }, "format": { "type": "string" }, "id": { "$ref": "#/components/schemas/EvidenceContractId" }, "non_claims": { "type": "array", "items": { "type": "string" } }, "required_approval_context": { "type": "array", "items": { "type": "string" } }, "required_artifacts": { "type": "array", "items": { "$ref": "#/components/schemas/EvidenceContractArtifactRequirement" } }, "required_policy_context": { "type": "array", "items": { "type": "string" } }, "required_source_classes": { "type": "array", "items": { "type": "string" } }, "required_trace_outcomes": { "type": "array", "items": { "type": "string" } }, "required_verifier_profile": { "$ref": "#/components/schemas/EvidenceContractVerifierProfile" } } }, "EvidenceContractArtifactRequirement": { "type": "object", "required": [ "class", "path", "role" ], "properties": { "class": { "type": "string" }, "path": { "type": "string" }, "role": { "type": "string" } } }, "EvidenceContractId": { "type": "string" }, "EvidenceContractVerifierProfile": { "type": "object", "required": [ "profile_id", "strict_embedded_required", "trusted_embedded_roots_required", "signed_receipt_required", "signed_pack_binding_required", "source_binding_required", "policy_replay_required", "checkpoint_required" ], "properties": { "checkpoint_required": { "type": "boolean" }, "policy_replay_required": { "type": "boolean" }, "profile_id": { "type": "string" }, "signed_pack_binding_required": { "type": "boolean" }, "signed_receipt_required": { "type": "boolean" }, "source_binding_required": { "type": "boolean" }, "strict_embedded_required": { "type": "boolean" }, "trusted_embedded_roots_required": { "type": "boolean" } } }, "EvidencePackArtifact": { "type": "object", "required": [ "path", "sha256", "data_b64" ], "properties": { "data_b64": { "type": "string" }, "path": { "type": "string" }, "sha256": { "type": "string" } } }, "EvidencePackBinding": { "type": "object", "required": [ "statement", "signature" ], "properties": { "signature": { "$ref": "#/components/schemas/EvidencePackBindingSignature" }, "statement": { "$ref": "#/components/schemas/EvidencePackBindingStatement" } } }, "EvidencePackBindingSignature": { "type": "object", "required": [ "algorithm", "signer_kid", "signature_b64" ], "properties": { "algorithm": { "type": "string" }, "signature_b64": { "type": "string" }, "signer_kid": { "type": "string" } } }, "EvidencePackBindingStatement": { "type": "object", "required": [ "format", "receipt_digest", "manifest_sha256", "included_artifacts_sha256", "summary_sha256", "chain_sha256", "governance_sha256", "artifact_class", "issued_at_unix", "signer_kid" ], "properties": { "artifact_class": { "type": "string" }, "chain_sha256": { "type": "string" }, "evidence_contract_sha256": { "type": [ "string", "null" ] }, "format": { "type": "string" }, "governance_sha256": { "type": "string" }, "included_artifacts_sha256": { "type": "string" }, "issued_at_unix": { "type": "integer", "format": "int64", "minimum": 0 }, "manifest_sha256": { "type": "string" }, "receipt_digest": { "type": "string" }, "signer_kid": { "type": "string" }, "summary_sha256": { "type": "string" } } }, "EvidencePackChain": { "type": "object", "required": [ "prev_hash", "chain_hash", "counter", "receipt_digest" ], "properties": { "chain_hash": { "type": "string" }, "counter": { "type": "integer", "format": "int64", "minimum": 0 }, "prev_hash": { "type": "string" }, "receipt_digest": { "type": "string" } } }, "EvidencePackCheckpoint": { "type": "object", "required": [ "format", "statement", "inclusion", "signature" ], "properties": { "format": { "type": "string" }, "inclusion": { "$ref": "#/components/schemas/EvidencePackInclusionProof" }, "signature": { "$ref": "#/components/schemas/EvidencePackCheckpointSignature" }, "statement": { "$ref": "#/components/schemas/EvidencePackCheckpointStatement" } } }, "EvidencePackCheckpointSignature": { "type": "object", "required": [ "algorithm", "signer_kid", "signature_b64" ], "properties": { "algorithm": { "type": "string" }, "signature_b64": { "type": "string" }, "signer_kid": { "type": "string" } } }, "EvidencePackCheckpointStatement": { "type": "object", "required": [ "format", "scope", "issued_at_unix", "merkle_root", "retained_window", "completeness" ], "properties": { "completeness": { "$ref": "#/components/schemas/EvidencePackCompleteness" }, "format": { "type": "string" }, "issued_at_unix": { "type": "integer", "format": "int64", "minimum": 0 }, "merkle_root": { "type": "string" }, "retained_window": { "$ref": "#/components/schemas/EvidencePackRetainedWindow" }, "scope": { "$ref": "#/components/schemas/EvidencePackScope" } } }, "EvidencePackCompleteness": { "type": "object", "required": [ "status", "statement", "independent_reconciliation" ], "properties": { "independent_reconciliation": { "type": "string" }, "statement": { "type": "string" }, "status": { "type": "string" } } }, "EvidencePackCustomerStorageLayout": { "type": "object", "required": [ "format", "manifest_path", "pack_path", "checkpoint_path", "artifacts_root" ], "properties": { "artifacts_root": { "type": "string" }, "checkpoint_path": { "type": "string" }, "format": { "type": "string" }, "manifest_path": { "type": "string" }, "pack_path": { "type": "string" } } }, "EvidencePackGovernance": { "type": "object", "required": [ "workflow_id", "policy_set_id", "governance_version", "policy_snapshot", "profile_id", "signer_kid" ], "properties": { "governance_version": { "type": "string" }, "policy_set_id": { "type": "string" }, "policy_snapshot": { "type": "string" }, "profile_id": { "type": "string" }, "signer_kid": { "type": "string" }, "workflow_id": { "type": "string" } } }, "EvidencePackInclusionProof": { "type": "object", "required": [ "algorithm", "leaf_hash", "leaf_index", "leaf_count", "siblings" ], "properties": { "algorithm": { "type": "string" }, "leaf_count": { "type": "integer", "format": "int64", "minimum": 0 }, "leaf_hash": { "type": "string" }, "leaf_index": { "type": "integer", "format": "int64", "minimum": 0 }, "siblings": { "type": "array", "items": { "type": "string" } } } }, "EvidencePackManifest": { "type": "object", "required": [ "format", "scope", "included_artifacts", "customer_storage" ], "properties": { "checkpoint": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EvidencePackManifestCheckpointBinding" } ] }, "customer_storage": { "$ref": "#/components/schemas/EvidencePackCustomerStorageLayout" }, "evidence_contract": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EvidencePackManifestContractBinding" } ] }, "format": { "type": "string" }, "included_artifacts": { "type": "array", "items": { "$ref": "#/components/schemas/EvidencePackManifestEntry" } }, "scope": { "$ref": "#/components/schemas/EvidencePackScope" } } }, "EvidencePackManifestCheckpointBinding": { "type": "object", "required": [ "statement_sha256", "inclusion_sha256", "signature_sha256", "merkle_root" ], "properties": { "inclusion_sha256": { "type": "string" }, "merkle_root": { "type": "string" }, "signature_sha256": { "type": "string" }, "statement_sha256": { "type": "string" } } }, "EvidencePackManifestContractBinding": { "type": "object", "required": [ "contract_id", "artifact_path", "sha256" ], "properties": { "artifact_path": { "type": "string" }, "contract_id": { "$ref": "#/components/schemas/EvidenceContractId" }, "sha256": { "type": "string" } } }, "EvidencePackManifestEntry": { "type": "object", "required": [ "path", "sha256", "role" ], "properties": { "path": { "type": "string" }, "role": { "type": "string" }, "sha256": { "type": "string" } } }, "EvidencePackRailConfirmationBinding": { "type": "object", "description": "The additive, separately-verifiable rail-confirmation binding carried at the\ntop level of an evidence pack. The decision-pack [`EvidencePackBinding`] and\nmanifest are NOT modified by settlement.", "required": [ "statement", "signature" ], "properties": { "signature": { "$ref": "#/components/schemas/RailConfirmationBindingSignature" }, "statement": { "$ref": "#/components/schemas/RailConfirmationBindingStatement" } } }, "EvidencePackReceipt": { "type": "object", "required": [ "receipt_bytes_b64", "receipt_digest" ], "properties": { "receipt_bytes_b64": { "type": "string" }, "receipt_digest": { "type": "string" } } }, "EvidencePackRetainedWindow": { "type": "object", "required": [ "receipts", "first_counter", "last_counter" ], "properties": { "first_counter": { "type": "integer", "format": "int64", "minimum": 0 }, "last_counter": { "type": "integer", "format": "int64", "minimum": 0 }, "receipts": { "type": "integer", "format": "int64", "minimum": 0 } } }, "EvidencePackScope": { "type": "object", "required": [ "tenant_id", "workflow_id", "action_type", "policy_set_id" ], "properties": { "action_type": { "type": "string" }, "policy_set_id": { "type": "string" }, "tenant_id": { "type": "string" }, "workflow_id": { "type": "string" } } }, "EvidencePackSummary": { "type": "object", "required": [ "workflow_id", "action_type", "action_digest", "decision", "engine_reason_str", "engine_reason", "policy_reason", "policy_detail", "actor_id", "actor_role", "actor_verified", "actor_verification_method", "subject_type", "subject_id", "portability_note" ], "properties": { "action_digest": { "type": "string" }, "action_type": { "type": "string" }, "actor_id": { "type": "string" }, "actor_role": { "type": "string" }, "actor_verification_method": { "type": "string" }, "actor_verified": { "type": "boolean" }, "decision": { "type": "string" }, "engine_reason": { "type": "integer", "format": "int32", "minimum": 0 }, "engine_reason_str": { "type": "string" }, "policy_detail": { "type": "string" }, "policy_reason": { "type": "string" }, "portability_note": { "type": "string" }, "reason_codes": { "type": "array", "items": { "type": "string" } }, "subject_id": { "type": "string" }, "subject_type": { "type": "string" }, "subject_version": { "type": [ "string", "null" ] }, "workflow_id": { "type": "string" } } }, "EvidencePackVerifier": { "type": "object", "required": [ "format", "receipt_format", "verification_scope", "cli_hint" ], "properties": { "cli_hint": { "type": "string" }, "format": { "type": "string" }, "receipt_format": { "type": "string" }, "verification_scope": { "type": "string" } } }, "GateErrorResponse": { "type": "object", "description": "Error response body", "required": [ "error", "code" ], "properties": { "code": { "type": "string" }, "detail": { "type": [ "string", "null" ] }, "error": { "type": "string" } } }, "GateRequest": { "type": "object", "description": "The current appliance `/gate` request payload.\nDomain-agnostic within the supported appliance, but not the canonical\nlong-term Farigate evidence-event model.", "required": [ "action_type", "action_digest", "actor", "subject", "requested_decision" ], "properties": { "action_digest": { "type": "string", "description": "SHA-256 hash of the underlying document/artifact being reviewed.\nFormat: \"sha256:\" (64 hex chars after prefix).\nThis is the cryptographic anchor to the actual content.\nThe client computes this on their side — Farigate never sees the raw document." }, "action_type": { "type": "string", "description": "What kind of governance action is being gated.\nExamples: \"document_approval\", \"model_deploy\", \"kyc_decision\"" }, "actor": { "$ref": "#/components/schemas/Actor", "description": "Identity of the actor requesting the gate decision." }, "agent_payment": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AgentPaymentContext", "description": "Structured AP2 mandate context. Generic `/gate` clients omit this\nfield, but it is required when action_type is `agent_payment`; the\nembedded checkout/payment mandate tokens are required mandate evidence\nfor that regulated action contract." } ] }, "context": { "description": "Additional context. Farigate does NOT inspect or store the contents.\nWARNING: Do not include PII. This value is hashed into the receipt's\ncomposite request digest." }, "regulated_client_entitlement": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/RegulatedClientEntitlement", "description": "Structured client entitlement context. Generic `/gate` clients omit this\nfield, but it is required when action_type is `regulated_client_entitlement`;\nthe embedded source_snapshots are required source evidence for that\nregulated action contract." } ] }, "regulated_monitoring_coverage": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/RegulatedMonitoringCoverage", "description": "Optional structured monitoring coverage context. Existing `/gate`\nclients can omit this field; the v0 monitoring-coverage flow uses it to\nbind source records, monitored records, exclusions, approvals, and the\nmapping version into the decision receipt." } ] }, "regulated_platform_change": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/RegulatedPlatformChange", "description": "Structured platform change context. Generic `/gate` clients omit this\nfield, but it is required when action_type is `regulated_platform_change`;\nthe embedded source_snapshots are required source evidence for that\nregulated action contract." } ] }, "regulated_product_activation": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/RegulatedProductActivation", "description": "Structured product activation context. Generic `/gate` clients omit this\nfield, but it is required when action_type is `regulated_product_activation`;\nthe embedded source_snapshots are required source evidence for that\nregulated action contract." } ] }, "requested_decision": { "type": "string", "description": "Requested decision: \"approve\", \"deny\", \"escalate\"" }, "subject": { "$ref": "#/components/schemas/Subject", "description": "The thing being reviewed/approved/denied." } } }, "GateResponse": { "type": "object", "description": "The gate response returned to the client.\nContains the signed receipt — client stores this in their own infrastructure.", "required": [ "decision", "engine_reason", "engine_reason_code", "policy_reason", "policy_detail", "receipt_bytes_b64", "receipt_digest", "policy_snapshot", "policy_set_id", "governance_version", "profile_id", "timestamp_unix", "counter", "chain_hash", "actor_verified", "actor_verification_method", "evidence_pack", "artifact_class" ], "properties": { "actor_verification_method": { "type": "string", "description": "How the actor was verified: \"actor_bound_api_key\" or \"self_reported\"" }, "actor_verified": { "type": "boolean", "description": "Whether the actor identity was verified via an actor-bound API key." }, "artifact_class": { "$ref": "#/components/schemas/ArtifactClass", "description": "Artifact class identifying the primary artifact type in this response.\nThe /gate endpoint always returns a decision receipt as the primary artifact." }, "chain_hash": { "type": "string", "description": "Tenant-scoped hash chain value" }, "counter": { "type": "integer", "format": "int64", "description": "Monotonic counter value (per-tenant, strictly increasing)", "minimum": 0 }, "decision": { "type": "string", "description": "Decision: \"allow\", \"deny\", \"escalate\"" }, "engine_reason": { "type": "string", "description": "Engine-level reason string (e.g. \"ENGINE_ALLOW\")." }, "engine_reason_code": { "type": "integer", "format": "int32", "description": "Engine-level numeric reason code bound into the signed receipt.", "minimum": 0 }, "evidence_pack": { "$ref": "#/components/schemas/ActionEvidencePack", "description": "Self-contained action evidence pack for offline storage and verification." }, "governance_version": { "type": "string", "description": "Governance bundle version used at decision time." }, "policy_detail": { "type": "string", "description": "Policy-provided human-readable detail (opaque to engine)." }, "policy_reason": { "type": "string", "description": "Policy-provided reason identifier (opaque to engine)." }, "policy_set_id": { "type": "string", "description": "Versioned governance bundle reference used at decision time." }, "policy_snapshot": { "type": "string", "description": "SHA-256 hex of the policy bundle active at decision time" }, "profile_id": { "type": "string", "description": "PoG profile ID bound into the signed receipt and governance bundle." }, "reason_codes": { "type": "array", "items": { "type": "string" }, "description": "Stable product-meaningful reason codes in priority order." }, "receipt_bytes_b64": { "type": "string", "description": "Base64-encoded CBOR receipt envelope — the portable cryptographic proof." }, "receipt_digest": { "type": "string", "description": "SHA-256 hex digest of the receipt bytes" }, "timestamp_unix": { "type": "integer", "format": "int64", "description": "Unix timestamp of the decision", "minimum": 0 } } }, "LocalApprovalRef": { "type": "object", "required": [ "ref_id" ], "properties": { "approved_at": { "type": [ "string", "null" ] }, "jurisdiction": { "type": [ "string", "null" ] }, "ref_id": { "type": "string" } } }, "MonitoringControlExclusion": { "type": "object", "required": [ "source_record_id", "reason_code" ], "properties": { "approval_ref": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LocalApprovalRef" } ] }, "reason_code": { "type": "string" }, "source_record_id": { "type": "string" } } }, "MonitoringControlRecord": { "type": "object", "required": [ "record_id", "source_record_id" ], "properties": { "record_id": { "type": "string" }, "source_record_id": { "type": "string" } } }, "MonitoringMappingVersion": { "type": "object", "required": [ "version", "approved_at", "expires_at" ], "properties": { "approved_at": { "type": "string" }, "expires_at": { "type": "string" }, "version": { "type": "string" } } }, "MonitoringPopulationRecord": { "type": "object", "required": [ "record_id" ], "properties": { "record_id": { "type": "string" } } }, "RailConfirmation": { "type": "object", "description": "A separately-signed rail-confirmation layer proving the payment SETTLED on\nthe rail as authorized.\n\nThis is the additive settlement layer that links to a decision receipt by\n`receipt_digest`. It is NOT part of the decision-time pack binding (which is\nsealed at decision time); it rides as its own artifact plus its own signed\nbinding statement ([`RailConfirmationBindingStatement`]).\n\nAP2 mapping (`core/crates/farigate-mandate/spec/schemas/payment_receipt.json`):\n- [`RailConfirmation::status`] ~ AP2 `status` (`Success`→`approved`,\n `Error`→`error`; `declined` is a network decline distinct from a\n processing error).\n- [`RailConfirmation::network_transaction_id`] ~ AP2 `network_confirmation_id`\n (the network's transaction confirmation id, i.e. the Visa ARN /\n `transactionIdentifier`, carried as a string).\n- [`RailConfirmation::approval_code`] ~ the issuer approval/auth code.\n- [`RailConfirmation::receipt_digest`] ~ AP2 `reference` in spirit: it binds\n this rail confirmation to the closed decision it settles.", "required": [ "format", "rail", "status", "action_code", "network_transaction_id", "settled_at_unix", "amount_minor_units", "currency", "receipt_digest" ], "properties": { "action_code": { "type": "string", "description": "Rail/network response action code (e.g. ISO `\"00\"` for approved)." }, "amount_minor_units": { "type": "integer", "format": "int64", "description": "Settled amount in minor units; cross-checked against the decision's\nmandate-derived amount by the gate and the offline verifier." }, "approval_code": { "type": [ "string", "null" ], "description": "Issuer approval/authorization code, when present." }, "currency": { "type": "string", "description": "Settled currency; cross-checked against the decision's mandate-derived\ncurrency." }, "format": { "type": "string", "description": "Always [`RAIL_CONFIRMATION_FORMAT`]." }, "network_transaction_id": { "type": "string", "description": "Network transaction id (Visa ARN / `transactionIdentifier`) as a string.\nMaps to AP2 `network_confirmation_id`." }, "rail": { "type": "string", "description": "Rail identifier, e.g. `\"visa_direct\"`." }, "receipt_digest": { "type": "string", "description": "SHA-256 hex digest of the decision receipt this settlement closes. Links\nthe rail confirmation to exactly one decision." }, "settled_at_unix": { "type": "integer", "format": "int64", "description": "Unix seconds at which the rail reported settlement.", "minimum": 0 }, "status": { "$ref": "#/components/schemas/RailConfirmationStatus", "description": "Settlement status reported by the rail." } } }, "RailConfirmationBindingSignature": { "type": "object", "description": "Signature envelope over a [`RailConfirmationBindingStatement`].", "required": [ "algorithm", "signer_kid", "signature_b64" ], "properties": { "algorithm": { "type": "string" }, "signature_b64": { "type": "string" }, "signer_kid": { "type": "string" } } }, "RailConfirmationBindingStatement": { "type": "object", "description": "The signed binding statement over a [`RailConfirmation`].\n\nMirrors [`EvidencePackBindingStatement`] in spirit: a small canonical\nstatement that the receipt signer signs, committing to the rail\nconfirmation bytes and the decision it settles. Deliberately minimal so the\nsettlement binding cannot be confused with the decision-pack binding.", "required": [ "format", "receipt_digest", "rail_confirmation_sha256", "settled_at_unix", "signer_kid" ], "properties": { "format": { "type": "string", "description": "Always [`RAIL_CONFIRMATION_BINDING_FORMAT`]." }, "rail_confirmation_sha256": { "type": "string", "description": "`sha256:` digest of the canonical [`RailConfirmation`] JSON bytes." }, "receipt_digest": { "type": "string", "description": "Decision receipt digest this settlement closes (must equal the rail\nconfirmation's `receipt_digest`)." }, "settled_at_unix": { "type": "integer", "format": "int64", "description": "Unix seconds at which the rail reported settlement.", "minimum": 0 }, "signer_kid": { "type": "string", "description": "Hex kid of the receipt signer that produced this binding." } } }, "RailConfirmationStatus": { "type": "string", "description": "Settlement status reported by the payment rail.\n\nMirrors the AP2 `payment_receipt.json` `status` enum\n(`Success`/`Error`) plus an explicit `declined` state for a network-level\ndecline that is not an internal error.", "enum": [ "approved", "declined", "error" ] }, "RegulatedClientEntitlement": { "type": "object", "required": [ "entitlement_code", "target_state", "client_id", "account_id", "account_type", "product_code", "regulated_entity", "jurisdiction", "client_segment", "effective_at", "expires_at", "channel" ], "properties": { "account_id": { "type": "string" }, "account_type": { "type": "string" }, "approval_ref": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LocalApprovalRef" } ] }, "channel": { "type": "string" }, "classification_evidence_ref": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ActivationEvidenceRef" } ] }, "client_id": { "type": "string" }, "client_segment": { "type": "string" }, "derivatives_knowledge_state": { "type": [ "string", "null" ] }, "effective_at": { "type": "string" }, "entitlement_code": { "type": "string" }, "expires_at": { "type": "string" }, "jurisdiction": { "type": "string" }, "product_code": { "type": "string" }, "professional_investor_state": { "type": [ "string", "null" ] }, "regulated_entity": { "type": "string" }, "source_snapshots": { "type": "array", "items": { "$ref": "#/components/schemas/SourceSnapshotRef" } }, "suitability_evidence_ref": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ActivationEvidenceRef" } ] }, "target_state": { "type": "string" }, "va_knowledge_state": { "type": [ "string", "null" ] }, "warning_evidence_ref": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ActivationEvidenceRef" } ] } } }, "RegulatedMonitoringCoverage": { "type": "object", "required": [ "control_id", "regulated_entity", "jurisdiction", "period_start", "period_end", "source_population", "monitoring_population", "exclusions", "approvals", "mapping_version" ], "properties": { "approvals": { "type": "array", "items": { "$ref": "#/components/schemas/LocalApprovalRef" } }, "control_id": { "type": "string" }, "exclusions": { "type": "array", "items": { "$ref": "#/components/schemas/MonitoringControlExclusion" } }, "jurisdiction": { "type": "string" }, "mapping_version": { "$ref": "#/components/schemas/MonitoringMappingVersion" }, "monitoring_population": { "type": "array", "items": { "$ref": "#/components/schemas/MonitoringControlRecord" } }, "period_end": { "type": "string" }, "period_start": { "type": "string" }, "regulated_entity": { "type": "string" }, "source_population": { "type": "array", "items": { "$ref": "#/components/schemas/MonitoringPopulationRecord" } }, "source_snapshots": { "type": "array", "items": { "$ref": "#/components/schemas/SourceSnapshotRef" } } } }, "RegulatedPlatformChange": { "type": "object", "required": [ "change_id", "change_type", "target_state", "target_system", "target_object", "regulated_entity", "jurisdiction", "channel", "product_scope", "client_segment_scope", "risk_class", "change_ticket_ref", "rollback_ref", "control_owner", "effective_at", "change_window_start", "change_window_end", "emergency_override" ], "properties": { "approval_ref": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LocalApprovalRef" } ] }, "change_id": { "type": "string" }, "change_ticket_ref": { "type": "string" }, "change_type": { "type": "string" }, "change_window_end": { "type": "string" }, "change_window_start": { "type": "string" }, "channel": { "type": "string" }, "client_segment_scope": { "type": "string" }, "control_owner": { "type": "string" }, "effective_at": { "type": "string" }, "emergency_override": { "type": "boolean" }, "jurisdiction": { "type": "string" }, "product_scope": { "type": "string" }, "regulated_entity": { "type": "string" }, "release_ref": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ReleaseAuthorizationRef" } ] }, "risk_class": { "type": "string" }, "rollback_ref": { "type": "string" }, "source_snapshots": { "type": "array", "items": { "$ref": "#/components/schemas/SourceSnapshotRef" } }, "target_object": { "type": "string" }, "target_state": { "type": "string" }, "target_system": { "type": "string" }, "vendor_dependency_ref": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/VendorDependencyRef" } ] } } }, "RegulatedProductActivation": { "type": "object", "required": [ "product_code", "product_class", "regulated_entity", "jurisdiction", "client_segment", "effective_at", "rollback_ref", "channel" ], "properties": { "approval_ref": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LocalApprovalRef" } ] }, "channel": { "type": "string" }, "client_segment": { "type": "string" }, "effective_at": { "type": "string" }, "jurisdiction": { "type": "string" }, "product_class": { "type": "string" }, "product_code": { "type": "string" }, "professional_investor_state": { "type": [ "string", "null" ] }, "regulated_entity": { "type": "string" }, "release_ref": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ReleaseAuthorizationRef" } ] }, "rollback_ref": { "type": "string" }, "source_snapshots": { "type": "array", "items": { "$ref": "#/components/schemas/SourceSnapshotRef" } }, "suitability_evidence_ref": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ActivationEvidenceRef" } ] }, "warning_evidence_ref": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ActivationEvidenceRef" } ] } } }, "ReleaseAuthorizationRef": { "type": "object", "required": [ "ref_id", "authorized" ], "properties": { "authorized": { "type": "boolean" }, "authorized_at": { "type": [ "string", "null" ] }, "jurisdiction": { "type": [ "string", "null" ] }, "ref_id": { "type": "string" } } }, "SettleRequest": { "type": "object", "description": "Request body for `POST /gate/settle`.", "required": [ "request_key", "rail_confirmation" ], "properties": { "rail_confirmation": { "$ref": "#/components/schemas/RailConfirmation", "description": "The rail's settlement result to bind." }, "request_key": { "type": "string", "description": "The decision's durable request key (returned context for the original\n`/gate` call). The settlement is bound to this exact committed decision." } } }, "SettleResponse": { "type": "object", "description": "Response body for `POST /gate/settle`: the signed rail-confirmation binding\nplus the updated full evidence pack (decision pack + rail layer).", "required": [ "rail_confirmation_binding", "evidence_pack" ], "properties": { "evidence_pack": { "$ref": "#/components/schemas/ActionEvidencePack" }, "rail_confirmation_binding": { "$ref": "#/components/schemas/EvidencePackRailConfirmationBinding" } } }, "SourceAttestation": { "type": "object", "required": [ "format", "source_profile_id", "source_profile_hash", "source_id", "source_system", "source_kind", "upstream_url_hash", "request_hash", "response_hash", "record_set_hash", "attested_at", "source_attester_kid", "signature_b64" ], "properties": { "attested_at": { "type": "string" }, "format": { "type": "string" }, "record_set_hash": { "type": "string" }, "request_hash": { "type": "string" }, "response_hash": { "type": "string" }, "signature_b64": { "type": "string" }, "source_attester_kid": { "type": "string" }, "source_id": { "type": "string" }, "source_kind": { "type": "string" }, "source_profile_hash": { "type": "string" }, "source_profile_id": { "type": "string" }, "source_system": { "type": "string" }, "upstream_url_hash": { "type": "string" } } }, "SourceRetrievalProof": { "type": "object", "required": [ "format", "source_profile_id", "source_profile_hash", "source_snapshot_hash", "source_id", "source_system", "source_kind", "capture_method", "captured_at", "upstream_url_hash", "request_hash", "response_hash", "record_set_json_pointer", "capturer_kid", "signature_b64" ], "properties": { "capture_method": { "type": "string" }, "captured_at": { "type": "string" }, "capturer_kid": { "type": "string" }, "format": { "type": "string" }, "record_set_json_pointer": { "type": "string" }, "request_hash": { "type": "string" }, "response_hash": { "type": "string" }, "signature_b64": { "type": "string" }, "source_id": { "type": "string" }, "source_kind": { "type": "string" }, "source_profile_hash": { "type": "string" }, "source_profile_id": { "type": "string" }, "source_snapshot_hash": { "type": "string" }, "source_system": { "type": "string" }, "upstream_url_hash": { "type": "string" } } }, "SourceSnapshotMaterial": { "type": "object", "required": [ "request_bytes_b64", "response_bytes_b64", "schema_json", "record_set_json" ], "properties": { "record_set_json": {}, "request_bytes_b64": { "type": "string" }, "response_bytes_b64": { "type": "string" }, "schema_json": {} } }, "SourceSnapshotRef": { "type": "object", "required": [ "ref_id", "source_id", "source_system", "source_kind", "capture_method", "evidence_strength", "captured_at", "request_hash", "response_hash", "schema_hash", "record_set_hash", "snapshot_hash" ], "properties": { "capture_method": { "type": "string" }, "captured_at": { "type": "string" }, "evidence_strength": { "type": "string" }, "material": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SourceSnapshotMaterial" } ] }, "record_set_hash": { "type": "string" }, "ref_id": { "type": "string" }, "request_hash": { "type": "string" }, "response_hash": { "type": "string" }, "retrieval_proof": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SourceRetrievalProof" } ] }, "schema_hash": { "type": "string" }, "snapshot_hash": { "type": "string" }, "source_attestation": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SourceAttestation" } ] }, "source_id": { "type": "string" }, "source_kind": { "type": "string" }, "source_system": { "type": "string" }, "verification_material": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SourceVerificationMaterial" } ] } } }, "SourceVerificationMaterial": { "type": "object", "required": [ "source_profile_hash", "source_profile_json", "profile_signer_kid", "profile_signer_pubkey_b64", "capturer_kid", "capturer_pubkey_b64", "source_attester_kid", "source_attester_pubkey_b64" ], "properties": { "capturer_kid": { "type": "string" }, "capturer_pubkey_b64": { "type": "string" }, "profile_signer_kid": { "type": "string" }, "profile_signer_pubkey_b64": { "type": "string" }, "source_attester_kid": { "type": "string" }, "source_attester_pubkey_b64": { "type": "string" }, "source_profile_hash": { "type": "string" }, "source_profile_json": {} } }, "Subject": { "type": "object", "required": [ "type", "id" ], "properties": { "hash": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "type": { "type": "string" }, "version": { "type": [ "string", "null" ] } } }, "VendorDependencyRef": { "type": "object", "required": [ "ref_id", "approved" ], "properties": { "approved": { "type": "boolean" }, "approved_at": { "type": [ "string", "null" ] }, "jurisdiction": { "type": [ "string", "null" ] }, "ref_id": { "type": "string" } } } }, "securitySchemes": { "bearer_api_key": { "type": "http", "scheme": "bearer", "description": "FARIGATE API key: `fg_live_...` (tenant-scoped) or `fg_actor_...` (actor-bound; required for verified actor binding in strict mode)" } } }, "tags": [ { "name": "gate", "description": "Authenticated gate decision endpoints (bearer API key)" }, { "name": "meta", "description": "Unauthenticated API metadata" } ] }