openapi: 3.1.0

info:
  version: 1.0.0
  title: Warg Registry API
  description: |
    [warg](https://warg.io/) is an open source protocol for WebAssembly component registries.
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0

# The Warg APIs currently do not use an authentication scheme
# Publishing requires that entries are signed with an acceptable key
x-42c-no-authentication: true

# Ignore warnings regarding strings in responses not having a pattern or maximum length
x-42c-skipIssues:
  - v3-schema-response-string-pattern
  - v3-schema-response-string-maxlength

tags:
  - name: fetch
    description: API for fetching checkpoints, logs and package names from the registry.
  - name: package
    description: API for managing package logs in the registry.
  - name: content
    description: API for content sources in the registry.
  - name: proof
    description: API for proving the integrity of the registry.
  - name: monitor
    description: API for verifying registry checkpoints.
  - name: ledger
    description: API for fetching the ledger.

servers:
  - url: http://localhost:8090/v1
    description: Local development server

paths:
  /fetch/names:
    post:
      summary: Fetch package names
      operationId: fetchNames
      security: []
      tags:
        - fetch
      description: |
        Fetch the package names for registry log IDs.
      parameters:
        - name: Warg-Registry
          in: header
          $ref: "#/components/headers/WargRegistryHeader"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FetchPackageNamesRequest"
      responses:
        "200":
          description: The package names were successfully fetched.
          headers:
            Warg-Registry:
              $ref: "#/components/headers/WargRegistryHeader"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FetchPackageNamesResponse"
        "404":
          description: A requested entity was not found.
          headers:
            Warg-Registry:
              $ref: "#/components/headers/WargRegistryHeader"
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                  - status
                  - type
                  - id
                properties:
                  status:
                    type: integer
                    description: The HTTP status code for the error.
                    example: 404
                  type:
                    type: string
                    description: The type of entity that was not found.
                    enum: [log]
                    example: log
                  id:
                    type: string
                    description: The identifier of the entity that was not found.
                    example: sha256:b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c
        default:
          description: An error occurred when processing the request.
          headers:
            Warg-Registry:
              $ref: "#/components/headers/WargRegistryHeader"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /fetch/logs:
    post:
      summary: Fetch registry logs
      operationId: fetchLogs
      security: []
      tags:
        - fetch
      description: |
        Fetch the operator and packages logs from the registry.
      parameters:
        - name: Warg-Registry
          in: header
          $ref: "#/components/headers/WargRegistryHeader"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FetchLogsRequest"
      responses:
        "200":
          description: The logs were successfully fetched.
          headers:
            Warg-Registry:
              $ref: "#/components/headers/WargRegistryHeader"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FetchLogsResponse"
        "404":
          description: A requested entity was not found.
          headers:
            Warg-Registry:
              $ref: "#/components/headers/WargRegistryHeader"
          content:
            application/json:
              schema:
                oneOf:
                  - "$ref": "#/components/schemas/FetchLogsIDNotFoundError"
                  - "$ref": "#/components/schemas/FetchLogsLogLengthNotFoundError"
        default:
          description: An error occurred when processing the request.
          headers:
            Warg-Registry:
              $ref: "#/components/headers/WargRegistryHeader"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /fetch/checkpoint:
    get:
      summary: Fetch latest registry checkpoint
      operationId: getCheckpoint
      security: []
      tags:
        - fetch
      description: Fetch the latest checkpoint from the registry.
      parameters:
        - name: Warg-Registry
          in: header
          $ref: "#/components/headers/WargRegistryHeader"
      responses:
        "200":
          description: The checkpoint was successfully fetched.
          headers:
            Warg-Registry:
              $ref: "#/components/headers/WargRegistryHeader"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SignedCheckpoint"
        default:
          description: An error occurred when processing the request.
          headers:
            Warg-Registry:
              $ref: "#/components/headers/WargRegistryHeader"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /package/{logId}/record:
    post:
      summary: Publish package record
      operationId: publishPackageRecord
      security: []
      tags:
        - package
      description: |
        Attempts to publish a new record to a package log.

        Publishing package records is an asynchronous operation.

        The record must be signed by a key that is authorized to modify the package log.
      parameters:
        - name: logId
          in: path
          description: The package log identifier.
          required: true
          schema:
            "$ref": "#/components/schemas/AnyHash"
        - name: Warg-Registry
          in: header
          $ref: "#/components/headers/WargRegistryHeader"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PublishPackageRecordRequest"
      responses:
        "202":
          description: The package record was accepted.
          headers:
            Warg-Registry:
              $ref: "#/components/headers/WargRegistryHeader"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/PackageRecord"
        "401":
          description: |
            Unauthorized rejection from the registry.
          headers:
            Warg-Registry:
              $ref: "#/components/headers/WargRegistryHeader"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: A requested entity was not found.
          headers:
            Warg-Registry:
              $ref: "#/components/headers/WargRegistryHeader"
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                  - status
                  - type
                  - id
                properties:
                  status:
                    type: integer
                    description: The HTTP status code for the error.
                    example: 404
                  type:
                    type: string
                    description: The type of entity that was not found.
                    enum: [namespace]
                    example: namespace
                  id:
                    type: string
                    description: |
                      The identifier of the entity that was not found.
        "409":
          description: The requested package publish conflicts.
          headers:
            Warg-Registry:
              $ref: "#/components/headers/WargRegistryHeader"
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                  - status
                  - type
                  - id
                properties:
                  status:
                    type: integer
                    description: The HTTP status code for the error.
                    example: 409
                  type:
                    type: string
                    description: The type of entity that was not found.
                    enum: [name, namespace, namespaceImport, record]
                    example: namespace
                  id:
                    type: string
                    description: |
                      The identifier of the entity that was not found.
        "422":
          description: |
            The package was rejected by the registry.
          headers:
            Warg-Registry:
              $ref: "#/components/headers/WargRegistryHeader"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "501":
          description: |
            The server does not support publishing package records with explicitly
            specified content source locations.
          headers:
            Warg-Registry:
              $ref: "#/components/headers/WargRegistryHeader"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: An error occurred when processing the request.
          headers:
            Warg-Registry:
              $ref: "#/components/headers/WargRegistryHeader"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /package/{logId}/record/{recordId}:
    get:
      summary: Get package record status
      operationId: getPackageRecord
      security: []
      tags:
        - package
      description: |
        Gets package record status from the registry.

        A package record is in one of the following states:
          * `sourcing`: The package record needs content sources.
          * `processing`: The package record is being processed.
          * `rejected`: The package record was rejected.
          * `published`: The package record was published to the log.
      parameters:
        - name: logId
          in: path
          description: The package log identifier.
          required: true
          schema:
            "$ref": "#/components/schemas/AnyHash"
        - name: recordId
          in: path
          description: The record identifier.
          required: true
          schema:
            "$ref": "#/components/schemas/AnyHash"
        - name: Warg-Registry
          in: header
          $ref: "#/components/headers/WargRegistryHeader"
      responses:
        "200":
          description: The package record.
          headers:
            Warg-Registry:
              $ref: "#/components/headers/WargRegistryHeader"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/PackageRecord"
        "404":
          description: A requested entity was not found.
          headers:
            Warg-Registry:
              $ref: "#/components/headers/WargRegistryHeader"
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                  - status
                  - type
                  - id
                properties:
                  status:
                    type: integer
                    description: The HTTP status code for the error.
                    example: 404
                  type:
                    type: string
                    description: The type of entity that was not found.
                    enum: [log, record]
                    example: log
                  id:
                    "$ref": "#/components/schemas/AnyHash"
                    description: |
                      The identifier of the entity that was not found.
        default:
          description: An error occurred when processing the request.
          headers:
            Warg-Registry:
              $ref: "#/components/headers/WargRegistryHeader"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /content/{digest}:
    get:
      summary: Get content sources
      operationId: getContentSources
      security: []
      tags:
        - content
      description: |
        Gets a content sources for the given digest from the registry.
      parameters:
        - name: digest
          in: path
          description: The content digest.
          required: true
          schema:
            "$ref": "#/components/schemas/AnyHash"
        - name: Warg-Registry
          in: header
          $ref: "#/components/headers/WargRegistryHeader"
      responses:
        "200":
          description: The content digest sources.
          headers:
            Warg-Registry:
              $ref: "#/components/headers/WargRegistryHeader"
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ContentSourcesResponse"
        "404":
          description: A requested entity was not found.
          headers:
            Warg-Registry:
              $ref: "#/components/headers/WargRegistryHeader"
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                  - status
                  - type
                  - id
                properties:
                  status:
                    type: integer
                    description: The HTTP status code for the error.
                    example: 404
                  type:
                    type: string
                    description: The type of entity that was not found.
                    enum: [contentDigest]
                    example: contentDigest
                  id:
                    "$ref": "#/components/schemas/AnyHash"
                    description: |
                      The identifier of the entity that was not found.
        default:
          description: An error occurred when processing the request.
          headers:
            Warg-Registry:
              $ref: "#/components/headers/WargRegistryHeader"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /proof/consistency:
    post:
      summary: Prove registry checkpoint consistency
      operationId: proveConsistency
      security: []
      tags:
        - proof
      description: |
        Proves the consistency of the registry between two specified checkpoints.
      parameters:
        - name: Warg-Registry
          in: header
          $ref: "#/components/headers/WargRegistryHeader"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProveConsistencyRequest"
      responses:
        "200":
          description: The consistency proof was generated successfully.
          headers:
            Warg-Registry:
              $ref: "#/components/headers/WargRegistryHeader"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProveConsistencyResponse"
        "404":
          description: A requested entity was not found.
          headers:
            Warg-Registry:
              $ref: "#/components/headers/WargRegistryHeader"
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                  - status
                  - type
                  - id
                properties:
                  status:
                    type: integer
                    description: The HTTP status code for the error.
                    example: 404
                  type:
                    type: string
                    description: The type of entity that was not found.
                    enum: [logLength]
                    example: logLength
                  id:
                    type: integer
                    description: The identifier of the entity that was not found. 
        "422":
          description: The proof bundle could not be generated.
          headers:
            Warg-Registry:
              $ref: "#/components/headers/WargRegistryHeader"
          content:
            application/json:
              schema:
                oneOf:
                  - "$ref": "#/components/schemas/BundleFailureError"
                discriminator:
                  propertyName: reason
                  mapping:
                    failure: "#/components/schemas/BundleFailureError"
        default:
          description: An error occurred when processing the request.
          headers:
            Warg-Registry:
              $ref: "#/components/headers/WargRegistryHeader"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /proof/inclusion:
    post:
      summary: Prove log leaf inclusion
      operationId: proveInclusion
      security: []
      tags:
        - proof
      description: |
        Proves that the given log leafs are present in the given registry checkpoint.
      parameters:
        - name: Warg-Registry
          in: header
          $ref: "#/components/headers/WargRegistryHeader"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProveInclusionRequest"
      responses:
        "200":
          description: The inclusion proof was generated successfully.
          headers:
            Warg-Registry:
              $ref: "#/components/headers/WargRegistryHeader"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProveInclusionResponse"
        "404":
          description: A requested entity was not found.
          headers:
            Warg-Registry:
              $ref: "#/components/headers/WargRegistryHeader"
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                  - status
                  - type
                  - id
                properties:
                  status:
                    type: integer
                    description: The HTTP status code for the error.
                    example: 404
                  type:
                    type: string
                    description: The type of entity that was not found.
                    enum: [logLength, leaf]
                    example: logLength
                  id:
                    type: integer
                    description: The identifier of the entity that was not found.
        "422":
          description: The proof bundle could not be generated.
          headers:
            Warg-Registry:
              $ref: "#/components/headers/WargRegistryHeader"
          content:
            application/json:
              schema:
                oneOf:
                  - "$ref": "#/components/schemas/PackageNotIncludedError"
                  - "$ref": "#/components/schemas/IncorrectProofError"
                  - "$ref": "#/components/schemas/BundleFailureError"
                discriminator:
                  propertyName: reason
                  mapping:
                    packageNotIncluded: "#/components/schemas/PackageNotIncludedError"
                    incorrectProof: "#/components/schemas/IncorrectProofError"
                    failure: "#/components/schemas/BundleFailureError"
        default:
          description: An error occurred when processing the request.
          headers:
            Warg-Registry:
              $ref: "#/components/headers/WargRegistryHeader"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /verify/checkpoint:
    post:
      summary: Verify registry checkpoint
      operationId: verifyCheckpoint
      security: []
      tags:
        - monitor
      description: Verify checkpoint from the registry. The client must interpret the response body to determine the verification status.
      parameters:
        - name: Warg-Registry
          in: header
          $ref: "#/components/headers/WargRegistryHeader"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SignedCheckpoint"
      responses:
        "200":
          description: The checkpoint verification request was processed. The client must interpret the response body to determine the verification status. 
          headers:
            Warg-Registry:
              $ref: "#/components/headers/WargRegistryHeader"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CheckpointVerificationResponse"
        default:
          description: An error occurred when processing the request.
          headers:
            Warg-Registry:
              $ref: "#/components/headers/WargRegistryHeader"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /ledger:
    get:
      summary: Fetch ledger sources
      operationId: getLedgerSources
      security: []
      tags:
        - ledger
      description: Fetch the registry ledger download URL sources.
      parameters:
        - name: Warg-Registry
          in: header
          $ref: "#/components/headers/WargRegistryHeader"
      responses:
        "200":
          description: The ledger sources was successfully fetched.
          headers:
            Warg-Registry:
              $ref: "#/components/headers/WargRegistryHeader"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LedgerSourcesResponse"
        default:
          description: An error occurred when processing the request.
          headers:
            Warg-Registry:
              $ref: "#/components/headers/WargRegistryHeader"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

components:
  headers:
    WargRegistryHeader:
      description: If present and supported, this registry responds on behalf of the other registry specified in this header value.
      required: false
      schema:
        type: string
      example: registry.example.com
  schemas:
    Error:
      type: object
      description: A generic error response.
      additionalProperties: false
      required:
        - status
        - message
      properties:
        status:
          type: integer
          description: The HTTP status code for the error.
          example: 406
        message:
          type: string
          description: The error message.
          example: the server cannot produce an acceptable response
    AnyHash:
      type: string
      description: Represents a supported hash.
      example: sha256:b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c
      pattern: ^[a-z0-9-]+:[a-f0-9]+$
    FetchPackageNamesRequest:
      type: object
      description: A request to fetch package names from the registry.
      additionalProperties: false
      required:
        - packages
      properties:
        packages:
          type: array
          description: The log ID for each requested package.
          example: ["sha256:7d865e959b2466918c9863afca942d0fb89d7c9ac0c99bafc3749504ded9773"]
          minimum: 1
          items:
            $ref: "#/components/schemas/AnyHash"
            description: The log ID for each package.
    FetchPackageNamesResponse:
      type: object
      description: A response containing the requested package names.
      additionalProperties: false
      properties:
        packages:
          type: object
          description: The map of log ID to package name.
          patternProperties:
            "^[a-z0-9-]+:[a-f0-9]+$":
              type: string
              nullable: true
              description: The package name for each package. If `null`, the package name is not able to be provided for the log ID.
          example:
            "sha256:7d865e959b2466918c9863afca942d0fb89d7c9ac0c99bafc3749504ded9773": "example-namespace:package-name"
            "sha256:b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c": null
    FetchLogsRequest:
      type: object
      description: A request to fetch logs from the registry.
      additionalProperties: false
      required:
        - logLength
      properties:
        logLength:
          type: integer
          description: The registry checkpoint log length to fetch from.
          example: 101
          minimum: 1
        limit:
          type: integer
          description: The limit of operator and packages records to return for the fetch request.
          example: 100
          default: 100
          minimum: 1
          maximum: 1000
          format: int16
        operator:
          $ref: "#/components/schemas/AnyHash"
          description: The last known operator record fetch token.
        packages:
          type: object
          description: |
            The map of package log identifier to last known package record fetch token.

            If the last package record identifier is null, records are returned from the start of the log.
          patternProperties:
            "^[a-z0-9-]+:[a-f0-9]+$":
              $ref: "#/components/schemas/AnyHash"
              description: The last known package record identifier.
              nullable: true
          example:
            "sha256:7d865e959b2466918c9863afca942d0fb89d7c9ac0c99bafc3749504ded9773": "sha256:7d865e959b2466918c9863afca942d0fb89d7c9ac0c99bafc3749504ded97730"
            "sha256:b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c": null
    FetchLogsResponse:
      type: object
      description: A response containing the requested logs.
      additionalProperties: false
      properties:
        more:
          type: boolean
          description: |
            Whether there may be more records available.

            This occurs when the number of records returned for a log reaches the requested limit.

            If `true`, the client should make another request with the new last known record identifiers.
          example: false
        operator:
          type: array
          description: The operator log records for the given checkpoint since the last known record.
          maxItems: 1000
          items:
            $ref: "#/components/schemas/PublishedRecordEnvelope"
        warnings:
          type: array
          description: An optional list of warnings.
          maxItems: 1000
          items:
            $ref: "#/components/schemas/FetchWarning"
        packages:
          type: object
          description: The map of package log identifier to package records.
          patternProperties:
            "^[a-z0-9-]+:[a-f0-9]+$":
              type: array
              description: The package log records for the given checkpoint since the last known record.
              maxItems: 1000
              items:
                $ref: "#/components/schemas/PublishedRecordEnvelope"
          example:
            ? "sha256:7d865e959b2466918c9863afca942d0fb89d7c9ac0c99bafc3749504ded97730"
            : - contentBytes: "ZXhhbXBsZQ=="
                keyId: "sha256:7d865e959b2466918c9863afca942d0fb89d7c9ac0c99bafc3749504ded97730"
                signature: "ecdsa-p256:MEUCIQCzWZBW6ux9LecP66Y+hjmLZTP/hZVz7puzlPTXcRT2wwIgQZO7nxP0nugtw18MwHZ26ROFWcJmgCtKOguK031Y1D0="
                registryIndex: 101
                fetchToken: "sha256:7d865e959b2466918c9863afca942d0fb89d7c9ac0c99bafc3749504ded97730"
              - contentBytes: "ZXhhbXBsZQ=="
                keyId: "sha256:7d865e959b2466918c9863afca942d0fb89d7c9ac0c99bafc3749504ded97730"
                signature: "ecdsa-p256:MEUCIQCzWZBW6ux9LecP66Y+hjmLZTP/hZVz7puzlPTXcRT2wwIgQZO7nxP0nugtw18MwHZ26ROFWcJmgCtKOguK031Y1D0="
                registryIndex: 305
                fetchToken: "sha256:b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c"
            ? "sha256:b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c"
            : - contentBytes: "ZXhhbXBsZQ=="
                keyId: "sha256:7d865e959b2466918c9863afca942d0fb89d7c9ac0c99bafc3749504ded97730"
                signature: "ecdsa-p256:MEUCIQCzWZBW6ux9LecP66Y+hjmLZTP/hZVz7puzlPTXcRT2wwIgQZO7nxP0nugtw18MwHZ26ROFWcJmgCtKOguK031Y1D0="
                registryIndex: 732
                fetchToken: "sha256:ygdb4e8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae00a8y"
    PublishPackageRecordRequest:
      type: object
      description: A request to publish a record to a package log.
      additionalProperties: false
      required:
        - packageName
        - record
      properties:
        packageName:
          type: string
          description: The name of the package log being published to.
          maxLength: 128
          example: wasi:http
        record:
          "$ref": "#/components/schemas/EnvelopeBody"
          description: The package record being published to the log.
        contentSources:
          "$ref": "#/components/schemas/ContentSourceMap"
          description: |
            The map of all content sources for the record.

            A registry may not support specifying content sources for a record.

            If a registry does not support content sources, a 501 will be returned
            and content will need to be directly uploaded to the registry.
    PackageRecord:
      description: A package log record.
      allOf:
        - type: object
          required:
            - recordId
          properties:
            recordId:
              "$ref": "#/components/schemas/AnyHash"
              description: The record identifier.
        - oneOf:
            - "$ref": "#/components/schemas/SourcingRecord"
            - "$ref": "#/components/schemas/ProcessingRecord"
            - "$ref": "#/components/schemas/RejectedRecord"
            - "$ref": "#/components/schemas/PublishedRecord"
          discriminator:
            propertyName: state
            mapping:
              sourcing: "#/components/schemas/SourcingRecord"
              processing: "#/components/schemas/ProcessingRecord"
              rejected: "#/components/schemas/RejectedRecord"
              published: "#/components/schemas/PublishedRecord"
    ProveConsistencyRequest:
      type: object
      description: A request to prove the consistency of the registry.
      additionalProperties: false
      required:
        - from
        - to
      properties:
        from:
          type: integer
          description: The starting log length.
          minimum: 1
          example: 42
        to:
          type: integer
          description: The ending log length.
          minimum: 1
          example: 42
    ProveConsistencyResponse:
      type: object
      description: A response containing the consistency proof bundle.
      additionalProperties: false
      required:
        - proof
      properties:
        proof:
          type: string
          description: The consistency proof bundle.
          format: byte
          example: "ZXhhbXBsZQ=="
    ProveInclusionRequest:
      type: object
      description: A request to prove the inclusion of log leafs in a checkpoint.
      additionalProperties: false
      required:
        - logLength
        - leafs
      properties:
        logLength:
          type: integer
          description: The checkpoint log length to prove the inclusion for.
        leafs:
          type: array
          maxItems: 1000
          description: The log leaf registry log index to prove the inclusion for.
          items:
            type: integer
    ProveInclusionResponse:
      type: object
      description: A response containing the inclusion proof bundle.
      additionalProperties: false
      required:
        - log
        - map
      properties:
        log:
          type: string
          description: The log inclusion proof bundle.
          format: byte
          example: "ZXhhbXBsZQ=="
        map:
          type: string
          description: The map inclusion proof bundle.
          format: byte
          example: "ZXhhbXBsZQ=="
    SourcingRecord:
      type: object
      description: The package record is sourcing content.
      required:
        - state
        - missingContent
      properties:
        state:
          type: string
          description: The state of the package record.
          enum: [sourcing]
          example: sourcing
        missingContent:
          "$ref": "#/components/schemas/MissingContentMap"
          description: The missing content for the package record.
          minProperties: 1
    ProcessingRecord:
      type: object
      description: A record that is being processed.
      required:
        - state
      properties:
        state:
          type: string
          description: The state of the package record.
          enum: [processing]
          example: processing
    RejectedRecord:
      type: object
      description: A rejected package record.
      required:
        - state
        - reason
      properties:
        state:
          type: string
          description: The state of the package record.
          enum: [rejected]
          example: rejected
        reason:
          type: string
          description: The reason the package record was rejected.
          example: the first entry of the log is not `init`
    PublishedRecord:
      type: object
      description: A record that has been published to the log.
      required:
        - state
        - registryIndex
      properties:
        state:
          type: string
          description: The state of the package record.
          enum: [published]
          example: published
        registryIndex:
          type: integer
          description: The index of the record in the registry log.
    Checkpoint:
      type: object
      description: |
        A registry checkpoint.

        Checkpoints are hashed by concatenating the following:
          * A prefix of the byte string `WARG-CHECKPOINT-V0`
          * The LEB128-encoded `logLength`
          * The LEB128-length-prefixed `logRoot`
          * The LEB128-length-prefixed `mapRoot`
      additionalProperties: false
      required:
        - logLength
        - logRoot
        - mapRoot
      properties:
        logLength:
          type: integer
          description: The log length of the checkpoint.
          minimum: 1
          example: 42
        logRoot:
          $ref: "#/components/schemas/AnyHash"
          description: The log root hash of the checkpoint.
        mapRoot:
          $ref: "#/components/schemas/AnyHash"
          description: The map root hash of the checkpoint.
    TimestampedCheckpoint:
      description: |
        A timestamped registry checkpoint.

        Checkpoints are hashed by concatenating the following:
          * A prefix of the byte string `WARG-TIMESTAMPED-CHECKPOINT-V0`
          * The LEB128-encoded `logLength`
          * The LEB128-length-prefixed `logRoot`
          * The LEB128-length-prefixed `mapRoot`
          * The LEB128-encoded `timestamp`
      allOf:
        - $ref: "#/components/schemas/Checkpoint"
        - type: object
          additionalProperties: false
          required:
            - timestamp
          properties:
            timestamp:
              type: integer
              description: |
                The time that the checkpoint was generated, in seconds since
                the Unix epoch.
              minimum: 1
              example: 1692035502
    SignedCheckpoint:
      description: A signed registry checkpoint.
      allOf:
        - type: object
          required:
            - contents
          properties:
            contents:
              $ref: "#/components/schemas/TimestampedCheckpoint"
        - $ref: "#/components/schemas/Signature"
    EnvelopeBody:
      description: A signed envelope body.
      allOf:
        - type: object
          required:
            - contentBytes
          properties:
            contentBytes:
              type: string
              description: |
                Base64-encoded bytes of the content.

                The content of an envelope body is typically a serialized protocol buffer
                representing an operator or package record.
              format: byte
              maxLength: 1048576
              example: "ZXhhbXBsZQ=="
        - $ref: "#/components/schemas/Signature"
    FetchWarning:
      description: A warning message
      properties:
        message:
          description: The warning message itself.
          type: string 
    PublishedRecordEnvelope:
      description: A signed envelope body with the published registry log index.
      allOf:
        - type: object
          required:
            - registryIndex
            - fetchToken
          properties:
            registryIndex:
              type: integer
              description: The index of the published record in the registry log.
              example: 42
            fetchToken:
              type: string
              description: The fetch token for the registry log. Used as a cursor for incrementally fetching log records.
              example: "sha256:b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c"
        - $ref: "#/components/schemas/EnvelopeBody"
        - $ref: "#/components/schemas/Signature"
    Signature:
      type: object
      description: Represents a signature of content.
      required:
        - keyId
        - signature
      properties:
        keyId:
          $ref: "#/components/schemas/AnyHash"
          description: The signing key identifier.
        signature:
          type: string
          description: The algorithm-prefixed bytes of the signature (base64 encoded).
          pattern: ^[a-z0-9-]+:(?:[A-Za-z0-9+\/]{4})*(?:[A-Za-z0-9+\/]{4}|[A-Za-z0-9+\/]{3}=|[A-Za-z0-9+\/]{2}={2})$
          example: "ecdsa-p256:MEUCIQCzWZBW6ux9LecP66Y+hjmLZTP/hZVz7puzlPTXcRT2wwIgQZO7nxP0nugtw18MwHZ26ROFWcJmgCtKOguK031Y1D0="
    MissingContentMap:
      type: object
      description: The map of content digest to missing content info.
      patternProperties:
        "^[a-z0-9-]+:[a-f0-9]+$":
          "$ref": "#/components/schemas/MissingContent"
      example:
        ? "sha256:7d865e959b2466918c9863afca942d0fb89d7c9ac0c99bafc3749504ded9773"
        : upload:
            - type: http
              method: "POST"
              url: "https://example.com/7d865e959b2466918c9863afca942d0fb89d7c9ac0c99bafc3749504ded9773"
    MissingContent:
      description: Information about missing content.
      properties:
        upload:
          description: Upload endpoint(s) for the missing content.
          type: array 
          items:
            oneOf:
              - "$ref": "#/components/schemas/HttpUpload"
            discriminator:
              propertyName: type
              mapping:
                http: "#/components/schemas/HttpUpload"
    HttpUpload:
      type: object
      description: A HTTP upload endpoint.
      required:
        - type
        - method
        - url
      properties:
        type:
          type: string
          description: The type of upload endpoint.
          enum: [http]
          example: http
        method:
          type: string
          description: The HTTP method for the upload request. Uppercase is required.
          enum: [POST, PUT]
          example: POST
        url:
          type: string
          description: The URL of the upload endpoint, which may be relative to the API base URL.
          example: https://example.com/contents.wasm
          format: uri
        headers:
          type: object
          description: The HTTP headers for upload request. Header name is required to be all lowercase.
          properties:
            authorization:
              type: string
              description: Authorization header.
              example: "Bearer cn389ncoiwuencr"
            "content-type":
              type: string
              description: Content type header.
              example: "application/wasm"
    ContentSourcesResponse:
      type: object
      description: Content digest sources for download.
      required:
        - contentSources
      properties:
        contentSources:
          "$ref": "#/components/schemas/ContentSourceMap"
          description: The content sources for the content digest.
    ContentSourceMap:
      type: object
      description: The map of content digest to sources.
      patternProperties:
        "^[a-z0-9-]+:[a-f0-9]+$":
          type: array
          items:
            "$ref": "#/components/schemas/ContentSource"
          description: The array of sources for the content digest.
          minItems: 1
          maxItems: 128
      example:
        ? "sha256:7d865e959b2466918c9863afca942d0fb89d7c9ac0c99bafc3749504ded9773"
        : - type: httpGet
            url: https://example.com/7d865e959b2466918c9863afca942d0fb89d7c9ac0c99bafc3749504ded9773
    ContentSource:
      description: A known content source.
      oneOf:
        - "$ref": "#/components/schemas/HttpGet"
      discriminator:
        propertyName: type
        mapping:
          httpGet: "#/components/schemas/HttpGet"
    HttpGet:
      type: object
      description: A known GET HTTP content source.
      required:
        - type
        - url
      properties:
        type:
          type: string
          description: The type of content source.
          enum: [httpGet]
          example: httpGet
        url:
          type: string
          description: The URL of the content.
          example: https://example.com/contents.wasm
          format: uri
        acceptRanges:
          type: boolean
          description: Flag indicating if the server accepts byte ranges with `Range` header.
        size:
          type: integer
          description: Content size in bytes.
          example: 1024
    PackageNotIncludedError:
      type: object
      additionalProperties: false
      required:
        - status
        - reason
        - logId
      properties:
        status:
          type: integer
          description: The HTTP status code for the error.
          example: 422
        reason:
          type: string
          description: The reason why the bundle could not be generated.
          enum: [packageNotIncluded]
          example: packageNotIncluded
        logId:
          "$ref": "#/components/schemas/AnyHash"
          description: The identifier of the log that was not included.
    IncorrectProofError:
      type: object
      additionalProperties: false
      required:
        - status
        - reason
        - root
        - found
      properties:
        status:
          type: integer
          description: The HTTP status code for the error.
          example: 422
        reason:
          type: string
          description: The reason why the bundle could not be generated.
          enum: [incorrectProof]
          example: incorrectProof
        root:
          "$ref": "#/components/schemas/AnyHash"
          description: The map or log root hash from the checkpoint that was provided.
        found:
          "$ref": "#/components/schemas/AnyHash"
          description: The hash that was found in the proof.
    BundleFailureError:
      type: object
      additionalProperties: false
      required:
        - status
        - reason
        - message
      properties:
        status:
          type: integer
          description: The HTTP status code for the error.
          example: 422
        reason:
          type: string
          description: The reason why the bundle could not be generated.
          enum: [failure]
          example: failure
        message:
          type: string
          description: The failure error message.
          example: bundle must contain proofs for the same root
    FetchLogsIDNotFoundError:
        type: object
        additionalProperties: false
        required:
          - status
          - type
          - id
        properties:
          status:
            type: integer
            description: The HTTP status code for the error.
            example: 404
          type:
            type: string
            description: The type of entity that was not found.
            enum: [log, fetchToken]
            example: log
          id:
            type: string
            description: The identifier of the entity that was not found.
            example: sha256:b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c
    FetchLogsLogLengthNotFoundError:
        type: object
        additionalProperties: false
        required:
          - status
          - type
          - id
        properties:
          status:
            type: integer
            description: The HTTP status code for the error.
            example: 404
          type:
            type: string
            description: The type of entity that was not found.
            enum: [logLength]
            example: log
          id:
            type: integer
            description: The log length that was not found.
            example: 1001
    LedgerSourcesResponse:
      type: object
      description: A response containing the registry ledger sources.
      additionalProperties: false
      properties:
        hashAlgorithm:
          type: string
          description: The type of hash algorithm used for log and record IDs.
          enum: [sha256]
          example: sha256
        sources:
          type: array
          description: The ledger sources.
          items:
            type: object
            description: Ledger source HTTP get URL.
            additionalProperties: false
            required:
              - firstRegistryIndex
              - lastRegistryIndex
              - url
              - contentType
            properties:
              firstRegistryIndex:
                type: integer
                description: The first registry index included in the source.
                example: 0
              lastRegistryIndex:
                type: integer
                description: The last registry index included in the source.
                example: 999
              url:
                type: string
                description: The HTTP GET URL to fetch the source.
                example: http://registry.example.com/ledger/0
              contentType:
                type: string
                description: The content type of source.
                enum: ["application/vnd.warg.ledger.packed"]
                example: "application/vnd.warg.ledger.packed"
              acceptRanges:
                type: boolean
                description: Flag indicating if the server accepts byte ranges with `Range` header.
    CheckpointVerificationResponse:
      type: object
      additionalProperties: false
      required:
        - checkpoint
        - signature
      properties:
        checkpoint:
          type: string
          description: |
            The verification of the checkpoint's `logLength`, `logRoot` and `mapRoot`:

              * `unverified`: checkpoint may be valid or invalid; if `retryAfter` is provided, the client should retry the request;
              * `verified`: `logLength`, `logRoot` and `mapRoot` are verified;
              * `invalid`: checkpoint with the specified `logLength` was either not produced or does not match the correct `logRoot` and `mapRoot`;
          enum: [unverified, verified, invalid]
          example: verified
        signature:
          type: string
          description: |
            The verification of the checkpoint's `keyId` and `signature`:

              * `unverified`: checkpoint's `signature` may be valid or invalid; if `retryAfter` is provided, the client should retry the request;
              * `verified`: checkpoint's `signature` is verified;
              * `invalid`: `keyId` is not known or does not have authorization (could have been revoke or never granted) to sign checkpoints or the `signature` itself is invalid;
          enum: [unverified, verified, invalid]
          example: unverified
        retryAfter:
          type: integer
          description: If either `checkpoint` or `signature` is `unverified` status, then the server may instruct the client to retry the request after the specified number of seconds.
          example: 60