was-teaching-server 0.9.1

package/src/lib/kmsRecordCipher.ts

@@ -0,0 +1,292 @@
+/**
+ * At-rest cipher for WebKMS key records (`KMS_RECORD_KEK`, the optional
+ * hardening increment). Envelope-encrypts the
+ * secret-bearing fields of a stored key so a disk/database dump exposes only
+ * ciphertext and a `kekId`, while the wire projection (`KmsKeyDescription`) and
+ * the whole authorization model stay byte-for-byte identical.
+ *
+ * The design mirrors bedrock's `@bedrock/record-cipher`: a deny-by-default field
+ * split (an explicit plaintext allowlist; every other `key` field is a secret),
+ * a fresh per-record content-encryption key (`A256GCM`) wrapped (`A256KW`) under
+ * a config-supplied AES-256 KEK, and a per-record `kekId` so a rotated-in KEK
+ * never forces a rewrite. It reuses the same `node:crypto` primitives the KMS
+ * module already relies on for AES-KW (`id-aes256-wrap`), so no new crypto
+ * dependency is introduced.
+ *
+ * This module is pure and backend-agnostic: KEK(s) are injected (no env reads
+ * here), and it neither touches storage nor knows about Fastify. The
+ * orchestration seam (`src/requests/KeyRequest.ts`) applies it around the
+ * backend's `insertKey` / `getKey`.
+ */
+import {
+  createCipheriv,
+  createDecipheriv,
+  createHash,
+  randomBytes
+} from 'node:crypto'
+import { IdDecoder } from '@digitalcredentials/bnid'
+import type {
+  KmsEncryptedEnvelope,
+  KmsKeyRecord,
+  KmsStoredKey,
+  RecordKek,
+  KmsRecordKekRegistry
+} from '../types.js'
+
+/**
+ * The plaintext allowlist: the `KmsStoredKey` fields that stay in the clear (and
+ * queryable) at rest. EVERY other field of `key` -- `privateKeyMultibase`,
+ * `secret`, and any secret-bearing field added later -- is swept into the
+ * envelope, so new secrets are protected by default unless explicitly added
+ * here. (Bedrock additionally lists `controller`; this server never stores
+ * `controller` on the key -- it is read from the live keystore config at
+ * description time -- so it is simply absent.)
+ */
+export const PLAINTEXT_KEY_FIELDS: ReadonlySet<string> = new Set([
+  '@context',
+  'id',
+  'type',
+  'publicKeyMultibase',
+  'maxCapabilityChainLength',
+  'publicAlias',
+  'publicAliasTemplate'
+])
+
+/**
+ * The Multikey header for an AES-256 symmetric key (`0xa2 0x01`, the multicodec
+ * varint for `aes-256`), the two bytes a `KMS_RECORD_KEK` multibase value
+ * carries before its 32 key bytes -- matching bedrock's KEK encoding.
+ */
+const AES_256_MULTIKEY_HEADER = Buffer.from([0xa2, 0x01])
+
+/** Content-encryption algorithm: AES-256-GCM (`A256GCM`). */
+const CEK_ALGORITHM = 'aes-256-gcm'
+/** GCM initialization-vector length in bytes (96-bit, per the JWE `A256GCM` profile). */
+const GCM_IV_BYTES = 12
+/**
+ * Key-wrap algorithm: AES Key Wrap (RFC 3394) with a 256-bit KEK (`A256KW`),
+ * the same primitive the KMS module uses for its AES-KW key type. Its default
+ * IV is the RFC's `0xA6` octet repeated eight times; the wrap is integrity-
+ * checked, so a wrong KEK throws on unwrap.
+ */
+const KEK_WRAP_ALGORITHM = 'id-aes256-wrap'
+const KEK_WRAP_DEFAULT_IV = Buffer.alloc(8, 0xa6)
+
+/**
+ * Derives a KEK's non-secret, stable id from its raw key bytes: a SHA-256 digest
+ * (one-way, so storing it per record leaks nothing about the key). Self-
+ * describing and deterministic, so a rotated-in KEK gets a stable id from its
+ * material alone -- the convention bedrock follows.
+ * @param key {Buffer}   the 32-byte AES-256 KEK
+ * @returns {string}   the derived `urn:kek:sha256:<hex>` id
+ */
+export function deriveKekId(key: Buffer): string {
+  return `urn:kek:sha256:${createHash('sha256').update(key).digest('hex')}`
+}
+
+/**
+ * Parses a `secretKeyMultibase` (base58btc Multikey) AES-256 KEK into a
+ * `RecordKek` (its raw key plus a derived id). Throws a plain `Error` on a
+ * malformed value -- callers are config parsing (fails startup) and tests, not
+ * the request path. The error messages name `label` (the offending config
+ * variable, e.g. a `KMS_RECORD_KEKS entry N` position) but NEVER echo the secret
+ * value itself.
+ * @param secretKeyMultibase {string}   the multibase (`z...`) KEK value
+ * @param [label] {string}   the config source named in error messages
+ *   (defaults to `KMS_RECORD_KEK`)
+ * @returns {RecordKek}
+ */
+export function parseKekMultibase(
+  secretKeyMultibase: string,
+  label = 'KMS_RECORD_KEK'
+): RecordKek {
+  const decoder = new IdDecoder({ encoding: 'base58', multibase: true })
+  let decoded: Buffer
+  try {
+    decoded = Buffer.from(decoder.decode(secretKeyMultibase))
+  } catch {
+    throw new Error(`${label} is not a valid multibase (base58btc) value.`)
+  }
+  if (!decoded.subarray(0, 2).equals(AES_256_MULTIKEY_HEADER)) {
+    throw new Error(
+      `${label} must carry the AES-256 Multikey header (0xa2 0x01).`
+    )
+  }
+  const key = decoded.subarray(2)
+  if (key.length !== 32) {
+    throw new Error(
+      `${label} must be a 256-bit (32-byte) key; got ${key.length} bytes.`
+    )
+  }
+  return { id: deriveKekId(key), key }
+}
+
+/**
+ * The KEK that wraps NEW records, or `undefined` when encryption is disabled
+ * (no registry, or `currentKekId: null`).
+ * @param [registry] {KmsRecordKekRegistry}
+ * @returns {RecordKek | undefined}
+ */
+export function currentRecordKek(
+  registry?: KmsRecordKekRegistry
+): RecordKek | undefined {
+  if (registry === undefined || registry.currentKekId === null) {
+    return undefined
+  }
+  return registry.keks.get(registry.currentKekId)
+}
+
+/**
+ * A KEK-lookup function over a registry, resolving a record's stored `kekId` to
+ * its `RecordKek` for decryption (`undefined` when the KEK is not registered, or
+ * there is no registry at all). The decrypt seam for the pass-through /
+ * rotation upgrade paths.
+ * @param [registry] {KmsRecordKekRegistry}
+ * @returns {(kekId: string) => RecordKek | undefined}
+ */
+export function recordKekLoader(
+  registry?: KmsRecordKekRegistry
+): (kekId: string) => RecordKek | undefined {
+  return (kekId: string) => registry?.keks.get(kekId)
+}
+
+/**
+ * Encrypts the secret-bearing fields of a key record under a KEK, returning a
+ * record whose `key` carries the allowlisted plaintext fields plus an
+ * `encrypted` envelope in place of the secrets. Pure: the KEK is injected, no
+ * storage or env access. The record's non-`key` members (`keystoreId`,
+ * `localId`, `meta`) are unchanged.
+ * @param options {object}
+ * @param options.record {KmsKeyRecord}   the plaintext (secret-bearing) record
+ * @param options.kek {RecordKek}   the KEK to wrap the fresh CEK under
+ * @returns {KmsKeyRecord}   the at-rest record (secrets replaced by `encrypted`)
+ */
+export function encryptKeyRecord({
+  record,
+  kek
+}: {
+  record: KmsKeyRecord
+  kek: RecordKek
+}): KmsKeyRecord {
+  const publicFields: Record<string, unknown> = {}
+  const secretFields: Record<string, unknown> = {}
+  for (const [field, value] of Object.entries(record.key)) {
+    if (PLAINTEXT_KEY_FIELDS.has(field)) {
+      publicFields[field] = value
+    } else {
+      secretFields[field] = value
+    }
+  }
+
+  const plaintext = Buffer.from(JSON.stringify(secretFields), 'utf8')
+
+  // Fresh per-record content-encryption key (CEK), A256GCM. The `protected`
+  // header doubles as the GCM additional-authenticated-data (AAD), per JWE.
+  const cek = randomBytes(32)
+  const iv = randomBytes(GCM_IV_BYTES)
+  const protectedHeader = Buffer.from(
+    JSON.stringify({ enc: 'A256GCM' }),
+    'utf8'
+  ).toString('base64url')
+  const cipher = createCipheriv(CEK_ALGORITHM, cek, iv)
+  cipher.setAAD(Buffer.from(protectedHeader, 'ascii'))
+  const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()])
+  const tag = cipher.getAuthTag()
+
+  // Wrap the CEK under the KEK (A256KW / RFC 3394).
+  const wrap = createCipheriv(KEK_WRAP_ALGORITHM, kek.key, KEK_WRAP_DEFAULT_IV)
+  const wrappedCek = Buffer.concat([wrap.update(cek), wrap.final()])
+
+  const encrypted: KmsEncryptedEnvelope = {
+    kekId: kek.id,
+    jwe: {
+      protected: protectedHeader,
+      recipients: [
+        {
+          header: { alg: 'A256KW', kid: kek.id },
+          encrypted_key: wrappedCek.toString('base64url')
+        }
+      ],
+      iv: iv.toString('base64url'),
+      ciphertext: ciphertext.toString('base64url'),
+      tag: tag.toString('base64url')
+    },
+    encoding: 'json'
+  }
+
+  return {
+    ...record,
+    key: { ...publicFields, encrypted } as unknown as KmsStoredKey
+  }
+}
+
+/**
+ * Decrypts a key record: pass-through when `key.encrypted` is absent (a
+ * plaintext record -- the default, and the pass-through upgrade path), else
+ * looks up the KEK by the record's stored `kekId`, unwraps the CEK, decrypts the
+ * secret subset, and splices the secret fields back onto the allowlisted ones
+ * (dropping the envelope). Pure: KEK(s) injected via `kekLoader`, no storage or
+ * env access. Throws a plain `Error` when the record's KEK is not registered or
+ * the ciphertext fails to authenticate; the request seam wraps that as a 500.
+ * @param options {object}
+ * @param options.record {KmsKeyRecord}   the at-rest (or plaintext) record
+ * @param options.kekLoader {(kekId: string) => RecordKek | undefined}   KEK lookup
+ * @returns {KmsKeyRecord}   the decrypted record (secrets restored on `key`)
+ */
+export function decryptKeyRecord({
+  record,
+  kekLoader
+}: {
+  record: KmsKeyRecord
+  kekLoader: (kekId: string) => RecordKek | undefined
+}): KmsKeyRecord {
+  const { encrypted } = record.key
+  if (encrypted === undefined) {
+    // Plaintext record: unconditional pass-through (so enabling a KEK on an
+    // existing plaintext tree leaves old records readable).
+    return record
+  }
+
+  const kek = kekLoader(encrypted.kekId)
+  if (kek === undefined) {
+    throw new Error(
+      `No KEK registered for kekId "${encrypted.kekId}"; ` +
+        'cannot decrypt WebKMS key record.'
+    )
+  }
+  const { jwe } = encrypted
+
+  // Unwrap the CEK (A256KW), then decrypt the secret subset (A256GCM). Both
+  // steps authenticate: a wrong KEK fails the RFC 3394 integrity check, and a
+  // tampered ciphertext fails the GCM tag.
+  const wrappedCek = Buffer.from(jwe.recipients[0]!.encrypted_key, 'base64url')
+  const unwrap = createDecipheriv(
+    KEK_WRAP_ALGORITHM,
+    kek.key,
+    KEK_WRAP_DEFAULT_IV
+  )
+  const cek = Buffer.concat([unwrap.update(wrappedCek), unwrap.final()])
+
+  const decipher = createDecipheriv(
+    CEK_ALGORITHM,
+    cek,
+    Buffer.from(jwe.iv, 'base64url')
+  )
+  decipher.setAAD(Buffer.from(jwe.protected, 'ascii'))
+  decipher.setAuthTag(Buffer.from(jwe.tag, 'base64url'))
+  const plaintext = Buffer.concat([
+    decipher.update(Buffer.from(jwe.ciphertext, 'base64url')),
+    decipher.final()
+  ])
+  const secretFields = JSON.parse(plaintext.toString('utf8')) as Record<
+    string,
+    unknown
+  >
+
+  // Splice the secrets back onto the public fields, dropping the envelope.
+  const { encrypted: _envelope, ...publicFields } = record.key
+  return {
+    ...record,
+    key: { ...publicFields, ...secretFields } as KmsStoredKey
+  }
+}

package/src/lib/pagination.ts

@@ -0,0 +1,22 @@
+/**
+ * Shared page sizing for the List Collection operation's cursor-based
+ * pagination and the change feed (spec "Pagination"). Both storage backends
+ * clamp through these so an oversized `limit` behaves identically everywhere.
+ */
+
+/**
+ * Page sizing: `DEFAULT_PAGE_SIZE` applies when a request omits `limit`;
+ * `MAX_PAGE_SIZE` is the server maximum an oversized `limit` is clamped down to
+ * (rather than rejected).
+ */
+export const DEFAULT_PAGE_SIZE = 100
+export const MAX_PAGE_SIZE = 1000
+
+/**
+ * Clamps a requested `limit` to `[1, MAX_PAGE_SIZE]`.
+ * @param limit {number}
+ * @returns {number}
+ */
+export function clampPageSize(limit: number): number {
+  return Math.min(Math.max(Math.trunc(limit), 1), MAX_PAGE_SIZE)
+}

package/src/lib/paths.ts

@@ -0,0 +1,382 @@
+/**
+ * Single source of truth for the server's relative URL path templates. The route
+ * shapes registered in `routes.ts` (the `/spaces` repository, `/space/:spaceId`,
+ * `/space/:spaceId/:collectionId`, the `policy` / `linkset` auxiliary resources,
+ * and the `export` / `import` actions) are mirrored here as builder functions, so
+ * handlers, the policy code, and the storage backends construct the same paths
+ * from one place rather than re-deriving them inline (which risks drift from the
+ * routes).
+ *
+ * Builders return the canonical, no-trailing-slash member form by default. The
+ * spec assigns distinct meaning to a trailing slash -- it addresses the
+ * container / "list-or-add-to" view of a member -- so the container builders take
+ * an explicit `trailingSlash` option (or, for the always-container `/spaces/` and
+ * `.../collections/`, bake the slash in) rather than leaving the slash to drift
+ * across call sites. A leaf Resource has no children, so `resourcePath` has no
+ * container form.
+ */
+
+/**
+ * The SpacesRepository container (`/spaces/`) or one of its members
+ * (`/spaces/:spaceId`). The member form is used for the `Location` header of a
+ * newly created Space; the container form is the `POST`/`GET` target.
+ * @param options {object}
+ * @param [options.spaceId] {string}   when present, the repository member path;
+ *   otherwise the (trailing-slash) container path
+ * @returns {string}
+ */
+export function spacesPath({ spaceId }: { spaceId?: string } = {}): string {
+  return spaceId !== undefined ? `/spaces/${spaceId}` : `/spaces/`
+}
+
+/**
+ * `/space/:spaceId` (member) or `/space/:spaceId/` (container -- the
+ * "add a Collection" / Space-as-container view) when `trailingSlash` is set.
+ * @param options {object}
+ * @param options.spaceId {string}
+ * @param [options.trailingSlash] {boolean}   address the container form
+ * @returns {string}
+ */
+export function spacePath({
+  spaceId,
+  trailingSlash = false
+}: {
+  spaceId: string
+  trailingSlash?: boolean
+}): string {
+  return `/space/${spaceId}${trailingSlash ? '/' : ''}`
+}
+
+/**
+ * `/space/:spaceId/collections/` -- the "List Collections" container path.
+ * @param options {object}
+ * @param options.spaceId {string}
+ * @returns {string}
+ */
+export function collectionsPath({ spaceId }: { spaceId: string }): string {
+  return `${spacePath({ spaceId })}/collections/`
+}
+
+/**
+ * `/space/:spaceId/export` -- the "Export Space" action path.
+ * @param options {object}
+ * @param options.spaceId {string}
+ * @returns {string}
+ */
+export function exportPath({ spaceId }: { spaceId: string }): string {
+  return `${spacePath({ spaceId })}/export`
+}
+
+/**
+ * `/space/:spaceId/import` -- the "Import Space" action path.
+ * @param options {object}
+ * @param options.spaceId {string}
+ * @returns {string}
+ */
+export function importPath({ spaceId }: { spaceId: string }): string {
+  return `${spacePath({ spaceId })}/import`
+}
+
+/**
+ * `/space/:spaceId/:collectionId` (member) or `/space/:spaceId/:collectionId/`
+ * (container -- the "add a Resource" / "list items" view) when `trailingSlash`
+ * is set.
+ * @param options {object}
+ * @param options.spaceId {string}
+ * @param options.collectionId {string}
+ * @param [options.trailingSlash] {boolean}   address the container form
+ * @returns {string}
+ */
+export function collectionPath({
+  spaceId,
+  collectionId,
+  trailingSlash = false
+}: {
+  spaceId: string
+  collectionId: string
+  trailingSlash?: boolean
+}): string {
+  return `/space/${spaceId}/${collectionId}${trailingSlash ? '/' : ''}`
+}
+
+/**
+ * `/space/:spaceId/:collectionId/:resourceId`
+ * @param options {object}
+ * @param options.spaceId {string}
+ * @param options.collectionId {string}
+ * @param options.resourceId {string}
+ * @returns {string}
+ */
+export function resourcePath({
+  spaceId,
+  collectionId,
+  resourceId
+}: {
+  spaceId: string
+  collectionId: string
+  resourceId: string
+}): string {
+  return `/space/${spaceId}/${collectionId}/${resourceId}`
+}
+
+/**
+ * The `policy` auxiliary resource path for whichever level the ids address:
+ * Space (`spaceId`), Collection (`+ collectionId`), or Resource
+ * (`+ collectionId + resourceId`).
+ * @param options {object}
+ * @param options.spaceId {string}
+ * @param [options.collectionId] {string}
+ * @param [options.resourceId] {string}
+ * @returns {string}
+ */
+export function policyPath({
+  spaceId,
+  collectionId,
+  resourceId
+}: {
+  spaceId: string
+  collectionId?: string
+  resourceId?: string
+}): string {
+  if (collectionId !== undefined && resourceId !== undefined) {
+    return `${resourcePath({ spaceId, collectionId, resourceId })}/policy`
+  }
+  if (collectionId !== undefined) {
+    return `${collectionPath({ spaceId, collectionId })}/policy`
+  }
+  return `${spacePath({ spaceId })}/policy`
+}
+
+/**
+ * `/space/:spaceId/backends` -- the "Space Backends Available" list path.
+ * @param options {object}
+ * @param options.spaceId {string}
+ * @returns {string}
+ */
+export function backendsPath({ spaceId }: { spaceId: string }): string {
+  return `${spacePath({ spaceId })}/backends`
+}
+
+/**
+ * `/space/:spaceId/backends/:backendId` -- a single registered `external`
+ * backend record (the `POST` `Location` target, and the `PUT`/`DELETE` member
+ * path). Distinct from {@link backendPath}, which is a Collection's *selected*
+ * backend resource.
+ * @param options {object}
+ * @param options.spaceId {string}
+ * @param options.backendId {string}
+ * @returns {string}
+ */
+export function registeredBackendPath({
+  spaceId,
+  backendId
+}: {
+  spaceId: string
+  backendId: string
+}): string {
+  return `${backendsPath({ spaceId })}/${backendId}`
+}
+
+/**
+ * `/space/:spaceId/quotas` -- the Space Quota report path (spec "Quotas").
+ * @param options {object}
+ * @param options.spaceId {string}
+ * @returns {string}
+ */
+export function quotasPath({ spaceId }: { spaceId: string }): string {
+  return `${spacePath({ spaceId })}/quotas`
+}
+
+/**
+ * `/space/:spaceId/:collectionId/:resourceId/meta` -- the Resource Metadata
+ * (reserved `meta` segment) path. Reserved only at the Resource level, so it
+ * takes the full id triple.
+ * @param options {object}
+ * @param options.spaceId {string}
+ * @param options.collectionId {string}
+ * @param options.resourceId {string}
+ * @returns {string}
+ */
+export function metaPath({
+  spaceId,
+  collectionId,
+  resourceId
+}: {
+  spaceId: string
+  collectionId: string
+  resourceId: string
+}): string {
+  return `${resourcePath({ spaceId, collectionId, resourceId })}/meta`
+}
+
+/**
+ * `/space/:spaceId/:collectionId/backend` -- the "Collection Backend Selected"
+ * resource path (reserved `backend` segment at the Resource level).
+ * @param options {object}
+ * @param options.spaceId {string}
+ * @param options.collectionId {string}
+ * @returns {string}
+ */
+export function backendPath({
+  spaceId,
+  collectionId
+}: {
+  spaceId: string
+  collectionId: string
+}): string {
+  return `${collectionPath({ spaceId, collectionId })}/backend`
+}
+
+/**
+ * `/space/:spaceId/:collectionId/quota` -- the per-Collection storage quota
+ * report path (reserved `quota` segment at the Resource level; spec "Quotas").
+ * @param options {object}
+ * @param options.spaceId {string}
+ * @param options.collectionId {string}
+ * @returns {string}
+ */
+export function quotaPath({
+  spaceId,
+  collectionId
+}: {
+  spaceId: string
+  collectionId: string
+}): string {
+  return `${collectionPath({ spaceId, collectionId })}/quota`
+}
+
+/**
+ * `/space/:spaceId/:collectionId/query` -- the reserved `query` endpoint for a
+ * Collection (spec "Collection-level reserved endpoints"). The WAS server serves
+ * the replication change feed as the `changes` profile of this endpoint.
+ * @param options {object}
+ * @param options.spaceId {string}
+ * @param options.collectionId {string}
+ * @returns {string}
+ */
+export function queryPath({
+  spaceId,
+  collectionId
+}: {
+  spaceId: string
+  collectionId: string
+}): string {
+  return `${collectionPath({ spaceId, collectionId })}/query`
+}
+
+/**
+ * The `linkset` discovery resource path for a Space (`spaceId`) or Collection
+ * (`+ collectionId`).
+ * @param options {object}
+ * @param options.spaceId {string}
+ * @param [options.collectionId] {string}
+ * @returns {string}
+ */
+export function linksetPath({
+  spaceId,
+  collectionId
+}: {
+  spaceId: string
+  collectionId?: string
+}): string {
+  const anchor =
+    collectionId !== undefined
+      ? collectionPath({ spaceId, collectionId })
+      : spacePath({ spaceId })
+  return `${anchor}/linkset`
+}
+
+/**
+ * `/kms/keystores` -- the WebKMS keystores collection (create/list target; the
+ * `/kms` facet) or one of its member keystores
+ * (`/kms/keystores/:keystoreId`). Unlike the WAS builders there is no
+ * trailing-slash container form: the webkms protocol
+ * (`@interop/webkms-client`) posts to the bare collection path.
+ * @param options {object}
+ * @param [options.keystoreId] {string}   the keystore's server-generated local
+ *   id; when present, the member path, otherwise the collection path
+ * @returns {string}
+ */
+export function kmsKeystoresPath({
+  keystoreId
+}: { keystoreId?: string } = {}): string {
+  return keystoreId !== undefined
+    ? `/kms/keystores/${keystoreId}`
+    : '/kms/keystores'
+}
+
+/**
+ * `/kms/keystores/:keystoreId/keys` -- a keystore's keys collection (the
+ * `GenerateKeyOperation` target) or one of its member keys
+ * (`/kms/keystores/:keystoreId/keys/:keyId`, the key-operation / description
+ * target). Like `kmsKeystoresPath`, no trailing-slash form exists: the webkms
+ * protocol's URLs are exact.
+ * @param options {object}
+ * @param options.keystoreId {string}   the keystore's local id
+ * @param [options.keyId] {string}   the key's server-generated local id; when
+ *   present, the member path, otherwise the collection path
+ * @returns {string}
+ */
+export function kmsKeysPath({
+  keystoreId,
+  keyId
+}: {
+  keystoreId: string
+  keyId?: string
+}): string {
+  const keysPath = `${kmsKeystoresPath({ keystoreId })}/keys`
+  return keyId !== undefined ? `${keysPath}/${keyId}` : keysPath
+}
+
+/**
+ * `/kms/keystores/:keystoreId/zcaps/revocations/:revocationId` -- a keystore's
+ * zcap revocation submission target (POST; the ezcap-express
+ * `/zcaps/revocations/` convention). `revocationId` is the *to-be-revoked
+ * capability's id*, URL-encoded into the single path segment the route
+ * expects -- the same `encodeURIComponent` framing `@interop/webkms-client`'s
+ * `revokeCapability` puts on the wire.
+ * @param options {object}
+ * @param options.keystoreId {string}   the keystore's local id
+ * @param options.revocationId {string}   the to-be-revoked capability's id
+ *   (raw, un-encoded)
+ * @returns {string}
+ */
+export function kmsRevocationsPath({
+  keystoreId,
+  revocationId
+}: {
+  keystoreId: string
+  revocationId: string
+}): string {
+  return (
+    `${kmsKeystoresPath({ keystoreId })}/zcaps/revocations/` +
+    encodeURIComponent(revocationId)
+  )
+}
+
+/**
+ * `/space/:spaceId/zcaps/revocations/:revocationId` -- a Space's zcap
+ * revocation submission target (POST), the WAS-route sibling of
+ * `kmsRevocationsPath` and the same ezcap-express `/zcaps/revocations/`
+ * convention. `revocationId` is the *to-be-revoked capability's id*,
+ * URL-encoded into the single path segment the route expects. The `zcaps`
+ * segment sits four levels under `/space`, deeper than any Collection or
+ * Resource route, so it shadows neither and needs no reserved-id entry.
+ * @param options {object}
+ * @param options.spaceId {string}
+ * @param options.revocationId {string}   the to-be-revoked capability's id
+ *   (raw, un-encoded)
+ * @returns {string}
+ */
+export function spaceRevocationsPath({
+  spaceId,
+  revocationId
+}: {
+  spaceId: string
+  revocationId: string
+}): string {
+  return (
+    `${spacePath({ spaceId })}/zcaps/revocations/` +
+    encodeURIComponent(revocationId)
+  )
+}