openapi: 3.1.0
info:
  title: TrigGuard Execution Authorization API
  version: "1.0.0"
  description: |
    Authorization protocol for system execution surfaces.

    TrigGuard evaluates requests before irreversible work proceeds, returning deterministic
    decisions (PERMIT, DENY, SILENCE) with cryptographically signed receipts where applicable.
  contact:
    email: security@trigguardai.com
  license:
    name: Proprietary
    url: https://www.trigguardai.com/terms

servers:
  - url: https://api.trigguardai.com/v1
    description: Production API

security:
  - BearerAuth: []

paths:
  /execute:
    post:
      operationId: executeAuthorization
      summary: Request execution authorization
      description: |
        Submit an authorization request for a system execution surface.
        Returns a signed receipt containing the authorization decision when evaluation completes.
      tags:
        - Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExecuteRequest'
            example:
              surface: "deploy.release"
              metadata:
                environment: "production"
                service: "api-gateway"
                version: "2.4.1"
              request_id: "req_a1b2c3d4"
      responses:
        '200':
          description: Authorization decision returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecuteResponse'
              examples:
                permit:
                  summary: PERMIT — execution authorized
                  value:
                    decision: "PERMIT"
                    enforcement: "EXECUTED"
                    receipt_id: "tgr_92a71f3b"
                    surface: "deploy.release"
                    timestamp: "2026-03-13T14:22:00.000Z"
                    signature: "ed25519:YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXo..."
                    key_id: "tgk_2026_q1"
                    policy_id: "pol_prod_deploy"
                deny:
                  summary: DENY — execution refused
                  value:
                    decision: "DENY"
                    enforcement: "BLOCKED"
                    receipt_id: "tgr_deny_8x2k"
                    surface: "deploy.release"
                    timestamp: "2026-03-13T14:22:00.000Z"
                    signature: "ed25519:eHl6YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd..."
                    key_id: "tgk_2026_q1"
                    policy_id: "pol_prod_deploy"
                    reason_code: "POLICY_VIOLATION"
                silence:
                  summary: SILENCE — evaluation indeterminate (fail-closed)
                  value:
                    decision: "SILENCE"
                    enforcement: "BLOCKED"
                    receipt_id: "tgr_silence_9m1q"
                    surface: "deploy.release"
                    timestamp: "2026-03-13T14:22:00.000Z"
                    signature: "ed25519:Zm9vYmFyYmF6cXV4c3R1dnd4eXo..."
                    key_id: "tgk_2026_q1"
                    policy_id: "pol_prod_deploy"
                    reason_code: "INDETERMINATE_EVALUATION"
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /.well-known/trigguard-keys.json:
    get:
      operationId: getVerificationKeys
      summary: Retrieve public keys for receipt verification
      description: |
        Returns the public keys used to verify execution receipt signatures.
        Keys are Ed25519 public keys encoded in base64.

        This endpoint is publicly accessible and does not require authentication.
        Clients should cache keys locally and refresh periodically.
      tags:
        - Verification
      security: []
      responses:
        '200':
          description: Public keys returned
          headers:
            Cache-Control:
              schema:
                type: string
              example: "public, max-age=3600"
            Access-Control-Allow-Origin:
              schema:
                type: string
              example: "*"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeysResponse'
              example:
                keys:
                  - id: "tgk_2026_q1"
                    algorithm: "Ed25519"
                    public_key: "MCowBQYDK2VwAyEA..."
                    created_at: "2026-01-01T00:00:00Z"
                  - id: "tgk_2025_q4"
                    algorithm: "Ed25519"
                    public_key: "MCowBQYDK2VwAyEA..."
                    created_at: "2025-10-01T00:00:00Z"
                    expires_at: "2026-04-01T00:00:00Z"

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: API key obtained from TrigGuard dashboard

  schemas:
    ExecuteRequest:
      type: object
      required:
        - surface
      properties:
        surface:
          type: string
          description: Execution surface identifier
          example: "deploy.release"
        actor:
          type: string
          description: Identity of the executing actor (e.g. agent.billing, support-agent). Optional; enables policy by who is executing.
          example: "agent.billing"
        metadata:
          type: object
          description: Context about the execution request
          additionalProperties: true
          example:
            environment: "production"
            service: "api-gateway"
        request_id:
          type: string
          description: Client-generated idempotency key
          example: "req_a1b2c3d4"

    ExecuteResponse:
      type: object
      required:
        - decision
        - enforcement
        - receipt_id
        - surface
        - timestamp
        - signature
        - key_id
      properties:
        decision:
          type: string
          enum:
            - PERMIT
            - DENY
            - SILENCE
          description: Deterministic decision on the evaluation layer (never BLOCK; BLOCK is enforcement-only).
        enforcement:
          type: string
          enum:
            - EXECUTED
            - BLOCKED
          description: Runtime outcome. DENY and SILENCE yield BLOCKED; PERMIT yields EXECUTED when downstream work proceeds under a verified receipt.
        receipt_id:
          type: string
          description: Unique receipt identifier
          example: "tgr_92a71f3b"
        surface:
          type: string
          description: Execution surface that was evaluated
          example: "deploy.release"
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 timestamp of the decision
        signature:
          type: string
          description: Ed25519 signature over the canonical receipt payload
          example: "ed25519:YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXo..."
        key_id:
          type: string
          description: ID of the key used to sign the receipt
          example: "tgk_2026_q1"
        policy_id:
          type: string
          description: Policy that produced this decision
          example: "pol_prod_deploy"
        reason_code:
          type: string
          description: Deterministic reason code (present on DENY and SILENCE)
          example: "POLICY_VIOLATION"

    KeysResponse:
      type: object
      required:
        - keys
      properties:
        keys:
          type: array
          items:
            $ref: '#/components/schemas/PublicKey'

    PublicKey:
      type: object
      required:
        - id
        - algorithm
        - public_key
        - created_at
      properties:
        id:
          type: string
          description: Key identifier referenced in receipts
          example: "tgk_2026_q1"
        algorithm:
          type: string
          enum:
            - Ed25519
          description: Signature algorithm
        public_key:
          type: string
          description: Base64-encoded public key
          example: "MCowBQYDK2VwAyEA..."
        created_at:
          type: string
          format: date-time
          description: Key creation timestamp
        expires_at:
          type: string
          format: date-time
          description: Optional key expiration timestamp

    Error:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
          description: Error code
          example: "invalid_request"
        message:
          type: string
          description: Human-readable error message
          example: "Missing required field: surface"

tags:
  - name: Authorization
    description: Request execution authorization and receive signed receipts
  - name: Verification
    description: Retrieve public keys for offline receipt verification