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
x-42c-no-authentication: true
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