was-teaching-server 0.9.1

package/dist/requests/SpacesRepositoryRequest.js

@@ -0,0 +1,159 @@
+import { v4 as uuidv4 } from 'uuid';
+import { isRootInvocation, verifyZcap } from '../zcap.js';
+import { invalidateSpaceDescription } from './spaceContext.js';
+import { verifyBodyControllerConsent } from './controllerConsent.js';
+import { invokerDid } from '../auth-header-hooks.js';
+import { assertValidId } from '../lib/validateId.js';
+import { spacePath, spacesPath } from '../lib/paths.js';
+import { assertValidController } from '../lib/validateDid.js';
+import { SpaceControllerMismatchError, InvalidRequestBodyError, IdConflictError } from '../errors.js';
+export class SpacesRepositoryRequest {
+    /**
+     * GET /spaces/
+     * Request handler for "List Spaces" (spec "List Spaces Operation"): returns
+     * `{ url, totalItems, items }` with only the Spaces the caller is authorized
+     * to see. An anonymous or unauthorized request is NOT an error -- it gets the
+     * empty-items 200, the spec's explicit exception to 404 masking -- so nothing
+     * is revealed about which Spaces exist.
+     *
+     * Authorization is per Space controller: the root capability for `/spaces/`
+     * is synthesized with the candidate Space's controller (see `verifyZcap`), so
+     * one verification decides visibility for every Space sharing that
+     * controller. A bare-root invocation can only verify where the signer *is*
+     * the controller, so those candidates are filtered before any signature
+     * work; a delegated invocation reveals the Spaces of whichever controller
+     * roots its capability chain.
+     *
+     * @param request {import('fastify').FastifyRequest}
+     * @param reply {import('fastify').FastifyReply}
+     * @returns {Promise<FastifyReply>}
+     */
+    static async get(request, reply) {
+        const { url, method, headers } = request;
+        const { serverUrl, storage } = request.server;
+        const items = [];
+        const listing = { url: spacesPath(), totalItems: 0, items };
+        // No (complete) authorization presented: authorized to see no Spaces,
+        // which is the empty 200, not an error.
+        if (!request.zcap?.invocation) {
+            return reply.send(listing);
+        }
+        const { keyId, invocation } = request.zcap;
+        const [zcapSigningDid] = keyId.split('#');
+        const rootInvocation = isRootInvocation({ invocation });
+        const allowedTarget = new URL(spacesPath(), serverUrl).toString();
+        // Visibility is identical across Spaces sharing a controller (the
+        // verification depends only on the controller), so verify once per
+        // distinct controller. A failed verification just excludes that
+        // controller's Spaces -- never an error response.
+        const verifiedByController = new Map();
+        for (const space of await storage.listSpaces()) {
+            const { controller } = space;
+            if (rootInvocation && controller !== zcapSigningDid) {
+                continue; // a bare-root invocation cannot verify for another controller
+            }
+            let authorized = verifiedByController.get(controller);
+            if (authorized === undefined) {
+                try {
+                    const result = await verifyZcap({
+                        url,
+                        allowedTarget,
+                        allowedAction: 'GET',
+                        method,
+                        headers,
+                        serverUrl,
+                        spaceController: controller
+                    });
+                    authorized = result.verified === true;
+                }
+                catch (err) {
+                    request.log.debug({ err }, 'List Spaces: invocation did not verify for a candidate controller');
+                    authorized = false;
+                }
+                verifiedByController.set(controller, authorized);
+            }
+            if (authorized) {
+                const item = {
+                    id: space.id,
+                    url: spacePath({ spaceId: space.id })
+                };
+                if (space.name !== undefined) {
+                    item.name = space.name;
+                }
+                items.push(item);
+            }
+        }
+        listing.totalItems = items.length;
+        return reply.send(listing);
+    }
+    /**
+     * POST /spaces/
+     * Request handler for "Create Space" request
+     * Before this, `parseAuthHeaders()` hook executed, resulting in:
+     * request.zcap: {
+     *   keyId, headers, signature, created, expires, invocation, digest
+     * }
+     *
+     * @param request {import('fastify').FastifyRequest}
+     * @param reply {import('fastify').FastifyReply}
+     * @returns {Promise<FastifyReply>}
+     */
+    static async post(request, reply) {
+        const { body } = request;
+        const { serverUrl, storage } = request.server;
+        // The Space Description body must carry a controller DID. The `name`
+        // property is optional (see spec: Space Description object).
+        if (!body?.controller) {
+            throw new InvalidRequestBodyError({
+                requestName: 'Create Space',
+                detail: 'Space Description body requires a "controller" property.',
+                pointer: '#/controller'
+            });
+        }
+        // Reject a malformed / non-`did:key` controller before it is stored.
+        assertValidController(body.controller, { requestName: 'Create Space' });
+        // Reject a path-traversal / non-URL-safe client-supplied space id.
+        if (body.id !== undefined) {
+            assertValidId(body.id, { kind: 'space', requestName: 'Create Space' });
+            // POST must never replace an existing Space: the signature below is
+            // verified against the *body's* controller, so without this check any
+            // caller could overwrite a Space (controller included) by POSTing its
+            // id. Spec: `id-conflict` (409); create-or-replace by id is PUT's job.
+            if (await storage.getSpaceDescription({ spaceId: body.id })) {
+                throw new IdConflictError({ kind: 'Space' });
+            }
+        }
+        const spaceId = body.id || uuidv4();
+        const spaceDescription = { ...body, id: spaceId, type: ['Space'] };
+        // The invocation must be *authorized by* the body's controller (spec:
+        // Create Space): signed directly by it, or via a delegation chain rooted
+        // in it (see `verifyBodyControllerConsent`). Skipped when the provisioning
+        // policy already vouched for the request (e.g. a valid onboarding token).
+        if (!request.provisioningAuthorized) {
+            await verifyBodyControllerConsent({
+                request,
+                controller: body.controller,
+                allowedTarget: new URL(spacesPath(), serverUrl).toString(),
+                allowedAction: 'POST',
+                MismatchError: SpaceControllerMismatchError,
+                requestName: 'Create Space'
+            });
+        }
+        // zCap checks out, continue. A token-provisioned create carries no
+        // invocation, so it records no `createdBy`.
+        const createdBy = invokerDid(request);
+        await storage.writeSpace({ spaceId, spaceDescription, createdBy });
+        // Bust any cached (e.g. negatively cached) description for this id so the
+        // next read sees the freshly created Space.
+        invalidateSpaceDescription({ storage, spaceId });
+        const createdSpaceUrl = new URL(spacesPath({ spaceId }), serverUrl).toString();
+        reply.header('Location', createdSpaceUrl);
+        // Echo what was persisted, `createdBy` included, so the create response and
+        // a subsequent Get Space agree. An id already in use was rejected as a 409
+        // above, so this write created the Space and its creator is this invoker.
+        return reply
+            .status(201)
+            .send({ ...spaceDescription, ...(createdBy && { createdBy }) });
+    }
+}
+//# sourceMappingURL=SpacesRepositoryRequest.js.map

package/dist/requests/SpacesRepositoryRequest.js.map

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

package/dist/requests/collectionContext.d.ts

@@ -0,0 +1,21 @@
+import type { CollectionDescription, StorageBackend } from '../types.js';
+/**
+ * Fetches a Collection Description or throws CollectionNotFoundError (404)
+ * when absent.
+ * @param options {object}
+ * @param options.storage {StorageBackend}   the request's storage backend
+ * @param options.spaceId {string}
+ * @param options.collectionId {string}
+ * @param options.requestName {string}   human-readable request name, used in
+ *   error titles
+ * @returns {Promise<CollectionDescription & { descriptionVersion?: number }>}
+ */
+export declare function getCollectionOrThrow({ storage, spaceId, collectionId, requestName }: {
+    storage: StorageBackend;
+    spaceId: string;
+    collectionId: string;
+    requestName: string;
+}): Promise<CollectionDescription & {
+    descriptionVersion?: number;
+}>;
+//# sourceMappingURL=collectionContext.d.ts.map

package/dist/requests/collectionContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collectionContext.d.ts","sourceRoot":"","sources":["../../src/requests/collectionContext.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,qBAAqB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAExE;;;;;;;;;;GAUG;AACH,wBAAsB,oBAAoB,CAAC,EACzC,OAAO,EACP,OAAO,EACP,YAAY,EACZ,WAAW,EACZ,EAAE;IACD,OAAO,EAAE,cAAc,CAAA;IACvB,OAAO,EAAE,MAAM,CAAA;IACf,YAAY,EAAE,MAAM,CAAA;IACpB,WAAW,EAAE,MAAM,CAAA;CACpB,GAAG,OAAO,CAAC,qBAAqB,GAAG;IAAE,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CASnE"}

package/dist/requests/collectionContext.js

@@ -0,0 +1,30 @@
+/**
+ * Shared handler prelude: fetch a Collection Description or 404 (paralleling
+ * spaceContext.ts / keystoreContext.ts). Nearly every Collection- and
+ * Resource-level handler repeats the same shape after authorization -- load
+ * the Collection Description for context, throw `CollectionNotFoundError`
+ * when absent -- so it lives here.
+ */
+import { CollectionNotFoundError } from '../errors.js';
+/**
+ * Fetches a Collection Description or throws CollectionNotFoundError (404)
+ * when absent.
+ * @param options {object}
+ * @param options.storage {StorageBackend}   the request's storage backend
+ * @param options.spaceId {string}
+ * @param options.collectionId {string}
+ * @param options.requestName {string}   human-readable request name, used in
+ *   error titles
+ * @returns {Promise<CollectionDescription & { descriptionVersion?: number }>}
+ */
+export async function getCollectionOrThrow({ storage, spaceId, collectionId, requestName }) {
+    const collectionDescription = await storage.getCollectionDescription({
+        spaceId,
+        collectionId
+    });
+    if (!collectionDescription) {
+        throw new CollectionNotFoundError({ requestName });
+    }
+    return collectionDescription;
+}
+//# sourceMappingURL=collectionContext.js.map

package/dist/requests/collectionContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collectionContext.js","sourceRoot":"","sources":["../../src/requests/collectionContext.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAA;AAGtD;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,EACzC,OAAO,EACP,OAAO,EACP,YAAY,EACZ,WAAW,EAMZ;IACC,MAAM,qBAAqB,GAAG,MAAM,OAAO,CAAC,wBAAwB,CAAC;QACnE,OAAO;QACP,YAAY;KACb,CAAC,CAAA;IACF,IAAI,CAAC,qBAAqB,EAAE,CAAC;QAC3B,MAAM,IAAI,uBAAuB,CAAC,EAAE,WAAW,EAAE,CAAC,CAAA;IACpD,CAAC;IACD,OAAO,qBAAqB,CAAA;AAC9B,CAAC"}

package/dist/requests/controllerConsent.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Shared handler prelude for the create-by-consent bootstrap (paralleling
+ * spaceContext.ts / keystoreContext.ts): the operations that create a
+ * top-level resource owned by a DID named in the request *body* (Create
+ * Space, the create form of Update Space, Create Keystore) have no stored
+ * controller to verify against yet, so the invocation must be *authorized by*
+ * the body's controller -- signed directly by it, or via a delegation chain
+ * rooted in it. Verifying against the signer instead would let anyone install
+ * an unrelated, non-consenting DID as controller.
+ */
+import type { FastifyRequest } from 'fastify';
+import type { ProblemError } from '../errors.js';
+import type { IDID } from '../types.js';
+/**
+ * Verifies that the invocation is authorized by `controller` (the DID named
+ * in the request body). For the bare-root invocation form the signer *is* the
+ * invoker, so a mismatch is rejected up front, before any signature work. The
+ * delegated form instead carries a capability chain, judged by the
+ * verification (which synthesizes the root capability with `controller` as
+ * its controller): a delegated invocation that fails to verify is a chain not
+ * rooted in the body's controller, wrapped in `MismatchError` (spec
+ * `controller-mismatch`, 400). Root-form verification failures keep their
+ * generic errors -- the signer already matched the controller.
+ *
+ * @param options {object}
+ * @param options.request {FastifyRequest}   supplies url, method, headers,
+ *   logger, `request.zcap`, and `request.server` for serverUrl
+ * @param options.controller {IDID}   the controller DID named in the request
+ *   body, which must authorize the invocation
+ * @param options.allowedTarget {string}   the capability's expected
+ *   invocationTarget (full URL, including host and port)
+ * @param options.allowedAction {string}   expected action, e.g. an HTTP verb
+ * @param options.MismatchError {new (options) => ProblemError}   the
+ *   operation's `controller-mismatch` error class (constructed with
+ *   `{ zcapSigningDid, controller, cause? }`)
+ * @param [options.requestName] {string}   human-readable request name, used
+ *   in error titles
+ * @param [options.maxChainLength] {number}   max delegation chain length,
+ *   root included (see `verifyZcap`)
+ * @param [options.maxDelegationTtl] {number}   max delegated-zcap TTL in
+ *   milliseconds (see `verifyZcap`)
+ * @returns {Promise<void>}
+ */
+export declare function verifyBodyControllerConsent({ request, controller, allowedTarget, allowedAction, MismatchError, requestName, maxChainLength, maxDelegationTtl }: {
+    request: FastifyRequest;
+    controller: IDID;
+    allowedTarget: string;
+    allowedAction: string;
+    MismatchError: new (options: {
+        zcapSigningDid: string;
+        controller: string;
+        cause?: Error;
+    }) => ProblemError;
+    requestName?: string;
+    maxChainLength?: number;
+    maxDelegationTtl?: number;
+}): Promise<void>;
+//# sourceMappingURL=controllerConsent.d.ts.map

package/dist/requests/controllerConsent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"controllerConsent.d.ts","sourceRoot":"","sources":["../../src/requests/controllerConsent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAE7C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAChD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAEvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAsB,2BAA2B,CAAC,EAChD,OAAO,EACP,UAAU,EACV,aAAa,EACb,aAAa,EACb,aAAa,EACb,WAAW,EACX,cAAc,EACd,gBAAgB,EACjB,EAAE;IACD,OAAO,EAAE,cAAc,CAAA;IACvB,UAAU,EAAE,IAAI,CAAA;IAChB,aAAa,EAAE,MAAM,CAAA;IACrB,aAAa,EAAE,MAAM,CAAA;IACrB,aAAa,EAAE,KAAK,OAAO,EAAE;QAC3B,cAAc,EAAE,MAAM,CAAA;QACtB,UAAU,EAAE,MAAM,CAAA;QAClB,KAAK,CAAC,EAAE,KAAK,CAAA;KACd,KAAK,YAAY,CAAA;IAClB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAC1B,GAAG,OAAO,CAAC,IAAI,CAAC,CAwChB"}

package/dist/requests/controllerConsent.js

@@ -0,0 +1,73 @@
+import { handleZcapVerify, isRootInvocation } from '../zcap.js';
+/**
+ * Verifies that the invocation is authorized by `controller` (the DID named
+ * in the request body). For the bare-root invocation form the signer *is* the
+ * invoker, so a mismatch is rejected up front, before any signature work. The
+ * delegated form instead carries a capability chain, judged by the
+ * verification (which synthesizes the root capability with `controller` as
+ * its controller): a delegated invocation that fails to verify is a chain not
+ * rooted in the body's controller, wrapped in `MismatchError` (spec
+ * `controller-mismatch`, 400). Root-form verification failures keep their
+ * generic errors -- the signer already matched the controller.
+ *
+ * @param options {object}
+ * @param options.request {FastifyRequest}   supplies url, method, headers,
+ *   logger, `request.zcap`, and `request.server` for serverUrl
+ * @param options.controller {IDID}   the controller DID named in the request
+ *   body, which must authorize the invocation
+ * @param options.allowedTarget {string}   the capability's expected
+ *   invocationTarget (full URL, including host and port)
+ * @param options.allowedAction {string}   expected action, e.g. an HTTP verb
+ * @param options.MismatchError {new (options) => ProblemError}   the
+ *   operation's `controller-mismatch` error class (constructed with
+ *   `{ zcapSigningDid, controller, cause? }`)
+ * @param [options.requestName] {string}   human-readable request name, used
+ *   in error titles
+ * @param [options.maxChainLength] {number}   max delegation chain length,
+ *   root included (see `verifyZcap`)
+ * @param [options.maxDelegationTtl] {number}   max delegated-zcap TTL in
+ *   milliseconds (see `verifyZcap`)
+ * @returns {Promise<void>}
+ */
+export async function verifyBodyControllerConsent({ request, controller, allowedTarget, allowedAction, MismatchError, requestName, maxChainLength, maxDelegationTtl }) {
+    const { url, method, headers } = request;
+    const { serverUrl } = request.server;
+    // The strict `requireAuthHeaders` hook guarantees auth headers were present
+    // and `parseAuthHeaders` set `request.zcap` before any calling handler.
+    const { keyId, invocation } = request.zcap;
+    const [zcapSigningDid] = keyId.split('#');
+    const rootInvocation = isRootInvocation({ invocation });
+    if (rootInvocation && zcapSigningDid !== controller) {
+        throw new MismatchError({ zcapSigningDid: zcapSigningDid, controller });
+    }
+    try {
+        await handleZcapVerify({
+            url,
+            allowedTarget,
+            allowedAction,
+            method,
+            headers,
+            serverUrl,
+            spaceController: controller,
+            requestName,
+            logger: request.log,
+            // Consent verifies a chain rooted in the BODY's controller for a
+            // resource that does not exist yet, so there is no keystore or Space
+            // scope a revocation could have been stored under.
+            revocation: 'no-revocation-scope',
+            maxChainLength,
+            maxDelegationTtl
+        });
+    }
+    catch (err) {
+        if (!rootInvocation) {
+            throw new MismatchError({
+                zcapSigningDid: zcapSigningDid,
+                controller,
+                cause: err
+            });
+        }
+        throw err;
+    }
+}
+//# sourceMappingURL=controllerConsent.js.map

package/dist/requests/controllerConsent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"controllerConsent.js","sourceRoot":"","sources":["../../src/requests/controllerConsent.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAI/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAAC,EAChD,OAAO,EACP,UAAU,EACV,aAAa,EACb,aAAa,EACb,aAAa,EACb,WAAW,EACX,cAAc,EACd,gBAAgB,EAcjB;IACC,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAA;IACxC,MAAM,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,MAAM,CAAA;IACpC,4EAA4E;IAC5E,wEAAwE;IACxE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,IAAK,CAAA;IAC3C,MAAM,CAAC,cAAc,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IACzC,MAAM,cAAc,GAAG,gBAAgB,CAAC,EAAE,UAAU,EAAE,CAAC,CAAA;IACvD,IAAI,cAAc,IAAI,cAAc,KAAK,UAAU,EAAE,CAAC;QACpD,MAAM,IAAI,aAAa,CAAC,EAAE,cAAc,EAAE,cAAe,EAAE,UAAU,EAAE,CAAC,CAAA;IAC1E,CAAC;IAED,IAAI,CAAC;QACH,MAAM,gBAAgB,CAAC;YACrB,GAAG;YACH,aAAa;YACb,aAAa;YACb,MAAM;YACN,OAAO;YACP,SAAS;YACT,eAAe,EAAE,UAAU;YAC3B,WAAW;YACX,MAAM,EAAE,OAAO,CAAC,GAAG;YACnB,iEAAiE;YACjE,qEAAqE;YACrE,mDAAmD;YACnD,UAAU,EAAE,qBAAqB;YACjC,cAAc;YACd,gBAAgB;SACjB,CAAC,CAAA;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,cAAc,EAAE,CAAC;YACpB,MAAM,IAAI,aAAa,CAAC;gBACtB,cAAc,EAAE,cAAe;gBAC/B,UAAU;gBACV,KAAK,EAAE,GAAY;aACpB,CAAC,CAAA;QACJ,CAAC;QACD,MAAM,GAAG,CAAA;IACX,CAAC;AACH,CAAC"}

package/dist/requests/keystoreContext.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Shared WebKMS keystore context helper (the `/kms` facet): the keystore
+ * analogue of `fetchSpaceAndVerify`
+ * (spaceContext.ts), used by the keystore-lifecycle, key-operation, and
+ * revocation request handlers.
+ */
+import type { FastifyRequest } from 'fastify';
+import type { KeystoreConfig } from '../types.js';
+/**
+ * Loads a keystore config by its URL param, masking an unknown (or
+ * non-URL-safe) id as the 404 `KeystoreNotFoundError` -- the WAS
+ * existence-masking convention. The verification-free half of
+ * `fetchKeystoreAndVerify`, for handlers that need the config before they can
+ * build their expected values (the revocation route).
+ *
+ * @param options {object}
+ * @param options.request {FastifyRequest}   supplies `request.server.storage`
+ * @param options.keystoreId {string}   the keystore's local id (URL param)
+ * @param options.requestName {string}   request name used in error titles
+ * @returns {Promise<KeystoreConfig>}   the stored config
+ */
+export declare function fetchKeystore({ request, keystoreId, requestName }: {
+    request: FastifyRequest;
+    keystoreId: string;
+    requestName: string;
+}): Promise<KeystoreConfig>;
+/**
+ * Loads the keystore config (404 `KeystoreNotFoundError` when absent -- the
+ * WAS existence-masking convention) and verifies the capability invocation
+ * against the *stored* config's controller, with the keystore URL as the root
+ * invocation target. `allowedAction` is the webkms action (`read` / `write` /
+ * an operation name), not the HTTP verb. The verification carries the unified
+ * `/kms` delegation policy (`KMS_MAX_CHAIN_LENGTH`, `KMS_MAX_DELEGATION_TTL`;
+ * the zcap library itself already requires `expires` on every delegated
+ * capability) and the keystore's revocation-store chain inspector, so a
+ * revoked delegation fails on every keystore-rooted route.
+ *
+ * @param options {object}
+ * @param options.request {FastifyRequest}   supplies url, method, headers,
+ *   logger, and `request.server` for serverUrl + storage
+ * @param options.keystoreId {string}   the keystore's local id (URL param)
+ * @param options.allowedAction {string}   expected zcap action
+ * @param options.requestName {string}   request name used in error titles
+ * @param [options.allowTargetAttenuation] {boolean}   accept a request URL
+ *   under the keystore URL (the key routes: every key operation roots in the
+ *   keystore's capability, with the key URL as an attenuated target -- see
+ *   `verifyZcap`)
+ * @param [options.allowTargetQuery] {boolean}   tolerate query parameters on
+ *   the request URL that are absent from the capability target (the List Keys
+ *   route's `?limit` / `?cursor` pagination parameters select a page within an
+ *   already-authorized target; the same treatment as List Keystores)
+ * @returns {Promise<{ config: KeystoreConfig, dereferencedChainLength: number }>}
+ *   the stored config and the verified invocation's chain length, root
+ *   included (a root invocation is 1) -- the input to the per-key
+ *   `maxCapabilityChainLength` gate at operation time
+ */
+export declare function fetchKeystoreAndVerify({ request, keystoreId, allowedAction, requestName, allowTargetAttenuation, allowTargetQuery }: {
+    request: FastifyRequest;
+    keystoreId: string;
+    allowedAction: string;
+    requestName: string;
+    allowTargetAttenuation?: boolean;
+    allowTargetQuery?: boolean;
+}): Promise<{
+    config: KeystoreConfig;
+    dereferencedChainLength: number;
+}>;
+//# sourceMappingURL=keystoreContext.d.ts.map

package/dist/requests/keystoreContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keystoreContext.d.ts","sourceRoot":"","sources":["../../src/requests/keystoreContext.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAS7C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAEjD;;;;;;;;;;;;GAYG;AACH,wBAAsB,aAAa,CAAC,EAClC,OAAO,EACP,UAAU,EACV,WAAW,EACZ,EAAE;IACD,OAAO,EAAE,cAAc,CAAA;IACvB,UAAU,EAAE,MAAM,CAAA;IAClB,WAAW,EAAE,MAAM,CAAA;CACpB,GAAG,OAAO,CAAC,cAAc,CAAC,CAW1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAsB,sBAAsB,CAAC,EAC3C,OAAO,EACP,UAAU,EACV,aAAa,EACb,WAAW,EACX,sBAA8B,EAC9B,gBAAwB,EACzB,EAAE;IACD,OAAO,EAAE,cAAc,CAAA;IACvB,UAAU,EAAE,MAAM,CAAA;IAClB,aAAa,EAAE,MAAM,CAAA;IACrB,WAAW,EAAE,MAAM,CAAA;IACnB,sBAAsB,CAAC,EAAE,OAAO,CAAA;IAChC,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAC3B,GAAG,OAAO,CAAC;IAAE,MAAM,EAAE,cAAc,CAAC;IAAC,uBAAuB,EAAE,MAAM,CAAA;CAAE,CAAC,CA4BvE"}

package/dist/requests/keystoreContext.js

@@ -0,0 +1,87 @@
+import { handleZcapVerify } from '../zcap.js';
+import { isUrlSafeSegment } from '../lib/validateId.js';
+import { kmsKeystoresPath } from '../lib/paths.js';
+import { KMS_MAX_CHAIN_LENGTH, KMS_MAX_DELEGATION_TTL } from '../config.default.js';
+import { KeystoreNotFoundError } from '../errors.js';
+/**
+ * Loads a keystore config by its URL param, masking an unknown (or
+ * non-URL-safe) id as the 404 `KeystoreNotFoundError` -- the WAS
+ * existence-masking convention. The verification-free half of
+ * `fetchKeystoreAndVerify`, for handlers that need the config before they can
+ * build their expected values (the revocation route).
+ *
+ * @param options {object}
+ * @param options.request {FastifyRequest}   supplies `request.server.storage`
+ * @param options.keystoreId {string}   the keystore's local id (URL param)
+ * @param options.requestName {string}   request name used in error titles
+ * @returns {Promise<KeystoreConfig>}   the stored config
+ */
+export async function fetchKeystore({ request, keystoreId, requestName }) {
+    // A non-URL-safe id cannot name a stored keystore (ids are server-generated
+    // base58 values) and must not reach the filesystem layer: same 404 masking.
+    if (!isUrlSafeSegment(keystoreId)) {
+        throw new KeystoreNotFoundError({ requestName });
+    }
+    const config = await request.server.storage.getKeystore({ keystoreId });
+    if (!config) {
+        throw new KeystoreNotFoundError({ requestName });
+    }
+    return config;
+}
+/**
+ * Loads the keystore config (404 `KeystoreNotFoundError` when absent -- the
+ * WAS existence-masking convention) and verifies the capability invocation
+ * against the *stored* config's controller, with the keystore URL as the root
+ * invocation target. `allowedAction` is the webkms action (`read` / `write` /
+ * an operation name), not the HTTP verb. The verification carries the unified
+ * `/kms` delegation policy (`KMS_MAX_CHAIN_LENGTH`, `KMS_MAX_DELEGATION_TTL`;
+ * the zcap library itself already requires `expires` on every delegated
+ * capability) and the keystore's revocation-store chain inspector, so a
+ * revoked delegation fails on every keystore-rooted route.
+ *
+ * @param options {object}
+ * @param options.request {FastifyRequest}   supplies url, method, headers,
+ *   logger, and `request.server` for serverUrl + storage
+ * @param options.keystoreId {string}   the keystore's local id (URL param)
+ * @param options.allowedAction {string}   expected zcap action
+ * @param options.requestName {string}   request name used in error titles
+ * @param [options.allowTargetAttenuation] {boolean}   accept a request URL
+ *   under the keystore URL (the key routes: every key operation roots in the
+ *   keystore's capability, with the key URL as an attenuated target -- see
+ *   `verifyZcap`)
+ * @param [options.allowTargetQuery] {boolean}   tolerate query parameters on
+ *   the request URL that are absent from the capability target (the List Keys
+ *   route's `?limit` / `?cursor` pagination parameters select a page within an
+ *   already-authorized target; the same treatment as List Keystores)
+ * @returns {Promise<{ config: KeystoreConfig, dereferencedChainLength: number }>}
+ *   the stored config and the verified invocation's chain length, root
+ *   included (a root invocation is 1) -- the input to the per-key
+ *   `maxCapabilityChainLength` gate at operation time
+ */
+export async function fetchKeystoreAndVerify({ request, keystoreId, allowedAction, requestName, allowTargetAttenuation = false, allowTargetQuery = false }) {
+    const { serverUrl, storage } = request.server;
+    const config = await fetchKeystore({ request, keystoreId, requestName });
+    const { url, method, headers } = request;
+    const allowedTarget = new URL(kmsKeystoresPath({ keystoreId }), serverUrl).toString();
+    const zcapVerifyResult = await handleZcapVerify({
+        url,
+        allowedTarget,
+        allowedAction,
+        method,
+        headers,
+        serverUrl,
+        spaceController: config.controller,
+        requestName,
+        logger: request.log,
+        allowTargetAttenuation,
+        allowTargetQuery,
+        revocation: { storage, scope: { keystoreId } },
+        maxChainLength: KMS_MAX_CHAIN_LENGTH,
+        maxDelegationTtl: KMS_MAX_DELEGATION_TTL
+    });
+    return {
+        config,
+        dereferencedChainLength: zcapVerifyResult.dereferencedChain?.length ?? 1
+    };
+}
+//# sourceMappingURL=keystoreContext.js.map

package/dist/requests/keystoreContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keystoreContext.js","sourceRoot":"","sources":["../../src/requests/keystoreContext.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAC7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAClD,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACvB,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAA;AAGpD;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,EAClC,OAAO,EACP,UAAU,EACV,WAAW,EAKZ;IACC,4EAA4E;IAC5E,4EAA4E;IAC5E,IAAI,CAAC,gBAAgB,CAAC,UAAU,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,qBAAqB,CAAC,EAAE,WAAW,EAAE,CAAC,CAAA;IAClD,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,UAAU,EAAE,CAAC,CAAA;IACvE,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,qBAAqB,CAAC,EAAE,WAAW,EAAE,CAAC,CAAA;IAClD,CAAC;IACD,OAAO,MAAM,CAAA;AACf,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,EAC3C,OAAO,EACP,UAAU,EACV,aAAa,EACb,WAAW,EACX,sBAAsB,GAAG,KAAK,EAC9B,gBAAgB,GAAG,KAAK,EAQzB;IACC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,MAAM,CAAA;IAC7C,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,CAAC,CAAA;IACxE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAA;IACxC,MAAM,aAAa,GAAG,IAAI,GAAG,CAC3B,gBAAgB,CAAC,EAAE,UAAU,EAAE,CAAC,EAChC,SAAS,CACV,CAAC,QAAQ,EAAE,CAAA;IACZ,MAAM,gBAAgB,GAAG,MAAM,gBAAgB,CAAC;QAC9C,GAAG;QACH,aAAa;QACb,aAAa;QACb,MAAM;QACN,OAAO;QACP,SAAS;QACT,eAAe,EAAE,MAAM,CAAC,UAAU;QAClC,WAAW;QACX,MAAM,EAAE,OAAO,CAAC,GAAG;QACnB,sBAAsB;QACtB,gBAAgB;QAChB,UAAU,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,UAAU,EAAE,EAAE;QAC9C,cAAc,EAAE,oBAAoB;QACpC,gBAAgB,EAAE,sBAAsB;KACzC,CAAC,CAAA;IACF,OAAO;QACL,MAAM;QACN,uBAAuB,EAAE,gBAAgB,CAAC,iBAAiB,EAAE,MAAM,IAAI,CAAC;KACzE,CAAA;AACH,CAAC"}

package/dist/requests/resourceInput.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Request-layer adapter: resolves a Fastify request into a transport-neutral
+ * `ResourceInput` value object, so that storage backends never depend on
+ * Fastify. JSON bodies pass through as parsed values; raw blob bodies and
+ * multipart uploads are normalized to a readable byte stream.
+ */
+import type { FastifyRequest } from 'fastify';
+import type { ResourceInput, StorageBackend } from '../types.js';
+/**
+ * @param request {import('fastify').FastifyRequest}
+ * @param [dataBackend] {StorageBackend}   the resolved data-plane backend the
+ *   write targets (the Collection's selected backend); its `maxUploadBytes` and
+ *   `describe().id` size and label the `payload-too-large` (413) for a multipart
+ *   upload. Defaults to the server `storage` backend, read lazily only on the
+ *   multipart path so non-multipart callers need not supply it.
+ * @returns {Promise<ResourceInput>}
+ */
+export declare function resolveResourceInput(request: FastifyRequest, dataBackend?: StorageBackend): Promise<ResourceInput>;
+//# sourceMappingURL=resourceInput.d.ts.map

package/dist/requests/resourceInput.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resourceInput.d.ts","sourceRoot":"","sources":["../../src/requests/resourceInput.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAQ7C,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAEhE;;;;;;;;GAQG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,cAAc,EACvB,WAAW,CAAC,EAAE,cAAc,GAC3B,OAAO,CAAC,aAAa,CAAC,CAyFxB"}