was-teaching-server 0.9.1

package/dist/requests/KeystoreRequest.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Request handlers for the WebKMS keystore lifecycle (the `/kms` facet):
+ * - POST /kms/keystores (Create Keystore)
+ * - GET /kms/keystores?controller=<did> (List Keystores by controller)
+ * - GET /kms/keystores/:keystoreId (Get Keystore config)
+ * - POST /kms/keystores/:keystoreId (Update Keystore config)
+ *
+ * The wire contract is protocol-fixed by `@interop/webkms-client` (which is
+ * also the conformance suite for it): all routes are zcap-invoked with
+ * `read` / `write` actions (not HTTP verbs), the create response is the bare
+ * config (201 + `Location`), list wraps in `{ results }`, and update wraps in
+ * `{ config }`. The `meterId` / `ipAllowList` fields are deliberately dropped;
+ * the body schemas remain `additionalProperties: false`, so supplying them is
+ * rejected.
+ */
+import type { FastifyReply, FastifyRequest } from 'fastify';
+import type { IDID } from '../types.js';
+/** The keystore config fields a client may supply (create and update). */
+interface KeystoreConfigBody {
+    id?: string;
+    controller: IDID;
+    sequence: number;
+    kmsModule?: string;
+}
+export declare class KeystoreRequest {
+    /**
+     * POST /kms/keystores
+     * Create Keystore. Authorization is the keystore-creation bootstrap rule,
+     * mirroring Create Space (`SpacesRepositoryRequest.post`): the invocation
+     * must be *authorized by* the `controller` DID in the request body -- signed
+     * directly by it, or via a delegation chain rooted in it -- so anyone can
+     * create their own keystore by proving control of the DID they name.
+     * Responds 201 with `Location` and the bare config -- the client asserts a
+     * string `id` on it.
+     *
+     * @param request {import('fastify').FastifyRequest}
+     * @param reply {import('fastify').FastifyReply}
+     * @returns {Promise<FastifyReply>}
+     */
+    static post(request: FastifyRequest<{
+        Body: KeystoreConfigBody;
+    }>, reply: FastifyReply): Promise<FastifyReply>;
+    /**
+     * GET /kms/keystores?controller=<did>
+     * List Keystores by controller. The root capability for `/kms/keystores` is
+     * synthesized with the `controller` *query parameter* as its controller, so
+     * a caller can only list their own keystores (a failed verification is the
+     * masked 404, per the server-wide convention). The query string rides the
+     * request URL, so verification runs in target-attenuation mode (the same
+     * `allowTargetQuery` treatment as List Collection pagination). Responds
+     * `{ results }`, capped at `KEYSTORE_LIST_LIMIT`.
+     *
+     * @param request {import('fastify').FastifyRequest}
+     * @param reply {import('fastify').FastifyReply}
+     * @returns {Promise<FastifyReply>}
+     */
+    static list(request: FastifyRequest<{
+        Querystring: {
+            controller?: string;
+        };
+    }>, reply: FastifyReply): Promise<FastifyReply>;
+    /**
+     * GET /kms/keystores/:keystoreId
+     * Get Keystore config: capability-verified against the stored config's
+     * controller (`read`), responding with the bare config.
+     *
+     * @param request {import('fastify').FastifyRequest}
+     * @param reply {import('fastify').FastifyReply}
+     * @returns {Promise<FastifyReply>}
+     */
+    static get(request: FastifyRequest<{
+        Params: {
+            keystoreId: string;
+        };
+    }>, reply: FastifyReply): Promise<FastifyReply>;
+    /**
+     * POST /kms/keystores/:keystoreId
+     * Update Keystore config. Verified against the *stored* config's controller
+     * (`write`) -- so a controller change is authorized by the current
+     * controller and takes effect immediately. The body's `id` must match the
+     * keystore URL (400); the storage layer applies the update atomically iff
+     * `sequence` is exactly previous+1 and `kmsModule` is unchanged (409
+     * `KeystoreStateConflictError` otherwise; an omitted `kmsModule` defaults to
+     * the stored one). Responds `{ config }` -- note the
+     * wrapper, unlike get/create.
+     *
+     * @param request {import('fastify').FastifyRequest}
+     * @param reply {import('fastify').FastifyReply}
+     * @returns {Promise<FastifyReply>}
+     */
+    static update(request: FastifyRequest<{
+        Params: {
+            keystoreId: string;
+        };
+        Body: KeystoreConfigBody;
+    }>, reply: FastifyReply): Promise<FastifyReply>;
+}
+export {};
+//# sourceMappingURL=KeystoreRequest.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"KeystoreRequest.d.ts","sourceRoot":"","sources":["../../src/requests/KeystoreRequest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAiB3D,OAAO,KAAK,EAAE,IAAI,EAAkB,MAAM,aAAa,CAAA;AAEvD,0EAA0E;AAC1E,UAAU,kBAAkB;IAC1B,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,UAAU,EAAE,IAAI,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAoFD,qBAAa,eAAe;IAC1B;;;;;;;;;;;;;OAaG;WACU,IAAI,CACf,OAAO,EAAE,cAAc,CAAC;QAAE,IAAI,EAAE,kBAAkB,CAAA;KAAE,CAAC,EACrD,KAAK,EAAE,YAAY,GAClB,OAAO,CAAC,YAAY,CAAC;IA0CxB;;;;;;;;;;;;;OAaG;WACU,IAAI,CACf,OAAO,EAAE,cAAc,CAAC;QAAE,WAAW,EAAE;YAAE,UAAU,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC,EACjE,KAAK,EAAE,YAAY,GAClB,OAAO,CAAC,YAAY,CAAC;IA4CxB;;;;;;;;OAQG;WACU,GAAG,CACd,OAAO,EAAE,cAAc,CAAC;QAAE,MAAM,EAAE;YAAE,UAAU,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC,EAC3D,KAAK,EAAE,YAAY,GAClB,OAAO,CAAC,YAAY,CAAC;IAUxB;;;;;;;;;;;;;;OAcG;WACU,MAAM,CACjB,OAAO,EAAE,cAAc,CAAC;QACtB,MAAM,EAAE;YAAE,UAAU,EAAE,MAAM,CAAA;SAAE,CAAA;QAC9B,IAAI,EAAE,kBAAkB,CAAA;KACzB,CAAC,EACF,KAAK,EAAE,YAAY,GAClB,OAAO,CAAC,YAAY,CAAC;CAoCzB"}

package/dist/requests/KeystoreRequest.js

@@ -0,0 +1,247 @@
+import { generateId } from '@digitalcredentials/bnid';
+import { handleZcapVerify } from '../zcap.js';
+import { assertValidController } from '../lib/validateDid.js';
+import { kmsKeystoresPath } from '../lib/paths.js';
+import { fetchKeystoreAndVerify } from './keystoreContext.js';
+import { verifyBodyControllerConsent } from './controllerConsent.js';
+import { DEFAULT_KMS_MODULE, KEYSTORE_LIST_LIMIT, KMS_MAX_CHAIN_LENGTH, KMS_MAX_DELEGATION_TTL } from '../config.default.js';
+import { InvalidRequestBodyError, KeystoreControllerMismatchError } from '../errors.js';
+/**
+ * Validates a keystore config request body against the webkms schema shape
+ * (minus the dropped `meterId` / `ipAllowList`): required fields present, no
+ * unknown fields (`additionalProperties: false`), `controller` a valid
+ * did:key, `sequence` a non-negative integer -- exactly 0 on create; the
+ * update path's previous+1 gate is the storage layer's, where it is atomic.
+ * Throws `InvalidRequestBodyError` (400).
+ *
+ * @param options {object}
+ * @param options.body {unknown}   the parsed request body
+ * @param options.requestName {string}   request name used in error titles
+ * @param [options.isUpdate] {boolean}   validate the update shape (requires
+ *   `id`, allows any non-negative `sequence`)
+ * @returns {KeystoreConfigBody}   the body, narrowed
+ */
+function assertKeystoreConfigBody({ body, requestName, isUpdate = false }) {
+    if (typeof body !== 'object' || body === null || Array.isArray(body)) {
+        throw new InvalidRequestBodyError({
+            requestName,
+            detail: 'Keystore config body must be a JSON object.'
+        });
+    }
+    const allowedKeys = isUpdate
+        ? ['id', 'controller', 'sequence', 'kmsModule']
+        : ['controller', 'sequence', 'kmsModule'];
+    for (const key of Object.keys(body)) {
+        if (!allowedKeys.includes(key)) {
+            throw new InvalidRequestBodyError({
+                requestName,
+                detail: `Unexpected keystore config property "${key}".`,
+                pointer: `#/${key}`
+            });
+        }
+    }
+    const config = body;
+    assertValidController(config.controller, { requestName });
+    if (!Number.isInteger(config.sequence) ||
+        config.sequence < 0 ||
+        config.sequence > Number.MAX_SAFE_INTEGER - 1) {
+        throw new InvalidRequestBodyError({
+            requestName,
+            detail: 'Keystore config "sequence" must be a non-negative integer.',
+            pointer: '#/sequence'
+        });
+    }
+    if (!isUpdate && config.sequence !== 0) {
+        throw new InvalidRequestBodyError({
+            requestName,
+            detail: 'Keystore config sequence must be "0" on create.',
+            pointer: '#/sequence'
+        });
+    }
+    if (isUpdate && typeof config.id !== 'string') {
+        throw new InvalidRequestBodyError({
+            requestName,
+            detail: 'Keystore config "id" is required.',
+            pointer: '#/id'
+        });
+    }
+    if (config.kmsModule !== undefined &&
+        (typeof config.kmsModule !== 'string' || config.kmsModule.length === 0)) {
+        throw new InvalidRequestBodyError({
+            requestName,
+            detail: 'Keystore config "kmsModule" must be a non-empty string.',
+            pointer: '#/kmsModule'
+        });
+    }
+    return config;
+}
+export class KeystoreRequest {
+    /**
+     * POST /kms/keystores
+     * Create Keystore. Authorization is the keystore-creation bootstrap rule,
+     * mirroring Create Space (`SpacesRepositoryRequest.post`): the invocation
+     * must be *authorized by* the `controller` DID in the request body -- signed
+     * directly by it, or via a delegation chain rooted in it -- so anyone can
+     * create their own keystore by proving control of the DID they name.
+     * Responds 201 with `Location` and the bare config -- the client asserts a
+     * string `id` on it.
+     *
+     * @param request {import('fastify').FastifyRequest}
+     * @param reply {import('fastify').FastifyReply}
+     * @returns {Promise<FastifyReply>}
+     */
+    static async post(request, reply) {
+        const requestName = 'Create Keystore';
+        const { body } = request;
+        const { serverUrl, storage } = request.server;
+        assertKeystoreConfigBody({ body, requestName });
+        // The invocation must be *authorized by* the body's controller (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(kmsKeystoresPath(), serverUrl).toString(),
+                allowedAction: 'write',
+                MismatchError: KeystoreControllerMismatchError,
+                requestName,
+                maxChainLength: KMS_MAX_CHAIN_LENGTH,
+                maxDelegationTtl: KMS_MAX_DELEGATION_TTL
+            });
+        }
+        // Server-generated local id, per webkms-switch `generateRandom`: multibase
+        // base58btc of a multihash-framed (identity, 16-byte) 128-bit random value.
+        const keystoreId = await generateId({ multihash: true });
+        const keystoreUrl = new URL(kmsKeystoresPath({ keystoreId }), serverUrl).toString();
+        const config = {
+            id: keystoreUrl,
+            controller: body.controller,
+            sequence: 0,
+            kmsModule: body.kmsModule ?? DEFAULT_KMS_MODULE
+        };
+        await storage.writeKeystore({ keystoreId, config });
+        reply.header('Location', keystoreUrl);
+        return reply.status(201).send(config);
+    }
+    /**
+     * GET /kms/keystores?controller=<did>
+     * List Keystores by controller. The root capability for `/kms/keystores` is
+     * synthesized with the `controller` *query parameter* as its controller, so
+     * a caller can only list their own keystores (a failed verification is the
+     * masked 404, per the server-wide convention). The query string rides the
+     * request URL, so verification runs in target-attenuation mode (the same
+     * `allowTargetQuery` treatment as List Collection pagination). Responds
+     * `{ results }`, capped at `KEYSTORE_LIST_LIMIT`.
+     *
+     * @param request {import('fastify').FastifyRequest}
+     * @param reply {import('fastify').FastifyReply}
+     * @returns {Promise<FastifyReply>}
+     */
+    static async list(request, reply) {
+        const requestName = 'List Keystores';
+        const { url, method, headers, query } = request;
+        const { serverUrl, storage } = request.server;
+        // The list query schema: `controller` required, no other parameters.
+        // The controller names whose keystores are being asked for
+        // (and thereby the root controller the invocation must verify against).
+        for (const key of Object.keys(query)) {
+            if (key !== 'controller') {
+                throw new InvalidRequestBodyError({
+                    requestName,
+                    detail: `Unexpected query parameter "${key}".`
+                });
+            }
+        }
+        assertValidController(query.controller, { requestName });
+        const controller = query.controller;
+        const allowedTarget = new URL(kmsKeystoresPath(), serverUrl).toString();
+        await handleZcapVerify({
+            url,
+            allowedTarget,
+            allowedAction: 'read',
+            method,
+            headers,
+            serverUrl,
+            spaceController: controller,
+            requestName,
+            logger: request.log,
+            allowTargetQuery: true,
+            // The chain roots at the keystores-collection URL (keyed by the query
+            // `controller`), not at any one keystore, so no RevocationScope exists
+            // for it -- collection-level capabilities are outside the per-scope
+            // revocation model.
+            revocation: 'no-revocation-scope',
+            maxChainLength: KMS_MAX_CHAIN_LENGTH,
+            maxDelegationTtl: KMS_MAX_DELEGATION_TTL
+        });
+        const configs = await storage.listKeystoresByController({ controller });
+        return reply.send({ results: configs.slice(0, KEYSTORE_LIST_LIMIT) });
+    }
+    /**
+     * GET /kms/keystores/:keystoreId
+     * Get Keystore config: capability-verified against the stored config's
+     * controller (`read`), responding with the bare config.
+     *
+     * @param request {import('fastify').FastifyRequest}
+     * @param reply {import('fastify').FastifyReply}
+     * @returns {Promise<FastifyReply>}
+     */
+    static async get(request, reply) {
+        const { config } = await fetchKeystoreAndVerify({
+            request,
+            keystoreId: request.params.keystoreId,
+            allowedAction: 'read',
+            requestName: 'Get Keystore'
+        });
+        return reply.send(config);
+    }
+    /**
+     * POST /kms/keystores/:keystoreId
+     * Update Keystore config. Verified against the *stored* config's controller
+     * (`write`) -- so a controller change is authorized by the current
+     * controller and takes effect immediately. The body's `id` must match the
+     * keystore URL (400); the storage layer applies the update atomically iff
+     * `sequence` is exactly previous+1 and `kmsModule` is unchanged (409
+     * `KeystoreStateConflictError` otherwise; an omitted `kmsModule` defaults to
+     * the stored one). Responds `{ config }` -- note the
+     * wrapper, unlike get/create.
+     *
+     * @param request {import('fastify').FastifyRequest}
+     * @param reply {import('fastify').FastifyReply}
+     * @returns {Promise<FastifyReply>}
+     */
+    static async update(request, reply) {
+        const requestName = 'Update Keystore';
+        const { body } = request;
+        const { storage } = request.server;
+        const { keystoreId } = request.params;
+        assertKeystoreConfigBody({ body, requestName, isUpdate: true });
+        const { config: existing } = await fetchKeystoreAndVerify({
+            request,
+            keystoreId,
+            allowedAction: 'write',
+            requestName
+        });
+        // The stored `id` is the keystore's full URL; the submitted config must
+        // name the same keystore it is posted to.
+        if (body.id !== existing.id) {
+            throw new InvalidRequestBodyError({
+                requestName,
+                detail: 'Configuration "id" does not match request URL.',
+                pointer: '#/id'
+            });
+        }
+        const config = {
+            id: existing.id,
+            controller: body.controller,
+            sequence: body.sequence,
+            kmsModule: body.kmsModule ?? existing.kmsModule
+        };
+        // Throws the merged 409 state conflict on a sequence / kmsModule mismatch,
+        // atomically with the write.
+        await storage.updateKeystore({ keystoreId, config });
+        return reply.send({ config });
+    }
+}
+//# sourceMappingURL=KeystoreRequest.js.map

package/dist/requests/KeystoreRequest.js.map

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

package/dist/requests/PolicyRequest.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Request handlers for access-control policy operations: get/update/delete the
+ * `policy` auxiliary resource at the Space, Collection, or Resource level (the
+ * level is selected by which path params are present). Reading or modifying a
+ * policy is privileged: every operation verifies a capability invocation against
+ * the Space controller (the read-method relaxation in auth-header-hooks.ts does
+ * not apply here -- a policy is controller-managed metadata, not public data).
+ */
+import type { FastifyReply, FastifyRequest } from 'fastify';
+/** Path params shared by the three policy route shapes. */
+interface PolicyParams {
+    spaceId: string;
+    collectionId?: string;
+    resourceId?: string;
+}
+export declare class PolicyRequest {
+    /**
+     * GET /space/:spaceId[/:collectionId[/:resourceId]]/policy
+     * Read the access-control policy document set at this level.
+     *
+     * @param request {import('fastify').FastifyRequest}
+     * @param reply {import('fastify').FastifyReply}
+     * @returns {Promise<FastifyReply>}
+     */
+    static get(request: FastifyRequest<{
+        Params: PolicyParams;
+    }>, reply: FastifyReply): Promise<FastifyReply>;
+    /**
+     * PUT /space/:spaceId[/:collectionId[/:resourceId]]/policy
+     * Create or replace the access-control policy document at this level.
+     *
+     * @param request {import('fastify').FastifyRequest}
+     * @param reply {import('fastify').FastifyReply}
+     * @returns {Promise<FastifyReply>}
+     */
+    static put(request: FastifyRequest<{
+        Params: PolicyParams;
+        Body: unknown;
+    }>, reply: FastifyReply): Promise<FastifyReply>;
+    /**
+     * DELETE /space/:spaceId[/:collectionId[/:resourceId]]/policy
+     * Remove the access-control policy document at this level (idempotent).
+     *
+     * @param request {import('fastify').FastifyRequest}
+     * @param reply {import('fastify').FastifyReply}
+     * @returns {Promise<FastifyReply>}
+     */
+    static delete(request: FastifyRequest<{
+        Params: PolicyParams;
+    }>, reply: FastifyReply): Promise<FastifyReply>;
+}
+export {};
+//# sourceMappingURL=PolicyRequest.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PolicyRequest.d.ts","sourceRoot":"","sources":["../../src/requests/PolicyRequest.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAW3D,2DAA2D;AAC3D,UAAU,YAAY;IACpB,OAAO,EAAE,MAAM,CAAA;IACf,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAiBD,qBAAa,aAAa;IACxB;;;;;;;OAOG;WACU,GAAG,CACd,OAAO,EAAE,cAAc,CAAC;QAAE,MAAM,EAAE,YAAY,CAAA;KAAE,CAAC,EACjD,KAAK,EAAE,YAAY,GAClB,OAAO,CAAC,YAAY,CAAC;IA+BxB;;;;;;;OAOG;WACU,GAAG,CACd,OAAO,EAAE,cAAc,CAAC;QAAE,MAAM,EAAE,YAAY,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC,EAChE,KAAK,EAAE,YAAY,GAClB,OAAO,CAAC,YAAY,CAAC;IA2CxB;;;;;;;OAOG;WACU,MAAM,CACjB,OAAO,EAAE,cAAc,CAAC;QAAE,MAAM,EAAE,YAAY,CAAA;KAAE,CAAC,EACjD,KAAK,EAAE,YAAY,GAClB,OAAO,CAAC,YAAY,CAAC;CAmBzB"}

package/dist/requests/PolicyRequest.js

@@ -0,0 +1,124 @@
+import { fetchSpaceAndVerify } from './spaceContext.js';
+import { assertValidIds } from '../lib/validateId.js';
+import { policyPath } from '../lib/paths.js';
+import { InvalidPolicyError, MissingAuthError, PolicyNotFoundError } from '../errors.js';
+/**
+ * Asserts the request carries auth headers, throwing MissingAuthError (401)
+ * otherwise. Needed for the GET handler, which the `requireAuthHeaders` hook
+ * lets through unauthenticated (it is a safe method); PUT/DELETE are already
+ * gated by the hook.
+ * @param request {FastifyRequest}
+ * @returns {void}
+ */
+function requireAuth(request) {
+    const { headers } = request;
+    if (!(headers.authorization && headers['capability-invocation'])) {
+        throw new MissingAuthError();
+    }
+}
+export class PolicyRequest {
+    /**
+     * GET /space/:spaceId[/:collectionId[/:resourceId]]/policy
+     * Read the access-control policy document set at this level.
+     *
+     * @param request {import('fastify').FastifyRequest}
+     * @param reply {import('fastify').FastifyReply}
+     * @returns {Promise<FastifyReply>}
+     */
+    static async get(request, reply) {
+        const { spaceId, collectionId, resourceId } = request.params;
+        const { storage } = request.server;
+        const requestName = 'Get Policy';
+        assertValidIds({ spaceId, collectionId, resourceId }, { requestName });
+        requireAuth(request);
+        // Verify (capability-only): a policy is controller-managed metadata, so
+        // reading it requires a valid capability invocation -- no policy fallback.
+        await fetchSpaceAndVerify({
+            request,
+            spaceId,
+            targetPath: policyPath({ spaceId, collectionId, resourceId }),
+            requestName
+        });
+        const policy = await storage.getPolicy({
+            spaceId,
+            collectionId,
+            resourceId
+        });
+        if (!policy) {
+            throw new PolicyNotFoundError({ requestName });
+        }
+        return reply
+            .status(200)
+            .type('application/json')
+            .send(JSON.stringify(policy));
+    }
+    /**
+     * PUT /space/:spaceId[/:collectionId[/:resourceId]]/policy
+     * Create or replace the access-control policy document at this level.
+     *
+     * @param request {import('fastify').FastifyRequest}
+     * @param reply {import('fastify').FastifyReply}
+     * @returns {Promise<FastifyReply>}
+     */
+    static async put(request, reply) {
+        const { spaceId, collectionId, resourceId } = request.params;
+        const { body } = request;
+        const { storage } = request.server;
+        const requestName = 'Update Policy';
+        assertValidIds({ spaceId, collectionId, resourceId }, { requestName });
+        // A policy document must be a JSON object carrying a non-empty string
+        // `type`. The set of recognized types is intentionally open (unknown types
+        // are stored and fail-closed at evaluation time, see policy.ts), so this is
+        // a shape check only -- it does not gate on a known-types allowlist.
+        const policyType = typeof body === 'object' && body !== null
+            ? body.type
+            : undefined;
+        if (typeof policyType !== 'string' || policyType.trim() === '') {
+            throw new InvalidPolicyError({ requestName });
+        }
+        const policy = body;
+        // Verify (capability-only): a policy is controller-managed metadata, so
+        // writing it requires a valid capability invocation -- no policy fallback.
+        const { allowedTarget: policyUrl } = await fetchSpaceAndVerify({
+            request,
+            spaceId,
+            targetPath: policyPath({ spaceId, collectionId, resourceId }),
+            requestName
+        });
+        const existing = await storage.getPolicy({
+            spaceId,
+            collectionId,
+            resourceId
+        });
+        await storage.writePolicy({ spaceId, collectionId, resourceId, policy });
+        reply.header('Location', policyUrl);
+        return existing
+            ? reply.status(204).send() // update
+            : reply.status(201).send(policy); // create
+    }
+    /**
+     * DELETE /space/:spaceId[/:collectionId[/:resourceId]]/policy
+     * Remove the access-control policy document at this level (idempotent).
+     *
+     * @param request {import('fastify').FastifyRequest}
+     * @param reply {import('fastify').FastifyReply}
+     * @returns {Promise<FastifyReply>}
+     */
+    static async delete(request, reply) {
+        const { spaceId, collectionId, resourceId } = request.params;
+        const { storage } = request.server;
+        const requestName = 'Delete Policy';
+        assertValidIds({ spaceId, collectionId, resourceId }, { requestName });
+        // Verify (capability-only): a policy is controller-managed metadata, so
+        // deleting it requires a valid capability invocation -- no policy fallback.
+        await fetchSpaceAndVerify({
+            request,
+            spaceId,
+            targetPath: policyPath({ spaceId, collectionId, resourceId }),
+            requestName
+        });
+        await storage.deletePolicy({ spaceId, collectionId, resourceId });
+        return reply.status(204).send();
+    }
+}
+//# sourceMappingURL=PolicyRequest.js.map

package/dist/requests/PolicyRequest.js.map

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