SynOI Inc

US joshua@foundationx.com https://github.com/synoi/synoi-gap/issues

Internet The Governed Action Protocol (GAP) is an open wire protocol for a Universal Action Coordination Fabric. GAP defines a four-phase lifecycle (Declare, Grant, Invoke, Receipt) that governs every action an AI agent, smart device, industrial controller, or automated pipeline may take. Every gate decision produces a content-addressed, immutable receipt; receipts are signed at L2+ (Ed25519) and L4 (hybrid ML-DSA-65). The protocol is designed to be language- and platform-neutral, applicable across enterprise AI agent pipelines, consumer smart home devices, medical equipment, industrial control systems, and game engines. This document specifies the wire format, object model, grant evaluation rules, HTTP API surface, workflow semantics, revocation mechanisms, and conformance tiers for GAP version 1.0.

Introduction As AI agents and automated systems proliferate, the absence of a common authorization and auditability layer creates compounding risk. Each environment (AI agent frameworks, smart home hubs, industrial SCADA systems, game engines, medical devices) builds its own integration layer with its own permission model, its own audit log (if any), and its own revocation mechanism. None share an audit trail. None speak to each other. None produce verifiable, portable evidence of what was authorized. GAP is the fabric underneath all of them. An actor declares what it can do. An operator grants what it may do, under what conditions. Every invocation is evaluated against an active grant. Every gate decision (allow, deny, defer, timeout) produces a content-addressed, immutable receipt (signed at L2+). The same protocol that governs an AI agent's tool calls also governs an industrial valve controller, a door lock, and a medication infusion pump.

Motivation Several properties motivate a unified open protocol:

Portability:

Authorization evidence must be independently verifiable by any party with access to the gateway's public key, without contacting the gateway.

Non-repudiation:

A signed, content-addressed receipt cannot be silently modified after issuance.

Composability:

Delegation chains, multi-party approvals, and workflow orchestration must compose from the same primitive objects.

Physical-safety applicability:

The protocol must carry safety classification metadata and define fail-closed semantics for capabilities that affect physical systems.

Scope This document defines:

• The CDRO (Content-addressed, Deterministic, Replayable Object) wire format
• OID computation (canonical JSON + SHA-256)
• The four lifecycle phases: Declare, Grant, Invoke, Receipt
• Grant evaluation algorithm including scope narrowing and delegation
• Workflow orchestration and Human-in-the-Loop (HITL) signaling
• Revocation (immediate, scheduled, provisional block, and L3 quorum)
• The HTTP API surface for GAP-conformant gateways
• Conformance tiers L1 through L4

Security considerations for implementing a GAP gateway are specified in {{security-considerations}}. The protocol specification is dedicated to the public domain under CC0 1.0 Universal. Implementations of this specification may be licensed independently.

Conventions and Definitions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here. The following terms are used throughout this document:

Actor:

An entity (AI agent, service, device, or human user) that can declare capabilities and invoke them subject to grants.

Operator:

The human or organizational entity that issues grants. An operator holds the root of trust for a tenant.

Tenant:

An isolated authorization domain. CDROs never implicitly cross tenant boundaries.

CDRO:

Content-addressed, Deterministic, Replayable Object. The base unit of the GAP object model.

OID:

Object Identifier. A content-addressed string of the form sha256:<hex> computed over the canonical JSON serialization of a CDRO's body fields.

Gateway:

A GAP-conformant server that evaluates invocations against active grants and produces signed decision receipts.

Physical-safety capability:

A capability whose invocation can cause irreversible physical consequences. Identified by physical_safety: true in the capability declaration.

Object Model

CDRO Envelope Every GAP record is a CDRO. A CDRO is a JSON object with the following fields:

Field	Required	Description
oid	yes	sha256:<64 hex chars>, content-addressed identifier
type	yes	One of the gap:* type strings defined in this document
gap_version	yes	Always "1.0" for this specification
tenant_id	yes	The owning tenant identifier
created_at_ms	yes	Unix epoch milliseconds
created_by	yes	OID of the actor creating this record
body	yes	Type-specific payload
signature	no	Ed25519 signature over the canonical envelope, base64url
signature_key_id	no	Identifies the signing key
signature_algorithm	no	Signature algorithm: Ed25519, ML-DSA-65, or Ed25519+ML-DSA-65. Verifiers MUST NOT guess the algorithm from key length.
supersedes	no	OID of the CDRO this record replaces

The defined type values are:

Type string	Body type
gap:capability_declaration	CapabilityDeclarationBody
gap:capability_grant	CapabilityGrantBody
gap:capability_invocation	CapabilityInvocationBody
gap:decision_receipt	GapDecisionReceiptBody
gap:revocation_event	RevocationEventBody
gap:workflow_definition	WorkflowDefinitionBody
gap:workflow_instance	WorkflowInstanceBody
gap:stage_transition	StageTransitionBody
gap:channel_event	ChannelEventBody
gap:break_glass_token	BreakGlassTokenBody
gap:local_override_credential	LocalOverrideCredentialBody
gap:lca_root	LcaRootBody ({ root_public_key_base64: string, algorithm: string, tenant_id: string, valid_from_ms: number, expires_at_ms: number })
gap:erasure_event	ErasureEventBody
gap:orchestration_chain	OrchestrationChainBody [DESIGN]
gap:consent_record	ConsentRecordBody [DESIGN]
gap:pip_response	PipResponseBody [DESIGN]

OID Computation An OID is computed as follows:

1. Take the CDRO envelope object.
2. Remove the fields oid, gap_version, signature, signature_key_id, and supersedes.
3. Canonicalize the resulting object per {{canonical-json}}.
4. Compute SHA-256 over the UTF-8 encoding of the canonical string.
5. Hex-encode the digest (lowercase).
6. Prepend sha256:.

The result is the OID for this CDRO. The same input MUST always produce the same OID. Implementations MUST compute and store the OID before signing so that the signature covers the canonical content.

Canonical JSON The canonical JSON form of a value is defined recursively:

• string: standard JSON string encoding
• number: standard JSON number encoding (no trailing zeros beyond the decimal point)
• boolean: true or false
• null: excluded; null values MUST be omitted from canonical form
• array: [ + elements joined by , (order preserved, null elements omitted) + ]
• object: { + key-value pairs joined by ,, keys sorted lexicographically (Unicode code-point order), pairs with null values omitted, keys encoded as JSON strings + }

Note: GAP canonical JSON is NOT identical to JSON Canonicalization Scheme (JCS) . The primary difference is that GAP omits null values while JCS preserves them. Implementors MUST NOT use a JCS library for OID computation without first stripping null values.

Phase 1: Declare

Purpose Before any capability can be granted or invoked, the actor offering it MUST publish a CapabilityDeclaration. The declaration is an immutable record of what the actor can do, the safety classification of each capability, and optional scope constraints.

CapabilityDeclarationBody

Field	Required	Description
actor_type	yes	One of: service, device, agent, human_user, mcp_server, gateway_subsystem, skill
actor_id	yes	Stable identifier for the declaring actor
actor_name	yes	Human-readable name
actor_version	yes	Semantic version string
capabilities	yes	Array of CapabilitySpec

Each CapabilitySpec:

Field	Required	Description
capability	yes	Dotted-taxonomy capability name (e.g. home.lock.engage)
safety_class	yes	A (reversible), B (state-changing), or C (irreversible/critical)
physical_safety	no	Boolean. true if invocation can cause physical harm
description	no	Human-readable description
scope_narrowing_schema	no	JSON Schema describing allowed scope_narrowing keys
privacy_classification	no	none, pii, phi, financial, or privileged (legally privileged content: attorney-client, work product, common-interest; the gateway routes receipts to a privilege-isolated store and suppresses them from standard list endpoints)
require_signed_receipt	no	Boolean. When true, the gateway MUST attach a cryptographic signature to every decision receipt for this capability. When false, the gateway SHOULD omit signing even on a server that signs by default (useful for high-frequency low-risk capabilities where signing cost outweighs benefit). When absent, the gateway applies its configured default signing policy. The operator MAY override this per-grant via GrantedCapabilityScope.require_signed_receipt.
pii_args	no	Array of arg key strings whose values contain PII, PHI, or NPI requiring tokenization before storage. The gateway MUST replace each listed key's value with a keyed HMAC token (one-way, using a per-tenant key) before constructing the invocation CDRO and receipt body. The original value is used for capability execution by the adapter but MUST NOT be stored in any CDRO.
privilege_protected	no	Boolean. When true, the gateway: routes receipts to a privilege-isolated store; suppresses the receipt body from GET /receipts list endpoint; requires an explicit attorney-assertion header on fetch by OID; excludes the receipt from automated compliance exports. Controls access routing, not deletion. Add privilege_asserted to the compliance_tags vocabulary when this field is true.

When privilege_protected: true is set on a CapabilitySpec, the gateway: routes receipts to a privilege-isolated store; suppresses the receipt body from GET /receipts list endpoint; requires an explicit attorney-assertion header on fetch by OID; excludes the receipt from automated compliance exports. privilege_protected controls access routing, not deletion. For capabilities with privacy_classification: phi or matching medical.* or financial.*, any arg key whose name is listed in pii_args MUST be tokenized before CDRO construction. The canonical JSON used for OID computation is taken from the unencrypted args before tokenization so OID integrity is maintained. A GET /v1/gap/receipts/:oid?include_pii=true path with elevated authorization serves authorized reviewers.

Supersession An actor MAY publish a new declaration superseding an existing one by setting supersedes to the OID of the prior declaration. A gateway MUST treat the prior declaration as inactive once the superseding declaration is accepted. A gateway MUST NOT accept a new declaration with the same actor_id unless it includes a valid supersedes pointer to the currently active declaration for that actor_id within the tenant.

Ephemeral Actors Some actors have a lifecycle tied to a session, job, or deployment instance rather than a persistent identity. Add actor_lifecycle to CapabilityDeclarationBody:

Field	Required	Description
actor_lifecycle	no	persistent (default) or ephemeral. Ephemeral declarations are exempt from the supersession uniqueness rule; each declaration gets a fresh OID and is valid for its session only.
actor_instance_id	no	UUID or job ID distinguishing this instance from others with the same actor_id. When present, two declarations with the same actor_id but different actor_instance_id MUST NOT be treated as superseding each other.
session_expires_at_ms	no	For ephemeral actors: when this session ends. The gateway MUST auto-revoke all grants scoped to this actorinstanceid at this time.

Grants issued to an actor_id without actor_instance_id apply to all instances of that actor_id. Grants scoped to a specific actor_instance_id expire with that instance.

MCP Tool-Call Governance [DESIGN] Actors of type mcp_server expose tools via the Model Context Protocol (MCP) tools/list response. A GAP gateway auto-generates CapabilityDeclarations from those responses. Capability names for MCP tools follow the pattern: mcp.<server_id>.<tool_name>. MUST: a gateway MUST reject any auto-generated capability name that starts with gap: or matches any normative capability name defined in this specification. This prevents namespace pollution from attacker-controlled MCP servers that return malicious tools/list responses. An invocation for an MCP-originated capability MAY carry mcp_tool_call on the CapabilityInvocationBody:

Field	Required	Description
server_id	yes	Stable identifier for the MCP server
tool_name	yes	Name of the tool as returned by tools/list
tool_schema_hash	no	SHA-256 hash of the tool's JSON schema, for drift detection

Identity Binding [DESIGN] A CapabilityDeclarationBody MAY carry an identity_binding object that ties the actor_oid to a real-world credential using a hardware-backed signature. The canonical binding payload is domain-separated: "gap-identity-binding-v1" + ":" + actor_oid + ":" + tenant_id + ":" + credential_identifier The binding_signature field carries the credential holder's signature over the canonical binding payload. IdentityBinding fields:

Field	Required	Description
credential_kind	yes	One of the normative values below
credential_identifier	yes	Stable identifier within the credential_kind namespace
binding_signature	yes	Signature over canonical binding payload, base64url
binding_alg	yes	Signature algorithm (e.g. Ed25519, ES256, RS256)
bound_at_ms	yes	Unix epoch ms when binding was established
issuer	no	Issuer identifier (CA DN, OIDC issuer URL, etc.)
expires_at_ms	no	Expiry of the binding; absent means no expiry

Normative credential_kind values:

Value	Credential type
piv_cac	US Federal PIV or Common Access Card
x509	X.509 certificate
fido2	FIDO2 / WebAuthn credential
tpm_attestation	TPM 2.0 attestation key
oidc_sub	OIDC subject claim from a trusted IdP
spiffe_svid	SPIFFE SVID (X.509 or JWT)
wallet_address	Cryptographic wallet address
professional_license	Licensed professional credential (e.g. medical, legal)

Compartment-Based Access Scoping [DESIGN] A compartment field MAY be added to CapabilityDeclarationBody, CapabilityGrantBody, and CapabilityInvocationBody. Accepted values: UNCLASS, CUI, or any reverse-domain operator-defined label (e.g. com.acme.project-alpha). MUST: at invocation time, if the grant carries a compartment, the invocation compartment MUST exactly match. A compartment mismatch MUST be treated as a denial. MUST: a gateway MUST return HTTP 404 (not HTTP 403) when the invoking actor's compartment level is insufficient to know that a resource exists. OID existence MUST NOT leak across compartment boundaries. Cross-compartment access requires a bridge grant issued through a TPI-gated HITL workflow. Bridge grants MUST be issued by an operator whose declaration carries both compartment labels and MUST produce a compliance_tag of cross_compartment_bridge on the receipt.

Phase 2: Grant

Purpose A CapabilityGrant authorizes a specific actor (the grantee) to invoke one or more capabilities declared by a specific actor (the declarer), subject to optional scope constraints, time limits, and preconditions.

CapabilityGrantBody

Field	Required	Description
grantee	yes	ActorRef identifying the authorized actor
capability_scopes	yes	Array of GrantedCapabilityScope
granted_at_ms	yes	Unix epoch milliseconds
granted_by	yes	OID of the operator issuing the grant
expires_at_ms	no	Expiry timestamp in milliseconds
parent_grant_oid	no	OID of the parent grant (delegation chains)
limits	no	InvocationLimits
additional_preconditions	no	Array of Precondition
timestamp_window_seconds	no	For safetyclass C without physicalsafety: override for the default timestamp validation window in seconds. Gateway applies its default if absent.
offline_grace_seconds	no	Additional seconds beyond grant expiry during which offline provisional receipts are accepted at reconciliation. Defaults to 0.
max_grant_offline_ttl_ms	no	Maximum duration any device may use this grant without syncing to the gateway. After this window, further invocations MUST be denied until the device reconnects.
max_revocation_bundle_age_ms	no	Maximum acceptable age of a revocation bundle for this grant. Devices MUST deny physical_safety/class C invocations if the bundle is older than this value.

Each GrantedCapabilityScope:

Field	Required	Description
capability	yes	Capability name or wildcard pattern
capability_declaration_oid	yes*	OID of the CapabilityDeclaration. REQUIRED when safety_class is C or physical_safety is true
scope_narrowing	no	Object constraining invocation arguments (see Scope Narrowing Evaluation)
additional_preconditions	no	Array of Precondition evaluated at invocation time for this scope (in addition to grant-level preconditions)
require_signed_receipt	no	Operator override for receipt signing. When set, takes precedence over the capability declaration's require_signed_receipt. Allows an operator to require signing for a capability the actor declared unsigned, or suppress signing for a high-frequency capability the actor flagged as requiring it.

InvocationLimits:

Field	Description
max_invocations	Maximum total invocation count
max_per_window	Maximum invocations within a rolling time window
window_seconds	Window duration in seconds
aggregate_limits	Array of AggregateLimitEntry

AggregateLimitEntry:

Field	Description
key	The invocation argument key to sum
max	Maximum rolling sum (non-negative)
window_seconds	Rolling window duration in seconds

Cross-Grant Aggregate Limit Groups An aggregate_limit_group field on InvocationLimits references a named shared limit pool at the tenant level. Multiple grants referencing the same pool share a single rolling counter enforced atomically by the gateway.

Field	Required	Description
aggregate_limit_group	no	Named pool identifier. All grants with the same aggregate_limit_group share rolling aggregate counters defined in the tenant's pool configuration.

The gateway MUST maintain atomic counters per pool and MUST deny any invocation from any grant in the pool that would exceed the pool ceiling. Pool configuration is out of scope for this specification and is implementation-defined.

Precondition Kind Registry A normative precondition_kind registry defines semantics for standard kinds. Custom kinds use reverse-domain prefixes (e.g. com.example.custom_check).

Kind	Required args	Description
time_window	days_of_week, start_hour_utc, end_hour_utc	Invocation only permitted in the specified UTC time window
rate_limit	max_count, window_seconds	Maximum invocations per rolling window (cross-invocation, tracked by gateway)
sanctions_screening	list_version, screening_provider, subject_fields	Screens named arg keys against a sanctions list. Gateway MUST record screening result OID in the receipt. Gateway MUST NOT proceed to execution if result is denied.
external_pip	endpoint_url, cache_ttl_seconds, subject_fields, pip_response_oid (optional)	POSTs invocation args to an external Policy Information Point and evaluates the boolean allowed response. Result is cached per (tenant, capability, args-hash) for cache_ttl_seconds. When pip_response_oid is present the response is ENFORCING (see Signed PIP Response below).
inventory_check	resource_key, min_available	Verifies the named resource has sufficient availability before execution
token_budget	model_scope, max_input_tokens, max_output_tokens, max_cost_usd, window_seconds	[DESIGN] Rolling token-budget cap evaluated post_invoke. See Token Budget Governance below.
consent_current	(none)	[DESIGN] Evaluates at invocation time whether the actor's most recent gap:consent_record for the capability's context has consented: true. The gateway MUST NOT use the idempotency cache for this evaluation. See Consent Version Chain below.

Token Budget Governance [DESIGN] The token_budget precondition kind governs token consumption across invocations that call an LLM. Evaluation timing: post_invoke (settled after execution). The gateway writes the actual consumption to token_consumption on the decision receipt. TokenBudgetArgs:

Field	Required	Description
model_scope	yes	Shell-glob pattern matching model IDs (e.g. anthropic/claude-*)
max_input_tokens	no	Maximum input tokens within window_seconds
max_output_tokens	no	Maximum output tokens within window_seconds
max_cost_usd	no	Maximum cost in USD within window_seconds. [MODELED]; not authoritative until a conformance vector exists.
window_seconds	yes	Rolling window length in seconds

The gateway settles actual consumption onto the receipt via the token_consumption field (see Phase 4: Receipt). Uses the aggregate_limit_group counter mechanism for cross-grant budgeting.

Signed PIP Response [DESIGN] When an external_pip precondition carries pip_response_oid, the referenced CDRO is a gap:pip_response that the external PIP emitted and the gateway re-signed. Distinction:

• Unsigned external reads (no pip_response_oid): ADVISORY. The response influences the gate decision but MUST NOT be the sole basis for an allow outcome.
• Signed gap:pip_response (with pip_response_oid): ENFORCING. The gateway MAY use it as the sole basis for allow or deny.

MUST: if pip_response_oid is present, the gateway MUST verify the CDRO signature before treating the response as enforcing. PipResponseBody:

Field	Required	Description
pip_endpoint	yes	URL of the external PIP endpoint
request_args_hash	yes	SHA-256 hash of the canonical request args sent to the PIP
response_body_hash	yes	SHA-256 hash of the raw response body from the PIP
response_summary	no	Human-readable summary (not authoritative)
evaluated_at_ms	yes	Unix epoch ms when the PIP was queried
cache_ttl_ms	yes	How long (ms) this response may be cached by the gateway
pip_signature	no	Optional signature from the PIP itself, base64url
pip_signature_alg	no	Algorithm used for pip_signature

For any invocation of financial.wire.initiate or financial.payment.initiate, a gateway MUST enforce sanctions_screening precondition evaluation even when absent from the grant's additional_preconditions. The gateway MUST reject the invocation and produce a denial receipt if the screening result is denied.

Scope Narrowing Evaluation When a grant contains scope_narrowing, a gateway MUST enforce the following rules at invocation time:

1. For each key K in scope_narrowing:
   • The invocation arguments MUST contain key K. If absent, the invocation MUST be denied.
   • If the scope value is a string: args[K] MUST equal the scope value (exact match, case-sensitive). Key names are exact and singular/plural variants are distinct keys.
   • If the scope value is a boolean: args[K] MUST equal the scope value.
   • If the scope value is a number and the key name has the prefix min_: args[K] MUST be greater than or equal to the scope value (lower bound).
   • If the scope value is a number and the key name does not have the prefix min_: args[K] MUST be less than or equal to the scope value (upper bound). For physical_safety: true capabilities, negative values for args[K] MUST be rejected even when they would satisfy the upper-bound check.
   • If the scope value is a string array: args[K] MUST be a member of the array.

Dot-path expansion: A scope_narrowing key containing a dot (e.g. position.x) evaluates against the nested arg path args.position.x. This enables constraint of nested arg structures without requiring flat arg schemas. Envelope constraint (optional): when a scope_narrowing value is an object with $constraint_oid, the gateway evaluates the named constraint CDRO (a pre-registered function) against the full args object, returning boolean. This enables correlated multi-axis constraints (e.g. motor speed AND torque within a 2D operating envelope).

Granted-By Verification A gateway MUST verify at grant acceptance time that body.granted_by OID matches the actor OID associated with the authenticated Bearer token or SSC credential. A grant where these do not match MUST be rejected with HTTP 403.

Delegation A grant MAY delegate authority to a sub-grantee by setting parent_grant_oid. A gateway MUST enforce all of the following when evaluating a delegated grant:

1. The granted_by field of the child grant MUST equal the grantee.actor_oid of the parent grant.
2. For every capability scope in the child grant, a matching scope MUST exist in the parent grant (using capability pattern matching per {{patterns}}).
3. For every key in the child grant's scope_narrowing, the child value MUST satisfy the subset rule against the parent value for the same key:
   • String: child value MUST equal parent value.
   • String array: every element of the child array MUST appear in the parent array.
   • Number (upper bound, no min_ prefix): child value MUST be less than or equal to the parent value.
   • Number (lower bound, min_ prefix): child value MUST be greater than or equal to the parent value.
   • Key present in parent but absent in child: MUST be denied (a child cannot drop a parent constraint).
4. The child grant MUST NOT increase max_delegation_depth beyond the parent's value. For physical_safety: true grants, max_delegation_depth MUST default to 0 (no further delegation) when absent.
5. For physical_safety: true grants, the child MUST inherit all additional_preconditions from all ancestors in the chain.
6. At invocation time, the gateway MUST re-validate that all grants in the delegation chain are non-expired and non-revoked.

Capability Pattern Matching A capability pattern matches a capability name as follows:

• * matches any capability name (match-all).
• prefix.* matches direct children only (single path segment). game.* matches game.session but NOT game.admin.delete.users.
• prefix.** matches all descendants recursively. game.** matches all nested paths under game, including game.session, game.admin.delete.users, etc. The prefix itself also matches (game.** matches game).
• An exact string matches only that exact name (no wildcard).

Two wildcard levels are defined: prefix.* matches direct children only (single path segment); prefix.** matches all descendants recursively. Implementations MUST support both levels.

Phase 3: Invoke

Purpose A CapabilityInvocation is the actor's request to exercise a granted capability. The gateway evaluates the invocation against active grants and produces a GapDecisionReceipt.

CapabilityInvocationBody

Field	Required	Description
caller	yes	CallerRef (actortype, actoroid, grant_oid)
capability	yes	The capability being invoked
args	yes	Invocation arguments (flat JSON object)
invoked_at_ms	yes	Client-supplied or server-stamped timestamp
idempotency_key	no	Client-provided deduplication key
client_event_ms	no	Unix epoch ms when the action originally occurred in the caller's reference frame (game-world time, clinical queue time, SCADA scan cycle). Populated by the client; not used for replay prevention. Stored in receipt for audit.
queued_at_ms	no	Unix epoch ms when the invocation was enqueued for submission (e.g. at reconnect after offline period). Optional; aids debugging of delivery latency.

Timestamp Validation Timestamp validation is per safety_class:

safety_class	physical_safety	Max client_timestamp age	Gateway behavior
A	any	5 minutes	Reject if invokedatms (client-supplied) is more than 5 minutes in the past
B	any	120 seconds	Reject if more than 120 seconds in the past
C	false	operator-configurable	Grant field timestamp_window_seconds sets the window; gateway default if absent
C	true	server-stamp only	Gateway MUST ignore client-supplied invokedatms; stamps receipt time authoritatively

When rejecting due to timestamp, the denial receipt MUST include: - detail: 'timestamp_rejected' - server_time_ms field containing the gateway's current Unix epoch ms so clients can resync clocks For physical_safety: true capabilities:

• The gateway MUST server-stamp invoked_at_ms and ignore any client-supplied value. The client-supplied value, if present, MUST be stored in client_claimed_at_ms on the receipt for audit purposes.

Idempotency A gateway SHOULD implement idempotency keyed by (tenant_id, capability, idempotency_key). On a cache hit:

• The gateway MUST re-validate that the grant is still non-revoked and non-expired. If the grant has been revoked since the original execution, the gateway MUST return HTTP 410 with a new denial receipt.
• The gateway MUST verify that the arguments in the new request exactly match the stored arguments. If they differ, the gateway MUST return HTTP 409.
• The receipt MUST have is_idempotency_replay: true.
• For physical_safety: true capabilities, the maximum idempotency window MUST NOT exceed 60 seconds.

Grant Selection When multiple active grants match an invocation, a gateway MUST use the following deterministic selection order:

1. Prefer the grant with more scope_narrowing keys (more specific).
2. Among grants with equal key count, prefer lower numeric upper-bound values.
3. Among grants with equal numeric bounds, prefer smaller string-array cardinality.

Phase 4: Receipt

GapDecisionReceiptBody A GapDecisionReceipt is produced for every gate decision. It is immutable.

GDPR Erasure GDPR Article 17 (right to erasure) requires a mechanism to handle erasure requests for receipts containing personal data. The GAP erasure mechanism preserves OID integrity while satisfying erasure obligations. A gap:erasure_event CDRO replaces the body of a targeted receipt with a fixed erasure sentinel while preserving envelope metadata. ErasureEventBody:

Field	Required	Description
target_oid	yes	OID of the CDRO being erased
erasure_reason	yes	gdpr_article_17, ccpa, or operator_policy
erased_at_ms	yes	Unix epoch ms of erasure
erased_by	yes	Actor OID issuing the erasure
fields_erased	yes	Array of field paths erased from the target CDRO body

The erasure event's OID anchors to the original CDRO OID and is itself a signed CDRO, making it non-repudiable. Verifiers MUST treat an erasure event as authoritative over the prior OID body. Add gdpr_erasure to the compliance_tags vocabulary. For privacy_classification: pii capabilities, gateways operating under GDPR SHOULD use pii_args tokenization (see Phase 1: Declare) to minimize PII stored in receipts before erasure is required.

Field	Required	Description
subject_kind	yes	capability_invocation, workflow_stage, provisional_block, or grant_evaluation
subject_oid	yes	OID of the evaluated object
status	yes	DecisionStatus (see below)
capability_grant_oids	yes	Array of grant OIDs that were evaluated
decided_at_ms	yes	Gateway-stamped decision timestamp
detail	no	Error code string (from the error code registry)
compliance_tags	no	Array of compliance tag strings (gateway-populated, not in OID hash)
is_idempotency_replay	no	Boolean. true if this receipt is a cached replay
client_claimed_at_ms	no	Client-supplied invoked_at_ms for physical_safety invocations
max_offline_ttl_ms	no	Maximum duration a verifier MAY cache this receipt offline
signer_identity	no	For 21 CFR Part 11 contexts: display name, role, and credential identifier of the authorizing human. The granted_by actor OID SHOULD resolve to this identity.
sequence_number	no	Monotonically increasing integer within the tenant, incremented per receipt, gapless. Gaps in the sequence indicate dropped receipts. Provides determinable ordering within a millisecond for high-frequency deployments (MiFID II RTS 25).
decided_at_ns	no	Optional nanoseconds since Unix epoch for sub-millisecond precision. RECOMMENDED for financial.* capabilities.

A gateway MUST guarantee strict monotonicity of sequence_number within a tenant. For financial.* capabilities, the gateway SHOULD populate decided_at_ns. DecisionStatus values: ok, denied, failed, deferred, timed_out, pending, rate_limited.

Token Consumption on Receipt [DESIGN] When a token_budget precondition is active, the gateway settles actual consumption onto the receipt after execution via the token_consumption field. TokenConsumption:

Field	Required	Description
input_tokens	yes	Input (prompt) tokens consumed; non-negative integer
output_tokens	yes	Output (completion) tokens consumed; non-negative integer
model	yes	Model identifier
cost_usd	no	Estimated cost in USD. [MODELED]
settled_at_ms	yes	Unix epoch ms when consumption was settled

Compliance Tags A gateway MUST populate compliance_tags on every receipt. The minimum tag set:

Tag	When set
safety_class:A, safety_class:B, safety_class:C	Capability safety class
physical_safety	physical_safety: true capability
hitl_approved	Workflow reached terminal_outcome: approved
hitl_denied	Workflow reached terminal_outcome: denied
idempotency_replay	is_idempotency_replay: true
rate_limited	status: rate_limited
phi	Declaration has privacy_classification: phi

compliance_tags are gateway-populated. They MUST NOT be included in the OID hash computation. A verifier MUST NOT trust compliance_tags as normative; they are informational audit annotations.

Agent Delegation Chain [DESIGN] A gap:orchestration_chain CDRO captures the ordered sequence of delegation hops that authorized a terminal capability invocation. It consolidates multi-agent pipelines into a single auditable object.

Structure An OrchestrationChainBody:

Field	Required	Description
root_actor_oid	yes	Actor OID that initiated the chain
steps	yes	Ordered array of DelegationStep, maximum 10
capability_name	yes	The capability name being delegated through the chain
final_invocation_oid	yes	OID of the terminal CapabilityInvocation CDRO

Each DelegationStep:

Field	Required	Description
step_index	yes	Zero-based position of this hop in the chain
delegator_actor_oid	yes	Actor OID performing the delegation
delegatee_actor_oid	yes	Actor OID receiving authority
grant_oid	yes	OID of the grant authorizing this hop
prior_receipt_oid	no	OID of the receipt from the prior hop (absent for step_index 0)
delegated_at_ms	yes	Unix epoch ms of delegation
step_signature	yes	Signature over canonical(priorreceiptoid + invocation_body), base64url
step_signature_alg	yes	Algorithm used for step_signature

Constraints MUST: the steps array MUST NOT exceed 10 entries. A gateway MUST return HTTP 400 with error code delegation_depth_exceeded when this limit is breached. MUST: signing keys for each hop MUST be declared at grant issuance. The gateway MUST verify each step's signature before allowing the terminal invocation. MUST: at invocation time, the gateway MUST re-validate that all grants referenced in the chain are non-expired and non-revoked. Partial chain validation is insufficient. A CapabilityInvocationBody MAY carry delegation_chain (array of DelegationStep) as a shorthand when the full gap:orchestration_chain CDRO is not yet materialized. The same maximum-10-hop and per-step signature verification rules apply.

Consent Version Chain [DESIGN] GAP consent records form an append-only chain. Each record references prior_consent_oid, making consent history non-repudiable and auditable.

gap:consent_record ConsentRecordBody:

Field	Required	Description
actor_oid	yes	Actor OID whose consent this record captures
tenant_id	yes	Tenant scope
context	yes	Free-form context string (e.g. hiring.background_check, clinical.data_sharing)
consented	yes	Boolean: true = consent granted; false = consent withdrawn
prior_consent_oid	no	OID of the prior record for this actor + context
consented_at_ms	yes	Unix epoch ms of consent event
expires_at_ms	no	Optional expiry; the gateway MUST treat expired records as consented: false
consent_text_hash	no	SHA-256 hash of the disclosure text shown to the actor

Precondition: consent_current The consent_current precondition evaluates at invocation time whether the actor's most recent consent record for the capability's context has consented: true. MUST: the gateway MUST NOT use the idempotency cache for consent_current evaluation. Every invocation MUST re-read the most recent record. MUST: withdrawal of consent (a new record with consented: false) MUST take effect within 5 seconds across all gateway replicas. This single primitive subsumes all sector-specific consent patterns: hiring consent, learner consent, and clinical consent all use gap:consent_record with context-specific values in the context field.

Relationship to GDPR The consent chain is a complement to the erasure mechanism (see GDPR Erasure). Erasure removes PII from receipts; the consent chain records the authority under which invocations were permitted. Both chains SHOULD be linked in receipt compliance_tags when applicable.

Offline Execution Profile An Offline Execution Profile (OEP) enables a device or agent to evaluate grants and issue provisional receipts without network connectivity to the gateway.

OEP Bundle A gap:offline_bundle is a gateway-signed CDRO containing everything needed for offline grant evaluation:

Field	Required	Description
grant	yes	Full CapabilityGrant CDRO (inline, not by reference)
declaration	yes	Full CapabilityDeclaration CDRO for the granted actor
keyring	yes	KeyringExport CDRO (see Offline Key Distribution)
revocation_snapshot	yes	RevocationSnapshot CDRO (see Offline Revocation)
offline_policy	yes	OfflinePolicy block

OfflinePolicy:

Field	Required	Description
max_offline_duration_ms	yes	Maximum duration the bundle is valid for offline use
max_offline_invocations	yes	Maximum invocations permitted during the offline period
offline_capability_filter	no	Array of capability patterns permitted offline; absent = all granted capabilities permitted
offline_allowed	no	Boolean. For safetyclass C with physicalsafety: true, offline operation MUST NOT proceed unless this is explicitly true

OEP bundles are fetched via GET /v1/gap/offline-bundle?grant_oid=<oid> and expire at expires_at_ms.

Offline Evaluation When operating offline, the device:

1. Verifies the OEP bundle signature against the locally-held root public key
2. Checks grant.expires_at_ms against local clock
3. Checks offline_policy.max_offline_duration_ms from bundle issuance
4. Evaluates scope_narrowing against invocation args
5. Increments local invocation counter; denies if max_offline_invocations is reached
6. Issues a provisional receipt signed with the device-local key pre-provisioned at enrollment

Provisional receipts carry status: 'ok:offline' and include oep_bundle_oid referencing the OEP bundle. For safetyclass C capabilities with physicalsafety: true, offline operation MUST NOT proceed unless the OEP bundle's offline_policy.offline_allowed is explicitly true.

Reconciliation On reconnection, the device submits accumulated provisional receipts via POST /v1/gap/offline-receipts (array of provisional receipt CDROs). The gateway: 1. Validates each provisional receipt against the referenced OEP bundle 2. Issues an authoritative receipt (status: ok) or rejection receipt (status: denied) 3. Rejection does not retroactively void the physical action but establishes the audit record

Sovereign Mode For fully self-hosted deployments with no external connectivity, operators MAY run a locally-operated gateway with a locally-generated root-of-trust keypair. In sovereign mode: - All CDRO types are valid with locally-generated OIDs - The root public key is distributed at device provisioning time - No SynOI infrastructure is required at any point in the lifecycle

Workflows

Purpose A WorkflowDefinition describes a multi-stage Human-in-the-Loop (HITL) process triggered by a specific capability invocation. When a grant's pending_workflow field references a workflow definition, the gateway instantiates a WorkflowInstance instead of immediately producing a terminal receipt.

Workflow Lifecycle

1. On invocation, the gateway emits a receipt with status: pending.
2. The workflow proceeds through stages. Each stage may listen for channel events (SMS, push notification, webhook, overlay approval).
3. When the workflow reaches a terminal stage, the gateway emits a NEW receipt with the terminal status. The pending receipt MUST NOT be modified in place.
4. The terminal receipt's capability_grant_oids MUST include the grant OIDs from the triggering invocation.

Signal Sender Validation A gateway MUST validate the sender of every channel event used as a workflow signal:

• If a WorkflowStage's StageListen specifies required_from_binding, the gateway MUST verify the event's from field matches before accepting the event as a valid stage signal.
• For every channel kind on physical_safety: true stages, the gateway MUST verify the channel event's authenticity using the mechanism appropriate to the channel adapter (e.g. webhook HMAC, push token binding, local credential verification). No single channel is normatively required for this check; the Channel Adapter interface defines the verification contract.
• The same actor_oid MUST NOT be counted as two approvals for the same stage (no self-counting).

Channel Adapters GAP workflow stages deliver signals and receive responses through Channel Adapters. A Channel Adapter is an implementation of the following interface:

• kind: a ChannelKind string identifying the adapter
• performAction(stage, context): executes the stage action (sends alert, invokes tool, etc.)
• armListen(stage, context): arms the adapter to receive inbound signals (reply, button tap, etc.)
• health(): returns whether the adapter is currently operational

The gateway MUST support at minimum the sms channel kind. All other channel kinds are OPTIONAL but MUST conform to this interface when implemented.

Defined Channel Kinds

Kind	Description	Connectivity
sms	SMS message via any provider (Twilio, AWS SNS, etc.)	Internet
voice	Outbound voice call with IVR response	Internet
email	Email with approve/deny link	Internet
slack	Slack message with Block Kit interactive components	Internet
mobile_push	APNs / FCM push notification	Internet
sse	Server-Sent Events to a connected dashboard	LAN/Internet
webhook	HTTP POST to a configured endpoint	LAN/Internet
in_app	In-app overlay or notification	Local
game_engine	Game engine event (Unity, Unreal, Godot hook)	Local
local_terminal	Operator console at the local enforcement point; requires hardware token or biometric	Local/Air-gapped
hmi_panel	HMI touchscreen or physical operator panel at the device	Local/Air-gapped
opc_ua_ack	OPC-UA operator acknowledgement signal from a process historian or SCADA terminal	Local/Air-gapped
local_signed_token	Physical signed token (QR code, smart card, NFC) scanned at the device	Local/Air-gapped

Custom channel kinds MAY be used by implementing the Channel Adapter interface. The kind field accepts any string value; non-standard kinds SHOULD use a reverse-domain prefix (e.g. com.example.pager).

Air-Gapped HITL For deployments without external connectivity, air-gapped channel types (local_terminal, hmi_panel, opc_ua_ack, local_signed_token) produce stage transition CDROs signed by the local gateway instance. These are synchronized to the cloud gateway at next connectivity to establish the complete receipt chain. Local channel adapters authenticate the operator using locally-held credentials: - local_terminal: smart card, hardware token, or biometric; verified against locally-registered public key - hmi_panel: operator badge scan or PIN verified against local roster CDRO - opc_ua_ack: OPC-UA NodeId-scoped acknowledgement from an authorized operator session - local_signed_token: scanned CDRO (QR or NFC) verified against locally-held root public key The signal sender validation rule (required_from_binding) applies to all channel kinds. For local channels, required_from_binding references the operator's local actor OID rather than a phone number or Slack user ID.

Two-Person Integrity A stage MAY specify authorized_approvers (array of actor OIDs). When set:

• The gateway MUST verify the signal sender resolves to one of the listed OIDs.
• The workflow actor (the actor who triggered the invocation) MUST NOT serve as an approver (no self-approval).

Safety Constraints on Workflow Definitions For any stage triggered by a physical_safety: true or safety_class: C capability, a gateway MUST reject the workflow definition registration if any on_timeout path leads to a terminal stage with terminal_outcome: approved. Timeout MUST NOT produce approval for physical-safety capabilities. The minimum duration_seconds for any stage triggered by a safety_class: C capability is 30 seconds.

Revocation

Revocation Kinds

Kind	Effect	Use case
Immediate (L1)	Grant denied from effective_at_ms forward	Contractor access removal
Scheduled (L2)	Grant denied after effective_at_ms	Expiry enforcement
Provisional block	Capability temporarily blocked pending L3 quorum	Anomaly detection
L3 quorum	Block becomes permanent on quorum; may auto-renew	High-stakes revocation

Provisional Block Policy A RevocationEvent with revocation_kind: provisional_block MAY carry provisional_block_policy:

Field	Description
on_expiry_without_quorum	renew or revert
min_approvers	Minimum approver count for quorum
provisional_block_ttl_ms	Operator override for the block TTL. Defaults to 72 hours. Minimum: 1 hour.

The provisional block TTL defaults to 72 hours. Operators MAY set provisional_block_ttl_ms on the RevocationEventBody to override. Minimum: 1 hour. For safety_class C capabilities with on_expiry_without_quorum: renew, the renewal cycle period equals provisional_block_ttl_ms. When the provisional block TTL expires and quorum has not been reached:

• If on_expiry_without_quorum is renew (or the field is absent on a physical_safety: true grant): the block MUST auto-renew. The renewal MUST produce a receipt with subject_kind: provisional_block and status: pending.
• If on_expiry_without_quorum is revert: the block is lifted (capability re-enabled). The revert value MUST NOT be used for physical_safety: true capabilities regardless of the field value.

Offline Revocation Bundle A gap:revocation_bundle enables offline devices to check grant revocation status without contacting the gateway. RevocationBundleBody:

Field	Required	Description
revocations	yes	Array of RevocationEntry
snapshot_at_ms	yes	Unix epoch ms when the snapshot was taken
expires_at_ms	yes	Maximum age of this bundle; devices MUST NOT use it after this time
tenant_id	yes	Tenant this bundle applies to

Each RevocationEntry:

Field	Required	Description
grant_oid	yes	OID of the revoked grant
effective_at_ms	yes	When the revocation became effective
kind	yes	immediate, scheduled, or provisional_block

Export via GET /v1/gap/revocations/bundle?since_ms=<ms>. The bundle is gateway-signed. Fail-safe rules for offline devices:

• Devices operating with physical_safety: true capabilities MUST require a valid (not-expired) revocation bundle as a precondition for any invocation
• If the device cannot obtain a fresh-enough bundle before expires_at_ms, the fail-safe action for physical_safety: true and safety_class C capabilities MUST be DENY
• The maximum acceptable bundle age is set by max_revocation_bundle_age_ms on the grant; if absent, the gateway default applies (RECOMMENDED: 24 hours for class C, 7 days for class A/B)

Break-Glass Grants A break-glass grant pre-authorizes a defined set of emergency capabilities with an offline-verifiable signed token, for use when the gateway is unreachable and immediate action is required for safety or clinical reasons.

Break-Glass Grant Fields A grant with break_glass: true additionally carries:

Field	Required	Description
break_glass	yes	Boolean true. Marks this grant as a break-glass grant.
break_glass_token	yes	A signed CDRO of type gap:break_glass_token pre-issued by the gateway and stored securely on the device.
break_glass_ttl_ms	yes	TTL of the break-glass token in milliseconds from issuance. RECOMMENDED: 4 hours.
break_glass_max_invocations	no	Maximum invocations allowed under this token before it is exhausted. Defaults to 1 for safety_class C.
break_glass_requires_reason	no	Boolean. When true, the invoker MUST supply a break_glass_reason string in invocation args.

Break-Glass Token A gap:break_glass_token CDRO body:

Field	Required	Description
grant_oid	yes	OID of the break-glass grant this token activates
actor_oid	yes	OID of the authorized invoker
valid_from_ms	yes	Token validity start (Unix epoch ms)
expires_at_ms	yes	Token validity end (Unix epoch ms)
permitted_capabilities	yes	Array of capability patterns this token authorizes (subset of the grant)
max_invocations	yes	Maximum invocations before token is exhausted

The token is gateway-signed at provisioning time. The device verifies the signature using the locally-held public key (from the key bundle, per Offline Key Distribution) before activating break-glass operation.

Break-Glass Invocation A break-glass invocation MUST carry break_glass_token_oid in the invocation args. The enforcement point verifies:

1. The token OID matches a locally-held break-glass token CDRO
2. The token signature is valid
3. The token has not expired (expires_at_ms > current local clock)
4. The invoked capability matches permitted_capabilities
5. The token invocation counter has not reached max_invocations
6. If break_glass_requires_reason: true, break_glass_reason is non-empty

Break-glass invocations produce a mandatory provisional receipt with compliance_tags: ['break_glass']. The device MUST submit these receipts to POST /v1/gap/offline-receipts at next connectivity.

Local Override Credential For lifting a provisional block when the gateway is unreachable, an operator MAY provision a Local Override Credential (LOC) at grant issuance time. A gap:local_override_credential CDRO body:

Field	Required	Description
grant_oid	yes	OID of the provisionally-blocked grant
actor_oid	yes	OID of the authorized override operator
expires_at_ms	yes	Credential expiry
single_use	yes	Always true. An LOC MUST be invalidated after first use.
override_reason_required	yes	Boolean. When true, operator MUST supply a reason string.

The LOC is signed by the operator's key at grant issuance time and stored physically at the installation site (QR code, USB token, or printed secure storage). When presented at the local enforcement point, it lifts the provisional block exactly once and produces a local override receipt synchronized at next uplink. Neither break-glass nor LOC mechanism allows indefinite ungoverned operation. Both produce mandatory audit trails submitted to the gateway at next connectivity.

L3 Quorum Approval A revocation event may collect approvals via POST /v1/gap/revoke/approve. Each approval MUST:

• Identify a unique approver_actor_oid (no duplicate approvers).
• Not be made by the same actor who created the revocation event (no self-approval).

When min_approvers is reached, the gateway MUST set effective_at_ms on the revocation event and enforce the revocation.

HTTP API Surface A GAP-conformant gateway MUST expose the following endpoints under a base path (conventionally /v1/gap). All endpoints require Bearer token authentication. Tenant isolation MUST be enforced: every CDRO fetch endpoint MUST verify stored_object.tenant_id === authenticated_tenant_id. On mismatch, the gateway MUST return HTTP 404 (never HTTP 403, which would confirm cross-tenant OID existence).

Core Endpoints

Method	Path	Description
POST	/declarations	Register a CapabilityDeclaration
GET	/declarations/:oid	Fetch a declaration by OID
POST	/grants	Issue a CapabilityGrant
GET	/grants	List grants (query: actor_oid, capability, status)
GET	/grants/:oid	Fetch a grant by OID
POST	/invoke	Invoke a capability
POST	/invoke/batch	Submit up to 1000 invocations sharing a tenant in a single request (L2 OPTIONAL). Returns array of receipts in submission order. Grant evaluation is independent per invocation.
GET	/receipts	List receipts (query: actor_oid, grant_oid, capability, from_ms, to_ms, status, limit, cursor)
GET	/receipts/:oid	Fetch a receipt by OID
GET	/limits/:pool_id	Returns current rolling sum and remaining headroom for a named aggregate limit pool.

Revocation Endpoints

Method	Path	Description
POST	/revoke	Immediate or scheduled revocation
POST	/revoke/provisional-block	Provisional block (anomaly response)
POST	/revoke/approve	Submit L3 quorum approval
GET	/revocations/:oid	Fetch a revocation event by OID
GET	/revocations	List revocation events (query: grant_oid, target_kind, since_ms)

Workflow Endpoints

Method	Path	Description
POST	/workflows/definitions	Register a WorkflowDefinition
GET	/workflows/definitions/:oid	Fetch a definition by OID
GET	/workflows/instances/:oid	Fetch a workflow instance
GET	/workflows/instances/:oid/transitions	List stage transitions
POST	/workflows/signal	Deliver a channel event signal

Key Endpoints

Method	Path	Description
GET	/keys/current	Fetch the current signing key (public)
GET	/keys/:key_id	Fetch a signing key by ID (public)
GET	/keys/bundle	Fetch a signed keyring export bundle for offline verifiers

Offline Endpoints

Method	Path	Description
GET	/offline-bundle	Fetch an OEP bundle for offline grant evaluation (query: grant_oid)
POST	/offline-receipts	Submit accumulated provisional receipts for reconciliation
GET	/revocations/bundle	Fetch a signed revocation snapshot bundle (query: since_ms)

Conformance GAP implementations declare a conformance tier. A higher tier is a superset of all lower tiers.

Tier L1: Object Layer An L1 implementation:

• MUST validate CDRO envelopes per {{object-model}}.
• MUST compute and verify content-addressed OIDs per {{oid-computation}}.
• MUST produce GapDecisionReceipts for every gate decision.
• MUST enforce tenant isolation on all CDRO fetch operations.
• Does NOT enforce scope_narrowing evaluation (steps 1-3 of grant evaluation only: expiry, revocation, grantee match).
• A grant containing any GrantedCapabilityScope with non-empty scope_narrowing MUST be rejected by an L1-conformant gateway at grant issuance time with HTTP 400 and error type tier_insufficient.

Tier L2: Grant Evaluation Layer An L2 implementation satisfies L1 and additionally:

• MUST enforce scope_narrowing per {{scope-narrowing}}.
• MUST enforce delegation subset rules per {{delegation}}.
• MUST enforce invocation timestamp validation.
• MUST implement idempotency per {{idempotency}}.
• MUST enforce aggregate_limits rolling windows.

Tier L3: Workflow Layer An L3 implementation satisfies L2 and additionally:

• MUST implement workflow instantiation, stage transitions, and HITL channel signaling.
• MUST implement optional_effects evaluation.
• MUST implement provisional block with quorum semantics.
• MUST emit the complete pending + terminal receipt chain for every workflow.

Tier L4: Federation Layer An L4 implementation satisfies L3 and additionally:

• MUST implement L3 quorum revocation with multi-party approval.
• MUST implement cross-tenant receipt verification.
• MUST implement federation handshakes.

L3-PQ and L4-PQ (Post-Quantum Only) For deployments under CNSA 2.0 (NSS policy) or equivalent post-quantum mandates where Ed25519 is not an approved algorithm:

Tier	Signing	Use case
L3-PQ	ML-DSA-65 only (no Ed25519)	Classified / NSS deployments requiring CNSA 2.0 compliance
L4-PQ	ML-DSA-65 only + authorized axis	Classified / regulated deployments requiring PQ + full audit chain

The existing L4 hybrid mode (Ed25519 + ML-DSA-65) remains for interoperability with non-classified systems. Pure ML-DSA-65 operation without Ed25519 is the conformant path for CNSA 2.0 deployments. The signature_algorithm field in the CDRO envelope (value: ML-DSA-65) identifies PQ-only receipts. Security Considerations: Ed25519 is not approved for National Security Systems under CNSSP-15 and CNSA 2.0. New NSS deployments MUST use L3-PQ or L4-PQ minimum.

Conformance by Sector

Sector	Minimum Tier	Rationale
MCP tool governance	L2	Scope enforcement mandatory
AI agent pipelines	L2	Delegation chains required
Smart home (consumer)	L2	User-issued grants with scope
Industrial / OT	L3	HITL + provisional block required
Medical device / clinical (21 CFR Part 11)	L4 MINIMUM	HITL + signed receipts + authorized axis required. L3 without signed receipts does not satisfy 21 CFR Part 11 Section 11.50 electronic signature requirements. An L3 deployment for medical devices is non-conformant to Part 11.
Physical security	L3	HITL + two-person integrity
Cross-tenant / federated	L4	Federation semantics

Security Considerations

OID Integrity The security of GAP receipts depends on the integrity of OID computation. An implementation MUST compute OIDs using the canonical JSON form defined in {{canonical-json}}. Divergence in canonical form between the issuing gateway and a verifier produces OID mismatch, which is detectable but MUST be investigated; it indicates either a bug or an active tampering attempt. Implementations across different languages MUST independently verify that their canonical JSON output matches the test vectors in the @synoi/gap TypeScript package and the Python synoi-gap package. The pinned test vectors in test/conformance.test.ts serve as cross-implementation reference points.

Signature Verification

When signing is required A gateway MUST sign a receipt with Ed25519 when any of the following are true:

1. The effective require_signed_receipt for the capability is true. The effective value is determined by evaluating in precedence order: (a) GrantedCapabilityScope.require_signed_receipt if present; (b) CapabilitySpec.require_signed_receipt if present; (c) the gateway's configured default signing policy.
2. The gateway is configured to sign all receipts by default and neither the grant nor the declaration has suppressed signing with require_signed_receipt: false.
3. The capability's effective privacy_classification is financial or matches financial.*, OR the deployment asserts 21 CFR Part 11 compliance. For capabilities in these categories, require_signed_receipt MUST default to true and MUST NOT be overridable to false by operator grant override.

A gateway MAY be configured with a safety_class_signing_floor that sets the minimum safety_class for which signatures are mandatory regardless of require_signed_receipt settings (e.g. B means all class B and C receipts are signed). Gateway configuration SHOULD document whether safety_class_signing_floor is set, as it affects the signing behavior for every tenant on that deployment. A gateway MUST NOT sign a receipt when the effective require_signed_receipt is false, regardless of the server's default policy. This allows actors to opt specific high-frequency capabilities out of signing cost. When signing is not required, the signature and signature_key_id fields MUST be omitted from the receipt envelope.

Verifier obligations Verifiers MUST:

• Fetch the signing key from the gateway's /keys/:key_id endpoint using the signature_key_id from the receipt.
• Verify that the key's expires_at_ms has not passed.
• Verify the signature over the canonical envelope (with the same field exclusions used for OID computation).

A verifier that receives a receipt without a signature field for a capability where require_signed_receipt is true MUST treat the receipt as invalid. Key rotation: a gateway MUST publish a new key before retiring an old one. Old keys remain valid for verifying receipts signed under them. The current key is always the one returned by GET /keys/current.

Offline Key Distribution A gap:keyring_export CDRO enables verifiers to operate without a live /keys endpoint. KeyringExportBody:

Field	Required	Description
keys	yes	Array of KeyEntry
exported_at_ms	yes	Unix epoch ms when the bundle was generated
expires_at_ms	yes	Bundle validity window

Each KeyEntry:

Field	Required	Description
key_id	yes	Key identifier matching signature_key_id on receipts
public_key_base64	yes	Base64url-encoded public key bytes
algorithm	yes	Ed25519, ML-DSA-65, or Ed25519+ML-DSA-65
valid_from_ms	yes	Key validity start
expires_at_ms	yes	Key validity end

The bundle is signed by the gateway's current root key so verifiers can authenticate it. Export via GET /v1/gap/keys/bundle. The bundle is distributable as a file, QR code, or USB for air-gapped deployments. Offline verifier rules: 1. Load the bundle at provisioning time; verify bundle signature against locally-installed root public key 2. On receipt verification, look up key_id in local bundle only 3. If key_id is not in the bundle, treat receipt as UNVERIFIABLE (not INVALID); the key may exist but has not been delivered yet 4. If the bundle is expired, treat all receipts issued after expires_at_ms as UNVERIFIABLE until a fresh bundle is obtained A signature_algorithm field MUST be added to the CDRO envelope (alongside signature and signature_key_id): values: Ed25519, ML-DSA-65, Ed25519+ML-DSA-65. Verifiers MUST NOT guess the algorithm from key length.

Tenant Isolation A gateway MUST NOT return a CDRO belonging to one tenant in response to a request authenticated as another tenant. The response for cross-tenant or not-found OIDs MUST be HTTP 404 to avoid confirming cross-tenant OID existence.

Delegation Chain Security A gateway MUST evaluate the full delegation chain on every invocation. A child grant whose parent has been revoked or expired MUST be denied, even if the child grant itself has not expired. Partial chain validation is insufficient.

Provisional Block Fail-Closed For physical_safety: true grants, a gateway MUST treat the absence of on_expiry_without_quorum as renew. A gateway MUST NOT allow revert semantics for physical-safety capabilities regardless of the field value. This ensures that a gateway with misconfigured or absent provisional block policy defaults to the safer state (block maintained).

Workflow Signal Injection A gateway MUST validate the sender identity of every channel event before advancing a workflow stage. Failure to validate enables unauthorized parties to advance or terminate HITL workflows by injecting signals. The required_from_binding field provides the expected sender identity; its enforcement is REQUIRED for physical_safety: true stages.

Idempotency Cache Staleness An idempotency cache hit MUST NOT return a cached approval receipt without re-validating that the underlying grant is still active. A grant may be revoked after the original approval. Returning a cached receipt for a revoked grant enables unauthorized capability exercise after revocation.

Negative Numeric Scope Values For physical_safety: true capabilities, a gateway MUST reject invocation arguments that contain negative numeric values for scope-constrained keys, even when those values would satisfy an upper-bound check. A negative value for a physical parameter (e.g. max_delta_units: -5.0) is almost always a sign of argument manipulation rather than a legitimate invocation.

Bearer Token Security GAP does not define the authentication mechanism for the Bearer tokens used to authenticate gateway API calls. Implementors MUST use short-lived tokens, rotate signing keys, and follow for Bearer token handling. Bearer token theft is not mitigated by this protocol; it is a deployment concern.

Self-Sovereign Credential Mode For deployments without external connectivity or without a SynOI-operated token issuer, a Self-Sovereign Credential (SSC) mode provides an alternative authentication path. In SSC mode: 1. The operator bootstraps a Local Credential Authority (LCA) by generating a local root signing keypair and publishing a gap:lca_root CDRO signed by the root key. 2. Actor credentials are short-lived signed tokens bound to actor_oid and tenant_id, issued by the LCA and signed with ML-DSA-65 (or Ed25519 for non-NSS deployments). 3. The gateway verifies actor credentials using the locally-held LCA public key only. 4. Credential rotation requires only local key material. The existing synoi-sk- Bearer token remains valid for cloud-connected deployments. SSC mode is a normative alternative, not a deployment footnote. The gap:lca_root CDRO type is defined with body: { root_public_key_base64: string, algorithm: string, tenant_id: string, valid_from_ms: number, expires_at_ms: number }.

IANA Considerations This document makes no requests to the Internet Assigned Numbers Authority (IANA) at this time. Future revisions of this specification MAY request registration of:

• A media type application/gap+json for GAP CDRO objects.
• A URI scheme gap: for portable CDRO references.

Normative References Informative References

Normative References

:

Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.

:

Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, May 2017.

:

Josefsson, S. and I. Liusvaara, "Edwards-Curve Digital Signature Algorithm (EdDSA)", RFC 8032, January 2017.

:

Jones, M. and D. Hardt, "The OAuth 2.0 Authorization Framework: Bearer Token Usage", RFC 6750, October 2012.

Informative References

:

Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", STD 90, RFC 8259, December 2017.

:

Rundgren, A., Jordan, B., and S. Erdtman, "JSON Canonicalization Scheme (JCS)", RFC 8785, June 2020.

:

Jones, M., "JSON Web Key (JWK)", RFC 7517, May 2015.

Acknowledgments The editors thank the SynOI protocol team and the early implementors who provided feedback on the wire format and grant evaluation algorithms during the cross-sector safety review that produced the ADR_006 safety protocol.