TG-KEY-DISCOVERY — TrigGuard Key Management Specification

Abstract

This document specifies the key discovery mechanism for TrigGuard Execution Receipts. Public keys used to verify receipt signatures are published at a well-known URL, enabling offline verification without runtime dependency on TrigGuard services.

1. Overview

TrigGuard uses Ed25519 public-key cryptography for receipt signing. To verify signatures, clients need access to public keys. This specification defines:

How keys are published
Key metadata format
Key rotation procedures
Caching recommendations

2. Well-Known Endpoint

2.1 URL

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

2.2 Production URL

https://api.trigguardai.com/.well-known/trigguard-keys.json

2.3 Response Headers

Header	Value
`Content-Type`	`application/json`
`Cache-Control`	`max-age=3600`
`Access-Control-Allow-Origin`	`*`

2.4 Response Status

Status	Meaning
200	Success
503	Service unavailable

3. Response Schema

3.1 JSON Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://trigguardai.com/schemas/keys.json",
  "title": "TrigGuard Key Set",
  "type": "object",
  "required": ["keys", "issuer"],
  "properties": {
    "keys": {
      "type": "array",
      "items": { "$ref": "#/definitions/key" }
    },
    "issuer": {
      "type": "string",
      "format": "uri"
    },
    "documentation": {
      "type": "string",
      "format": "uri"
    }
  },
  "definitions": {
    "key": {
      "type": "object",
      "required": ["key_id", "algorithm", "public_key", "status"],
      "properties": {
        "key_id": { "type": "string" },
        "algorithm": { "type": "string", "enum": ["Ed25519"] },
        "public_key": { "type": "string" },
        "status": { "type": "string", "enum": ["active", "deprecated", "revoked"] },
        "created_at": { "type": "string", "format": "date-time" },
        "expires_at": { "type": "string", "format": "date-time" },
        "deprecated_at": { "type": "string", "format": "date-time" }
      }
    }
  }
}

3.2 Example Response

{
  "keys": [
    {
      "key_id": "tg_prod_02",
      "algorithm": "Ed25519",
      "public_key": "MCowBQYDK2VwAyEAn8j/xb4Df2vB1sP+pzRw3Y5kLfKm9vE7h8QaXcW2rD0=",
      "status": "active",
      "created_at": "2026-03-01T00:00:00Z",
      "expires_at": "2026-06-01T00:00:00Z"
    },
    {
      "key_id": "tg_prod_01",
      "algorithm": "Ed25519",
      "public_key": "MCowBQYDK2VwAyEAz7Y2xK4pE8vN3mJ1cR9wB6fT5hL2qS0nG8jD4aX1kM0=",
      "status": "deprecated",
      "created_at": "2026-01-01T00:00:00Z",
      "expires_at": "2026-04-01T00:00:00Z",
      "deprecated_at": "2026-03-01T00:00:00Z"
    }
  ],
  "issuer": "https://api.trigguardai.com",
  "documentation": "https://trigguardai.com/protocol"
}

4. Key Fields

4.1 key_id

Property	Value
Type	string
Format	`tg_<environment>_<sequence>`
Environment	`prod`, `staging`, `dev`

Examples: tg_prod_01, tg_prod_02, tg_staging_01

4.2 algorithm

Property	Value
Type	string
Allowed Values	`Ed25519`

Only Ed25519 is supported in this version of the specification.

4.3 public_key

Property	Value
Type	string
Encoding	Base64 (RFC 4648)
Format	SubjectPublicKeyInfo (SPKI)

4.4 status

Status	Meaning	Verification
`active`	Current signing key	Accept signatures
`deprecated`	Previous key, still valid	Accept signatures
`revoked`	Compromised or retired	Reject signatures

5. Key Lifecycle

5.1 States

create │ ▼ ┌────────┐ │ active │ └───┬────┘ │ rotate ▼ ┌───────────┐ │deprecated │ └─────┬─────┘ │ expire/revoke ▼ ┌──────────┐ │ revoked │ └──────────┘

5.2 Rotation Schedule

Event	Timeline
New key created	Q1, Q2, Q3, Q4
Previous key deprecated	At new key creation
Deprecated key revoked	90 days after deprecation

5.3 Emergency Rotation

In case of key compromise:

New key created immediately
Compromised key revoked (not deprecated)
Alert published to status page
Affected receipts identified

6. Client Implementation

6.1 Key Fetching

Clients MUST:

Request /.well-known/trigguard-keys.json
Parse JSON response
Store keys locally
Handle HTTP errors gracefully

6.2 Caching

Clients SHOULD:

Cache keys for at least 1 hour
Refresh cache on signature verification failure
Store cache persistently for offline verification

Clients MUST NOT:

Cache keys indefinitely without refresh
Ignore key expiration

6.3 Key Selection

When verifying a receipt:

Extract key_id from receipt
Look up key in cached key set
If not found, refresh key cache
If still not found, verification fails

6.4 Status Validation

Key Status	Verification Action
`active`	Accept
`deprecated`	Accept
`revoked`	Reject
not found	Refresh cache, then reject if still not found

7. Examples

7.1 Fetching Keys (curl)

curl -s https://api.trigguardai.com/.well-known/trigguard-keys.json | jq

7.2 Key Lookup (Python)

import requests
import json

def fetch_keys():
    response = requests.get(
        "https://api.trigguardai.com/.well-known/trigguard-keys.json",
        timeout=10
    )
    return response.json()

def get_public_key(key_id):
    keys = fetch_keys()
    for key in keys["keys"]:
        if key["key_id"] == key_id and key["status"] != "revoked":
            return key["public_key"]
    return None

7.3 Full Verification (Python)

from nacl.signing import VerifyKey
import base64
import json

def verify_receipt(receipt, keys):
    # Find key
    key_id = receipt["key_id"]
    key_entry = next(
        (k for k in keys["keys"] if k["key_id"] == key_id),
        None
    )
    if not key_entry or key_entry["status"] == "revoked":
        return False
    
    # Decode public key (last 32 bytes of SPKI)
    spki = base64.b64decode(key_entry["public_key"])
    public_key_bytes = spki[-32:]
    
    # Construct payload
    payload = json.dumps({
        "context_hash": receipt["context_hash"],
        "decision": receipt["decision"],
        "receipt_id": receipt["receipt_id"],
        "surface": receipt["surface"],
        "timestamp": receipt["timestamp"]
    }, separators=(',', ':'), sort_keys=True)
    
    # Verify
    signature = bytes.fromhex(receipt["signature"].replace("ed25519:", ""))
    verify_key = VerifyKey(public_key_bytes)
    try:
        verify_key.verify(payload.encode(), signature)
        return True
    except:
        return False

8. Security Considerations

8.1 Transport Security

Clients MUST:

Use HTTPS for key fetching
Verify TLS certificates
Reject connections with invalid certificates

8.2 Key Pinning

Organizations with strict security requirements MAY:

Pin specific keys in configuration
Verify key hashes match expected values
Alert on unexpected key changes

8.3 Offline Operation

For air-gapped environments:

Keys can be distributed out-of-band
Local key stores must be updated manually
Document key hashes for manual verification

9. Conformance

Implementations MUST:

Support the JSON schema defined in Section 3
Respect key status (reject revoked keys)
Use HTTPS for key fetching

Implementations SHOULD:

Cache keys appropriately
Handle key rotation gracefully
Log key refresh events

References

RFC 8037 - CFRG Elliptic Curve Signatures in JOSE
RFC 5785 - Defining Well-Known URIs
RFC 8410 - Algorithm Identifiers for Ed25519