Authority Infrastructure
Every action passes through authority before reality changes
TrigGuard is the control layer between AI-generated intent and irreversible execution. One authority model across agents, applications, SDKs, and CI/CD pipelines.
System topology
Where the infrastructure actually sits
Deployment components for authorization. Callers never reach execution surfaces until the gateway returns a terminal decision. Hostnames and packages match the production deploy model.
Callers
- AI agents / MCP
- CI/CD
- Apps & SDKs
- CLI
Clients
trigguardSDK- CLI / GitHub Action
- Providers (mapAction)
Platform
- Gateway
api.trigguardai.com - Control plane
control.trigguardai.com - Decision log
- Policy eval + Ed25519 signing
State
- PostgreSQL
- In-process policy cache
- Optional Redis (global rate limits)
After PERMIT
- Receipt + audit trail
- Caller executes surface
- Offline verifier
| Component | Role | Package / host | Stateful? |
|---|---|---|---|
| Execution gateway | POST /execute, policy evaluation, receipt build/sign, decision-log append, /protocol/* on the authority rail |
trigguard-cloud · api.trigguardai.com (Cloud Run) |
Stateless compute; depends on Postgres + keys + log |
| Control plane | Orgs, API keys, billing, usage quotas used by gateway auth | trigguard-control-plane · control.trigguardai.com |
Stateful (Postgres) |
| Decision log | Transparency append for authorized decisions; may fail closed when required | trigguard-decision-log · TRIGGUARD_DECISION_LOG_URL |
Stateful (durable backend required in production) |
| PostgreSQL | Control-plane schema, customer key lookup, usage | DATABASE_URL (Cloud SQL or equivalent) |
Stateful |
| Policy cache | In-process cache of compiled / pinned policy material | Inside gateway process | Ephemeral per replica |
| Redis (optional) | Cross-replica rate limits when multi-instance caps must be global | Not required for single-replica; documented for HA rate limiting | Stateful when deployed |
| Signing / keys | Ed25519 receipt authority; published verification material | Secret Manager / env · JWKS / published keys | Secret material outside image |
| Public verify surfaces | Read-mostly protocol endpoints on site origin (capabilities, status, metadata, test vectors) | Firebase Hosting → Cloud Functions; separate from execute path | Stateless edge |
| Execution surfaces | Side effects after PERMIT - payments, cloud APIs, DB writes, CI, agents, robotics/OT | Caller-owned; not TrigGuard | Caller domain |
Gateway and control plane deploy as separate Cloud Run services with managed TLS at the edge. Verification HTTP on the marketing origin is intentionally decoupled from POST /execute uptime.
Trust boundaries
Trusted vs untrusted components
Intent is untrusted. Authorization is trusted only inside the platform. Execution remains with the caller after PERMIT - TrigGuard does not become the side-effect runtime.
Untrusted
- Agent / LLM intent and tool proposals
- Client SDK / CLI / MCP process memory
- CI runners and application hosts
- Downstream execution surfaces (Stripe, cloud APIs, DBs, robots)
Boundary
- Authenticated
POST /execute(API key) - Signed policy bundle + surface registry
- Terminal decision: PERMIT | DENY | ESCALATE | SILENCE
- No silent bypass; unknown / timeout → non-PERMIT
Trusted (platform)
- Gateway policy evaluation and receipt signing
- Control-plane identity and key issuance
- Decision-log append (when required)
- Published keys for offline verification
Observability (Datadog, stdout metrics) is outside the authorization path. Telemetry failure must not change PERMIT/DENY/ESCALATE/SILENCE. Decision-log append fail-closed is governance evidence, not observability babysitting.
Runtime architecture
Real request path
Conceptual hero diagram above shows outcomes. This is the wire path for a governed action.
- Caller Agent, app, CI job, or MCP host forms an execution request (surface + action + context).
- Client SDK / CLI / Action / provider
mapAction→ HTTP to gateway. Clients do not evaluate policy. - Gateway Auth → surface check → policy evaluation → terminal decision.
- Receipt Ed25519-signed receipt bound to action, actor, and policy context; decision-log append when configured.
- Verifier Caller or auditor verifies offline with published keys (no execute round-trip required).
- Execution Only on PERMIT does the caller perform the side effect on its surface. DENY / SILENCE / ESCALATE do not authorize execution.
Availability / failure model
What happens when a dependency fails
Production gateway mode is fail-closed. Missing authority does not degrade into PERMIT.
| Failure | Authorization outcome | Notes |
|---|---|---|
| Gateway unreachable / timeout | No PERMIT - client must not execute | Protocol: timeout is not a decision; treat as non-authorization |
| Policy bundle / registry missing or invalid | Boot or request fail-closed | Production mode forbids unconfigured policy |
| Signing key unavailable | Fail closed (no unsigned production receipts) | Strict production config requires authority key material |
| Decision log down + append required | Fail closed (non-PERMIT) | TRIGGUARD_REQUIRE_DECISION_LOG_APPEND=1 |
| PostgreSQL unavailable | Auth / quota / key lookup fail closed when DB-backed | Control plane and embedded customer auth depend on DATABASE_URL |
| Redis unavailable | No impact if unused; if used for global limits, fail closed or refuse excess per config | Default rate limits are in-process per replica |
| Network partition to surface after PERMIT | Authorization already issued; execution is caller's problem | Receipt remains the audit artifact; retry/idempotency owned by caller |
| Observability / Datadog outage | No change to decision semantics | Telemetry is not on the authorize path |
Scaling / HA
Stateless compute, stateful stores
Gateway replicas scale horizontally on Cloud Run. Durable truth lives in Postgres, decision log, and signing keys - not in a single gateway process.
Horizontal
Gateway and control-plane containers are horizontally scalable. Prefer more replicas over larger single processes for concurrency.
Stateful
PostgreSQL and the decision-log backend are the HA focus. Backups, multi-AZ, and connection pooling are operator-owned for enterprise deploys.
Concurrency
In-process policy cache and per-replica rate limits do not automatically synchronize. Strict global caps need Redis (or equivalent) across replicas.
Recovery
Cold start reconstitutes from signed policy bundle + secrets + DB. No "degraded PERMIT" path. Measured latency under load: see benchmarks (lab figures; production adds TLS/WAN/cold start).
Infrastructure properties
Built for production authority
The same guarantees whether you integrate via SDK, CLI, or public protocol interfaces.
Execution stops when authority is unavailable. No silent bypass, no degraded permit path.
Every decision produces Ed25519-signed proof bound to the action, actor, and policy context.
SDKs, APIs, and CLI share the same authority model. One protocol, multiple integration surfaces.
Every evaluation resolves to exactly one outcome: Permit, Deny, Escalate, or Silence.
Public interfaces
Protocol surfaces for automation
Machine-readable endpoints on the same origin as this site. Mapped by Firebase Hosting to Cloud Functions; authoritative verification and policy logic live in protocol repositories and client libraries.
Machine-readable authority capabilities and deterministic capability manifest.
Open endpoint →Authority health and availability. Protocol status snapshot for monitoring and integration checks.
Open endpoint →Versioning and deployment metadata. Engine and environment identifiers for conformance.
Open endpoint →Deterministic SDK conformance vectors with inputs and expected decisions.
Open endpoint →In-memory request and decision counters for this instance. Resets on cold start.
Open endpoint →Canonical receipt trust path: published keys plus local Ed25519 verification. No server round-trip required.
Verification guide →Request-access and lead flow. Not part of the core protocol API.
Contact →