openapi: 3.1.0
info:
  title: HardState API
  version: "1"
  summary: Public API for HardState Logs, receipts and Bitcoin anchors.
  description: |
    Reads are open and keyless. Writes need no API key: an event is accepted only if it extends its issuer's log and is
    signed by a key that log authorizes. Never trust this API's answers on their own: verify the returned HardState
    Proof locally (`@hardstate/receipt` `verifyReceipt`, format: https://github.com/Zevlat-Intelligence/hardstate-standard/blob/main/FORMAT.md)
    against Bitcoin.
  license: { name: HardState Terms, url: "https://app.hardstate.net/terms" }
servers:
  - url: https://api.hardstate.net
  - url: http://localhost:8787
tags:
  - name: logs
  - name: proofs
  - name: bitcoin
  - name: documents
  - name: billing
  - name: reports
  - name: ai
    description: Records of AI systems (the `ai.*` vocabulary)

paths:
  /v1/health:
    get: { summary: Liveness and anchoring network, responses: { "200": { description: OK } } }
  /v1/stats:
    get: { summary: Counts, last batch, last anchor, responses: { "200": { description: OK } } }
  /v1/coverage:
    get:
      summary: HardState Coverage Index
      description: Totals, map points and each institution's score (identity, activity, anchoring), from public data only.
      responses: { "200": { description: OK } }
  /v1/activity:
    get:
      summary: Latest events, across issuers or filtered by issuer and/or signer
      parameters:
        - { name: issuer, in: query, schema: { type: string } }
        - { name: actor, in: query, description: Signing key id, schema: { type: string } }
        - { name: limit, in: query, schema: { type: integer, maximum: 200, default: 30 } }
      responses:
        "200":
          description: >-
            { events: EventRow[] }. Each row carries where the event is on its way to Bitcoin: batch, otsStatus,
            otsHeight, anchor, anchorStatus, anchorHeight, plus batchClosedAt (ISO 8601), otsTime and anchorTime
            (block times, unix seconds), null until reached.

  /v1/issuers:
    get: { tags: [logs], summary: All issuers with their head and domain verification, responses: { "200": { description: OK } } }
  /v1/issuers/{id}:
    get:
      tags: [logs]
      summary: Profile, keys (as declared in the log, each with its department now), departments, head and cases
      description: |
        Departments: `depts: [{ id, name, parent, types, addedAt, closedAt }]` (`parent` nests one inside
        another, up to 4 levels); each key's `dept` reflects key.move. `genesis` is the hash of entry #0, which the domain
        link names. `brand` ({ domain, logo?, color? }) is what the issuer's receipts show: set on paid plans once the
        domain is linked, from the signed profile's `brand`, with the logo only when the linked domain serves it.
      parameters: [{ $ref: "#/components/parameters/issuer" }]
      responses: { "200": { description: OK }, "404": { $ref: "#/components/responses/Error" } }
  /v1/issuers/{id}/log:
    get:
      tags: [logs]
      summary: The signed HardState Log, in order (for completeness audits)
      parameters:
        - { $ref: "#/components/parameters/issuer" }
        - { name: from, in: query, schema: { type: integer, default: 0 } }
        - { name: limit, in: query, schema: { type: integer, default: 1000, maximum: 5000 } }
      responses:
        "200":
          description: Page of signed events; follow `next` until null.
          content:
            application/json:
              schema:
                type: object
                properties:
                  issuer: { type: string }
                  head: { type: object, properties: { seq: { type: integer }, hash: { $ref: "#/components/schemas/Hash" } } }
                  events: { type: array, items: { $ref: "#/components/schemas/SignedEvent" } }
                  next: { type: [integer, "null"] }
  /v1/issuers/{id}/cases/{case}:
    get:
      tags: [logs]
      summary: All events of one case
      parameters: [{ $ref: "#/components/parameters/issuer" }, { name: case, in: path, required: true, schema: { type: string } }]
      responses: { "200": { description: OK }, "404": { $ref: "#/components/responses/Error" } }
  /v1/issuers/{id}/signers:
    get:
      tags: [logs]
      summary: Every key the log declares, with its activity
      description: |
        Per key: the KeyInfo fields plus addedAt / revokedAt (seq), delegatedBy, expiresAt, and count, count7d, lastAt,
        cases (distinct cases signed) and rejected7d (see /rejections). Keys that never signed have count 0.
      parameters: [{ $ref: "#/components/parameters/issuer" }]
      responses: { "200": { description: "{ issuer, signers: Signer[] }" }, "404": { $ref: "#/components/responses/Error" } }
  /v1/issuers/{id}/rejections:
    get:
      tags: [logs]
      summary: How many writes this API refused for the issuer in the last 7 days
      description: A health signal, not evidence. The detail is for the institution's own people (`rejections/read`).
      parameters: [{ $ref: "#/components/parameters/issuer" }]
      responses:
        "200": { description: "{ issuer, refused7d }" }
        "404": { $ref: "#/components/responses/Error" }
  /v1/issuers/{id}/rejections/read:
    post:
      tags: [logs]
      summary: The refused writes that claimed one of the issuer's keys, signed by someone of the institution
      description: |
        `op: "rejections.read"`, signed by a person of the institution or a session they opened; `params` may carry
        `key` and `limit` (≤ 500). A rejected event proves nothing about who sent it, so `key` is only the signer it
        claimed; claims by unknown keys are only counted. Codes: stale_head, bad_signature, revoked_key, expired,
        out_of_scope, not_allowed, malformed, doc_mismatch, invalid.
      parameters: [{ $ref: "#/components/parameters/issuer" }]
      requestBody: { required: true, content: { application/json: { schema: { $ref: "#/components/schemas/SignedOperatorRequest" } } } }
      responses:
        "200": { description: "{ issuer, rejections: [{ at, key, type, code, message }], last7d: { <key>: { total, byCode } }, unknownKeys7d, refused7d }" }
        "403": { $ref: "#/components/responses/Error" }
  /v1/issuers/{id}/batches:
    get:
      tags: [logs]
      summary: The batches holding the issuer's events, one row per batch
      description: |
        A batch closes over everything queued, so it holds a contiguous run of each issuer's seqs: `from`–`to` places
        every event in it without listing them. `otsTime` and `anchorTime` are block times (unix seconds), null until
        the block is reached. Events received since `since` (default: 31 days ago).
      parameters:
        - { $ref: "#/components/parameters/issuer" }
        - { name: since, in: query, description: ISO 8601, schema: { type: string } }
      responses:
        "200": { description: "{ issuer, since, batches: [{ id, closedAt, from, to, n, otsStatus, otsHeight, otsTime, anchor, anchorStatus, anchorHeight, anchorTime }] }" }
        "404": { $ref: "#/components/responses/Error" }
  /v1/issuers/{id}/flow:
    get:
      tags: [logs]
      summary: Recent steps and batches as compact columns (the console overview's chart)
      description: |
        Steps from `seq0` on, contiguous: `t` (seconds from `base`), `s` (index into `signers`), `y` (index into
        `types`). `batches` are `[closed, from, to, n, blockHeight, blockTime, stage]` (unix seconds; stage 1 batched,
        2 on Bitcoin through OpenTimestamps, 3 anchored), the block being the first one the batch reached. With `after`,
        only steps past that seq; `bsince` limits batches to those whose events arrived since then.
      parameters:
        - { $ref: "#/components/parameters/issuer" }
        - { name: since, in: query, description: "ISO 8601 (default: 31 days ago)", schema: { type: string } }
        - { name: after, in: query, description: Only steps with a higher seq, schema: { type: integer } }
        - { name: bsince, in: query, description: "ISO 8601 (default: since)", schema: { type: string } }
      responses:
        "200": { description: "{ issuer, head, since, seq0, base, t, s, y, signers, types, batches }" }
        "404": { $ref: "#/components/responses/Error" }
  /v1/issuers/{id}/find:
    get:
      tags: [logs]
      summary: What an id is, within one institution
      description: |
        Matches a key's public code or id, a department (id or name), a case, or an event (hash or `#seq`). Public, like
        everything it can find: it never knows anyone's name.
      parameters:
        - { $ref: "#/components/parameters/issuer" }
        - { name: q, in: query, required: true, schema: { type: string, maxLength: 200 } }
      responses:
        "200": { description: "{ issuer, q, matches: [{ kind: event|key|dept|case, … }] }" }
        "400": { $ref: "#/components/responses/Error" }
        "404": { $ref: "#/components/responses/Error" }
  /v1/issuers/{id}/ai:
    get:
      tags: [ai]
      summary: The records of the institution's AI systems, with their public part
      description: |
        `ai.decision`, `ai.run`, `ai.review` and `ai.heartbeat` events, in order, each with its
        `public` object and how many documents it commits to. Contents are never here: inputs and outputs are salted
        commitments the institution keeps. With `case`, one case's AI records whatever their age; otherwise those
        received since `since` (default: 31 days ago).
      parameters:
        - { $ref: "#/components/parameters/issuer" }
        - { name: since, in: query, description: ISO 8601, schema: { type: string } }
        - { name: case, in: query, schema: { type: string } }
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  issuer: { type: string }
                  since: { type: string }
                  case: { type: string }
                  truncated: { type: boolean, description: "More than 20,000 records in the period (1,000 for a case)" }
                  events:
                    type: array
                    items:
                      type: object
                      properties:
                        hash: { $ref: "#/components/schemas/Hash" }
                        seq: { type: integer }
                        type: { type: string, enum: [ai.decision, ai.run, ai.review, ai.heartbeat] }
                        case: { type: [string, "null"] }
                        ts: { type: string }
                        actor: { type: string }
                        receivedAt: { type: string }
                        public: { type: object }
                        docs: { type: integer }
        "404": { $ref: "#/components/responses/Error" }
  /v1/issuers/{id}/directory/read:
    post:
      tags: [logs]
      summary: The private names of the institution's people (operator request directory.read)
      description: |
        The log never carries names: a person's key has a public code and a salted `holder` commitment. The
        names live in a private directory that any of the institution's people (or a session of theirs) can read with a
        signed operator request. Never public.
      parameters: [{ $ref: "#/components/parameters/issuer" }]
      requestBody: { required: true, content: { application/json: { schema: { $ref: "#/components/schemas/SignedOperatorRequest" } } } }
      responses:
        "200": { description: "{ issuer, entries: [{ keyId, code, name }] }" }
        "403": { description: Not signed by one of the institution's live keys }
  /v1/issuers/{id}/directory/write:
    post:
      tags: [logs]
      summary: Attach a person's name to their key (operator request directory.write; params keyId, name, salt)
      description: |
        Signed by an institution admin, or a department head for their branch. The name and the 16-byte hex salt must
        open the key's `holder` commitment, so the directory can only say what the log already commits to.
      parameters: [{ $ref: "#/components/parameters/issuer" }]
      requestBody: { required: true, content: { application/json: { schema: { $ref: "#/components/schemas/SignedOperatorRequest" } } } }
      responses:
        "200": { description: "{ keyId, code }" }
        "400": { description: Missing name or malformed salt }
        "403": { description: Not an admin, or a head outside their branch }
        "422": { description: "The name and salt do not open the key's holder commitment" }
  /v1/issuers/{id}/verify-domain:
    post:
      tags: [logs]
      summary: Link a domain
      description: |
        The domain must be the `website` the issuer's signed profile declares, and must name the log either at
        https://<domain>/.well-known/hardstate.json ({ issuer, genesis }) or in a TXT record
        `_hardstate.<domain>` = "issuer=<id> genesis=<hash>". Otherwise 422, with what to publish: `step: "website"`
        (declare it first, with issuer.update) or `step: "link"` with `file: { url, body }` and `dns: { name, type, value }`.
        Rate-limited per address (429).
      parameters: [{ $ref: "#/components/parameters/issuer" }]
      requestBody: { content: { application/json: { schema: { type: object, required: [domain], properties: { domain: { type: string } } } } } }
      responses: { "200": { description: "{ verified: domain, via: well-known | dns }" }, "422": { $ref: "#/components/responses/Error" }, "429": { $ref: "#/components/responses/Error" } }

  /v1/events/prepare:
    post:
      tags: [logs]
      summary: Prepare the next event on the live head, for integration in any language
      description: |
        Returns the exact event (with seq, prev and ts filled in), its RFC 8785 canonical form and the 32-byte hash to
        sign with Ed25519. Nothing is stored. Compare `event` with what you sent, sign `hash`, then POST /v1/events.
        See docs/integration/README.md.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [issuer, type, actor]
              properties:
                issuer: { type: string }
                type: { type: string }
                case: { type: string }
                public: { type: object }
                docs: { type: array, items: { type: object } }
                actor: { type: string }
                ts: { type: string, format: date-time }
      responses:
        "200":
          description: Prepared event
          content:
            application/json:
              schema:
                type: object
                properties:
                  event: { $ref: "#/components/schemas/Event" }
                  canonical: { type: string }
                  hash: { $ref: "#/components/schemas/Hash" }
                  challenge: { type: string, description: base64url of hash (the WebAuthn challenge for passkeys) }
        "404": { description: Unknown issuer (and type is not issuer.create) }
        "422": { description: Malformed event }
  /v1/events:
    post:
      tags: [logs]
      summary: Append a signed event to its issuer's log
      description: |
        `seq` must be head+1 and `prev` the head hash. On 409 the head moved: rebuild on the returned head and sign again
        (`HardStateClient.append` does this). `publish` lists documents whose salt and digest are revealed (then PUT the
        file to /v1/docs/{commitment}).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - { $ref: "#/components/schemas/SignedEvent" }
                - type: object
                  properties:
                    publish:
                      type: array
                      items: { type: object, required: [commitment, digest, salt], properties: { commitment: { $ref: "#/components/schemas/Hash" }, digest: { $ref: "#/components/schemas/Hash" }, salt: { $ref: "#/components/schemas/Hash" } } }
      responses:
        "201": { description: "{ hash, issuer, seq, status: queued, proof, receipt }" }
        "402": { description: "The plan's monthly fair-use limit is spent (10% grace); issuer.*, key.* and session.* events still go through: { error, plan, limit, records, upgrade }" }
        "404": { description: Issuer does not exist and the event is not issuer.create }
        "409": { description: "The log head moved: { error, head }" }
        "422": { description: Shape, chain, authorization or signature check failed }
        "429": { description: Rate limited }
  /v1/events/{hash}:
    get:
      tags: [logs]
      summary: One signed event, its pipeline status, published documents and the issuer's receipt `brand` (or null)
      parameters: [{ $ref: "#/components/parameters/hash" }]
      responses: { "200": { description: OK }, "404": { $ref: "#/components/responses/Error" } }

  /v1/proofs/{hash}:
    get:
      tags: [proofs]
      summary: HardState Proof for an event or a stamp
      parameters: [{ $ref: "#/components/parameters/hash" }]
      responses:
        "200":
          description: "{ proof: HardStateProof, status: queued|batched|timestamped|anchored, batch?, anchor?, receipt? }"
        "404": { $ref: "#/components/responses/Error" }
  /v1/issuers/{id}/absence:
    get:
      tags: [proofs]
      summary: Proof of Absence — nothing of a kind about an id was recorded, as of an entry of the institution's log
      description: |
        `kind=review` (id: an AI decision's hash) proves no human review of it; `kind=revoke` (id: a key id) proves no
        revocation of that key or closing of that session; `kind=doc` (id: a document commitment) proves no record of
        it. The answer names the log entry it holds for and is sealed on Bitcoin like any record: check it with
        `verifyAbsence` (`@hardstate/receipt`, HardState Receipt Format). When the thing was recorded, the answer is a
        409 with the entry that recorded it.
      parameters:
        - { $ref: "#/components/parameters/issuer" }
        - { name: kind, in: query, required: true, schema: { type: string, enum: [review, revoke, doc] } }
        - { name: id, in: query, required: true, schema: { type: string, maxLength: 200 } }
      responses:
        "200": { description: "AbsenceProof: { hardstate: absence, hss: 1, issuer, asOf: { seq, hash }, query, gap, index, batch, ots?, anchor?, issuedAt }" }
        "400": { $ref: "#/components/responses/Error" }
        "404": { $ref: "#/components/responses/Error" }
        "409": { description: "It was recorded: { error, seq, hash }" }
  /v1/stamp:
    post:
      tags: [proofs]
      summary: Anchor a bare SHA-256 digest (no account)
      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [digest], properties: { digest: { $ref: "#/components/schemas/Hash" } } } } } }
      responses: { "201": { description: "{ hash, status, proof, verify }" }, "429": { description: Rate limited } }

  /v1/batches:
    get: { tags: [bitcoin], summary: Recent batches with OpenTimestamps status, responses: { "200": { description: OK } } }
  /v1/batches/{id}:
    get: { tags: [bitcoin], summary: One batch with its ordered leaf list, parameters: [{ name: id, in: path, required: true, schema: { type: string } }], responses: { "200": { description: OK } } }
  /v1/batches/{id}/ots:
    get:
      tags: [bitcoin]
      summary: Detached .ots for the batch root (verify with `ots verify -d <root> <file>`)
      parameters: [{ name: id, in: path, required: true, schema: { type: string } }]
      responses: { "200": { description: OpenTimestamps proof, content: { application/vnd.opentimestamps.v1: {} } } }
  /v1/anchors:
    get: { tags: [bitcoin], summary: HardState Anchor transactions, responses: { "200": { description: OK } } }
  /v1/anchors/{id}:
    get: { tags: [bitcoin], summary: One anchor and its batches, parameters: [{ name: id, in: path, required: true, schema: { type: string } }], responses: { "200": { description: OK } } }
  /v1/anchors/express:
    post:
      tags: [bitcoin, billing]
      summary: Anchor now at the next-block fee, from the plan's monthly allowance (operator request anchor.express)
      requestBody: { required: true, content: { application/json: { schema: { $ref: "#/components/schemas/SignedOperatorRequest" } } } }
      responses:
        "201": { description: Broadcast (txid, feeSats, remaining) }
        "200": { description: "An express anchor sent in the last 15 minutes already covers the issuer's records ({ shared, txid, remaining })" }
        "202": { description: "Fees are above PLAN_EXPRESS_MAX_FEE_RATE: deferred to the next hourly or daily anchor, not counted ({ deferred, remaining })" }
        "402": { description: Not in the plan, or this month's allowance is used }
        "403": { description: Not signed by a live admin key of the issuer }

  /v1/plans:
    get: { tags: [billing], summary: "Plans institutions can buy (citizens never pay): limits, prices per interval and currency, features", responses: { "200": { description: "{ plans[], billing, testMode }" } } }
  /v1/issuers/{id}/account:
    get:
      tags: [billing]
      summary: "The issuer's plan, this month's usage (records, express anchors, open departments) and limits (departments: null = unlimited)"
      parameters: [{ $ref: "#/components/parameters/issuer" }]
      responses: { "200": { description: OK }, "404": { $ref: "#/components/responses/Error" } }
  /v1/operator:
    get:
      tags: [reports]
      summary: "The operator's public report key (an Ed25519 KeyInfo), which signs audit reports; null when reports are off"
      responses: { "200": { description: "{ url, reportKey }" } }
  /v1/issuers/{id}/reports:
    get:
      tags: [reports]
      summary: "The months and quarters the issuer can get a report for, which its plan includes, which are ready and which exist"
      parameters: [{ $ref: "#/components/parameters/issuer" }]
      responses: { "200": { description: "{ plan, monthly, quarterly, periods[{ period, kind, from, to, ready, included, hash }] }" }, "404": { $ref: "#/components/responses/Error" } }
  /v1/issuers/{id}/reports/{period}:
    get:
      tags: [reports]
      summary: A signed HardState Audit Report (core report.ts) for a month (2026-10) or a quarter (2026-Q4)
      description: |
        Monthly on Professional and above, quarterly on Institution and above (402 otherwise). Made on the first request
        a day after the period closes (409 before), then served unchanged. Every figure is recomputable from the public
        log; the operator signs sha256("hardstate/report/v1" ‖ JCS(report)) with the key at /v1/operator, and that hash is
        stamped on Bitcoin like a citizen's stamp (/v1/proofs/{hash}). Anyone can check it at app.hardstate.net/reports/{id}/{period}.
      parameters:
        - { $ref: "#/components/parameters/issuer" }
        - { name: period, in: path, required: true, schema: { type: string, pattern: "^\\d{4}-(0[1-9]|1[0-2]|Q[1-4])$" } }
      responses:
        "200": { description: "{ report, sig }" }
        "400": { $ref: "#/components/responses/Error" }
        "402": { $ref: "#/components/responses/Error" }
        "409": { $ref: "#/components/responses/Error" }
        "503": { $ref: "#/components/responses/Error" }
  /v1/billing/checkout:
    post:
      tags: [billing]
      summary: "Stripe Checkout URL for a self-serve plan (operator request billing.checkout; params: plan, interval)"
      requestBody: { required: true, content: { application/json: { schema: { $ref: "#/components/schemas/SignedOperatorRequest" } } } }
      responses: { "200": { description: "{ url }" }, "403": { description: Not a live admin key }, "409": { description: Nonce reused, or already subscribed }, "503": { description: Billing not configured on this node } }
  /v1/billing/invoice:
    post:
      tags: [billing]
      summary: "A subscription billed by invoice, net 30, payable by bank transfer (billing.invoice; params: plan, interval, email, name, address, taxId?, po?)"
      requestBody: { required: true, content: { application/json: { schema: { $ref: "#/components/schemas/SignedOperatorRequest" } } } }
      responses: { "201": { description: "{ invoice, url, pdf, dueInDays, email }" } }
  /v1/billing/portal:
    post:
      tags: [billing]
      summary: Stripe Customer Portal URL (billing.portal)
      requestBody: { required: true, content: { application/json: { schema: { $ref: "#/components/schemas/SignedOperatorRequest" } } } }
      responses: { "200": { description: "{ url }" }, "404": { description: No billing account yet } }

  /v1/keys/{id}:
    get: { tags: [logs], summary: A signing key and its issuer, parameters: [{ name: id, in: path, required: true, schema: { type: string } }], responses: { "200": { description: OK }, "404": { $ref: "#/components/responses/Error" } } }

  /v1/docs/{commitment}:
    put:
      tags: [documents]
      summary: Upload a published document (its SHA-256 must match the published digest)
      parameters: [{ $ref: "#/components/parameters/commitment" }]
      requestBody: { required: true, content: { application/octet-stream: {} } }
      responses: { "200": { description: Stored }, "413": { description: Over 25 MB }, "422": { description: Digest mismatch } }
    get:
      tags: [documents]
      summary: Download a published document (salt and digest in X-HardState-Salt / X-HardState-Digest)
      parameters: [{ $ref: "#/components/parameters/commitment" }]
      responses: { "200": { description: The file }, "404": { $ref: "#/components/responses/Error" } }
  /v1/lookup/{digest}:
    get:
      tags: [documents]
      summary: Published documents (and stamps) with this plain SHA-256
      parameters: [{ name: digest, in: path, required: true, schema: { $ref: "#/components/schemas/Hash" } }]
      responses: { "200": { description: "{ digest, documents[], stamped }" } }

components:
  parameters:
    issuer: { name: id, in: path, required: true, schema: { type: string, pattern: "^[a-z0-9][a-z0-9-]{1,62}[a-z0-9]$" } }
    hash: { name: hash, in: path, required: true, schema: { $ref: "#/components/schemas/Hash" } }
    commitment: { name: commitment, in: path, required: true, schema: { $ref: "#/components/schemas/Hash" } }
  responses:
    Error:
      description: Error
      content: { application/json: { schema: { type: object, properties: { error: { type: string } } } } }
  schemas:
    Hash: { type: string, pattern: "^[0-9a-f]{64}$" }
    KeyInfo:
      type: object
      required: [id, kind, alg, publicKey, role, label]
      properties:
        id: { type: string }
        kind: { enum: [passkey, ed25519] }
        alg: { enum: [-7, -257, -8] }
        publicKey: { type: string, description: SPKI DER, base64url }
        role: { enum: [admin, official, system, session] }
        label: { type: string }
        rpId: { type: string }
        scope:
          type: object
          properties:
            types: { type: array, items: { type: string }, description: 'exact types or "domain.*"' }
            expires: { type: string, format: date-time }
    Event:
      type: object
      additionalProperties: false
      required: [hss, issuer, seq, prev, type, ts, public, docs, actor]
      properties:
        hss: { const: 1 }
        issuer: { type: string }
        seq: { type: integer, minimum: 0 }
        prev: { oneOf: [{ $ref: "#/components/schemas/Hash" }, { type: "null" }] }
        type: { type: string }
        case: { type: string, maxLength: 128 }
        ts: { type: string, format: date-time }
        public: { type: object }
        docs:
          type: array
          items: { type: object, required: [label, commitment], properties: { label: { type: string }, commitment: { $ref: "#/components/schemas/Hash" }, mime: { type: string }, size: { type: integer } } }
        actor: { type: string }
    Signature:
      oneOf:
        - type: object
          required: [kind, authenticatorData, clientDataJSON, signature]
          properties: { kind: { const: passkey }, authenticatorData: { type: string }, clientDataJSON: { type: string }, signature: { type: string } }
        - type: object
          required: [kind, signature]
          properties: { kind: { const: ed25519 }, signature: { type: string } }
    SignedOperatorRequest:
      type: object
      description: |
        Not a log event: an admin's instruction to the operator. The signed hash is
        sha256("hardstate/operator/v1" ‖ JCS(request)); accepted within 5 minutes of ts, once per nonce, from a live
        admin key of the issuer.
      required: [request, sig]
      properties:
        request:
          type: object
          required: [op, issuer, key, ts, nonce]
          properties:
            op: { enum: [billing.checkout, billing.invoice, billing.portal, anchor.express] }
            issuer: { type: string }
            key: { type: string, description: The signing admin key id }
            ts: { type: string, format: date-time }
            nonce: { type: string, description: 16 random bytes, base64url }
            params: { type: object }
        sig: { $ref: "#/components/schemas/Signature" }
    SignedEvent:
      type: object
      required: [event, sig]
      properties: { event: { $ref: "#/components/schemas/Event" }, sig: { $ref: "#/components/schemas/Signature" } }
