git.stella-ops.org/docs/contracts/api-aggregate-2025-12-10.yaml

openapi: 3.1.0
info:
  title: StellaOps Aggregate API
  version: "2025-12-10"
  description: >
    Tagged aggregate OpenAPI snapshot for SDK Wave B/C generation.
    Covers Evidence Locker, timeline events, and metadata surfaces used by CLI,
    Console, and DevPortal offline bundles. Frozen on 2025-12-10 for reproducible
    SDK artifacts across TypeScript, Python, Go, and Java.
servers:
  - url: https://api.stellaops.local
    description: Sovereign control plane (staging)
  - url: https://api.stellaops.example.com
    description: Sovereign control plane (production)
security:
  - bearerAuth: []
paths:
  /v1/evidence-locker/bundles:
    get:
      summary: List evidence bundles
      description: Returns evidence bundles ordered by creation time with cursor pagination.
      parameters:
        - name: cursor
          in: query
          required: false
          schema:
            type: string
          description: Opaque cursor from a prior response; omit for first page.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 50
          description: Page size (max 200).
      responses:
        "200":
          description: Evidence bundle page.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EvidenceBundlePage"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
    post:
      summary: Create evidence bundle
      description: >
        Creates a new evidence bundle from client-supplied artifacts. Server returns a content-addressed
        bundle identifier and provenance digest for downstream attestations.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EvidenceBundleRequest"
      responses:
        "201":
          description: Evidence bundle created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EvidenceBundle"
        "400":
          $ref: "#/components/responses/ValidationError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
  /v1/evidence-locker/bundles/{bundleId}:
    get:
      summary: Get evidence bundle
      parameters:
        - name: bundleId
          in: path
          required: true
          schema:
            type: string
          description: Bundle identifier returned by the create operation.
      responses:
        "200":
          description: Evidence bundle by id.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EvidenceBundle"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "404":
          $ref: "#/components/responses/NotFoundError"
  /v1/timeline/events:
    get:
      summary: List timeline events
      description: >
        Returns timeline events with support for source filtering and consistent ordering
        for replay across offline bundles.
      parameters:
        - name: source
          in: query
          required: false
          schema:
            type: string
          description: Optional source filter (e.g., scanner, attestor).
        - name: cursor
          in: query
          required: false
          schema:
            type: string
          description: Cursor for pagination.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 100
          description: Page size (max 500).
      responses:
        "200":
          description: Timeline event page.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TimelineEventPage"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
  /v1/sdk/metadata:
    get:
      summary: SDK metadata surface
      description: >
        Provides deterministic metadata for SDK generation (hash guard, generator version,
        snapshot tag) to allow clients to verify provenance in offline environments.
      responses:
        "200":
          description: Metadata payload
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SdkMetadata"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    EvidenceBundleRequest:
      type: object
      required:
        - subject
        - artifacts
      properties:
        subject:
          type: string
          description: Content-addressed digest of the subject container/image.
        artifacts:
          type: array
          minItems: 1
          items:
            $ref: "#/components/schemas/EvidenceItem"
        annotations:
          type: object
          additionalProperties:
            type: string
          description: Optional annotations preserved in the bundle manifest.
    EvidenceItem:
      type: object
      required:
        - type
        - digest
      properties:
        type:
          type: string
          description: Evidence type (sbom, attestation, manifest, log).
        digest:
          type: string
          description: Content-addressed digest of the artifact (sha256:...).
        uri:
          type: string
          description: Optional URI to fetch artifact if not inlined.
    EvidenceBundle:
      type: object
      required:
        - id
        - createdAt
        - subject
        - artifacts
        - manifestDigest
      properties:
        id:
          type: string
          description: Bundle identifier.
        createdAt:
          type: string
          format: date-time
          description: Creation timestamp in UTC.
        subject:
          type: string
          description: Subject digest the bundle binds to.
        artifacts:
          type: array
          items:
            $ref: "#/components/schemas/EvidenceItem"
        manifestDigest:
          type: string
          description: Digest of the bundle manifest (sha256:...).
        provenance:
          type: object
          description: Optional DSSE statement describing bundle assembly.
    EvidenceBundlePage:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/EvidenceBundle"
        nextCursor:
          type: string
          nullable: true
          description: Opaque cursor for the next page; null when done.
    TimelineEvent:
      type: object
      required:
        - id
        - occurredAt
        - source
        - type
      properties:
        id:
          type: string
        occurredAt:
          type: string
          format: date-time
        source:
          type: string
        type:
          type: string
        data:
          type: object
          additionalProperties: true
    TimelineEventPage:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/TimelineEvent"
        nextCursor:
          type: string
          nullable: true
    SdkMetadata:
      type: object
      required:
        - snapshotTag
        - generatorVersion
        - snapshotSha256
      properties:
        snapshotTag:
          type: string
          example: api-aggregate-2025-12-10
        generatorVersion:
          type: string
          example: openapi-generator-cli@7.4.0
        snapshotSha256:
          type: string
          example: sha256:deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
        details:
          type: object
          additionalProperties: true
  responses:
    UnauthorizedError:
      description: Authentication failed.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    ValidationError:
      description: Validation failed.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    NotFoundError:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"