was-teaching-server 0.9.1

package/dist/lib/kmsRecordCipher.js

@@ -0,0 +1,226 @@
+/**
+ * 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';
+/**
+ * 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 = 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) {
+    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, label = 'KMS_RECORD_KEK') {
+    const decoder = new IdDecoder({ encoding: 'base58', multibase: true });
+    let decoded;
+    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) {
+    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) {
+    return (kekId) => 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 }) {
+    const publicFields = {};
+    const secretFields = {};
+    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 = {
+        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 }
+    };
+}
+/**
+ * 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 }) {
+    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'));
+    // Splice the secrets back onto the public fields, dropping the envelope.
+    const { encrypted: _envelope, ...publicFields } = record.key;
+    return {
+        ...record,
+        key: { ...publicFields, ...secretFields }
+    };
+}
+//# sourceMappingURL=kmsRecordCipher.js.map

package/dist/lib/kmsRecordCipher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kmsRecordCipher.js","sourceRoot":"","sources":["../../src/lib/kmsRecordCipher.ts"],"names":[],"mappings":"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"}

package/dist/lib/pagination.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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 declare const DEFAULT_PAGE_SIZE = 100;
+export declare const MAX_PAGE_SIZE = 1000;
+/**
+ * Clamps a requested `limit` to `[1, MAX_PAGE_SIZE]`.
+ * @param limit {number}
+ * @returns {number}
+ */
+export declare function clampPageSize(limit: number): number;
+//# sourceMappingURL=pagination.d.ts.map

package/dist/lib/pagination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../../src/lib/pagination.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,MAAM,CAAA;AACpC,eAAO,MAAM,aAAa,OAAO,CAAA;AAEjC;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnD"}

package/dist/lib/pagination.js

@@ -0,0 +1,21 @@
+/**
+ * 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) {
+    return Math.min(Math.max(Math.trunc(limit), 1), MAX_PAGE_SIZE);
+}
+//# sourceMappingURL=pagination.js.map

package/dist/lib/pagination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.js","sourceRoot":"","sources":["../../src/lib/pagination.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAG,CAAA;AACpC,MAAM,CAAC,MAAM,aAAa,GAAG,IAAI,CAAA;AAEjC;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,EAAE,aAAa,CAAC,CAAA;AAChE,CAAC"}

package/dist/lib/paths.d.ts

@@ -0,0 +1,273 @@
+/**
+ * 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 declare function spacesPath({ spaceId }?: {
+    spaceId?: string;
+}): string;
+/**
+ * `/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 declare function spacePath({ spaceId, trailingSlash }: {
+    spaceId: string;
+    trailingSlash?: boolean;
+}): string;
+/**
+ * `/space/:spaceId/collections/` -- the "List Collections" container path.
+ * @param options {object}
+ * @param options.spaceId {string}
+ * @returns {string}
+ */
+export declare function collectionsPath({ spaceId }: {
+    spaceId: string;
+}): string;
+/**
+ * `/space/:spaceId/export` -- the "Export Space" action path.
+ * @param options {object}
+ * @param options.spaceId {string}
+ * @returns {string}
+ */
+export declare function exportPath({ spaceId }: {
+    spaceId: string;
+}): string;
+/**
+ * `/space/:spaceId/import` -- the "Import Space" action path.
+ * @param options {object}
+ * @param options.spaceId {string}
+ * @returns {string}
+ */
+export declare function importPath({ spaceId }: {
+    spaceId: string;
+}): string;
+/**
+ * `/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 declare function collectionPath({ spaceId, collectionId, trailingSlash }: {
+    spaceId: string;
+    collectionId: string;
+    trailingSlash?: boolean;
+}): string;
+/**
+ * `/space/:spaceId/:collectionId/:resourceId`
+ * @param options {object}
+ * @param options.spaceId {string}
+ * @param options.collectionId {string}
+ * @param options.resourceId {string}
+ * @returns {string}
+ */
+export declare function resourcePath({ spaceId, collectionId, resourceId }: {
+    spaceId: string;
+    collectionId: string;
+    resourceId: string;
+}): string;
+/**
+ * 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 declare function policyPath({ spaceId, collectionId, resourceId }: {
+    spaceId: string;
+    collectionId?: string;
+    resourceId?: string;
+}): string;
+/**
+ * `/space/:spaceId/backends` -- the "Space Backends Available" list path.
+ * @param options {object}
+ * @param options.spaceId {string}
+ * @returns {string}
+ */
+export declare function backendsPath({ spaceId }: {
+    spaceId: string;
+}): string;
+/**
+ * `/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 declare function registeredBackendPath({ spaceId, backendId }: {
+    spaceId: string;
+    backendId: string;
+}): string;
+/**
+ * `/space/:spaceId/quotas` -- the Space Quota report path (spec "Quotas").
+ * @param options {object}
+ * @param options.spaceId {string}
+ * @returns {string}
+ */
+export declare function quotasPath({ spaceId }: {
+    spaceId: string;
+}): string;
+/**
+ * `/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 declare function metaPath({ spaceId, collectionId, resourceId }: {
+    spaceId: string;
+    collectionId: string;
+    resourceId: string;
+}): string;
+/**
+ * `/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 declare function backendPath({ spaceId, collectionId }: {
+    spaceId: string;
+    collectionId: string;
+}): string;
+/**
+ * `/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 declare function quotaPath({ spaceId, collectionId }: {
+    spaceId: string;
+    collectionId: string;
+}): string;
+/**
+ * `/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 declare function queryPath({ spaceId, collectionId }: {
+    spaceId: string;
+    collectionId: string;
+}): string;
+/**
+ * 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 declare function linksetPath({ spaceId, collectionId }: {
+    spaceId: string;
+    collectionId?: string;
+}): string;
+/**
+ * `/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 declare function kmsKeystoresPath({ keystoreId }?: {
+    keystoreId?: string;
+}): string;
+/**
+ * `/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 declare function kmsKeysPath({ keystoreId, keyId }: {
+    keystoreId: string;
+    keyId?: string;
+}): string;
+/**
+ * `/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 declare function kmsRevocationsPath({ keystoreId, revocationId }: {
+    keystoreId: string;
+    revocationId: string;
+}): string;
+/**
+ * `/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 declare function spaceRevocationsPath({ spaceId, revocationId }: {
+    spaceId: string;
+    revocationId: string;
+}): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/lib/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/lib/paths.ts"],"names":[],"mappings":"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"}