TrigGuard
TRIGGUARD PROTOCOL_SPEC
Request a demo

Technical specification

TG-01 — deterministic authorization protocol. Pre-execution governance: deterministic outcomes, no silent allow, cryptographically verifiable receipts.

New to the category? Read execution authorization · Products · Quickstart

PROTOCOL IDENTIFIER: TG-PRTCL-01

VERSION: 1.0.4-STABLE

LAST UPDATED: 2026

STATUS: PRODUCTION_ACTIVE

CLASSIFICATION: DETERMINISTIC_EXECUTION_CONTROL

// PROTOCOL PRIMITIVES

API

POST /execute

Single entry point for pre-execution evaluation. Request fields: surface, action, context, idempotency_key. Irreversible work proceeds only after an explicit PERMIT and signed receipt.

KEY_DISCOVERY

/.well-known/trigguard/keys.json

Public keys for offline verification. No callback to TrigGuard required after issuance.

SECURITY

Ed25519

Cryptographically signed receipts for every state-change. Tamper-evident, independently verifiable.

VERIFICATION

Offline Verification

Verify receipts against published keys locally. Third parties can validate enforcement without trusting our uptime.

// FORMAL PROTOCOL STANDARDS

Protocol Specification

TLS carries the channel; identity stays at your IdP. TrigGuard’s job is execution governance—binding outcomes and signed proof. Formal specs for audit and procurement.

TG-EXECUTION-AUTH-01 Protocol Specification Authorization flow, API schema, security model TG-RECEIPT-SCHEMA Receipt Schema JSON schema, signature payload, fields TG-KEY-DISCOVERY Key Management Well-known endpoint, key lifecycle

I. Abstract

The TrigGuard protocol (TGP) defines a cryptographic boundary between callers (automation, agents, CI) and irreversible execution. TGP operates before commit: every state-changing path must receive an explicit authorization decision and signed receipt. There is no silent default-allow—if evaluation fails or is incomplete, execution does not proceed.

II. Core Architecture: The Gate Model

The protocol follows a Request–Attestation–Receipt loop:

  1. Intercept: All POST /execute requests enter the single authoritative evaluation layer.
  2. Validation: Declared context is hashed and evaluated against deterministic policy—same conditions, same outcome.
  3. Signing: On PERMIT (only), the protocol issues an Ed25519-signed receipt. DENY and SILENCE still yield a deterministic, attributable outcome.
  4. Execution: Downstream systems must not commit without a valid PERMIT receipt binding that request.

TrigGuard operates at the point of irreversible execution, not just policy evaluation.

Technical Properties

Low latency (scoped)

Kernel hot path <5ms p99; end-to-end evaluation <15ms p99—no scoring layers, no hidden models in the decision path.

Cryptographically enforced

Ed25519-signed receipts. Tamper-evident outcomes auditors can verify offline.

Zero standing trust at verify

Integrate at the same choke point you use for deploy/pay/export. Enforce before commit, verify without callback.

III. Payload Specification

Every authorized action must contain the following header structure:

{
  "tg_receipt_id": "uuid-v4",
  "tg_signature": "base64_encoded_hash",
  "tg_timestamp": "unix_epoch",
  "tg_policy_ver": "1.0.4"
}

Protocol Flow

Request → authoritative evaluation → deterministic outcome → signed receipt (on PERMIT) → caller executes only if PERMIT.

AI AGENT HOST APP TGP GATE DOWNSTREAM 1. Executes Action (High Risk) 2. Intercepts Intent Payload 3. [SIGNED_RECEIPT] 4. Authorizes (WITH Receipt) 5. Returns Success

// 01 — Execution API

POST /execute

Request pre-execution evaluation for an irreversible action. TrigGuard returns PERMIT, DENY, or SILENCE; downstream execution proceeds only on PERMIT with a valid receipt.

# Request
POST https://api.trigguardai.com/execute
Authorization: Bearer $TG_API_KEY
Content-Type: application/json

{
  "surface": "deploy.release",
  "action": "promote-to-production",
  "context": {
    "commit": "a1b2c3d4",
    "branch": "main",
    "environment": "production",
    "actor": "ci-bot"
  },
  "idempotency_key": "deploy-2026-03-13-001"
}
# Response: PERMIT
HTTP/1.1 200 OK

{
  "decision": "PERMIT",
  "receipt_id": "tg_rcpt_7f3a9c2b1d4e5f6a",
  "timestamp": "2026-03-13T14:22:00.000Z",
  "expires_at": "2026-03-13T14:32:00.000Z",
  "signature": "ed25519:base64...",
  "key_id": "tg_key_2026_03"
}
# Response: DENY
HTTP/1.1 403 Forbidden

{
  "decision": "DENY",
  "reason": "policy_violation",
  "policy_id": "prod-deploy-hours",
  "message": "Production deploys denied outside business hours",
  "receipt_id": "tg_rcpt_8e4b2a1c3d5f6e7a",
  "signature": "ed25519:base64..."
}

// 02 — Decision Types

Three Possible Outcomes

Every request produces exactly one of three deterministic outcomes. No probabilistic reasoning. No ambiguity.

PERMIT

Action is authorized. Receipt is valid for the specified TTL. Proceed with execution.

DENY

Action is denied. Reason and policy ID included. Do not proceed.

SILENCE

SILENCE means no authorization was issued. Without authorization, execution cannot proceed. (Evaluation may be indeterminate in cause—still explicit non-permission.)

  • PERMIT → execution proceeds
  • DENY → system blocks execution
  • SILENCE → no authorization → execution cannot proceed

// LAYERS

Receipts record decisions. Runtimes record enforcement.

Do not mix vocabulary on a single axis. Decision (receipt-safe, auditor-facing): PERMIT, DENY, SILENCE. Enforcement (runtime telemetry, operator records): EXECUTED, BLOCKED. The word BLOCK is not a decision label—BLOCKED is what the system did after receiving a decision.

Rule: Decisions DENY. Systems BLOCK. A signed receipt always records what TrigGuard decided—not whether the caller later attempted execution.

# Correct two-field representation
{
  "decision": "DENY",
  "enforcement": "BLOCKED"
}

Invariant: any outcome other than PERMIT maps to enforcement = BLOCKED in a conformant integration. PERMIT may yield EXECUTED or BLOCKED only if downstream execution fails or an operator aborts.

Full decision & enforcement model →

// 03 — Key Discovery

GET /.well-known/trigguard/keys.json

Public keys for receipt verification are published at a well-known endpoint. Rotate keys without breaking verification.

# Request public keys
GET https://api.trigguardai.com/.well-known/trigguard/keys.json

# Response
{
  "keys": [
    {
      "key_id": "tg_key_2026_03",
      "algorithm": "Ed25519",
      "public_key": "base64...",
      "created_at": "2026-03-01T00:00:00Z",
      "expires_at": "2026-06-01T00:00:00Z",
      "status": "active"
    },
    {
      "key_id": "tg_key_2026_01",
      "algorithm": "Ed25519", 
      "public_key": "base64...",
      "created_at": "2026-01-01T00:00:00Z",
      "expires_at": "2026-04-01T00:00:00Z",
      "status": "deprecated"
    }
  ],
  "issuer": "https://api.trigguardai.com",
  "updated_at": "2026-03-01T00:00:00Z"
}

// 04 — Receipt Format

Signed Receipt Structure

Every decision produces a cryptographically signed receipt. Receipts are self-contained and verifiable offline.

receipt_id Unique identifier (tg_rcpt_...)
decision PERMIT | DENY | SILENCE
timestamp ISO 8601 UTC
expires_at Receipt validity window
signature Ed25519 signature (base64)
key_id Signing key identifier
surface Execution surface (deploy.release, etc.)
context_hash SHA-256 of request context

// 05 — Offline Verification

Verify Without Network Access

Once you have the public keys, verification requires no network call to TrigGuard. Cache keys, verify locally.

# Verification pseudocode
def verify_receipt(receipt, public_keys):
    key = find_key(public_keys, receipt.key_id)
    if not key:
        return False
    
    payload = canonical_json({
        "receipt_id": receipt.receipt_id,
        "decision": receipt.decision,
        "timestamp": receipt.timestamp,
        "surface": receipt.surface,
        "context_hash": receipt.context_hash
    })
    
    return ed25519_verify(
        key.public_key,
        payload,
        receipt.signature
    )

// PROTOCOL MAP

How the protocol is organized on this site

Canonical paths for crawlers and engineers—each page links back into products and docs so nothing sits orphaned.

SPECRequest/decision/response schemas and error semantics. ARCHITECTUREPipeline: signals, frame, safety engine, execution boundary. SURFACESinfra.apply, deploy.release, migrate, export, payments, secrets… RECEIPTSStructure, signatures, integrity, replay considerations. DECISION MODELPERMIT, DENY, SILENCE — fail-closed semantics. SECURITYThreat model, trust boundaries, governance guarantees.

Also see Products, Docs, and /protocol/spec ↔ /docs/api for cross-links.

// 06 — Formal Specifications

Protocol Standards

Complete protocol specifications in RFC-style documentation. Cite these in compliance reviews, security audits, and vendor assessments.

TG-EXECUTION-AUTH-01 Primary protocol specification. Authorization flow, API schema, security model. TG-RECEIPT-SCHEMA Receipt structure specification. JSON schema, signature payload, field definitions. TG-KEY-DISCOVERY Key management specification. Well-known endpoint, key lifecycle, client implementation.
Try Verification Integration Guide