TG-RECEIPT-SCHEMA

Abstract

This document specifies the schema for TrigGuard Execution Receipts. Receipts are cryptographically signed records of authorization decisions that can be stored, transmitted, and verified independently of the TrigGuard service.

1. Overview

An Execution Receipt is a self-contained, tamper-evident record of an authorization decision. Receipts serve as:

• Proof of authorization: Evidence that execution was approved
• Audit trail: Immutable record for compliance
• Verification artifact: Can be verified offline

2. Receipt Structure

2.1 JSON Schema

{
 "$schema": "http://json-schema.org/draft-07/schema#",
 "$id": "https://trigguardai.com/schemas/receipt.json",
 "title": "TrigGuard Execution Receipt",
 "type": "object",
 "required": [
 "receipt_id",
 "decision",
 "timestamp",
 "surface",
 "signature",
 "key_id"
 ],
 "properties": {
 "receipt_id": {
 "type": "string",
 "pattern": "^rcpt_[a-f0-9]+$"
 },
 "decision": {
 "type": "string",
 "enum": ["PERMIT", "DENY", "SILENCE"]
 },
 "timestamp": {
 "type": "string",
 "format": "date-time"
 },
 "expires_at": {
 "type": "string",
 "format": "date-time"
 },
 "surface": {
 "type": "string",
 "pattern": "^[a-z]+\\.[a-z]+$"
 },
 "context_hash": {
 "type": "string",
 "pattern": "^sha256:[a-f0-9]{64}$"
 },
 "signature": {
 "type": "string",
 "pattern": "^ed25519:[a-f0-9]+$"
 },
 "key_id": {
 "type": "string",
 "pattern": "^tg_[a-z]+_[0-9]+$"
 }
 }
}

3. Field Definitions

3.1 receipt_id

The receipt ID is a globally unique identifier assigned at receipt creation. IDs are generated using cryptographically secure random bytes.

3.2 decision

3.3 timestamp

3.4 context_hash

The context hash links the receipt to the original request without exposing context details.

4. Signature Computation

4.1 Payload Construction

The signature is computed over a canonical JSON payload:

{
 "receipt_id": "<receipt_id>",
 "decision": "<decision>",
 "timestamp": "<timestamp>",
 "surface": "<surface>",
 "context_hash": "<context_hash>"
}

4.2 Canonicalization Rules

1. Keys MUST be sorted alphabetically
2. No whitespace between tokens
3. Unicode characters MUST NOT be escaped
4. Numbers MUST NOT have trailing zeros
5. Encoding MUST be UTF-8

4.3 Canonical Payload Example

Receipt:

{
 "receipt_id": "rcpt_92a71f",
 "decision": "PERMIT",
 "timestamp": "2026-03-13T14:22:00.000Z",
 "surface": "deploy.release",
 "context_hash": "sha256:e3b0c442..."
}

Canonical payload (single line, sorted keys):

{"context_hash":"sha256:e3b0c442...","decision":"PERMIT","receipt_id":"rcpt_92a71f","surface":"deploy.release","timestamp":"2026-03-13T14:22:00.000Z"}

4.4 Signature Algorithm

1. Construct canonical payload (UTF-8 bytes)
2. Sign with Ed25519 private key
3. Encode signature as hexadecimal
4. Prepend ed25519: prefix

5. Receipt Processing

5.1 Creation (Server)

1. Generate receipt_id
2. Record timestamp (UTC)
3. Hash request context
4. Construct canonical payload
5. Sign with Ed25519
6. Return complete receipt

5.2 Verification (Client)

1. Parse receipt JSON
2. Validate required fields
3. Construct canonical payload
4. Fetch public key by key_id
5. Verify Ed25519 signature
6. Check expiration (if present)
7. Accept or reject receipt

5.3 Storage

Receipts SHOULD be stored:

• In deployment records
• In CI/CD logs
• In audit systems

Receipts MUST NOT be modified after creation.

6. Examples

6.1 PERMIT Receipt

{
 "receipt_id": "rcpt_7f3a9c2b1d4e",
 "decision": "PERMIT",
 "timestamp": "2026-03-13T14:22:00.000Z",
 "expires_at": "2026-03-13T14:32:00.000Z",
 "surface": "deploy.release",
 "context_hash": "sha256:e3b0c442...",
 "signature": "ed25519:af39c8e7b2d1f4a6...",
 "key_id": "tg_prod_01"
}

6.2 DENY Receipt

{
 "receipt_id": "rcpt_5e2b8d1a",
 "decision": "DENY",
 "timestamp": "2026-03-13T15:45:00.000Z",
 "surface": "infra.apply",
 "context_hash": "sha256:d7a8fbb3...",
 "signature": "ed25519:1a2b3c4d5e6f...",
 "key_id": "tg_prod_01"
}

7. Security Considerations

7.1 Receipt Confidentiality

Receipts do not expose request context. The context_hash allows verification that a receipt corresponds to a specific request without revealing details.

7.2 Replay Prevention

Systems SHOULD:

• Track processed receipt IDs
• Reject duplicate receipts
• Use expiration times for time-sensitive operations

8. Conformance

Implementations MUST:

• Accept all required fields
• Reject receipts with invalid signatures
• Support Ed25519 verification
• Handle missing optional fields gracefully

Implementations SHOULD:

• Cache public keys
• Validate receipt schema before verification
• Log verification results for audit