verify.yaml

openapi: 3.1.1
info:
  title: PEAC Reference Verifier API
  version: 0.13.0
  summary: Portable signed records for agent, API, MCP, and cross-runtime interactions.
  description: |
    Package-level OpenAPI contract for the PEAC reference verifier (`apps/api/`).

    Requests and responses are exchanged as `application/json`. The `receipt`
    field in the request body is a compact JWS string whose JOSE header
    `typ` is `interaction-record+jwt` (Wire 0.2). The `receipt` field is not
    itself an HTTP media type; it is a payload carried inside the JSON body.

    `POST /v1/verify` returns the deterministic DD-210 verification report.
    Content negotiation on the `Accept` header chooses between the
    byte-identical `application/json` report, the extended
    `application/peac-report+json` (which adds `report_id`, `verified_at`,
    `duration_ms`, `key_resolution`, and `failure_reasons`), and a
    `text/plain` human-readable summary.

    Error responses use RFC 9457 Problem Details (`application/problem+json`)
    extended with PEAC-canonical fields (`peac_error_code`, `peac_trace_id`).

    The reference verifier also keeps a runtime-reachable `POST /verify`
    alias for callers that have not yet migrated. The alias is omitted
    from this contract because the canonical operation is
    `POST /v1/verify`. Every response on the alias carries RFC 9745
    `Deprecation`, RFC 8594 `Sunset`, and RFC 8288 `Link` headers; the
    alias is scheduled for runtime removal no earlier than 2026-11-01
    and is documented in `docs/HOSTED_VERIFY_CONTRACT.md`.

    Size caps (enforced by the kernel and verifier, documented here for
    contract completeness):
      - receipt JWS (request body): 256 KiB (262 144 bytes)
      - any single extension group: 64 KiB (65 536 bytes)
      - all extensions combined: 256 KiB (262 144 bytes)
  contact:
    name: PEAC Protocol
    url: https://www.peacprotocol.org
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0

servers:
  - url: http://localhost:3000
    description: Local development (self-hosted reference verifier)

tags:
  - name: Verify
    description: Verification endpoint (canonical).
  - name: Issue
    description: Hosted issue endpoints (alpha).
  - name: Health
    description: Issuer health and reference-verifier liveness.

paths:
  /v1/verify:
    post:
      operationId: verifyReceipt
      tags: [Verify]
      summary: Verify a signed interaction record
      description: |
        Verify a compact JWS interaction record. The request body is
        `application/json`; its `receipt` field is the compact JWS string.
        Returns a deterministic verification report (DD-210 shape).
        Supports caller-provided public key or allowlisted issuer JWKS
        resolution. Accepts three response formats via content negotiation.
      parameters:
        - name: Accept
          in: header
          required: false
          schema:
            type: string
            enum:
              - application/json
              - application/peac-report+json
              - text/plain
            default: application/json
          description: |
            `application/json` returns the byte-identical DD-210 report.
            `application/peac-report+json` adds `report_id`, `verified_at`,
            `duration_ms`, `key_resolution`, and `failure_reasons`.
            `text/plain` returns a human-readable summary.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyRequest'
            examples:
              wire_0_2_with_issuer_discovery:
                summary: Wire 0.2 receipt, issuer resolved via discovery
                description: >
                  `receipt` is a compact JWS whose JOSE header `typ` is
                  `interaction-record+jwt`. The HTTP request body itself is
                  `application/json`.
                value:
                  receipt: eyJ0eXAiOiJpbnRlcmFjdGlvbi1yZWNvcmQrand0IiwiYWxnIjoiRWREU0EiLCJraWQiOiIyMDI2LTA0LTE4In0.eyJpc3MiOiJodHRwczovL2FwaS5leGFtcGxlLmNvbSIsImlhdCI6MTc4MTYwOTYwMCwianRpIjoiMDE5Njc2ZDAtMDAwMC03MDAwLTgwMDAtMDAwMDAwMDAwMDAwIiwidHlwZSI6Im9yZy5wZWFjcHJvdG9jb2wvYXBpLXJlY2VpcHQiLCJwaWxsYXJzIjpbImFjY2VzcyJdLCJwZWFjX3ZlcnNpb24iOiIwLjIiLCJzY2hlbWEiOiJpbnRlcmFjdGlvbi1yZWNvcmQrand0In0.signature_bytes_placeholder
                  options:
                    strictness: strict
              wire_0_2_with_caller_public_key:
                summary: Wire 0.2 receipt, caller-provided Ed25519 public key
                description: >
                  `receipt` is a compact JWS; `public_key` bypasses JWKS
                  resolution. The HTTP request body itself is `application/json`.
                value:
                  receipt: eyJ0eXAiOiJpbnRlcmFjdGlvbi1yZWNvcmQrand0IiwiYWxnIjoiRWREU0EiLCJraWQiOiJkaWQ6a2V5OnoifQ.eyJpc3MiOiJkaWQ6a2V5OnoifQ.signature_bytes_placeholder
                  public_key: MCowBQYDK2VwAyEAGb9ECWmEzf6FQbrBZ9w7lshQhqowtrbLDFw4rXAxZuE
                  options:
                    strictness: interop
      responses:
        '200':
          description: Verification completed. Response body indicates verified/failed state.
          headers:
            PEAC-Report-Id:
              description: UUID v4 report identifier unique per response.
              schema:
                type: string
                format: uuid
            Content-Type:
              description: Selected response representation.
              schema:
                type: string
            X-Content-Type-Options:
              description: nosniff (always present).
              schema:
                type: string
                const: nosniff
            Cache-Control:
              description: no-store (always present).
              schema:
                type: string
                const: no-store
            Referrer-Policy:
              description: no-referrer (always present).
              schema:
                type: string
                const: no-referrer
            Vary:
              description: PEAC-Receipt (always present).
              schema:
                type: string
                const: PEAC-Receipt
            RateLimit-Limit:
              description: Maximum requests per window (RFC 9333-style).
              schema:
                type: string
            RateLimit-Remaining:
              description: Remaining requests in current window.
              schema:
                type: string
            RateLimit-Reset:
              description: Seconds until rate-limit window resets.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifySuccessResponse'
            application/peac-report+json:
              schema:
                $ref: '#/components/schemas/ExtendedVerifyReport'
            text/plain:
              schema:
                type: string
                description: Human-readable verification summary.
        '400':
          description: Invalid request format.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '413':
          description: Request body too large (receipt exceeds 256 KiB).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '422':
          description: Verification or validation failure (signature invalid, claims invalid, policy mismatch).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '429':
          description: Rate limit exceeded.
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '502':
          description: Upstream resolution failure (JWKS fetch, issuer config fetch).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'

  /v1/issue:
    post:
      operationId: issueReceipt
      tags: [Issue]
      summary: '[ALPHA] BYO-key hosted issue'
      description: |
        Provisional hosted issue endpoint (alpha). Disabled by default;
        operators enable via `PEAC_HOSTED_ISSUE=true`. The caller supplies
        the signing key; the service returns a compact JWS whose JOSE
        header `typ` is `interaction-record+jwt`. Rate-limited
        independently from verify. Semantics subject to change until GA.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IssueRequest'
      responses:
        '200':
          description: Signed receipt issued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IssueSuccessResponse'
        '400':
          description: Invalid request format.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Hosted issue disabled (`PEAC_HOSTED_ISSUE=false`).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '422':
          description: Validation failure.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'

  /v1/issuer-health:
    get:
      operationId: getIssuerHealth
      tags: [Health]
      summary: Check an issuer's discovery and JWKS availability
      description: |
        SSRF-safe issuer-health probe. Performs bounded HTTPS fetches of
        `/.well-known/peac-issuer.json` and the referenced `jwks_uri`.
        Private/loopback/reserved addresses are blocked; redirects are
        disabled; every fetch enforces an explicit timeout.
      parameters:
        - name: issuer
          in: query
          required: true
          description: Issuer URI (https-only, no private/loopback/reserved addresses).
          schema:
            type: string
            format: uri
            pattern: '^https://'
      responses:
        '200':
          description: Issuer discovery and JWKS resolution succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IssuerHealthResponse'
        '400':
          description: Invalid issuer parameter.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '502':
          description: Issuer discovery or JWKS fetch failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'

  /health:
    get:
      operationId: getLiveness
      tags: [Health]
      summary: Reference-verifier liveness check
      responses:
        '200':
          description: Reference verifier is live.
          content:
            application/json:
              schema:
                type: object
                required: [ok]
                properties:
                  ok:
                    type: boolean
                    const: true

components:
  schemas:
    VerifyRequest:
      type: object
      required: [receipt]
      additionalProperties: false
      description: |
        Request body for verification. `receipt` is a compact JWS string
        whose JOSE header `typ` is `interaction-record+jwt` (Wire 0.2)
        or `peac-receipt/0.1` (legacy Wire 0.1, verify-only).
      properties:
        receipt:
          type: string
          minLength: 1
          maxLength: 262144
          description: Compact JWS string. Maximum size 256 KiB (262 144 bytes).
          example: eyJ0eXAiOiJpbnRlcmFjdGlvbi1yZWNvcmQrand0IiwiYWxnIjoiRWREU0EiLCJraWQiOiIyMDI2LTA0LTE4In0...
        public_key:
          type: string
          minLength: 1
          description: |
            Optional base64url-encoded Ed25519 public key (32 bytes). When
            supplied, skips issuer discovery and JWKS resolution.
        policy:
          type: object
          additionalProperties: false
          description: Optional policy expectation. Used for `policy_binding` check.
          properties:
            uri:
              type: string
              format: uri
            version:
              type: string
        options:
          type: object
          additionalProperties: false
          properties:
            issuer:
              type: string
              format: uri
              description: Expected issuer URI for binding check.
            max_clock_skew:
              type: integer
              minimum: 1
              maximum: 3600
              description: Clock-skew tolerance in seconds (default 300).
            strictness:
              type: string
              enum: [strict, interop]
              description: Verification strictness mode. Default `strict`.

    VerifySuccessResponse:
      type: object
      required:
        - verified
        - receipt_ref
        - claims
        - warnings
        - policy_binding
        - issuer
        - kid
        - wire_version
      additionalProperties: false
      description: DD-210 deterministic verification report (byte-identical across runs).
      properties:
        verified:
          type: boolean
          description: Whether the receipt passed all verification checks.
        receipt_ref:
          type: string
          pattern: '^sha256:[a-f0-9]{64}$'
          description: SHA-256 of the compact JWS bytes (`sha256:<hex>`).
        claims:
          type: object
          description: Validated interaction-record claims.
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/VerificationWarning'
          description: Non-fatal verification warnings (W_* codes).
        policy_binding:
          type: string
          enum: [unavailable, verified, failed]
          description: Three-state policy-binding result (legacy mirror; equals bindings.policy when bindings is present).
        bindings:
          type: object
          description: >
            Optional top-level bindings object (v0.12.14). Present only when caller supplied
            bindings.terms or a non-empty bindings.documents to verifyLocal. Absent when no
            terms or document digests were supplied (byte-stable with v0.12.13). Report-only;
            not stamped into the emitted record or envelope shape.
          properties:
            policy:
              type: string
              enum: [unavailable, verified, failed]
            terms:
              type: object
              description: Per-representation terms-binding result when caller supplied a terms digest.
            documents:
              type: array
              description: Per-document binding results when caller supplied document digests.
        issuer:
          type: string
          description: Issuer URI from the receipt.
        kid:
          type: string
          description: Key ID from the JWS header.
        wire_version:
          type: string
          description: Wire format version (for example "0.2").

    VerificationWarning:
      type: object
      required: [code, message]
      additionalProperties: false
      properties:
        code:
          type: string
          description: Warning code (for example `W_UNREGISTERED_TYPE`).
        message:
          type: string
          description: Human-readable warning message.
        pointer:
          type: string
          description: RFC 6901 JSON Pointer to the problematic field.

    FailureReason:
      type: object
      required: [code, detail]
      additionalProperties: false
      properties:
        code:
          type: string
          description: Kernel error code (for example `E_INVALID_SIGNATURE`).
        detail:
          type: string
          description: Human-readable failure reason.

    ExtendedVerifyReport:
      type: object
      required:
        - report_id
        - verified
        - verified_at
        - duration_ms
        - receipt_ref
        - key_resolution
        - failure_reasons
      additionalProperties: false
      description: |
        Extended verification report with timing, report ID, key-resolution
        method, and failure reasons. Returned when `Accept` contains
        `application/peac-report+json`.
      properties:
        report_id:
          type: string
          format: uuid
        verified:
          type: boolean
        verified_at:
          type: string
          format: date-time
        duration_ms:
          type: number
        receipt_ref:
          type: string
          pattern: '^sha256:[a-f0-9]{64}$'
        claims:
          type: object
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/VerificationWarning'
        policy_binding:
          type: string
          enum: [unavailable, verified, failed]
        bindings:
          type: object
          description: >
            Optional top-level bindings object (v0.12.14). Present only when caller supplied
            bindings.terms or a non-empty bindings.documents to verifyLocal. Absent when no
            terms or document digests were supplied (byte-stable with v0.12.13). Report-only;
            not stamped into the emitted record or envelope shape.
          properties:
            policy:
              type: string
              enum: [unavailable, verified, failed]
            terms:
              type: object
              description: Per-representation terms-binding result when caller supplied a terms digest.
            documents:
              type: array
              description: Per-document binding results when caller supplied document digests.
        issuer:
          type: string
        kid:
          type: string
        wire_version:
          type: string
        key_resolution:
          type: string
          enum: [provided, allowlist, discovery]
        failure_reasons:
          type: array
          items:
            $ref: '#/components/schemas/FailureReason'

    IssueRequest:
      type: object
      required: [claims, signing_key]
      additionalProperties: false
      properties:
        claims:
          type: object
          description: Interaction-record claims object (Wire 0.2).
        signing_key:
          type: string
          description: Base64url-encoded Ed25519 private key (32 bytes). Caller-custody only.
        kid:
          type: string
          description: Key identifier to embed in the JWS header.

    IssueSuccessResponse:
      type: object
      required: [receipt, receipt_ref, kid, wire_version]
      additionalProperties: false
      properties:
        receipt:
          type: string
          description: Signed compact JWS (JOSE header `typ` is `interaction-record+jwt`).
        receipt_ref:
          type: string
          pattern: '^sha256:[a-f0-9]{64}$'
        kid:
          type: string
        wire_version:
          type: string

    IssuerHealthResponse:
      type: object
      required: [issuer, discovery_ok, jwks_ok, duration_ms]
      additionalProperties: false
      properties:
        issuer:
          type: string
          format: uri
        discovery_ok:
          type: boolean
          description: Whether `/.well-known/peac-issuer.json` resolved.
        jwks_ok:
          type: boolean
          description: Whether the referenced `jwks_uri` resolved and parsed.
        jwks_uri:
          type: string
          format: uri
        duration_ms:
          type: number
        warnings:
          type: array
          items:
            type: string

    ProblemDetails:
      type: object
      required: [type, title, status, detail, peac_error_code]
      additionalProperties: true
      description: |
        RFC 9457 Problem Details with PEAC extensions. Returned with
        `Content-Type: application/problem+json` on any error response.
      properties:
        type:
          type: string
          format: uri
          description: Problem-type URI under `https://www.peacprotocol.org/problems/`.
        title:
          type: string
          description: Short human-readable summary of the problem type.
        status:
          type: integer
          description: HTTP status code for this occurrence.
        detail:
          type: string
          description: Human-readable explanation specific to this occurrence.
        instance:
          type: string
          description: URI reference identifying the specific occurrence.
        peac_error_code:
          type: string
          description: Kernel-canonical error code (for example `E_INVALID_FORMAT`).
        peac_trace_id:
          type: string
          description: Request trace identifier.
        errors:
          type: array
          description: Multi-error details for validation failures.
          items:
            type: object
            required: [pointer, detail]
            additionalProperties: false
            properties:
              pointer:
                type: string
                description: RFC 6901 JSON Pointer.
              detail:
                type: string
                description: Field-level error detail.