was-teaching-server 0.9.1

package/dist/policy.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Access-control policy evaluation: resolves the effective policy for a target
+ * (most-specific level wins) and decides whether a policy grants an action.
+ * Policies are the fallback authorization path -- consulted when a capability
+ * invocation is absent or does not grant access (see authorize.ts). v1
+ * recognizes only `{ "type": "PublicCanRead" }`; any other `type` grants nothing
+ * (fail-closed). Also builds the RFC9264 linkset that advertises a Space's or
+ * Collection's policy resource for discovery.
+ */
+import type { FastifyBaseLogger } from 'fastify';
+import type { PolicyDocument, StorageBackend } from './types.js';
+/** The kind of access a request needs; derived from the HTTP method. */
+export type AccessAction = 'read' | 'write';
+/**
+ * Resolves the policy that governs a target, honoring the spec's
+ * most-specific-wins inheritance: a Resource policy overrides a Collection
+ * policy, which overrides a Space policy. The first level that has a policy
+ * document is the effective policy; if none do, resolves undefined.
+ *
+ * @param options {object}
+ * @param options.storage {StorageBackend}   the request's storage backend
+ * @param options.spaceId {string}
+ * @param [options.collectionId] {string}
+ * @param [options.resourceId] {string}
+ * @returns {Promise<PolicyDocument | undefined>}
+ */
+export declare function resolveEffectivePolicy({ storage, spaceId, collectionId, resourceId }: {
+    storage: StorageBackend;
+    spaceId: string;
+    collectionId?: string;
+    resourceId?: string;
+}): Promise<PolicyDocument | undefined>;
+/**
+ * Decides whether a policy document grants the requested action. Dispatches on
+ * the policy `type`; an absent policy or an unrecognized `type` grants nothing
+ * (fail-closed).
+ *
+ * @param options {object}
+ * @param [options.policy] {PolicyDocument}   the effective policy, if any
+ * @param options.action {AccessAction}
+ * @param [options.logger] {FastifyBaseLogger}   logger for the fail-closed warn
+ *   on an unrecognized policy type
+ * @returns {boolean}
+ */
+export declare function policyGrants({ policy, action, logger }: {
+    policy?: PolicyDocument;
+    action: AccessAction;
+    logger?: FastifyBaseLogger;
+}): boolean;
+/**
+ * Builds the RFC9264 linkset for a Space or Collection, advertising its
+ * auxiliary resources for discovery. Collection vs Space is selected by whether
+ * `collectionId` is present.
+ *
+ * Relations:
+ * - `policy` (`POLICY_LINK_RELATION`) -- the access-control policy resource,
+ *   advertised only when a policy document is set at that exact level.
+ * - On a Collection (`collectionId` present): `backend` (`BACKEND_LINK_RELATION`)
+ *   and `quota` (`QUOTA_LINK_RELATION`), advertised unconditionally (every
+ *   Collection has a selected backend and a quota report endpoint).
+ * - On a Space (`collectionId` absent): `backends-available`
+ *   (`BACKENDS_AVAILABLE_LINK_RELATION`) and `quotas` (`QUOTAS_LINK_RELATION`),
+ *   advertised unconditionally (both endpoints always exist).
+ *
+ * @param options {object}
+ * @param options.storage {StorageBackend}   the request's storage backend
+ * @param options.spaceId {string}
+ * @param [options.collectionId] {string}
+ * @returns {Promise<object>} a `{ linkset: [...] }` object
+ */
+export declare function buildLinkset({ storage, spaceId, collectionId }: {
+    storage: StorageBackend;
+    spaceId: string;
+    collectionId?: string;
+}): Promise<{
+    linkset: Array<Record<string, unknown>>;
+}>;
+//# sourceMappingURL=policy.d.ts.map

package/dist/policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../src/policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAkBhE,wEAAwE;AACxE,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,OAAO,CAAA;AAE3C;;;;;;;;;;;;GAYG;AACH,wBAAsB,sBAAsB,CAAC,EAC3C,OAAO,EACP,OAAO,EACP,YAAY,EACZ,UAAU,EACX,EAAE;IACD,OAAO,EAAE,cAAc,CAAA;IACvB,OAAO,EAAE,MAAM,CAAA;IACf,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAkBtC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,EAC3B,MAAM,EACN,MAAM,EACN,MAAM,EACP,EAAE;IACD,MAAM,CAAC,EAAE,cAAc,CAAA;IACvB,MAAM,EAAE,YAAY,CAAA;IACpB,MAAM,CAAC,EAAE,iBAAiB,CAAA;CAC3B,GAAG,OAAO,CAiBV;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,YAAY,CAAC,EACjC,OAAO,EACP,OAAO,EACP,YAAY,EACb,EAAE;IACD,OAAO,EAAE,cAAc,CAAA;IACvB,OAAO,EAAE,MAAM,CAAA;IACf,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;CAAE,CAAC,CAiCvD"}

package/dist/policy.js

@@ -0,0 +1,115 @@
+import { POLICY_LINK_RELATION, BACKEND_LINK_RELATION, QUOTA_LINK_RELATION, BACKENDS_AVAILABLE_LINK_RELATION, QUOTAS_LINK_RELATION } from './config.default.js';
+import { collectionPath, spacePath, policyPath, backendPath, quotaPath, backendsPath, quotasPath } from './lib/paths.js';
+/**
+ * Resolves the policy that governs a target, honoring the spec's
+ * most-specific-wins inheritance: a Resource policy overrides a Collection
+ * policy, which overrides a Space policy. The first level that has a policy
+ * document is the effective policy; if none do, resolves undefined.
+ *
+ * @param options {object}
+ * @param options.storage {StorageBackend}   the request's storage backend
+ * @param options.spaceId {string}
+ * @param [options.collectionId] {string}
+ * @param [options.resourceId] {string}
+ * @returns {Promise<PolicyDocument | undefined>}
+ */
+export async function resolveEffectivePolicy({ storage, spaceId, collectionId, resourceId }) {
+    if (collectionId !== undefined && resourceId !== undefined) {
+        const resourcePolicy = await storage.getPolicy({
+            spaceId,
+            collectionId,
+            resourceId
+        });
+        if (resourcePolicy) {
+            return resourcePolicy;
+        }
+    }
+    if (collectionId !== undefined) {
+        const collectionPolicy = await storage.getPolicy({ spaceId, collectionId });
+        if (collectionPolicy) {
+            return collectionPolicy;
+        }
+    }
+    return await storage.getPolicy({ spaceId });
+}
+/**
+ * Decides whether a policy document grants the requested action. Dispatches on
+ * the policy `type`; an absent policy or an unrecognized `type` grants nothing
+ * (fail-closed).
+ *
+ * @param options {object}
+ * @param [options.policy] {PolicyDocument}   the effective policy, if any
+ * @param options.action {AccessAction}
+ * @param [options.logger] {FastifyBaseLogger}   logger for the fail-closed warn
+ *   on an unrecognized policy type
+ * @returns {boolean}
+ */
+export function policyGrants({ policy, action, logger }) {
+    if (!policy) {
+        return false;
+    }
+    switch (policy.type) {
+        case 'PublicCanRead':
+            return action === 'read';
+        default:
+            // Unknown policy type: grant nothing, fall through to zcap-only decision.
+            // Warn so a misconfigured / unsupported policy is diagnosable (the
+            // fail-closed behavior itself is correct; this is purely a signal).
+            logger?.warn({ policyType: policy.type }, 'Unrecognized access-control policy type; granting nothing (fail-closed).');
+            return false;
+    }
+}
+/**
+ * Builds the RFC9264 linkset for a Space or Collection, advertising its
+ * auxiliary resources for discovery. Collection vs Space is selected by whether
+ * `collectionId` is present.
+ *
+ * Relations:
+ * - `policy` (`POLICY_LINK_RELATION`) -- the access-control policy resource,
+ *   advertised only when a policy document is set at that exact level.
+ * - On a Collection (`collectionId` present): `backend` (`BACKEND_LINK_RELATION`)
+ *   and `quota` (`QUOTA_LINK_RELATION`), advertised unconditionally (every
+ *   Collection has a selected backend and a quota report endpoint).
+ * - On a Space (`collectionId` absent): `backends-available`
+ *   (`BACKENDS_AVAILABLE_LINK_RELATION`) and `quotas` (`QUOTAS_LINK_RELATION`),
+ *   advertised unconditionally (both endpoints always exist).
+ *
+ * @param options {object}
+ * @param options.storage {StorageBackend}   the request's storage backend
+ * @param options.spaceId {string}
+ * @param [options.collectionId] {string}
+ * @returns {Promise<object>} a `{ linkset: [...] }` object
+ */
+export async function buildLinkset({ storage, spaceId, collectionId }) {
+    const anchor = collectionId !== undefined
+        ? collectionPath({ spaceId, collectionId })
+        : spacePath({ spaceId });
+    const policyHref = policyPath({ spaceId, collectionId });
+    const policy = collectionId !== undefined
+        ? await storage.getPolicy({ spaceId, collectionId })
+        : await storage.getPolicy({ spaceId });
+    const entry = { anchor };
+    if (policy) {
+        entry[POLICY_LINK_RELATION] = [
+            { href: policyHref, type: 'application/json' }
+        ];
+    }
+    if (collectionId !== undefined) {
+        entry[BACKEND_LINK_RELATION] = [
+            { href: backendPath({ spaceId, collectionId }), type: 'application/json' }
+        ];
+        entry[QUOTA_LINK_RELATION] = [
+            { href: quotaPath({ spaceId, collectionId }), type: 'application/json' }
+        ];
+    }
+    else {
+        entry[BACKENDS_AVAILABLE_LINK_RELATION] = [
+            { href: backendsPath({ spaceId }), type: 'application/json' }
+        ];
+        entry[QUOTAS_LINK_RELATION] = [
+            { href: quotasPath({ spaceId }), type: 'application/json' }
+        ];
+    }
+    return { linkset: [entry] };
+}
+//# sourceMappingURL=policy.js.map

package/dist/policy.js.map

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

package/dist/provisioning.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Provisioning gate for the two open provisioning endpoints (`POST /spaces/`
+ * and `POST /kms/keystores`). By default provisioning is allowed -- anyone may
+ * create a Space or keystore by proving control of the controller DID named in
+ * the request body (the teaching-server behavior). A deployment that wants to
+ * gate provisioning supplies either an `onboardingToken` (a shared secret,
+ * checked here by the stock `onboardingTokenAuthorizer`) or a custom
+ * `authorizeProvisioning` callback; both flow through the same seam.
+ */
+import type { FastifyReply, FastifyRequest } from 'fastify';
+import type { AuthorizeProvisioning } from './types.js';
+/**
+ * onRequest hook: the provisioning gate. Runs first in the hook chain of the
+ * SpacesRepository and `/kms` route groups. For a `POST` to one of the two
+ * provisioning endpoints it consults the configured `authorizeProvisioning`
+ * callback: `verify` proceeds to normal zcap verification, `grant` marks the
+ * request as provisioning-authorized (skipping zcap verification downstream),
+ * and `deny` refuses with a 403. Every other request (and every deployment with
+ * no callback configured) passes straight through, so the default zcap path is
+ * unchanged.
+ * @param request {import('fastify').FastifyRequest}
+ * @param reply {import('fastify').FastifyReply}
+ * @returns {Promise<void>}
+ */
+export declare function provisioningGate(request: FastifyRequest, _reply: FastifyReply): Promise<void>;
+/**
+ * Builds the stock onboarding-token provisioning authorizer: a shared-secret
+ * gate that requires an `Authorization: Bearer <token>` header matching the
+ * configured token. A request signed with a zcap `Authorization: Signature ...`
+ * also lands here -- with a token configured, provisioning requires the token,
+ * full stop. Throws `MissingOnboardingTokenError` (401) when no Bearer token is
+ * present and `InvalidOnboardingTokenError` (403) when it does not match; a
+ * match returns `grant`.
+ * @param onboardingToken {string}   the configured shared-secret token
+ * @returns {AuthorizeProvisioning}
+ */
+export declare function onboardingTokenAuthorizer(onboardingToken: string): AuthorizeProvisioning;
+//# sourceMappingURL=provisioning.d.ts.map

package/dist/provisioning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provisioning.d.ts","sourceRoot":"","sources":["../src/provisioning.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAE3D,OAAO,KAAK,EAAE,qBAAqB,EAAwB,MAAM,YAAY,CAAA;AAc7E;;;;;;;;;;;;GAYG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,cAAc,EACvB,MAAM,EAAE,YAAY,GACnB,OAAO,CAAC,IAAI,CAAC,CAsBf;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CACvC,eAAe,EAAE,MAAM,GACtB,qBAAqB,CAmBvB"}

package/dist/provisioning.js

@@ -0,0 +1,72 @@
+import { createHash, timingSafeEqual } from 'node:crypto';
+import { InvalidOnboardingTokenError, MissingOnboardingTokenError, ProvisioningNotAuthorizedError } from './errors.js';
+/**
+ * The exact route URLs the provisioning gate acts on. `/spaces` (no trailing
+ * slash) is included so a token-authorized request reaches the canonical-slash
+ * 308 redirect instead of failing the auth-header check first.
+ */
+const PROVISIONING_ROUTES = new Set(['/spaces', '/spaces/', '/kms/keystores']);
+/**
+ * onRequest hook: the provisioning gate. Runs first in the hook chain of the
+ * SpacesRepository and `/kms` route groups. For a `POST` to one of the two
+ * provisioning endpoints it consults the configured `authorizeProvisioning`
+ * callback: `verify` proceeds to normal zcap verification, `grant` marks the
+ * request as provisioning-authorized (skipping zcap verification downstream),
+ * and `deny` refuses with a 403. Every other request (and every deployment with
+ * no callback configured) passes straight through, so the default zcap path is
+ * unchanged.
+ * @param request {import('fastify').FastifyRequest}
+ * @param reply {import('fastify').FastifyReply}
+ * @returns {Promise<void>}
+ */
+export async function provisioningGate(request, _reply) {
+    // Only the two provisioning POST endpoints are gated; everything else passes.
+    if (request.method !== 'POST' ||
+        !PROVISIONING_ROUTES.has(request.routeOptions.url ?? '')) {
+        return;
+    }
+    const authorize = request.server.authorizeProvisioning;
+    // No policy configured: default allow -- the zcap path is unchanged.
+    if (!authorize) {
+        return;
+    }
+    const decision = await authorize({ request });
+    if (decision === 'grant') {
+        request.provisioningAuthorized = true;
+        return;
+    }
+    if (decision === 'deny') {
+        throw new ProvisioningNotAuthorizedError();
+    }
+    // 'verify': fall through to the normal zcap capability-invocation path.
+}
+/**
+ * Builds the stock onboarding-token provisioning authorizer: a shared-secret
+ * gate that requires an `Authorization: Bearer <token>` header matching the
+ * configured token. A request signed with a zcap `Authorization: Signature ...`
+ * also lands here -- with a token configured, provisioning requires the token,
+ * full stop. Throws `MissingOnboardingTokenError` (401) when no Bearer token is
+ * present and `InvalidOnboardingTokenError` (403) when it does not match; a
+ * match returns `grant`.
+ * @param onboardingToken {string}   the configured shared-secret token
+ * @returns {AuthorizeProvisioning}
+ */
+export function onboardingTokenAuthorizer(onboardingToken) {
+    return async function authorizeWithOnboardingToken({ request }) {
+        const header = request.headers.authorization;
+        const match = header?.match(/^Bearer\s+(.+)$/i);
+        if (!match) {
+            throw new MissingOnboardingTokenError();
+        }
+        const presented = match[1];
+        // Timing-safe comparison over fixed-length SHA-256 digests, so mismatched
+        // token lengths do not leak through `timingSafeEqual`'s length check.
+        const presentedDigest = createHash('sha256').update(presented).digest();
+        const expectedDigest = createHash('sha256').update(onboardingToken).digest();
+        if (!timingSafeEqual(presentedDigest, expectedDigest)) {
+            throw new InvalidOnboardingTokenError();
+        }
+        return 'grant';
+    };
+}
+//# sourceMappingURL=provisioning.js.map

package/dist/provisioning.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provisioning.js","sourceRoot":"","sources":["../src/provisioning.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAEzD,OAAO,EACL,2BAA2B,EAC3B,2BAA2B,EAC3B,8BAA8B,EAC/B,MAAM,aAAa,CAAA;AAEpB;;;;GAIG;AACH,MAAM,mBAAmB,GAAG,IAAI,GAAG,CAAC,CAAC,SAAS,EAAE,UAAU,EAAE,gBAAgB,CAAC,CAAC,CAAA;AAE9E;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,OAAuB,EACvB,MAAoB;IAEpB,8EAA8E;IAC9E,IACE,OAAO,CAAC,MAAM,KAAK,MAAM;QACzB,CAAC,mBAAmB,CAAC,GAAG,CAAC,OAAO,CAAC,YAAY,CAAC,GAAG,IAAI,EAAE,CAAC,EACxD,CAAC;QACD,OAAM;IACR,CAAC;IACD,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,qBAAqB,CAAA;IACtD,qEAAqE;IACrE,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,OAAM;IACR,CAAC;IACD,MAAM,QAAQ,GAAG,MAAM,SAAS,CAAC,EAAE,OAAO,EAAE,CAAC,CAAA;IAC7C,IAAI,QAAQ,KAAK,OAAO,EAAE,CAAC;QACzB,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAA;QACrC,OAAM;IACR,CAAC;IACD,IAAI,QAAQ,KAAK,MAAM,EAAE,CAAC;QACxB,MAAM,IAAI,8BAA8B,EAAE,CAAA;IAC5C,CAAC;IACD,wEAAwE;AAC1E,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,yBAAyB,CACvC,eAAuB;IAEvB,OAAO,KAAK,UAAU,4BAA4B,CAAC,EACjD,OAAO,EACR;QACC,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,aAAa,CAAA;QAC5C,MAAM,KAAK,GAAG,MAAM,EAAE,KAAK,CAAC,kBAAkB,CAAC,CAAA;QAC/C,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,2BAA2B,EAAE,CAAA;QACzC,CAAC;QACD,MAAM,SAAS,GAAG,KAAK,CAAC,CAAC,CAAW,CAAA;QACpC,0EAA0E;QAC1E,sEAAsE;QACtE,MAAM,eAAe,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,MAAM,EAAE,CAAA;QACvE,MAAM,cAAc,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC,MAAM,EAAE,CAAA;QAC5E,IAAI,CAAC,eAAe,CAAC,eAAe,EAAE,cAAc,CAAC,EAAE,CAAC;YACtD,MAAM,IAAI,2BAA2B,EAAE,CAAA;QACzC,CAAC;QACD,OAAO,OAAO,CAAA;IAChB,CAAC,CAAA;AACH,CAAC"}

package/dist/requests/BackendRequest.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Request handlers for registering an `external` backend against a Space (spec
+ * "Backends"): register (`POST`), replace (`PUT`), and deregister (`DELETE`) a
+ * backend record. Authorization is the Space controller's key (capability-only,
+ * no policy fallback), exactly like Create Collection / Delete Space.
+ *
+ * The write body is secret-bearing (`BackendConnectionInput`), but every
+ * response returns the **sanitized** `BackendDescriptor` (via
+ * `sanitizeBackendRecord`), so a client response can never carry the secret. A
+ * registered backend is inert this increment: it is listed but not yet
+ * selectable as a Collection's `backend` (the live provider adapter is future
+ * work).
+ */
+import type { FastifyReply, FastifyRequest } from 'fastify';
+export declare class BackendRequest {
+    /**
+     * POST /space/:spaceId/backends
+     * Registers a new `external` backend. Rejects the reserved `default` id and a
+     * duplicate id (checked after capability verification so an unauthorized
+     * caller cannot probe ids). Responds 201 with the sanitized descriptor.
+     * @param request {import('fastify').FastifyRequest}
+     * @param reply {import('fastify').FastifyReply}
+     * @returns {Promise<FastifyReply>}
+     */
+    static post(request: FastifyRequest<{
+        Params: {
+            spaceId: string;
+        };
+        Body: unknown;
+    }>, reply: FastifyReply): Promise<FastifyReply>;
+    /**
+     * PUT /space/:spaceId/backends/:backendId
+     * Upsert (the re-consent path): create-or-replace a backend record at a chosen
+     * id. The body `id` (when present) must match the path id, and `default` is
+     * rejected. Responds 201 + Location + sanitized body on create, 204 on update.
+     * @param request {import('fastify').FastifyRequest}
+     * @param reply {import('fastify').FastifyReply}
+     * @returns {Promise<FastifyReply>}
+     */
+    static put(request: FastifyRequest<{
+        Params: {
+            spaceId: string;
+            backendId: string;
+        };
+        Body: unknown;
+    }>, reply: FastifyReply): Promise<FastifyReply>;
+    /**
+     * DELETE /space/:spaceId/backends/:backendId
+     * Deregisters a backend. Idempotent (204 even if the record was absent).
+     * @param request {import('fastify').FastifyRequest}
+     * @param reply {import('fastify').FastifyReply}
+     * @returns {Promise<FastifyReply>}
+     */
+    static delete(request: FastifyRequest<{
+        Params: {
+            spaceId: string;
+            backendId: string;
+        };
+    }>, reply: FastifyReply): Promise<FastifyReply>;
+}
+//# sourceMappingURL=BackendRequest.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"BackendRequest.d.ts","sourceRoot":"","sources":["../../src/requests/BackendRequest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAe3D,qBAAa,cAAc;IACzB;;;;;;;;OAQG;WACU,IAAI,CACf,OAAO,EAAE,cAAc,CAAC;QACtB,MAAM,EAAE;YAAE,OAAO,EAAE,MAAM,CAAA;SAAE,CAAA;QAC3B,IAAI,EAAE,OAAO,CAAA;KACd,CAAC,EACF,KAAK,EAAE,YAAY,GAClB,OAAO,CAAC,YAAY,CAAC;IAqDxB;;;;;;;;OAQG;WACU,GAAG,CACd,OAAO,EAAE,cAAc,CAAC;QACtB,MAAM,EAAE;YAAE,OAAO,EAAE,MAAM,CAAC;YAAC,SAAS,EAAE,MAAM,CAAA;SAAE,CAAA;QAC9C,IAAI,EAAE,OAAO,CAAA;KACd,CAAC,EACF,KAAK,EAAE,YAAY,GAClB,OAAO,CAAC,YAAY,CAAC;IAkExB;;;;;;OAMG;WACU,MAAM,CACjB,OAAO,EAAE,cAAc,CAAC;QACtB,MAAM,EAAE;YAAE,OAAO,EAAE,MAAM,CAAC;YAAC,SAAS,EAAE,MAAM,CAAA;SAAE,CAAA;KAC/C,CAAC,EACF,KAAK,EAAE,YAAY,GAClB,OAAO,CAAC,YAAY,CAAC;CA4BzB"}

package/dist/requests/BackendRequest.js

@@ -0,0 +1,152 @@
+import { fetchSpaceAndVerify } from './spaceContext.js';
+import { assertValidIds } from '../lib/validateId.js';
+import { DEFAULT_BACKEND_ID, assertProviderAllowed, assertValidBackendId, buildBackendRecord, parseBackendRegistration, sanitizeBackendRecord } from '../lib/backends.js';
+import { invalidateResolvedBackend } from '../lib/backendRegistry.js';
+import { backendsPath, registeredBackendPath } from '../lib/paths.js';
+import { InvalidRequestBodyError, IdConflictError } from '../errors.js';
+export class BackendRequest {
+    /**
+     * POST /space/:spaceId/backends
+     * Registers a new `external` backend. Rejects the reserved `default` id and a
+     * duplicate id (checked after capability verification so an unauthorized
+     * caller cannot probe ids). Responds 201 with the sanitized descriptor.
+     * @param request {import('fastify').FastifyRequest}
+     * @param reply {import('fastify').FastifyReply}
+     * @returns {Promise<FastifyReply>}
+     */
+    static async post(request, reply) {
+        const { params: { spaceId }, body } = request;
+        const { serverUrl, storage } = request.server;
+        const requestName = 'Register Backend';
+        // Reject path-traversal / non-URL-safe ids before any storage access.
+        assertValidIds({ spaceId }, { requestName });
+        const registration = parseBackendRegistration(body, { requestName });
+        // Fail fast if the server's registration allowlist excludes this provider
+        // (permissive when no allowlist is configured).
+        assertProviderAllowed({
+            provider: registration.provider,
+            enabledProviders: request.server.enabledBackendProviders
+        });
+        assertValidBackendId(registration.id, { requestName });
+        // Verify (capability-only): registering a backend requires a valid
+        // capability invocation by the Space controller; no policy fallback.
+        await fetchSpaceAndVerify({
+            request,
+            spaceId,
+            targetPath: backendsPath({ spaceId }),
+            requestName
+        });
+        // After verification (so an unauthorized caller cannot probe ids): the
+        // `default` id is reserved for the server backend, and POST must not replace
+        // an existing record (create-or-replace by id is PUT's job).
+        if (registration.id === DEFAULT_BACKEND_ID) {
+            throw new InvalidRequestBodyError({
+                requestName,
+                detail: `"${DEFAULT_BACKEND_ID}" is the reserved server backend id and cannot be registered.`,
+                pointer: '#/id'
+            });
+        }
+        if (await storage.getBackend({ spaceId, backendId: registration.id })) {
+            throw new IdConflictError({ kind: 'Backend' });
+        }
+        const record = buildBackendRecord(registration);
+        await storage.writeBackend({ spaceId, backendId: record.id, record });
+        const createdUrl = new URL(registeredBackendPath({ spaceId, backendId: record.id }), serverUrl).toString();
+        reply.header('Location', createdUrl);
+        return reply.status(201).send(sanitizeBackendRecord(record));
+    }
+    /**
+     * PUT /space/:spaceId/backends/:backendId
+     * Upsert (the re-consent path): create-or-replace a backend record at a chosen
+     * id. The body `id` (when present) must match the path id, and `default` is
+     * rejected. Responds 201 + Location + sanitized body on create, 204 on update.
+     * @param request {import('fastify').FastifyRequest}
+     * @param reply {import('fastify').FastifyReply}
+     * @returns {Promise<FastifyReply>}
+     */
+    static async put(request, reply) {
+        const { params: { spaceId, backendId }, body } = request;
+        const { serverUrl, storage } = request.server;
+        const requestName = 'Register Backend';
+        // Reject path-traversal / non-URL-safe ids before any storage access.
+        assertValidIds({ spaceId }, { requestName });
+        assertValidBackendId(backendId, { requestName });
+        const registration = parseBackendRegistration(body, { requestName });
+        // Fail fast if the server's registration allowlist excludes this provider
+        // (permissive when no allowlist is configured).
+        assertProviderAllowed({
+            provider: registration.provider,
+            enabledProviders: request.server.enabledBackendProviders
+        });
+        // The backend `id` is immutable: a body `id`, when present, must match the
+        // URL id; and `default` is the reserved server backend id.
+        if (registration.id !== backendId) {
+            throw new InvalidRequestBodyError({
+                requestName,
+                detail: `Backend "id" (${registration.id}) does not match the URL backend id (${backendId}).`,
+                pointer: '#/id'
+            });
+        }
+        if (backendId === DEFAULT_BACKEND_ID) {
+            throw new InvalidRequestBodyError({
+                requestName,
+                detail: `"${DEFAULT_BACKEND_ID}" is the reserved server backend id and cannot be registered.`,
+                pointer: '#/id'
+            });
+        }
+        // Verify (capability-only): no policy fallback for a write.
+        await fetchSpaceAndVerify({
+            request,
+            spaceId,
+            targetPath: registeredBackendPath({ spaceId, backendId }),
+            requestName
+        });
+        const existing = await storage.getBackend({ spaceId, backendId });
+        const record = buildBackendRecord(registration);
+        await storage.writeBackend({ spaceId, backendId, record });
+        // Bust any memoized adapter so the next resolve rebuilds it from the new
+        // connection material.
+        invalidateResolvedBackend({
+            providers: request.server.backendProviders,
+            spaceId,
+            backendId
+        });
+        if (existing) {
+            return reply.status(204).send();
+        }
+        const createdUrl = new URL(registeredBackendPath({ spaceId, backendId }), serverUrl).toString();
+        reply.header('Location', createdUrl);
+        return reply.status(201).send(sanitizeBackendRecord(record));
+    }
+    /**
+     * DELETE /space/:spaceId/backends/:backendId
+     * Deregisters a backend. Idempotent (204 even if the record was absent).
+     * @param request {import('fastify').FastifyRequest}
+     * @param reply {import('fastify').FastifyReply}
+     * @returns {Promise<FastifyReply>}
+     */
+    static async delete(request, reply) {
+        const { params: { spaceId, backendId } } = request;
+        const { storage } = request.server;
+        const requestName = 'Deregister Backend';
+        // Reject path-traversal / non-URL-safe ids before any storage access.
+        assertValidIds({ spaceId }, { requestName });
+        assertValidBackendId(backendId, { requestName });
+        // Verify (capability-only): no policy fallback for a write.
+        await fetchSpaceAndVerify({
+            request,
+            spaceId,
+            targetPath: registeredBackendPath({ spaceId, backendId }),
+            requestName
+        });
+        await storage.deleteBackend({ spaceId, backendId });
+        // Bust any memoized adapter for the now-removed record.
+        invalidateResolvedBackend({
+            providers: request.server.backendProviders,
+            spaceId,
+            backendId
+        });
+        return reply.status(204).send();
+    }
+}
+//# sourceMappingURL=BackendRequest.js.map

package/dist/requests/BackendRequest.js.map

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