# Experimental transparency log endpoints (planned future work).
# These endpoints are NOT part of the current specification.
# Conformant implementations MUST NOT expose or depend on them.
# This file exists to capture the intended design direction.
# See roadmap.md for the full feature index.

openapi: 3.1.0
info:
  title: "#trstd <protocol> - Transparency Log API (experimental)"
  version: "0.0.0-experimental"
  description: >
    Experimental transparency log endpoints for the #trstd <protocol>.
    These endpoints are non-normative and MUST NOT be implemented today.
    The design captures the intended direction for public auditability
    but carries no requirements until the trust model, Merkle tree
    construction, and consistency proof mechanisms are fully specified.
  contact:
    name: trstd Working Group
    url: https://example.org
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0

servers:
  - url: https://trust-authority.example.org/v1
    description: Trust Authority (production)

paths:
  /log/head:
    get:
      operationId: getLogHead
      summary: Get the latest transparency log head
      description: >
        Returns the current Merkle tree root hash and tree size.
      security: []
      responses:
        "200":
          description: Current log head
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LogHead"

  /log/entries:
    get:
      operationId: getLogEntries
      summary: Get transparency log entries
      description: >
        Returns log entries within the specified index range.
      security: []
      parameters:
        - name: start
          in: query
          required: true
          description: Start index (inclusive)
          schema:
            type: integer
            minimum: 0
        - name: end
          in: query
          required: true
          description: End index (exclusive)
          schema:
            type: integer
            minimum: 0
      responses:
        "200":
          description: Log entries within the specified range
          content:
            application/json:
              schema:
                type: object
                required:
                  - entries
                properties:
                  entries:
                    type: array
                    items:
                      $ref: "#/components/schemas/LogEntry"
        "400":
          description: Invalid range parameters
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /log/entries/{responseHash}/proof:
    get:
      operationId: getInclusionProof
      summary: Get a Merkle inclusion proof
      description: >
        Returns an inclusion proof for the log entry identified by its
        canonical response hash.
      security: []
      parameters:
        - name: responseHash
          in: path
          required: true
          description: Hash of the canonical (JCS) response body (hex-encoded)
          schema:
            type: string
        - name: hashAlgorithm
          in: query
          required: false
          description: Hash algorithm used (IANA Hash Function Textual Names registry). Defaults to sha-256.
          schema:
            type: [string, "null"]
            default: "sha-256"
        - name: treeSize
          in: query
          required: true
          description: Tree size to compute the proof against
          schema:
            type: integer
            minimum: 1
      responses:
        "200":
          description: Inclusion proof
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InclusionProof"
        "404":
          description: Hash not found in the log
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /log/responses/{responseId}:
    get:
      operationId: getResponseLog
      summary: Look up log entry by response ID
      description: >
        Returns the log entry for a specific verify response, including
        the responseHash.
      security: []
      parameters:
        - name: responseId
          in: path
          required: true
          description: UUID of the verify response to look up
          schema:
            type: string
            format: uuid
            example: "f47ac10b-58cc-4372-a567-0e02b2c3d479"
      responses:
        "200":
          description: Log entry for the specified response
          content:
            application/json:
              schema:
                type: object
                required:
                  - responseId
                  - responseHash
                  - hashAlgorithm
                  - timestamp
                properties:
                  responseId:
                    type: string
                    format: uuid
                    description: The queried response ID
                  responseHash:
                    type: string
                    description: Hash of the canonical (JCS) response body (hex-encoded)
                    example: "a3f2b8c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0"
                  hashAlgorithm:
                    type: string
                    description: Hash algorithm used (IANA Hash Function Textual Names registry)
                    example: "sha-256"
                  timestamp:
                    type: string
                    format: date-time
                    description: When this entry was logged. RFC 3339 with mandatory UTC (Z suffix).
        "404":
          description: Response ID not found in the log
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /log/responses/{responseId}/data:
    get:
      operationId: getResponseData
      summary: Get full response data by response ID
      description: >
        Returns the full response body (excluding the signature field) as
        stored at issuance time. Requires authentication.
      security:
        - didWebJwt: []
      parameters:
        - name: responseId
          in: path
          required: true
          description: UUID of the verify response to look up
          schema:
            type: string
            format: uuid
            example: "f47ac10b-58cc-4372-a567-0e02b2c3d479"
      responses:
        "200":
          description: Full response data for the specified response
          content:
            application/json:
              schema:
                type: object
                required:
                  - responseId
                  - responseHash
                  - hashAlgorithm
                  - responseData
                  - timestamp
                properties:
                  responseId:
                    type: string
                    format: uuid
                    description: The queried response ID
                  responseHash:
                    type: string
                    description: Hash of the canonical (JCS) response body (hex-encoded)
                  hashAlgorithm:
                    type: string
                    description: Hash algorithm used (IANA Hash Function Textual Names registry)
                    example: "sha-256"
                  responseData:
                    type: object
                    description: The full response body excluding the signature field, as stored at issuance time
                    additionalProperties: true
                  timestamp:
                    type: string
                    format: date-time
                    description: When this entry was logged. RFC 3339 with mandatory UTC (Z suffix).
        "401":
          description: Missing, expired, or invalid JWT
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Response ID not found in the log
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

components:
  securitySchemes:
    didWebJwt:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        A signed JWT with the agent's did:web identifier as the iss claim.
        DID resolution and JWT verification follow the TSAI protocol
        (https://github.com/awslabs/tsai-protocol).

  schemas:
    LogHead:
      type: object
      required:
        - treeSize
        - rootHash
        - hashAlgorithm
        - timestamp
      properties:
        treeSize:
          type: integer
          description: Current number of entries in the log
          example: 48231
        rootHash:
          type: string
          description: Merkle tree root hash (hex-encoded)
          example: "a3f2b8c1d4e5f6..."
        hashAlgorithm:
          type: string
          description: Hash algorithm used (IANA Hash Function Textual Names registry)
          example: "sha-256"
        timestamp:
          type: string
          format: date-time
          description: When this log head was computed. RFC 3339 with mandatory UTC (Z suffix).
          example: "2026-03-20T11:00:00Z"

    LogEntry:
      type: object
      description: >
        An append-only record of a verify response served by the authority.
        Each entry captures what the authority returned at a point in time.
        Lifecycle changes (updates, revocations) are visible by comparing
        successive entries for the same entity — no explicit action field
        is needed.
      required:
        - timestamp
        - responseId
        - entityId
        - responseHash
        - hashAlgorithm
      properties:
        timestamp:
          type: string
          format: date-time
          description: When the entry was logged. RFC 3339 with mandatory UTC (Z suffix).
        responseId:
          type: string
          format: uuid
          description: The verify response that produced this log entry
        entityId:
          type: string
          description: The entity identifier
        responseHash:
          type: string
          description: Hash of the canonical (JCS / RFC 8785) response body excluding the signature field (hex-encoded)
        hashAlgorithm:
          type: string
          description: Hash algorithm used for responseHash (IANA Hash Function Textual Names registry)
          example: "sha-256"

    InclusionProof:
      type: object
      required:
        - leafIndex
        - treeSize
        - hashes
        - hashAlgorithm
      properties:
        leafIndex:
          type: integer
          description: Index of the leaf in the Merkle tree
        treeSize:
          type: integer
          description: Tree size the proof was computed against
        hashes:
          type: array
          items:
            type: string
          description: Merkle path hashes (hex-encoded) from leaf to root
        hashAlgorithm:
          type: string
          description: Hash algorithm used for the Merkle tree (IANA Hash Function Textual Names registry)
          example: "sha-256"

    ErrorResponse:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
          description: Machine-readable error code
        message:
          type: string
          description: Human-readable error description
