was-teaching-server 0.9.1

package/dist/requests/ResourceRequest.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Request handlers for Resource operations: create-by-id, get, and delete a
+ * Resource (JSON object or binary blob).
+ */
+import type { FastifyReply, FastifyRequest } from 'fastify';
+export declare class ResourceRequest {
+    /**
+     * PUT /space/:spaceId/:collectionId/:resourceId
+     * Request handler for "Create (or Update) Resource by Id" 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 put(request: FastifyRequest<{
+        Params: {
+            spaceId: string;
+            collectionId: string;
+            resourceId: string;
+        };
+    }>, reply: FastifyReply): Promise<FastifyReply>;
+    /**
+     * GET /space/:spaceId/:collectionId/:resourceId
+     * Request handler for "Get Resource" 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 get(request: FastifyRequest<{
+        Params: {
+            spaceId: string;
+            collectionId: string;
+            resourceId: string;
+        };
+    }>, reply: FastifyReply): Promise<FastifyReply>;
+    /**
+     * HEAD /space/:spaceId/:collectionId/:resourceId
+     * Request handler for "Head Resource" request: the same authorization as Get
+     * Resource but with no response body. Per spec "Content Types and
+     * Representations", the response `Content-Type` and `Content-Length`
+     * correspond to the `contentType` and `size` of the Resource's Metadata object
+     * (the bytes a GET would return). HEAD is a safe method, authorized as a read
+     * (capability-or-policy), the same as GET; it reads only the Metadata so it
+     * never opens the resource byte stream.
+     *
+     * Registered explicitly (ahead of the GET route) rather than relying on
+     * Fastify's auto-exposed HEAD, which would share the GET handler and stream
+     * the whole body -- yielding no `Content-Length` for a streamed representation.
+     *
+     * @param request {import('fastify').FastifyRequest}
+     * @param reply {import('fastify').FastifyReply}
+     * @returns {Promise<FastifyReply>}
+     */
+    static head(request: FastifyRequest<{
+        Params: {
+            spaceId: string;
+            collectionId: string;
+            resourceId: string;
+        };
+    }>, reply: FastifyReply): Promise<FastifyReply>;
+    /**
+     * GET /space/:spaceId/:collectionId/:resourceId/meta
+     * Request handler for "Read Resource Metadata" request. Returns the REQUIRED
+     * server-managed fields (`contentType`, `size`), the OPTIONAL `createdAt` /
+     * `updatedAt` timestamps, and the user-writable `custom` object (omitted when
+     * empty). Authorization is capability-or-policy, the same as Get Resource:
+     * metadata reveals nothing beyond what a GET of the resource itself exposes via
+     * Content-Type / Content-Length, so a `PublicCanRead` policy also grants
+     * metadata reads.
+     *
+     * @param request {import('fastify').FastifyRequest}
+     * @param reply {import('fastify').FastifyReply}
+     * @returns {Promise<FastifyReply>}
+     */
+    static getMeta(request: FastifyRequest<{
+        Params: {
+            spaceId: string;
+            collectionId: string;
+            resourceId: string;
+        };
+    }>, reply: FastifyReply): Promise<FastifyReply>;
+    /**
+     * PUT /space/:spaceId/:collectionId/:resourceId/meta
+     * Request handler for "Update Resource Metadata" request. A full replacement
+     * of the Metadata object's user-writable `custom` object (any property omitted
+     * is cleared; a body with no `custom` clears them all). Server-managed
+     * properties are untouched, and any top-level property other than `custom` in
+     * the body is ignored (so a client may GET-modify-PUT the whole object). Does
+     * NOT create: a `PUT` to the `/meta` of a nonexistent Resource is a 404.
+     * Authorization is capability-only (the `PUT` action), the same as Put
+     * Resource. Returns 204.
+     *
+     * @param request {import('fastify').FastifyRequest}
+     * @param reply {import('fastify').FastifyReply}
+     * @returns {Promise<FastifyReply>}
+     */
+    static putMeta(request: FastifyRequest<{
+        Params: {
+            spaceId: string;
+            collectionId: string;
+            resourceId: string;
+        };
+        Body: unknown;
+    }>, reply: FastifyReply): Promise<FastifyReply>;
+    /**
+     * DELETE /space/:spaceId/:collectionId/:resourceId
+     * Request handler for "Delete Resource" 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 delete(request: FastifyRequest<{
+        Params: {
+            spaceId: string;
+            collectionId: string;
+            resourceId: string;
+        };
+    }>, reply: FastifyReply): Promise<FastifyReply>;
+}
+//# sourceMappingURL=ResourceRequest.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ResourceRequest.d.ts","sourceRoot":"","sources":["../../src/requests/ResourceRequest.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AA6F3D,qBAAa,eAAe;IAC1B;;;;;;;;;;;OAWG;WACU,GAAG,CACd,OAAO,EAAE,cAAc,CAAC;QACtB,MAAM,EAAE;YAAE,OAAO,EAAE,MAAM,CAAC;YAAC,YAAY,EAAE,MAAM,CAAC;YAAC,UAAU,EAAE,MAAM,CAAA;SAAE,CAAA;KACtE,CAAC,EACF,KAAK,EAAE,YAAY,GAClB,OAAO,CAAC,YAAY,CAAC;IA+ExB;;;;;;;;;;;OAWG;WACU,GAAG,CACd,OAAO,EAAE,cAAc,CAAC;QACtB,MAAM,EAAE;YAAE,OAAO,EAAE,MAAM,CAAC;YAAC,YAAY,EAAE,MAAM,CAAC;YAAC,UAAU,EAAE,MAAM,CAAA;SAAE,CAAA;KACtE,CAAC,EACF,KAAK,EAAE,YAAY,GAClB,OAAO,CAAC,YAAY,CAAC;IAgExB;;;;;;;;;;;;;;;;;OAiBG;WACU,IAAI,CACf,OAAO,EAAE,cAAc,CAAC;QACtB,MAAM,EAAE;YAAE,OAAO,EAAE,MAAM,CAAC;YAAC,YAAY,EAAE,MAAM,CAAC;YAAC,UAAU,EAAE,MAAM,CAAA;SAAE,CAAA;KACtE,CAAC,EACF,KAAK,EAAE,YAAY,GAClB,OAAO,CAAC,YAAY,CAAC;IAmExB;;;;;;;;;;;;;OAaG;WACU,OAAO,CAClB,OAAO,EAAE,cAAc,CAAC;QACtB,MAAM,EAAE;YAAE,OAAO,EAAE,MAAM,CAAC;YAAC,YAAY,EAAE,MAAM,CAAC;YAAC,UAAU,EAAE,MAAM,CAAA;SAAE,CAAA;KACtE,CAAC,EACF,KAAK,EAAE,YAAY,GAClB,OAAO,CAAC,YAAY,CAAC;IAoExB;;;;;;;;;;;;;;OAcG;WACU,OAAO,CAClB,OAAO,EAAE,cAAc,CAAC;QACtB,MAAM,EAAE;YAAE,OAAO,EAAE,MAAM,CAAC;YAAC,YAAY,EAAE,MAAM,CAAC;YAAC,UAAU,EAAE,MAAM,CAAA;SAAE,CAAA;QACrE,IAAI,EAAE,OAAO,CAAA;KACd,CAAC,EACF,KAAK,EAAE,YAAY,GAClB,OAAO,CAAC,YAAY,CAAC;IA2GxB;;;;;;;;;;;OAWG;WACU,MAAM,CACjB,OAAO,EAAE,cAAc,CAAC;QACtB,MAAM,EAAE;YAAE,OAAO,EAAE,MAAM,CAAC;YAAC,YAAY,EAAE,MAAM,CAAC;YAAC,UAAU,EAAE,MAAM,CAAA;SAAE,CAAA;KACtE,CAAC,EACF,KAAK,EAAE,YAAY,GAClB,OAAO,CAAC,YAAY,CAAC;CAmDzB"}

package/dist/requests/ResourceRequest.js

@@ -0,0 +1,548 @@
+import { fetchSpaceAndAuthorize, fetchSpaceAndVerify } from './spaceContext.js';
+import { getCollectionOrThrow } from './collectionContext.js';
+import { resolveResourceInput } from './resourceInput.js';
+import { invokerDid } from '../auth-header-hooks.js';
+import { resolveBackend } from '../lib/backendRegistry.js';
+import { assertEncryptedWriteConforms, assertEncryptedMetaConforms } from '../lib/encryption.js';
+import { assertValidIds } from '../lib/validateId.js';
+import { resourcePath, metaPath } from '../lib/paths.js';
+import { formatEtag, parseWritePreconditions } from '../lib/etag.js';
+import { parseKeyEpochHeader, parseMetaEpoch } from '../lib/keyEpoch.js';
+import { InvalidRequestBodyError, ResourceNotFoundError, rethrowOrWrapStorageError } from '../errors.js';
+/**
+ * Validates and extracts the user-writable `custom` object from an Update
+ * Resource Metadata request body on a **plaintext** Collection. The body MUST be
+ * a JSON object; any top-level property other than `custom` is ignored (so a
+ * client may GET-modify-PUT the whole Metadata object). A missing `custom`
+ * clears all user-writable properties (returns `{}`). Throws
+ * `InvalidRequestBodyError` (400) when the body or `custom` shape is wrong.
+ *
+ * On an **encrypted** Collection this shape check does not apply -- `custom` is
+ * the opaque encryption envelope, validated structurally by
+ * {@link assertEncryptedMetaConforms} instead (a `422` on non-conformance).
+ * `putMeta` branches on the Collection's `encryption` marker after authorization.
+ * @param body {unknown}   the parsed request body
+ * @returns {ResourceMetadataCustom}
+ */
+function parseCustomMetadata(body) {
+    const requestName = 'Update Resource Metadata';
+    if (typeof body !== 'object' || body === null || Array.isArray(body)) {
+        throw new InvalidRequestBodyError({
+            requestName,
+            detail: 'Request body must be a JSON object.'
+        });
+    }
+    const { custom } = body;
+    if (custom === undefined) {
+        return {};
+    }
+    if (typeof custom !== 'object' || custom === null || Array.isArray(custom)) {
+        throw new InvalidRequestBodyError({
+            requestName,
+            detail: 'The `custom` property must be a JSON object.',
+            pointer: '/custom'
+        });
+    }
+    const { name, tags } = custom;
+    if (name !== undefined && typeof name !== 'string') {
+        throw new InvalidRequestBodyError({
+            requestName,
+            detail: 'The `custom.name` property must be a string.',
+            pointer: '/custom/name'
+        });
+    }
+    if (tags !== undefined &&
+        (typeof tags !== 'object' || tags === null || Array.isArray(tags))) {
+        throw new InvalidRequestBodyError({
+            requestName,
+            detail: 'The `custom.tags` property must be a JSON object.',
+            pointer: '/custom/tags'
+        });
+    }
+    // Tag values MUST be strings (spec: values SHOULD be strings; the wire type
+    // models them as `Record<string, string>`).
+    if (tags !== undefined &&
+        Object.values(tags).some(value => typeof value !== 'string')) {
+        throw new InvalidRequestBodyError({
+            requestName,
+            detail: 'Every `custom.tags` value must be a string.',
+            pointer: '/custom/tags'
+        });
+    }
+    return {
+        ...(name !== undefined && { name }),
+        ...(tags !== undefined && { tags: tags })
+    };
+}
+export class ResourceRequest {
+    /**
+     * PUT /space/:spaceId/:collectionId/:resourceId
+     * Request handler for "Create (or Update) Resource by Id" 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 put(request, reply) {
+        const { params: { spaceId, collectionId, resourceId } } = request;
+        const { storage } = request.server;
+        const requestName = 'Put Resource';
+        // Reject path-traversal / non-URL-safe ids before any storage access.
+        assertValidIds({ spaceId, collectionId, resourceId }, { requestName });
+        // Verify (capability-only): creating/updating a Resource requires a valid
+        // capability invocation; no access-control-policy fallback.
+        await fetchSpaceAndVerify({
+            request,
+            spaceId,
+            targetPath: resourcePath({ spaceId, collectionId, resourceId }),
+            requestName
+        });
+        // zCap checks out, continue
+        // Fetch collection by id
+        const collectionDescription = await getCollectionOrThrow({
+            storage,
+            spaceId,
+            collectionId,
+            requestName
+        });
+        // Fail-closed encryption enforcement: if the Collection declares a recognized
+        // `encryption` scheme, the content write MUST be a conforming envelope of it
+        // (right media type + envelope shape), else `encryption-scheme-mismatch`
+        // (422). Runs after auth (above) and the 404, before the body is resolved --
+        // so a wrong content type is rejected without consuming the upload, and the
+        // 422 is only observable by a caller already authorized to write here.
+        assertEncryptedWriteConforms({
+            collectionDescription,
+            contentType: request.headers['content-type'],
+            body: request.body
+        });
+        // Route resource bytes to the Collection's selected (data-plane) backend.
+        const dataBackend = await resolveBackend({
+            request,
+            spaceId,
+            collectionId,
+            collectionDescription
+        });
+        const input = await resolveResourceInput(request, dataBackend);
+        // A content write into an encrypted Collection MAY declare the key epoch it
+        // encrypted under via the `WAS-Key-Epoch` header (the `key-epochs` feature);
+        // the server stores it opaquely and clears it when absent (the new
+        // ciphertext's epoch is unknown -- a stale stamp is worse than none).
+        // Advisory, non-signature-covered metadata.
+        const { epoch } = parseKeyEpochHeader({
+            headers: request.headers,
+            requestName
+        });
+        // Surface any `If-Match` / `If-None-Match` write precondition to the storage
+        // layer, which evaluates it atomically with the write (returning 412
+        // `precondition-failed` on a mismatch -- rethrown unchanged below).
+        let written;
+        try {
+            written = await dataBackend.writeResource({
+                spaceId,
+                collectionId,
+                resourceId,
+                input,
+                createdBy: invokerDid(request),
+                epoch,
+                ...parseWritePreconditions(request.headers)
+            });
+        }
+        catch (err) {
+            rethrowOrWrapStorageError({ err, requestName });
+        }
+        // Return the new ETag so a client can chain a subsequent conditional write.
+        return reply.status(204).header('etag', formatEtag(written.version)).send();
+    }
+    /**
+     * GET /space/:spaceId/:collectionId/:resourceId
+     * Request handler for "Get Resource" 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 get(request, reply) {
+        const { params: { spaceId, collectionId, resourceId } } = request;
+        const { storage } = request.server;
+        const requestName = 'Get Resource';
+        // Reject path-traversal / non-URL-safe ids before any storage access.
+        assertValidIds({ spaceId, collectionId, resourceId }, { requestName });
+        // Authorize (capability-or-policy): capability invocation first, then fall
+        // back to the effective access-control policy (e.g. a world-readable
+        // Resource). Throws on denial.
+        await fetchSpaceAndAuthorize({
+            request,
+            spaceId,
+            collectionId,
+            resourceId,
+            targetPath: resourcePath({ spaceId, collectionId, resourceId }),
+            requestName
+        });
+        // authorized, continue
+        // Fetch collection by id
+        const collectionDescription = await getCollectionOrThrow({
+            storage,
+            spaceId,
+            collectionId,
+            requestName
+        });
+        // Read the bytes from the Collection's selected (data-plane) backend.
+        const dataBackend = await resolveBackend({
+            request,
+            spaceId,
+            collectionId,
+            collectionDescription
+        });
+        const contentType = request.headers['content-type'];
+        let result;
+        try {
+            result = await dataBackend.getResource({
+                spaceId,
+                collectionId,
+                resourceId,
+                contentType
+            });
+        }
+        catch (err) {
+            // Rethrow a typed ProblemError unchanged -- `getResource`'s
+            // ResourceNotFoundError (404) for an absent resource, or a typed fault a
+            // data-plane backend raises -- and wrap anything unexpected as a 500.
+            rethrowOrWrapStorageError({ err, requestName });
+        }
+        const getReply = reply.status(200).type(result.storedResourceType);
+        // Surface the ETag validator (the conditional-writes feature) when the
+        // backend tracks a version for this Resource.
+        if (result.version !== undefined) {
+            getReply.header('etag', formatEtag(result.version));
+        }
+        return getReply.send(result.resourceStream);
+    }
+    /**
+     * HEAD /space/:spaceId/:collectionId/:resourceId
+     * Request handler for "Head Resource" request: the same authorization as Get
+     * Resource but with no response body. Per spec "Content Types and
+     * Representations", the response `Content-Type` and `Content-Length`
+     * correspond to the `contentType` and `size` of the Resource's Metadata object
+     * (the bytes a GET would return). HEAD is a safe method, authorized as a read
+     * (capability-or-policy), the same as GET; it reads only the Metadata so it
+     * never opens the resource byte stream.
+     *
+     * Registered explicitly (ahead of the GET route) rather than relying on
+     * Fastify's auto-exposed HEAD, which would share the GET handler and stream
+     * the whole body -- yielding no `Content-Length` for a streamed representation.
+     *
+     * @param request {import('fastify').FastifyRequest}
+     * @param reply {import('fastify').FastifyReply}
+     * @returns {Promise<FastifyReply>}
+     */
+    static async head(request, reply) {
+        const { params: { spaceId, collectionId, resourceId } } = request;
+        const { storage } = request.server;
+        const requestName = 'Head Resource';
+        // Reject path-traversal / non-URL-safe ids before any storage access.
+        assertValidIds({ spaceId, collectionId, resourceId }, { requestName });
+        // Authorize (capability-or-policy): the same read decision as Get Resource,
+        // against the same target (a HEAD reveals nothing a GET would not).
+        await fetchSpaceAndAuthorize({
+            request,
+            spaceId,
+            collectionId,
+            resourceId,
+            targetPath: resourcePath({ spaceId, collectionId, resourceId }),
+            requestName
+        });
+        // authorized, continue
+        // Fetch collection by id
+        const collectionDescription = await getCollectionOrThrow({
+            storage,
+            spaceId,
+            collectionId,
+            requestName
+        });
+        // Read Metadata from the Collection's selected (data-plane) backend.
+        const dataBackend = await resolveBackend({
+            request,
+            spaceId,
+            collectionId,
+            collectionDescription
+        });
+        let metadata;
+        try {
+            metadata = await dataBackend.getResourceMetadata({
+                spaceId,
+                collectionId,
+                resourceId
+            });
+        }
+        catch (err) {
+            // Rethrow a typed ProblemError from the data-plane backend unchanged;
+            // wrap anything unexpected as a 500.
+            rethrowOrWrapStorageError({ err, requestName });
+        }
+        if (!metadata) {
+            throw new ResourceNotFoundError({ requestName });
+        }
+        // Set the payload headers a GET would send, but send no body. Fastify keeps
+        // a manually-set `Content-Length` on a bodyless send (it is not recomputed
+        // to 0).
+        const headReply = reply
+            .status(200)
+            .type(metadata.contentType)
+            .header('content-length', metadata.size);
+        if (metadata.version !== undefined) {
+            headReply.header('etag', formatEtag(metadata.version));
+        }
+        return headReply.send();
+    }
+    /**
+     * GET /space/:spaceId/:collectionId/:resourceId/meta
+     * Request handler for "Read Resource Metadata" request. Returns the REQUIRED
+     * server-managed fields (`contentType`, `size`), the OPTIONAL `createdAt` /
+     * `updatedAt` timestamps, and the user-writable `custom` object (omitted when
+     * empty). Authorization is capability-or-policy, the same as Get Resource:
+     * metadata reveals nothing beyond what a GET of the resource itself exposes via
+     * Content-Type / Content-Length, so a `PublicCanRead` policy also grants
+     * metadata reads.
+     *
+     * @param request {import('fastify').FastifyRequest}
+     * @param reply {import('fastify').FastifyReply}
+     * @returns {Promise<FastifyReply>}
+     */
+    static async getMeta(request, reply) {
+        const { params: { spaceId, collectionId, resourceId } } = request;
+        const { storage } = request.server;
+        const requestName = 'Get Resource Metadata';
+        // Reject path-traversal / non-URL-safe ids before any storage access.
+        assertValidIds({ spaceId, collectionId, resourceId }, { requestName });
+        // Authorize (capability-or-policy): the capability's `invocationTarget` is
+        // the full `/meta` URL (matching the request URL), and the policy level
+        // resolves at the resource as for Get Resource.
+        await fetchSpaceAndAuthorize({
+            request,
+            spaceId,
+            collectionId,
+            resourceId,
+            targetPath: metaPath({ spaceId, collectionId, resourceId }),
+            requestName
+        });
+        // authorized, continue
+        // Fetch collection by id
+        const collectionDescription = await getCollectionOrThrow({
+            storage,
+            spaceId,
+            collectionId,
+            requestName
+        });
+        // Read Metadata from the Collection's selected (data-plane) backend.
+        const dataBackend = await resolveBackend({
+            request,
+            spaceId,
+            collectionId,
+            collectionDescription
+        });
+        let metadata;
+        try {
+            metadata = await dataBackend.getResourceMetadata({
+                spaceId,
+                collectionId,
+                resourceId
+            });
+        }
+        catch (err) {
+            // Rethrow a typed ProblemError from the data-plane backend unchanged;
+            // wrap anything unexpected as a 500.
+            rethrowOrWrapStorageError({ err, requestName });
+        }
+        if (!metadata) {
+            throw new ResourceNotFoundError({ requestName });
+        }
+        // `version` (content) and `metaVersion` (metadata) are out-of-band ETag
+        // validators, not part of the Resource Metadata wire body, so strip both
+        // before serializing. The `/meta` sub-resource carries its OWN ETag
+        // (`metaVersion`, V2) so a metadata-only edit does not disturb the content
+        // ETag; it is present only once metadata has been written.
+        const { version: _version, metaVersion, ...metadataBody } = metadata;
+        const metaReply = reply.status(200).type('application/json');
+        if (metaVersion !== undefined) {
+            metaReply.header('etag', formatEtag(metaVersion));
+        }
+        return metaReply.send(JSON.stringify(metadataBody));
+    }
+    /**
+     * PUT /space/:spaceId/:collectionId/:resourceId/meta
+     * Request handler for "Update Resource Metadata" request. A full replacement
+     * of the Metadata object's user-writable `custom` object (any property omitted
+     * is cleared; a body with no `custom` clears them all). Server-managed
+     * properties are untouched, and any top-level property other than `custom` in
+     * the body is ignored (so a client may GET-modify-PUT the whole object). Does
+     * NOT create: a `PUT` to the `/meta` of a nonexistent Resource is a 404.
+     * Authorization is capability-only (the `PUT` action), the same as Put
+     * Resource. Returns 204.
+     *
+     * @param request {import('fastify').FastifyRequest}
+     * @param reply {import('fastify').FastifyReply}
+     * @returns {Promise<FastifyReply>}
+     */
+    static async putMeta(request, reply) {
+        const { params: { spaceId, collectionId, resourceId } } = request;
+        const { storage } = request.server;
+        const requestName = 'Update Resource Metadata';
+        // Reject path-traversal / non-URL-safe ids before any storage access.
+        assertValidIds({ spaceId, collectionId, resourceId }, { requestName });
+        // Pre-auth body shape (400): the body MUST be a JSON object. The deeper
+        // `custom` shape check is deferred until after authorization, where the
+        // Collection's `encryption` marker decides whether `custom` is a plaintext
+        // `{ name, tags }` (validated by `parseCustomMetadata`) or an opaque envelope
+        // (validated structurally by `assertEncryptedMetaConforms`) -- neither is
+        // knowable before reading the Collection Description, and gating the check on
+        // auth keeps a 422/400 observable only to a caller authorized to write here.
+        if (typeof request.body !== 'object' ||
+            request.body === null ||
+            Array.isArray(request.body)) {
+            throw new InvalidRequestBodyError({
+                requestName,
+                detail: 'Request body must be a JSON object.'
+            });
+        }
+        // Verify (capability-only): writing metadata requires a valid capability
+        // invocation (the `PUT` action); no access-control-policy fallback.
+        await fetchSpaceAndVerify({
+            request,
+            spaceId,
+            targetPath: metaPath({ spaceId, collectionId, resourceId }),
+            requestName
+        });
+        // zCap checks out, continue
+        // Fetch collection by id
+        const collectionDescription = await getCollectionOrThrow({
+            storage,
+            spaceId,
+            collectionId,
+            requestName
+        });
+        // Branch on the Collection's encryption marker. On an encrypted Collection
+        // the `custom` value MUST be a conforming envelope of the scheme (stored
+        // opaquely, `422` on a plaintext/malformed value); on a plaintext Collection
+        // it MUST be a well-formed `{ name, tags }` object (`400` otherwise).
+        let custom;
+        if (collectionDescription.encryption?.scheme !== undefined) {
+            const rawCustom = request.body.custom;
+            assertEncryptedMetaConforms({ collectionDescription, custom: rawCustom });
+            custom = rawCustom;
+        }
+        else {
+            custom = parseCustomMetadata(request.body);
+        }
+        // The key-epoch stamp (the `key-epochs` feature) MAY also be declared here
+        // as a top-level `epoch` member (a sibling of `custom`). Unlike `custom`
+        // (full-replace), an omitted `epoch` PRESERVES the stored value -- it
+        // describes the content write, not the metadata write. A present value must
+        // be a non-empty string (400).
+        const { epoch } = parseMetaEpoch({
+            body: request.body,
+            requestName
+        });
+        // Write Metadata to the Collection's selected (data-plane) backend. An
+        // `If-Match` / `If-None-Match` precondition (the `conditional-writes`
+        // feature) is evaluated on the `/meta` `metaVersion` atomically with the
+        // write; a mismatch surfaces as 412 `precondition-failed` (rethrown unchanged).
+        const dataBackend = await resolveBackend({
+            request,
+            spaceId,
+            collectionId,
+            collectionDescription
+        });
+        let written;
+        try {
+            written = await dataBackend.writeResourceMetadata({
+                spaceId,
+                collectionId,
+                resourceId,
+                custom,
+                epoch,
+                ...parseWritePreconditions(request.headers)
+            });
+        }
+        catch (err) {
+            rethrowOrWrapStorageError({ err, requestName });
+        }
+        // A Metadata object cannot exist apart from its Resource: a PUT to the
+        // `/meta` of a nonexistent Resource is a 404 (this operation does not create).
+        if (!written) {
+            throw new ResourceNotFoundError({ requestName });
+        }
+        // Return the new `/meta` ETag (`metaVersion`) so a client can chain a
+        // subsequent conditional metadata write.
+        return reply
+            .status(204)
+            .header('etag', formatEtag(written.metaVersion))
+            .send();
+    }
+    /**
+     * DELETE /space/:spaceId/:collectionId/:resourceId
+     * Request handler for "Delete Resource" 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 delete(request, reply) {
+        const { params: { spaceId, collectionId, resourceId } } = request;
+        const { storage } = request.server;
+        const requestName = 'Delete Resource';
+        // Reject path-traversal / non-URL-safe ids before any storage access.
+        assertValidIds({ spaceId, collectionId, resourceId }, { requestName });
+        // Verify (capability-only): deleting a Resource requires a valid capability
+        // invocation; no access-control-policy fallback.
+        await fetchSpaceAndVerify({
+            request,
+            spaceId,
+            targetPath: resourcePath({ spaceId, collectionId, resourceId }),
+            requestName
+        });
+        // Fetch collection by id
+        const collectionDescription = await getCollectionOrThrow({
+            storage,
+            spaceId,
+            collectionId,
+            requestName
+        });
+        // zCap checks out, continue. An `If-Match` precondition is evaluated by the
+        // storage layer atomically with the removal; a mismatch surfaces as 412
+        // `precondition-failed` (rethrown unchanged below).
+        const { ifMatch } = parseWritePreconditions(request.headers);
+        // Delete from the Collection's selected (data-plane) backend.
+        const dataBackend = await resolveBackend({
+            request,
+            spaceId,
+            collectionId,
+            collectionDescription
+        });
+        try {
+            await dataBackend.deleteResource({
+                spaceId,
+                collectionId,
+                resourceId,
+                ifMatch
+            });
+        }
+        catch (err) {
+            rethrowOrWrapStorageError({ err, requestName });
+        }
+        return reply.status(204).send();
+    }
+}
+//# sourceMappingURL=ResourceRequest.js.map