openapi: 3.1.0
info:
  title: StellaOps Proof Chain API
  version: 1.0.0
  description: |
    API for proof chain operations including proof spine creation, verification receipts,
    VEX attestations, and trust anchor management.

    The proof chain provides cryptographic evidence linking SBOM entries to vulnerability
    assessments through attestable DSSE envelopes.

  license:
    name: AGPL-3.0-or-later
    url: https://www.gnu.org/licenses/agpl-3.0.html

servers:
  - url: https://api.stellaops.dev/v1
    description: Production API
  - url: http://localhost:5000/v1
    description: Local development

tags:
  - name: Proofs
    description: Proof spine and receipt operations
  - name: Anchors
    description: Trust anchor management
  - name: Verify
    description: Proof verification endpoints

paths:
  /proofs/{entry}/spine:
    post:
      operationId: createProofSpine
      summary: Create proof spine for SBOM entry
      description: |
        Assembles a merkle-rooted proof spine from evidence, reasoning, and VEX verdict
        for an SBOM entry. Returns a content-addressed proof bundle ID.
      tags: [Proofs]
      security:
        - bearerAuth: []
        - mtls: []
      parameters:
        - name: entry
          in: path
          required: true
          schema:
            type: string
            pattern: '^sha256:[a-f0-9]{64}:pkg:.+'
          description: SBOMEntryID in format sha256:<hash>:pkg:<purl>
          example: "sha256:abc123...def:pkg:npm/lodash@4.17.21"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSpineRequest'
      responses:
        '201':
          description: Proof spine created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateSpineResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'

    get:
      operationId: getProofSpine
      summary: Get proof spine for SBOM entry
      description: Retrieves the existing proof spine for an SBOM entry.
      tags: [Proofs]
      security:
        - bearerAuth: []
      parameters:
        - name: entry
          in: path
          required: true
          schema:
            type: string
            pattern: '^sha256:[a-f0-9]{64}:pkg:.+'
          description: SBOMEntryID
      responses:
        '200':
          description: Proof spine retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProofSpineDto'
        '404':
          $ref: '#/components/responses/NotFound'

  /proofs/{entry}/receipt:
    get:
      operationId: getProofReceipt
      summary: Get verification receipt
      description: |
        Retrieves a verification receipt for the SBOM entry's proof spine.
        The receipt includes merkle proof paths and signature verification status.
      tags: [Proofs]
      security:
        - bearerAuth: []
      parameters:
        - name: entry
          in: path
          required: true
          schema:
            type: string
            pattern: '^sha256:[a-f0-9]{64}:pkg:.+'
          description: SBOMEntryID
      responses:
        '200':
          description: Verification receipt
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationReceiptDto'
        '404':
          $ref: '#/components/responses/NotFound'

  /proofs/{entry}/vex:
    get:
      operationId: getProofVex
      summary: Get VEX attestation for entry
      description: Retrieves the VEX verdict attestation for the SBOM entry.
      tags: [Proofs]
      security:
        - bearerAuth: []
      parameters:
        - name: entry
          in: path
          required: true
          schema:
            type: string
            pattern: '^sha256:[a-f0-9]{64}:pkg:.+'
          description: SBOMEntryID
      responses:
        '200':
          description: VEX attestation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VexAttestationDto'
        '404':
          $ref: '#/components/responses/NotFound'

  /anchors:
    get:
      operationId: listAnchors
      summary: List trust anchors
      description: Lists all configured trust anchors with their status.
      tags: [Anchors]
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of trust anchors
          content:
            application/json:
              schema:
                type: object
                properties:
                  anchors:
                    type: array
                    items:
                      $ref: '#/components/schemas/TrustAnchorDto'

    post:
      operationId: createAnchor
      summary: Create trust anchor
      description: Creates a new trust anchor with the specified public key.
      tags: [Anchors]
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAnchorRequest'
      responses:
        '201':
          description: Trust anchor created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrustAnchorDto'
        '400':
          $ref: '#/components/responses/BadRequest'
        '409':
          description: Anchor already exists

  /anchors/{anchorId}:
    get:
      operationId: getAnchor
      summary: Get trust anchor
      description: Retrieves a specific trust anchor by ID.
      tags: [Anchors]
      security:
        - bearerAuth: []
      parameters:
        - name: anchorId
          in: path
          required: true
          schema:
            type: string
          description: Trust anchor ID
      responses:
        '200':
          description: Trust anchor details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrustAnchorDto'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      operationId: deleteAnchor
      summary: Delete trust anchor
      description: Deletes a trust anchor (soft delete, marks as revoked).
      tags: [Anchors]
      security:
        - bearerAuth: []
      parameters:
        - name: anchorId
          in: path
          required: true
          schema:
            type: string
          description: Trust anchor ID
      responses:
        '204':
          description: Anchor deleted
        '404':
          $ref: '#/components/responses/NotFound'

  /verify:
    post:
      operationId: verifyProofBundle
      summary: Verify proof bundle
      description: |
        Performs full verification of a proof bundle including:
        - DSSE signature verification
        - Content-addressed ID recomputation
        - Merkle path verification
        - Optional Rekor inclusion proof verification
      tags: [Verify]
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyRequest'
      responses:
        '200':
          description: Verification result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationResultDto'
        '400':
          $ref: '#/components/responses/BadRequest'

  /verify/batch:
    post:
      operationId: verifyBatch
      summary: Verify multiple proof bundles
      description: Performs batch verification of multiple proof bundles.
      tags: [Verify]
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - bundles
              properties:
                bundles:
                  type: array
                  items:
                    $ref: '#/components/schemas/VerifyRequest'
                  maxItems: 100
      responses:
        '200':
          description: Batch verification results
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/VerificationResultDto'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Authority-issued OpToken
    mtls:
      type: mutualTLS
      description: Mutual TLS with client certificate

  schemas:
    CreateSpineRequest:
      type: object
      required:
        - evidenceIds
        - reasoningId
        - vexVerdictId
        - policyVersion
      properties:
        evidenceIds:
          type: array
          description: Content-addressed IDs of evidence statements
          items:
            type: string
            pattern: '^sha256:[a-f0-9]{64}$'
          minItems: 1
          example: ["sha256:e7f8a9b0c1d2..."]
        reasoningId:
          type: string
          pattern: '^sha256:[a-f0-9]{64}$'
          description: Content-addressed ID of reasoning statement
          example: "sha256:f0e1d2c3b4a5..."
        vexVerdictId:
          type: string
          pattern: '^sha256:[a-f0-9]{64}$'
          description: Content-addressed ID of VEX verdict statement
          example: "sha256:d4c5b6a7e8f9..."
        policyVersion:
          type: string
          pattern: '^v[0-9]+\.[0-9]+\.[0-9]+$'
          description: Version of the policy used
          example: "v1.2.3"

    CreateSpineResponse:
      type: object
      required:
        - proofBundleId
      properties:
        proofBundleId:
          type: string
          pattern: '^sha256:[a-f0-9]{64}$'
          description: Content-addressed ID of the created proof bundle (merkle root)
          example: "sha256:1a2b3c4d5e6f..."
        receiptUrl:
          type: string
          format: uri
          description: URL to retrieve the verification receipt
          example: "/proofs/sha256:abc:pkg:npm/lodash@4.17.21/receipt"

    ProofSpineDto:
      type: object
      required:
        - sbomEntryId
        - proofBundleId
        - evidenceIds
        - reasoningId
        - vexVerdictId
        - policyVersion
        - createdAt
      properties:
        sbomEntryId:
          type: string
          description: The SBOM entry this spine covers
        proofBundleId:
          type: string
          description: Merkle root hash of the proof bundle
        evidenceIds:
          type: array
          items:
            type: string
          description: Sorted list of evidence IDs
        reasoningId:
          type: string
          description: Reasoning statement ID
        vexVerdictId:
          type: string
          description: VEX verdict statement ID
        policyVersion:
          type: string
          description: Policy version used
        createdAt:
          type: string
          format: date-time
          description: Creation timestamp (UTC ISO-8601)

    VerificationReceiptDto:
      type: object
      required:
        - graphRevisionId
        - findingKey
        - decision
        - createdAt
        - verified
      properties:
        graphRevisionId:
          type: string
          description: Graph revision ID this receipt was computed from
        findingKey:
          type: object
          properties:
            sbomEntryId:
              type: string
            vulnerabilityId:
              type: string
        rule:
          type: object
          properties:
            id:
              type: string
            version:
              type: string
        decision:
          type: object
          properties:
            verdict:
              type: string
              enum: [pass, fail, warn, skip]
            severity:
              type: string
            reasoning:
              type: string
        createdAt:
          type: string
          format: date-time
        verified:
          type: boolean
          description: Whether the receipt signature verified correctly

    VexAttestationDto:
      type: object
      required:
        - sbomEntryId
        - vulnerabilityId
        - status
        - vexVerdictId
      properties:
        sbomEntryId:
          type: string
        vulnerabilityId:
          type: string
        status:
          type: string
          enum: [not_affected, affected, fixed, under_investigation]
        justification:
          type: string
        policyVersion:
          type: string
        reasoningId:
          type: string
        vexVerdictId:
          type: string

    TrustAnchorDto:
      type: object
      required:
        - id
        - keyId
        - algorithm
        - status
        - createdAt
      properties:
        id:
          type: string
          description: Unique anchor identifier
        keyId:
          type: string
          description: Key identifier (fingerprint)
        algorithm:
          type: string
          enum: [ECDSA-P256, Ed25519, RSA-2048, RSA-4096]
          description: Signing algorithm
        publicKey:
          type: string
          description: PEM-encoded public key
        status:
          type: string
          enum: [active, revoked, expired]
        createdAt:
          type: string
          format: date-time
        revokedAt:
          type: string
          format: date-time

    CreateAnchorRequest:
      type: object
      required:
        - keyId
        - algorithm
        - publicKey
      properties:
        keyId:
          type: string
          description: Key identifier
        algorithm:
          type: string
          enum: [ECDSA-P256, Ed25519, RSA-2048, RSA-4096]
        publicKey:
          type: string
          description: PEM-encoded public key

    VerifyRequest:
      type: object
      required:
        - proofBundleId
      properties:
        proofBundleId:
          type: string
          pattern: '^sha256:[a-f0-9]{64}$'
          description: The proof bundle ID to verify
        checkRekor:
          type: boolean
          default: true
          description: Whether to verify Rekor inclusion proofs
        anchorIds:
          type: array
          items:
            type: string
          description: Specific trust anchors to use for verification

    VerificationResultDto:
      type: object
      required:
        - proofBundleId
        - verified
        - checks
      properties:
        proofBundleId:
          type: string
        verified:
          type: boolean
          description: Overall verification result
        checks:
          type: object
          properties:
            signatureValid:
              type: boolean
              description: DSSE signature verification passed
            idRecomputed:
              type: boolean
              description: Content-addressed IDs recomputed correctly
            merklePathValid:
              type: boolean
              description: Merkle path verification passed
            rekorInclusionValid:
              type: boolean
              description: Rekor inclusion proof verified (if checked)
        errors:
          type: array
          items:
            type: string
          description: Error messages if verification failed
        verifiedAt:
          type: string
          format: date-time

  responses:
    BadRequest:
      description: Invalid request
      content:
        application/problem+json:
          schema:
            type: object
            properties:
              title:
                type: string
              detail:
                type: string
              status:
                type: integer
                example: 400

    NotFound:
      description: Resource not found
      content:
        application/problem+json:
          schema:
            type: object
            properties:
              title:
                type: string
              detail:
                type: string
              status:
                type: integer
                example: 404

    ValidationError:
      description: Validation error
      content:
        application/problem+json:
          schema:
            type: object
            properties:
              title:
                type: string
              detail:
                type: string
              status:
                type: integer
                example: 422
              errors:
                type: object
                additionalProperties:
                  type: array
                  items:
                    type: string