openapi: 3.0.3
info:
  title: Stella Ops Gates API
  description: |
    Gate check API for unknowns queue integration.
    
    Sprint: SPRINT_20260118_018_Unknowns_queue_enhancement (UQ-006)
    
    ## Overview
    
    The Gates API provides endpoints to check if a component can pass through
    the release gate based on its unknowns status. It implements fail-closed
    semantics by default for HOT unknowns.
    
    ## Gate Decisions
    
    - **pass**: No blocking unknowns, component may proceed
    - **warn**: Non-blocking unknowns present, proceed with caution
    - **block**: HOT unknowns, KEV items, or SLA breaches require resolution
    
  version: 1.0.0
  contact:
    name: Stella Ops Team
  license:
    name: BUSL-1.1

servers:
  - url: /api/v1
    description: API v1

tags:
  - name: Gates
    description: Gate check operations for unknowns

paths:
  /gates/{bom_ref}:
    get:
      operationId: getGateStatus
      tags: [Gates]
      summary: Get gate check result for a component
      description: |
        Returns the current unknowns state and gate decision for a BOM reference.
        Results are cached for 30 seconds.
      parameters:
        - name: bom_ref
          in: path
          required: true
          description: URL-encoded BOM reference (PURL)
          schema:
            type: string
          example: pkg%3Anpm%2Flodash%404.17.21
      responses:
        '200':
          description: Gate status retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GateStatusResponse'
        '500':
          description: Internal server error

  /gates/{bom_ref}/check:
    post:
      operationId: checkGate
      tags: [Gates]
      summary: Perform gate check for a component
      description: |
        Performs a fresh gate check with optional verdict proposal.
        Returns 403 if the gate is blocked.
      parameters:
        - name: bom_ref
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GateCheckRequest'
      responses:
        '200':
          description: Gate passed or warning
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GateCheckResponse'
        '403':
          description: Gate blocked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GateCheckResponse'

  /gates/{bom_ref}/exception:
    post:
      operationId: requestGateException
      tags: [Gates]
      summary: Request an exception to bypass the gate
      description: |
        Requests approval to bypass blocking unknowns.
        Exceptions are not auto-granted and require manual approval.
      parameters:
        - name: bom_ref
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExceptionRequest'
      responses:
        '200':
          description: Exception granted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponse'
        '403':
          description: Exception denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponse'

components:
  schemas:
    GateStatusResponse:
      type: object
      required:
        - bom_ref
        - state
        - gate_decision
        - checked_at
      properties:
        bom_ref:
          type: string
          description: BOM reference (PURL)
          example: "pkg:npm/lodash@4.17.21"
        state:
          type: string
          enum: [resolved, pending, under_review, escalated, rejected]
          description: Aggregate state across all unknowns
        verdict_hash:
          type: string
          nullable: true
          description: SHA-256 hash of verdict if resolved
          example: "sha256:abc123..."
        unknowns:
          type: array
          items:
            $ref: '#/components/schemas/UnknownDto'
        gate_decision:
          type: string
          enum: [pass, warn, block]
          description: Gate decision
        checked_at:
          type: string
          format: date-time
          description: When the check was performed

    UnknownDto:
      type: object
      required:
        - unknown_id
        - band
        - state
      properties:
        unknown_id:
          type: string
          format: uuid
          description: Unknown entry ID
        cve_id:
          type: string
          nullable: true
          description: CVE identifier if applicable
          example: "CVE-2026-1234"
        band:
          type: string
          enum: [hot, warm, cold]
          description: Priority band based on score
        sla_remaining_hours:
          type: number
          nullable: true
          description: Hours remaining before SLA breach
        state:
          type: string
          enum: [pending, under_review, escalated, resolved, rejected]
          description: Current processing state

    GateCheckRequest:
      type: object
      properties:
        proposed_verdict:
          type: string
          nullable: true
          description: Proposed VEX verdict (e.g., "not_affected")
          example: "not_affected"

    GateCheckResponse:
      type: object
      required:
        - bom_ref
        - decision
        - state
        - checked_at
      properties:
        bom_ref:
          type: string
        decision:
          type: string
          enum: [pass, warn, block]
        state:
          type: string
        blocking_unknown_ids:
          type: array
          items:
            type: string
            format: uuid
        reason:
          type: string
          nullable: true
          description: Human-readable reason for decision
        exception_granted:
          type: boolean
          description: Whether an exception was granted
        exception_ref:
          type: string
          nullable: true
          description: Exception reference if granted
        checked_at:
          type: string
          format: date-time

    ExceptionRequest:
      type: object
      required:
        - justification
      properties:
        unknown_ids:
          type: array
          items:
            type: string
            format: uuid
          description: IDs of unknowns to bypass
        justification:
          type: string
          description: Business justification for exception
          minLength: 10

    ExceptionResponse:
      type: object
      required:
        - granted
        - requested_at
      properties:
        granted:
          type: boolean
          description: Whether exception was granted
        exception_ref:
          type: string
          nullable: true
          description: Exception reference for tracking
        denial_reason:
          type: string
          nullable: true
          description: Reason if not granted
        expires_at:
          type: string
          format: date-time
          nullable: true
          description: When exception expires
        requested_at:
          type: string
          format: date-time
          description: When request was made