was-teaching-server 0.9.1

package/dist/requests/resourceInput.js

@@ -0,0 +1,102 @@
+import { Readable } from 'node:stream';
+import { isJson } from '../lib/isJson.js';
+import { MissingContentTypeError, InvalidRequestBodyError, PayloadTooLargeError } from '../errors.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 async function resolveResourceInput(request, dataBackend) {
+    const contentType = request.headers['content-type'];
+    if (!contentType) {
+        throw new MissingContentTypeError({ requestName: 'Write Resource' });
+    }
+    if (isJson({ contentType })) {
+        return { kind: 'json', contentType, data: request.body };
+    }
+    if (contentType.startsWith('multipart')) {
+        // Spec ("Content Types and Representations"): a multipart write MUST carry
+        // exactly one file part -- reject zero file parts, or more than one, as
+        // `invalid-request-body` (400). Iterate every part rather than calling
+        // `request.file()` (which silently takes the first file part and ignores any
+        // extras). `toBuffer()` drains each file part's stream, which both lets the
+        // iterator advance to detect a second (disallowed) part and yields the exact
+        // byte length to pre-flight the upload cap. Buffering the part in memory is
+        // acceptable for this multipart convenience path (the HTML form workflow) --
+        // large binaries should use the streaming raw-body path. The buffer is
+        // bounded by the backend's `maxUploadBytes` (the multipart `fileSize` limit
+        // set in `plugin.ts`): `toBuffer()` throws `FST_REQ_FILE_TOO_LARGE` at the
+        // boundary, mapped here to `payload-too-large` (413).
+        const backend = dataBackend ?? request.server.storage;
+        let file;
+        for await (const part of request.parts()) {
+            if (part.type !== 'file') {
+                continue;
+            }
+            if (file) {
+                throw new InvalidRequestBodyError({
+                    requestName: 'Write Resource',
+                    detail: 'multipart request must carry exactly one file part.'
+                });
+            }
+            try {
+                file = { mimetype: part.mimetype, bytes: await part.toBuffer() };
+            }
+            catch (err) {
+                if (err.code === 'FST_REQ_FILE_TOO_LARGE') {
+                    throw new PayloadTooLargeError({
+                        maxUploadBytes: backend.maxUploadBytes,
+                        backendId: backend.describe().id
+                    });
+                }
+                throw err;
+            }
+        }
+        if (!file) {
+            throw new InvalidRequestBodyError({
+                requestName: 'Write Resource',
+                detail: 'multipart request is missing a file part.'
+            });
+        }
+        return {
+            kind: 'binary',
+            contentType: file.mimetype,
+            stream: Readable.from(file.bytes),
+            declaredBytes: file.bytes.length
+        };
+    }
+    // A `text/plain` body arrives already parsed as a **string** (Fastify's
+    // built-in text parser, which the `*` catch-all does not shadow); other
+    // `text/*` and binary media types arrive as a raw stream. Wrap a string (or
+    // Buffer) as a byte stream so it is written verbatim -- piping a string into
+    // the backend's `stream.pipeline` would iterate it by UTF-16 code unit (one
+    // write per character, splitting astral-plane characters into lone
+    // surrogates), corrupting the stored bytes.
+    const body = request.body;
+    if (typeof body === 'string' || Buffer.isBuffer(body)) {
+        const bytes = Buffer.from(body);
+        return {
+            kind: 'binary',
+            contentType,
+            stream: Readable.from(bytes),
+            declaredBytes: bytes.length
+        };
+    }
+    // A raw (non-multipart) blob body carries its size in `Content-Length` when
+    // present; expose it as `declaredBytes` so the backend can pre-flight the
+    // quota check before streaming. Ignore an absent or malformed value.
+    const contentLength = Number(request.headers['content-length']);
+    return {
+        kind: 'binary',
+        contentType,
+        stream: body,
+        declaredBytes: Number.isInteger(contentLength) && contentLength >= 0
+            ? contentLength
+            : undefined
+    };
+}
+//# sourceMappingURL=resourceInput.js.map

package/dist/requests/resourceInput.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resourceInput.js","sourceRoot":"","sources":["../../src/requests/resourceInput.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AACtC,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AACzC,OAAO,EACL,uBAAuB,EACvB,uBAAuB,EACvB,oBAAoB,EACrB,MAAM,cAAc,CAAA;AAGrB;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,OAAuB,EACvB,WAA4B;IAE5B,MAAM,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,cAAc,CAAC,CAAA;IACnD,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,MAAM,IAAI,uBAAuB,CAAC,EAAE,WAAW,EAAE,gBAAgB,EAAE,CAAC,CAAA;IACtE,CAAC;IAED,IAAI,MAAM,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,CAAC;QAC5B,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAA;IAC1D,CAAC;IACD,IAAI,WAAW,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;QACxC,2EAA2E;QAC3E,wEAAwE;QACxE,uEAAuE;QACvE,6EAA6E;QAC7E,4EAA4E;QAC5E,6EAA6E;QAC7E,4EAA4E;QAC5E,6EAA6E;QAC7E,uEAAuE;QACvE,4EAA4E;QAC5E,2EAA2E;QAC3E,sDAAsD;QACtD,MAAM,OAAO,GAAG,WAAW,IAAI,OAAO,CAAC,MAAM,CAAC,OAAO,CAAA;QACrD,IAAI,IAAqD,CAAA;QACzD,IAAI,KAAK,EAAE,MAAM,IAAI,IAAI,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC;YACzC,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;gBACzB,SAAQ;YACV,CAAC;YACD,IAAI,IAAI,EAAE,CAAC;gBACT,MAAM,IAAI,uBAAuB,CAAC;oBAChC,WAAW,EAAE,gBAAgB;oBAC7B,MAAM,EAAE,qDAAqD;iBAC9D,CAAC,CAAA;YACJ,CAAC;YACD,IAAI,CAAC;gBACH,IAAI,GAAG,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,KAAK,EAAE,MAAM,IAAI,CAAC,QAAQ,EAAE,EAAE,CAAA;YAClE,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAK,GAAyB,CAAC,IAAI,KAAK,wBAAwB,EAAE,CAAC;oBACjE,MAAM,IAAI,oBAAoB,CAAC;wBAC7B,cAAc,EAAE,OAAO,CAAC,cAAe;wBACvC,SAAS,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,EAAE;qBACjC,CAAC,CAAA;gBACJ,CAAC;gBACD,MAAM,GAAG,CAAA;YACX,CAAC;QACH,CAAC;QACD,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,MAAM,IAAI,uBAAuB,CAAC;gBAChC,WAAW,EAAE,gBAAgB;gBAC7B,MAAM,EAAE,2CAA2C;aACpD,CAAC,CAAA;QACJ,CAAC;QACD,OAAO;YACL,IAAI,EAAE,QAAQ;YACd,WAAW,EAAE,IAAI,CAAC,QAAQ;YAC1B,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC;YACjC,aAAa,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM;SACjC,CAAA;IACH,CAAC;IACD,wEAAwE;IACxE,wEAAwE;IACxE,4EAA4E;IAC5E,6EAA6E;IAC7E,4EAA4E;IAC5E,mEAAmE;IACnE,4CAA4C;IAC5C,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAA;IACzB,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACtD,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,IAAuB,CAAC,CAAA;QAClD,OAAO;YACL,IAAI,EAAE,QAAQ;YACd,WAAW;YACX,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC;YAC5B,aAAa,EAAE,KAAK,CAAC,MAAM;SAC5B,CAAA;IACH,CAAC;IACD,4EAA4E;IAC5E,0EAA0E;IAC1E,qEAAqE;IACrE,MAAM,aAAa,GAAG,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAA;IAC/D,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,WAAW;QACX,MAAM,EAAE,IAAgB;QACxB,aAAa,EACX,MAAM,CAAC,SAAS,CAAC,aAAa,CAAC,IAAI,aAAa,IAAI,CAAC;YACnD,CAAC,CAAC,aAAa;YACf,CAAC,CAAC,SAAS;KAChB,CAAA;AACH,CAAC"}

package/dist/requests/spaceContext.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Shared handler prelude: fetch a Space (for its controller) and authorize the
+ * request against a target. Nearly every handler repeats the same shape -- load
+ * the Space Description to get the controller key, build the capability's
+ * `invocationTarget` URL, then check authorization -- so it lives here.
+ *
+ * Two entry points, one per authorization model, so the call site names which it
+ * uses (rather than passing a flag):
+ *
+ * - `fetchSpaceAndAuthorize` -- **capability-or-policy**: capability invocation
+ *   first, then the target's effective access-control policy as a fallback. For
+ *   read/list endpoints that may be public-readable.
+ * - `fetchSpaceAndVerify` -- **capability-only**: capability invocation, no
+ *   policy fallback. For write/privileged endpoints and the controller-managed
+ *   policy resource.
+ */
+import type { FastifyRequest } from 'fastify';
+import type { IDID, SpaceDescription, StorageBackend } from '../types.js';
+/**
+ * Drops the cached Space Description for a Space. Call after any write that
+ * changes (or removes) it -- create/update/delete -- so the next read reflects
+ * the new state rather than a stale cached one.
+ * @param options {object}
+ * @param options.storage {StorageBackend}   the request's storage backend
+ * @param options.spaceId {string}
+ * @returns {void}
+ */
+export declare function invalidateSpaceDescription({ storage, spaceId }: {
+    storage: StorageBackend;
+    spaceId: string;
+}): void;
+/**
+ * Loads a Space Description by its URL param, masking an unknown (or
+ * non-URL-safe) id as the 404 `SpaceNotFoundError` -- the WAS
+ * existence-masking convention. The verification-free half of
+ * `fetchSpaceAndVerify`, for handlers that need the controller before they can
+ * build their expected values (the revocation route, whose invocation verifies
+ * under the dual-root rule rather than the usual single root). The Space
+ * analogue of `fetchKeystore` (keystoreContext.ts).
+ *
+ * @param options {object}
+ * @param options.request {FastifyRequest}   supplies `request.server.storage`
+ * @param options.spaceId {string}
+ * @param options.requestName {string}   human-readable request name, used in
+ *   error titles
+ * @returns {Promise<SpaceDescription>}
+ */
+export declare function fetchSpace({ request, spaceId, requestName }: {
+    request: FastifyRequest;
+    spaceId: string;
+    requestName: string;
+}): Promise<SpaceDescription>;
+/** The verified context every handler builds before touching storage. */
+export interface VerifiedSpaceContext {
+    /** the fetched Space Description (its controller authorized the request) */
+    spaceDescription: SpaceDescription;
+    /** the did:key that controls the Space */
+    spaceController: IDID;
+    /** the resolved invocationTarget URL the request was authorized against */
+    allowedTarget: string;
+    /**
+     * the Space's own URL -- the ancestor root target every space-family route
+     * also accepts for a delegated chain that attenuates down to the request
+     * URL (a Space- or Collection-scoped capability delegated by the controller)
+     */
+    spaceRootTarget: string;
+}
+/**
+ * Fetches the Space and AUTHORIZES the request **capability-or-policy**:
+ * capability invocation first, then the target's effective access-control policy
+ * as a fallback (see authorize.ts). Use for read/list endpoints that may be
+ * public-readable. The action checked is the request's HTTP method. Returns the
+ * fetched Space Description so callers that also serve it (e.g. "Read Space")
+ * need not fetch it twice.
+ *
+ * @param options {object}
+ * @param options.request {FastifyRequest}   supplies url, method, headers,
+ *   logger, and `request.server` for serverUrl + storage
+ * @param options.spaceId {string}
+ * @param [options.collectionId] {string}   policy-resolution level
+ * @param [options.resourceId] {string}   policy-resolution level
+ * @param options.targetPath {string}   the relative path of the capability's
+ *   invocationTarget, resolved against serverUrl (e.g. `/space/${spaceId}`)
+ * @param options.requestName {string}   human-readable request name, used in
+ *   error titles
+ * @returns {Promise<VerifiedSpaceContext>}
+ */
+export declare function fetchSpaceAndAuthorize({ request, spaceId, collectionId, resourceId, targetPath, requestName, allowTargetQuery }: {
+    request: FastifyRequest;
+    spaceId: string;
+    collectionId?: string;
+    resourceId?: string;
+    targetPath: string;
+    requestName: string;
+    /**
+     * When set, the capability-invocation path tolerates query parameters on
+     * the request URL that extend `targetPath` (e.g. List Collection's
+     * `?limit`/`cursor`), treating them as a RESTful attenuation of the same
+     * target rather than a different one. See `verifyZcap`.
+     */
+    allowTargetQuery?: boolean;
+}): Promise<VerifiedSpaceContext>;
+/**
+ * Fetches the Space and VERIFIES the request **capability-only**: a valid
+ * capability invocation is required, with no access-control-policy fallback (see
+ * zcap.ts). Use for write/privileged endpoints and the controller-managed policy
+ * resource. The action checked is the request's HTTP method. The Space's
+ * revocation store is consulted on every delegated chain, so a revoked
+ * capability fails here as it does on the `/kms` routes.
+ *
+ * @param options {object}
+ * @param options.request {FastifyRequest}   supplies url, method, headers,
+ *   logger, and `request.server` for serverUrl + storage
+ * @param options.spaceId {string}
+ * @param options.targetPath {string}   the relative path of the capability's
+ *   invocationTarget, resolved against serverUrl (e.g. `/space/${spaceId}`)
+ * @param options.requestName {string}   human-readable request name, used in
+ *   error titles
+ * @returns {Promise<VerifiedSpaceContext>}
+ */
+export declare function fetchSpaceAndVerify({ request, spaceId, targetPath, requestName }: {
+    request: FastifyRequest;
+    spaceId: string;
+    targetPath: string;
+    requestName: string;
+}): Promise<VerifiedSpaceContext>;
+//# sourceMappingURL=spaceContext.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"spaceContext.d.ts","sourceRoot":"","sources":["../../src/requests/spaceContext.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAW7C,OAAO,KAAK,EAAE,IAAI,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AA2BzE;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,EACzC,OAAO,EACP,OAAO,EACR,EAAE;IACD,OAAO,EAAE,cAAc,CAAA;IACvB,OAAO,EAAE,MAAM,CAAA;CAChB,GAAG,IAAI,CAGP;AAkCD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,UAAU,CAAC,EAC/B,OAAO,EACP,OAAO,EACP,WAAW,EACZ,EAAE;IACD,OAAO,EAAE,cAAc,CAAA;IACvB,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,MAAM,CAAA;CACpB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAW5B;AAED,yEAAyE;AACzE,MAAM,WAAW,oBAAoB;IACnC,4EAA4E;IAC5E,gBAAgB,EAAE,gBAAgB,CAAA;IAClC,0CAA0C;IAC1C,eAAe,EAAE,IAAI,CAAA;IACrB,2EAA2E;IAC3E,aAAa,EAAE,MAAM,CAAA;IACrB;;;;OAIG;IACH,eAAe,EAAE,MAAM,CAAA;CACxB;AAuCD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,sBAAsB,CAAC,EAC3C,OAAO,EACP,OAAO,EACP,YAAY,EACZ,UAAU,EACV,UAAU,EACV,WAAW,EACX,gBAAwB,EACzB,EAAE;IACD,OAAO,EAAE,cAAc,CAAA;IACvB,OAAO,EAAE,MAAM,CAAA;IACf,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,UAAU,EAAE,MAAM,CAAA;IAClB,WAAW,EAAE,MAAM,CAAA;IACnB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAC3B,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAmBhC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,mBAAmB,CAAC,EACxC,OAAO,EACP,OAAO,EACP,UAAU,EACV,WAAW,EACZ,EAAE;IACD,OAAO,EAAE,cAAc,CAAA;IACvB,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,MAAM,CAAA;IAClB,WAAW,EAAE,MAAM,CAAA;CACpB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAuBhC"}

package/dist/requests/spaceContext.js

@@ -0,0 +1,201 @@
+import { LruCache } from '@interop/lru-memoize';
+import { handleZcapVerify } from '../zcap.js';
+import { authorize } from '../authorize.js';
+import { spacePath } from '../lib/paths.js';
+import { isUrlSafeSegment } from '../lib/validateId.js';
+import { SpaceNotFoundError } from '../errors.js';
+import { SPACE_DESCRIPTION_CACHE_MAX, SPACE_DESCRIPTION_CACHE_TTL } from '../config.default.js';
+/**
+ * One short-TTL memoization cache per storage backend, keyed by `spaceId`. The
+ * cache is scoped to the backend instance (rather than module-global) via a
+ * WeakMap so two backends in one process -- e.g. parallel test suites -- never
+ * serve each other's descriptions, and a cache is discarded with its backend.
+ */
+const descriptionCaches = new WeakMap();
+/**
+ * Returns the (lazily created) Space Description cache for a backend.
+ * @param storage {StorageBackend}
+ * @returns {LruCache}
+ */
+function descriptionCacheFor(storage) {
+    let cache = descriptionCaches.get(storage);
+    if (!cache) {
+        cache = new LruCache({
+            max: SPACE_DESCRIPTION_CACHE_MAX,
+            ttl: SPACE_DESCRIPTION_CACHE_TTL
+        });
+        descriptionCaches.set(storage, cache);
+    }
+    return cache;
+}
+/**
+ * Drops the cached Space Description for a Space. Call after any write that
+ * changes (or removes) it -- create/update/delete -- so the next read reflects
+ * the new state rather than a stale cached one.
+ * @param options {object}
+ * @param options.storage {StorageBackend}   the request's storage backend
+ * @param options.spaceId {string}
+ * @returns {void}
+ */
+export function invalidateSpaceDescription({ storage, spaceId }) {
+    // Only touch a cache that already exists for this backend.
+    descriptionCaches.get(storage)?.delete(spaceId);
+}
+/**
+ * Fetches a Space Description or throws SpaceNotFoundError (404) when absent.
+ * Memoized per storage backend (short TTL) because this is read on every
+ * authorized handler; writes invalidate via `invalidateSpaceDescription`.
+ * @param options {object}
+ * @param options.storage {StorageBackend}   the request's storage backend
+ * @param options.spaceId {string}
+ * @param options.requestName {string}   human-readable request name, used in
+ *   error titles
+ * @returns {Promise<SpaceDescription>}
+ */
+async function getSpaceDescriptionOrThrow({ storage, spaceId, requestName }) {
+    const spaceDescription = await descriptionCacheFor(storage).memoize({
+        key: spaceId,
+        fn: () => storage.getSpaceDescription({ spaceId })
+    });
+    if (!spaceDescription) {
+        throw new SpaceNotFoundError({ requestName });
+    }
+    return spaceDescription;
+}
+/**
+ * Loads a Space Description by its URL param, masking an unknown (or
+ * non-URL-safe) id as the 404 `SpaceNotFoundError` -- the WAS
+ * existence-masking convention. The verification-free half of
+ * `fetchSpaceAndVerify`, for handlers that need the controller before they can
+ * build their expected values (the revocation route, whose invocation verifies
+ * under the dual-root rule rather than the usual single root). The Space
+ * analogue of `fetchKeystore` (keystoreContext.ts).
+ *
+ * @param options {object}
+ * @param options.request {FastifyRequest}   supplies `request.server.storage`
+ * @param options.spaceId {string}
+ * @param options.requestName {string}   human-readable request name, used in
+ *   error titles
+ * @returns {Promise<SpaceDescription>}
+ */
+export async function fetchSpace({ request, spaceId, requestName }) {
+    // A non-URL-safe id cannot name a stored Space and must not reach the
+    // filesystem layer: same 404 masking.
+    if (!isUrlSafeSegment(spaceId)) {
+        throw new SpaceNotFoundError({ requestName });
+    }
+    return await getSpaceDescriptionOrThrow({
+        storage: request.server.storage,
+        spaceId,
+        requestName
+    });
+}
+/**
+ * Loads the Space and builds the capability's invocationTarget URL -- the part
+ * shared by both authorization models below. Does not check authorization.
+ *
+ * @param options {object}
+ * @param options.request {FastifyRequest}   supplies `request.server` for
+ *   serverUrl + storage
+ * @param options.spaceId {string}
+ * @param options.targetPath {string}   the relative path of the capability's
+ *   invocationTarget, resolved against serverUrl (e.g. `/space/${spaceId}`)
+ * @param options.requestName {string}   human-readable request name, used in
+ *   error titles
+ * @returns {Promise<VerifiedSpaceContext>}
+ */
+async function fetchSpaceContext({ request, spaceId, targetPath, requestName }) {
+    const { serverUrl, storage } = request.server;
+    const spaceDescription = await getSpaceDescriptionOrThrow({
+        storage,
+        spaceId,
+        requestName
+    });
+    const spaceController = spaceDescription.controller;
+    const allowedTarget = new URL(targetPath, serverUrl).toString();
+    const spaceRootTarget = new URL(spacePath({ spaceId }), serverUrl).toString();
+    return { spaceDescription, spaceController, allowedTarget, spaceRootTarget };
+}
+/**
+ * Fetches the Space and AUTHORIZES the request **capability-or-policy**:
+ * capability invocation first, then the target's effective access-control policy
+ * as a fallback (see authorize.ts). Use for read/list endpoints that may be
+ * public-readable. The action checked is the request's HTTP method. Returns the
+ * fetched Space Description so callers that also serve it (e.g. "Read Space")
+ * need not fetch it twice.
+ *
+ * @param options {object}
+ * @param options.request {FastifyRequest}   supplies url, method, headers,
+ *   logger, and `request.server` for serverUrl + storage
+ * @param options.spaceId {string}
+ * @param [options.collectionId] {string}   policy-resolution level
+ * @param [options.resourceId] {string}   policy-resolution level
+ * @param options.targetPath {string}   the relative path of the capability's
+ *   invocationTarget, resolved against serverUrl (e.g. `/space/${spaceId}`)
+ * @param options.requestName {string}   human-readable request name, used in
+ *   error titles
+ * @returns {Promise<VerifiedSpaceContext>}
+ */
+export async function fetchSpaceAndAuthorize({ request, spaceId, collectionId, resourceId, targetPath, requestName, allowTargetQuery = false }) {
+    const context = await fetchSpaceContext({
+        request,
+        spaceId,
+        targetPath,
+        requestName
+    });
+    await authorize({
+        request,
+        allowedTarget: context.allowedTarget,
+        spaceId,
+        collectionId,
+        resourceId,
+        spaceController: context.spaceController,
+        requestName,
+        allowTargetQuery,
+        attenuatedRootTarget: context.spaceRootTarget
+    });
+    return context;
+}
+/**
+ * Fetches the Space and VERIFIES the request **capability-only**: a valid
+ * capability invocation is required, with no access-control-policy fallback (see
+ * zcap.ts). Use for write/privileged endpoints and the controller-managed policy
+ * resource. The action checked is the request's HTTP method. The Space's
+ * revocation store is consulted on every delegated chain, so a revoked
+ * capability fails here as it does on the `/kms` routes.
+ *
+ * @param options {object}
+ * @param options.request {FastifyRequest}   supplies url, method, headers,
+ *   logger, and `request.server` for serverUrl + storage
+ * @param options.spaceId {string}
+ * @param options.targetPath {string}   the relative path of the capability's
+ *   invocationTarget, resolved against serverUrl (e.g. `/space/${spaceId}`)
+ * @param options.requestName {string}   human-readable request name, used in
+ *   error titles
+ * @returns {Promise<VerifiedSpaceContext>}
+ */
+export async function fetchSpaceAndVerify({ request, spaceId, targetPath, requestName }) {
+    const context = await fetchSpaceContext({
+        request,
+        spaceId,
+        targetPath,
+        requestName
+    });
+    const { url, method, headers } = request;
+    const { serverUrl, storage } = request.server;
+    await handleZcapVerify({
+        url,
+        allowedTarget: context.allowedTarget,
+        allowedAction: method,
+        method,
+        headers,
+        serverUrl,
+        spaceController: context.spaceController,
+        requestName,
+        logger: request.log,
+        attenuatedRootTarget: context.spaceRootTarget,
+        revocation: { storage, scope: { spaceId } }
+    });
+    return context;
+}
+//# sourceMappingURL=spaceContext.js.map

package/dist/requests/spaceContext.js.map

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

package/dist/routes.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Route layer: maps URL patterns to *Request handler methods. Each group first
+ * installs the `requireAuthHeadersOrPublicRead` then `parseAuthHeaders`
+ * onRequest hooks, and redirects slash/no-slash variants to the canonical form.
+ * (The WebKMS `/kms` group is the exception on both counts: it installs the
+ * strict `requireAuthHeaders` -- the webkms protocol has no public reads --
+ * and no slash redirects, since the protocol's URLs are exact.)
+ */
+import type { FastifyInstance, FastifyPluginOptions } from 'fastify';
+/**
+ * Registers SpacesRepository routes (POST/GET /spaces). Installs the
+ * `requireAuthHeadersOrPublicRead` then `parseAuthHeaders` onRequest hooks and
+ * the `handleError` error handler.
+ * @param app {import('fastify').FastifyInstance}
+ * @param options {object}   Fastify plugin options
+ * @returns {Promise<void>}
+ */
+export declare function initSpacesRepositoryRoutes(app: FastifyInstance, _options: FastifyPluginOptions): Promise<void>;
+/**
+ * Registers Space routes (get/update/delete a Space, add/list Collections,
+ * export/import). Installs the auth hooks and the `handleError` error handler.
+ * @param app {import('fastify').FastifyInstance}
+ * @param options {object}   Fastify plugin options
+ * @returns {Promise<void>}
+ */
+export declare function initSpaceRoutes(app: FastifyInstance, _options: FastifyPluginOptions): Promise<void>;
+/**
+ * Registers Collection routes (get/update/delete a Collection, list its items,
+ * add a Resource). Installs the auth hooks and the `handleError` error handler.
+ * @param app {import('fastify').FastifyInstance}
+ * @param options {object}   Fastify plugin options
+ * @returns {Promise<void>}
+ */
+export declare function initCollectionRoutes(app: FastifyInstance, _options: FastifyPluginOptions): Promise<void>;
+/**
+ * Registers Resource routes (create-by-id, get, delete a Resource). Installs the
+ * auth hooks and the `handleError` error handler.
+ * @param app {import('fastify').FastifyInstance}
+ * @param options {object}   Fastify plugin options
+ * @returns {Promise<void>}
+ */
+export declare function initResourceRoutes(app: FastifyInstance, _options: FastifyPluginOptions): Promise<void>;
+/**
+ * Registers the WebKMS keystore and key routes (the `/kms` facet).
+ * Installs the same hook chain as the WAS groups
+ * except that the auth requirement is the strict `requireAuthHeaders`: every
+ * webkms route, GETs included, is zcap-invoked -- the protocol has no public
+ * reads. No slash-redirect variants either; the protocol's URLs are exact --
+ * only these shapes are registered.
+ * @param app {import('fastify').FastifyInstance}
+ * @param options {object}   Fastify plugin options
+ * @returns {Promise<void>}
+ */
+export declare function initKmsRoutes(app: FastifyInstance, _options: FastifyPluginOptions): Promise<void>;
+//# sourceMappingURL=routes.d.ts.map

package/dist/routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../src/routes.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EACV,eAAe,EACf,oBAAoB,EAGrB,MAAM,SAAS,CAAA;AAyEhB;;;;;;;GAOG;AACH,wBAAsB,0BAA0B,CAC9C,GAAG,EAAE,eAAe,EACpB,QAAQ,EAAE,oBAAoB,GAC7B,OAAO,CAAC,IAAI,CAAC,CA0Bf;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,eAAe,EACpB,QAAQ,EAAE,oBAAoB,GAC7B,OAAO,CAAC,IAAI,CAAC,CA8Ef;AAED;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,eAAe,EACpB,QAAQ,EAAE,oBAAoB,GAC7B,OAAO,CAAC,IAAI,CAAC,CA6Df;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,eAAe,EACpB,QAAQ,EAAE,oBAAoB,GAC7B,OAAO,CAAC,IAAI,CAAC,CAuDf;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,eAAe,EACpB,QAAQ,EAAE,oBAAoB,GAC7B,OAAO,CAAC,IAAI,CAAC,CAkDf"}