@jini-ai/cms 0.5.2 → 0.5.4

package/dist/seo/xml-escape.js

@@ -0,0 +1,19 @@
+/**
+ * @file The one HTML/XML text escaper. A leaf module with NO imports, on purpose: the old copies
+ * lived inside `render.ts`, `form-render.ts` and `static-render.ts` and were duplicated rather than
+ * shared because importing them would have closed a runtime import cycle. A module that imports
+ * nothing can be imported from anywhere.
+ *
+ * `&` is replaced first: it is the escape character for every entity after it, so replacing any
+ * other character first would double-escape the `&` that replacement introduced. The apostrophe
+ * becomes the numeric `'` in HTML, because `'` is undefined in HTML4/XHTML1.
+ */
+const XML_ENTITIES = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&apos;" };
+const SPECIAL = /[&<>"']/g;
+/** {@link escapeHtml} with the XML named entity `&apos;` for the apostrophe (sitemap and feed XML).
+ *  @complexity O(text length). */
+// escapeHtml stays with the host renderer. A shared core owner for this leaf is a coordinator follow-up.
+export function escapeXml(required, _optional = {}) {
+    return required.text.replace(SPECIAL, (char) => XML_ENTITIES[char] ?? char);
+}
+//# sourceMappingURL=xml-escape.js.map

package/dist/settings/express/cms-adapter.d.ts

@@ -0,0 +1,20 @@
+import { type SettingsWriteServiceDeps, type SettingsRepoPort } from "../index.js";
+import type { SettingsService, SettingsPermissions, SettingsChangeFeed } from "./contracts.js";
+/** Keep the CMS write chokepoint while translating its permission vocabulary to host policy. */
+/** Bind the CMS ledger and write chokepoint without copying their domain logic.
+ * Effective reads scan definitions and resolve each namespace key; mutations inherit CMS transactions/errors.
+ * @complexity O(1) setup. Per operation: O(definitions + keys) reads, or O(batch size) writes.
+ * @example createCmsSettingsService({ deps: cmsPorts, permissions });
+ */
+export declare function createCmsSettingsService(required: {
+    deps: SettingsWriteServiceDeps;
+    permissions: SettingsPermissions;
+}): SettingsService;
+/** Adapt the ledger through CMS tenant/principal disclosure rules, returning names and cursors only.
+ * @complexity O(1) setup; collect is O(page size), with namespace lookup per visible revision.
+ * @example createCmsSettingsChangeFeed({ repo });
+ */
+export declare function createCmsSettingsChangeFeed(required: {
+    repo: SettingsRepoPort;
+}): SettingsChangeFeed;
+//# sourceMappingURL=cms-adapter.d.ts.map

package/dist/settings/express/cms-adapter.js

@@ -0,0 +1,124 @@
+import { getEffective, resolveDefinition, set, clear, resetNamespace, registerDefinitions, NON_REGISTER_DEFINITION_OPS, parseNonRegisterDefinitionOp, collectChangedNamespaces, } from "../index.js";
+/** Keep the CMS write chokepoint while translating its permission vocabulary to host policy. */
+/** Bind the CMS ledger and write chokepoint without copying their domain logic.
+ * Effective reads scan definitions and resolve each namespace key; mutations inherit CMS transactions/errors.
+ * @complexity O(1) setup. Per operation: O(definitions + keys) reads, or O(batch size) writes.
+ * @example createCmsSettingsService({ deps: cmsPorts, permissions });
+ */
+export function createCmsSettingsService(required) {
+    const { deps: original, permissions } = required;
+    const permissionMap = new Map([
+        ["settings.definitions.manage", permissions.manageDefinitions],
+        ["settings.global.write", permissions.writeGlobal],
+        ["settings.workspace.write", permissions.writeWorkspace],
+        ["settings.user.self.write", permissions.writeUserSelf],
+        ["settings.user.write", permissions.writeUserOther],
+        ["settings.reset.global", permissions.reset.global],
+        ["settings.reset.workspace", permissions.reset.workspace],
+        ["settings.reset.user", permissions.reset.user],
+    ]);
+    const deps = { ...original,
+        authorize: (input) => {
+            const permission = permissionMap.get(input.permission);
+            if (permission === undefined)
+                return Promise.resolve({ allowed: false, reason: "unknown_settings_permission" });
+            return original.authorize({ ...input, permission });
+        },
+    };
+    const repo = deps.repo;
+    const listDefinitions = async ({ workspaceId }) => {
+        const [platform, workspace] = await Promise.all([
+            repo.listActiveDefinitions({ workspaceId: null }), repo.listActiveDefinitions({ workspaceId }),
+        ]);
+        return [...platform, ...workspace];
+    };
+    return {
+        listDefinitions,
+        effective: async ({ namespace, workspaceId, principalId }) => {
+            const defs = await listDefinitions({ workspaceId });
+            const keys = new Set(defs.filter((d) => d.namespace === namespace).map((d) => d.key));
+            const data = [];
+            for (const key of keys) {
+                const result = await getEffective({ repo }, { namespace, key, scopeContext: { workspaceId, principalId } });
+                if (result)
+                    data.push({ key, value: result.value, sourceLayer: result.sourceLayer, defVersion: result.defVersion });
+            }
+            return data;
+        },
+        raw: async ({ namespace, key, workspaceId, principalId }) => {
+            const definition = await resolveDefinition({ repo }, { namespace, key, workspaceId });
+            if (!definition)
+                return null;
+            const settingId = definition.settingId;
+            const records = await Promise.all([
+                repo.getGlobalValue(settingId), repo.getWorkspaceValue({ workspaceId, settingId }),
+                principalId ? repo.getUserValue({ workspaceId, principalId, settingId }) : Promise.resolve(null),
+            ]);
+            const values = records.map((r) => r?.state === "set" ? r.valueJson : null);
+            return { key: `${namespace}.${key}`, global: values[0], workspace: values[1], user: values[2], default: definition.defaultValue };
+        },
+        set: (input) => set({ deps, input }),
+        clear: (input) => clear({ deps, input }),
+        reset: async (input) => {
+            const definitions = await repo.listActiveDefinitions({ workspaceId: input.scope === "global" ? null : (input.workspaceId ?? input.authWorkspaceId ?? null) });
+            const keys = definitions.filter((d) => d.namespace === input.namespace).map((d) => d.key);
+            return resetNamespace({ deps, input }, keys);
+        },
+        definitions: ({ items, callerPrincipalId, authWorkspaceId }) => applyDefinitions({ deps, items, callerPrincipalId, authWorkspaceId }),
+    };
+}
+/** Preserve register batching and ordered non-register writes over existing CMS operation contracts.
+ * Unknown operations return their name. Earlier non-register writes are not rolled back by later failures.
+ * @complexity O(item count) time/space plus CMS effects; this batch is not atomic.
+ */
+async function applyDefinitions(required) {
+    const { deps, items, callerPrincipalId, authWorkspaceId } = required;
+    const toRegister = [];
+    const applied = [];
+    for (const raw of items) {
+        const item = raw;
+        const op = String(item.op ?? "register");
+        const namespace = String(item.namespace ?? "");
+        const key = String(item.key ?? "");
+        const ownerKind = item.ownerKind;
+        const workspaceId = ownerKind === "site" ? authWorkspaceId : null;
+        const defaultValue = (item.defaultJson ?? null);
+        if (op === "register") {
+            toRegister.push({ namespace, key, ownerKind, workspaceId, schema: item.schemaJson,
+                defaultValue, scopes: Number(item.scopes), secret: Boolean(item.secret ?? false) });
+        }
+        else {
+            const parsedOp = parseNonRegisterDefinitionOp({ op });
+            if (!parsedOp)
+                return { unknownOp: op };
+            const opItem = { namespace, key, ownerKind, workspaceId, defaultJson: defaultValue,
+                ...(item.newNamespace === undefined ? {} : { newNamespace: item.newNamespace }),
+                ...(item.newKey === undefined ? {} : { newKey: item.newKey }),
+                ...(item.schemaJson === undefined ? {} : { schemaJson: item.schemaJson }),
+                ...(item.coercionJson === undefined ? {} : { coercionJson: item.coercionJson }),
+            };
+            await NON_REGISTER_DEFINITION_OPS[parsedOp]({ ctx: { deps, callerPrincipalId, authWorkspaceId }, item: opItem });
+        }
+        applied.push({ key: `${namespace}.${key}`, op, status: "applied" });
+    }
+    if (toRegister.length)
+        await registerDefinitions({ deps, input: { definitions: toRegister, callerPrincipalId, authWorkspaceId } });
+    return { applied };
+}
+/** Adapt the ledger through CMS tenant/principal disclosure rules, returning names and cursors only.
+ * @complexity O(1) setup; collect is O(page size), with namespace lookup per visible revision.
+ * @example createCmsSettingsChangeFeed({ repo });
+ */
+export function createCmsSettingsChangeFeed(required) {
+    const { repo } = required;
+    return {
+        head: () => repo.maxRevisionSeq(),
+        collect: async ({ sinceSeq, limit, viewer }) => {
+            const revisions = await repo.listRevisionsSince({ sinceSeq, limit, workspaceId: viewer.workspaceId });
+            // Resolve afresh each batch: a rename must never leave a stale namespace cached forever.
+            const batch = await collectChangedNamespaces({ revisions, viewer, resolveNamespace: async ({ settingId }) => (await repo.findDefinitionBySettingId({ settingId }))?.namespace ?? null });
+            return { ...batch, examinedCount: revisions.length };
+        },
+    };
+}
+//# sourceMappingURL=cms-adapter.js.map

package/dist/settings/express/contracts.d.ts

@@ -0,0 +1,135 @@
+import type { Request, Response, Express } from "express";
+import type { SettingScope, SettingDefinitionRecord, SetValueRequired, ClearValueRequired, ResetNamespaceRequired, ChangeFeedViewer, ChangeFeedBatch } from "../index.js";
+export type Authorize = (required: {
+    principalId: string;
+    workspaceId: string;
+    permission: string;
+    entityType: string;
+}) => Promise<{
+    allowed: boolean;
+    reason: string;
+}>;
+export type PrincipalResolver = (required: {
+    request: Request;
+    response: Response;
+}) => Promise<{
+    id: string;
+} | null> | {
+    id: string;
+} | null;
+export interface Scheduler {
+    /** Return an idempotent cancellation callback. */
+    every(required: {
+        intervalMs: number;
+        callback: () => void;
+    }): () => void;
+}
+export interface SettingsPermissions {
+    read: string;
+    readRaw: string;
+    readDefinitions: string;
+    readOtherUser: string;
+    manageDefinitions: string;
+    writeGlobal: string;
+    writeWorkspace: string;
+    writeUserSelf: string;
+    writeUserOther: string;
+    reset: Record<SettingScope, string>;
+}
+export interface SettingsRoutes {
+    definitions: string;
+    effective: string;
+    raw: string;
+    value: string;
+    reset: string;
+    events: string;
+    workspaceParam: string;
+}
+export type EffectiveSettingRow = {
+    key: string;
+    value: unknown;
+    sourceLayer: string;
+    defVersion: number;
+};
+export type RawSetting = {
+    key: string;
+    global: unknown;
+    workspace: unknown;
+    user: unknown;
+    default: unknown;
+};
+export type DefinitionResult = {
+    applied: Array<{
+        key: string;
+        op: string;
+        status: string;
+    }>;
+} | {
+    unknownOp: string;
+};
+export interface SettingsService {
+    listDefinitions(required: {
+        workspaceId: string;
+    }): Promise<SettingDefinitionRecord[]>;
+    effective(required: {
+        namespace: string;
+        workspaceId: string;
+        principalId: string | undefined;
+    }): Promise<EffectiveSettingRow[]>;
+    raw(required: {
+        namespace: string;
+        key: string;
+        workspaceId: string;
+        principalId: string | undefined;
+    }): Promise<RawSetting | null>;
+    set(required: SetValueRequired["input"]): Promise<{
+        value: unknown;
+        revisionSeq: number;
+    }>;
+    clear(required: ClearValueRequired["input"]): Promise<{
+        revisionSeq: number;
+    }>;
+    reset(required: ResetNamespaceRequired["input"]): Promise<{
+        clearedCount: number;
+        revisionSeqs: number[];
+    }>;
+    definitions(required: {
+        items: readonly unknown[];
+        callerPrincipalId: string;
+        authWorkspaceId: string;
+    }): Promise<DefinitionResult>;
+}
+export interface SettingsChangeFeed {
+    head(required: Record<string, never>): Promise<number>;
+    /** Cursor advances across invisible rows. The emitted id MUST use batch.cursor, never head. */
+    collect(required: {
+        sinceSeq: number;
+        limit: number;
+        viewer: ChangeFeedViewer;
+    }): Promise<ChangeFeedBatch & {
+        examinedCount: number;
+    }>;
+}
+export interface SettingsHttpRequired {
+    app: Pick<Express, "get" | "post" | "put" | "delete">;
+    workspaceId: string;
+    ready: Promise<void>;
+    service: SettingsService;
+    changeFeed: SettingsChangeFeed;
+    principalResolver: PrincipalResolver;
+    authorize: Authorize;
+    scheduler: Scheduler;
+    routes: SettingsRoutes;
+    permissions: SettingsPermissions;
+}
+export interface SettingsHttpOptions {
+    pollIntervalMs?: number;
+    keepaliveIntervalMs?: number;
+    reauthorizeIntervalMs?: number;
+    revisionPageSize?: number;
+    onError?: (required: {
+        operation: string;
+        error: unknown;
+    }) => void;
+}
+//# sourceMappingURL=contracts.d.ts.map

package/dist/settings/express/contracts.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=contracts.js.map

package/dist/settings/express/http.d.ts

@@ -0,0 +1,10 @@
+import type { SettingsHttpRequired, SettingsHttpOptions } from "./contracts.js";
+/** Mount all eight endpoints. The returned disposer closes active feeds and cancels their schedules. */
+/** Injected policy and services preserve the settings HTTP response envelopes.
+ * O(1) mounting; read/mutation work is delegated. Feed resources are bounded per connection.
+ * @example registerSettingsRoutes({ app, workspaceId, ready, service, changeFeed, principalResolver, authorize, scheduler, routes, permissions });
+ */
+export declare function registerSettingsRoutes(required: SettingsHttpRequired, optional?: SettingsHttpOptions): {
+    dispose(): void;
+};
+//# sourceMappingURL=http.d.ts.map

package/dist/settings/express/http.js

@@ -0,0 +1,211 @@
+import { AliasDepthExceededError, DefinitionInvalidError, DefinitionNotFoundError, DefinitionTombstonedError, ForbiddenError, PrincipalNotFoundError, RenameRetypeConflictError, ScopeNotAllowedError, SecretNotSupportedError, ValueValidationFailedError, } from "../index.js";
+import { respondToSettingsError, resolveTargetWorkspaceId, resolveUserLayerReadTarget, settingsWritePermission } from "./shared.js";
+import { openSettingsChangeStream } from "./stream.js";
+const VALUE_ERRORS = [
+    { matches: (e) => e instanceof PrincipalNotFoundError, status: 404, code: "PRINCIPAL_NOT_FOUND" },
+    { matches: (e) => e instanceof DefinitionNotFoundError, status: 404, code: "DEFINITION_NOT_FOUND" },
+    { matches: (e) => e instanceof DefinitionTombstonedError, status: 409, code: "DEFINITION_TOMBSTONED" },
+    { matches: (e) => e instanceof ScopeNotAllowedError, status: 400, code: "SCOPE_NOT_ALLOWED" },
+    { matches: (e) => e instanceof ValueValidationFailedError, status: 400, code: "VALUE_VALIDATION_FAILED" },
+    { matches: (e) => e instanceof ForbiddenError, status: 403, code: "FORBIDDEN" },
+];
+const DEFINITION_ERRORS = [
+    { matches: (e) => e instanceof SecretNotSupportedError, status: 400, code: "SECRET_NOT_SUPPORTED" },
+    { matches: (e) => e instanceof DefinitionInvalidError, status: 400, code: "DEFINITION_INVALID" },
+    { matches: (e) => e instanceof RenameRetypeConflictError, status: 409, code: "RENAME_RETYPE_CONFLICT" },
+    { matches: (e) => e instanceof AliasDepthExceededError, status: 409, code: "ALIAS_DEPTH_EXCEEDED" },
+    { matches: (e) => e instanceof DefinitionTombstonedError, status: 409, code: "DEFINITION_TOMBSTONED" },
+    { matches: (e) => e instanceof ForbiddenError, status: 403, code: "FORBIDDEN" },
+];
+const RESET_ERRORS = VALUE_ERRORS.filter((m) => m.code === "FORBIDDEN");
+const scopes = ["global", "workspace", "user"];
+function validation(res, error) {
+    res.status(400).json({ error, code: "VALIDATION_ERROR" });
+}
+function denied(res, principalId, permission, reason) {
+    res.status(403).json({ error: `principal '${principalId}' is not authorized for '${permission}' (${reason})`,
+        code: "FORBIDDEN", details: { permission, reason } });
+}
+function bodyOf(req) {
+    return req.body && typeof req.body === "object" && !Array.isArray(req.body) ? req.body : {};
+}
+/** Mount all eight endpoints. The returned disposer closes active feeds and cancels their schedules. */
+/** Injected policy and services preserve the settings HTTP response envelopes.
+ * O(1) mounting; read/mutation work is delegated. Feed resources are bounded per connection.
+ * @example registerSettingsRoutes({ app, workspaceId, ready, service, changeFeed, principalResolver, authorize, scheduler, routes, permissions });
+ */
+export function registerSettingsRoutes(required, optional = {}) {
+    const { app, workspaceId, service, routes, permissions } = required;
+    const streams = new Set();
+    let disposed = false;
+    const wrap = (handler, mappings = []) => async (req, res) => {
+        if (disposed) {
+            res.status(503).json({ error: "settings routes are disposed", code: "UNAVAILABLE" });
+            return;
+        }
+        if (String(req.params[routes.workspaceParam] ?? "") !== workspaceId) {
+            res.status(404).json({ error: "workspace was not found" });
+            return;
+        }
+        let principal;
+        try {
+            await required.ready;
+            principal = await required.principalResolver({ request: req, response: res });
+        }
+        catch {
+            // Readiness/principal failures preserve the authentication boundary's existing 401 envelope.
+            res.status(401).json({ error: "unauthenticated", code: "UNAUTHENTICATED" });
+            return;
+        }
+        if (!principal) {
+            res.status(401).json({ error: "unauthenticated", code: "UNAUTHENTICATED" });
+            return;
+        }
+        try {
+            await handler(req, res, principal.id);
+        }
+        catch (error) {
+            if (res.headersSent) {
+                // Reporting cannot prevent ending a response whose headers have already been sent.
+                try {
+                    optional.onError?.({ operation: "settings-request", error });
+                }
+                catch { /* Host diagnostics are best-effort. */ }
+                finally {
+                    res.end();
+                }
+            }
+            else
+                respondToSettingsError({ response: res, error, mappings });
+        }
+    };
+    const check = async (res, principalId, permission, entityType) => {
+        const result = await required.authorize({ principalId, permission, workspaceId, entityType });
+        if (!result.allowed)
+            denied(res, principalId, permission, result.reason);
+        return result.allowed;
+    };
+    const readTarget = async (res, principalId, requestedPrincipalId) => {
+        const result = await resolveUserLayerReadTarget({ deps: { workspaceId, authorize: required.authorize, permission: permissions.readOtherUser },
+            input: { callerPrincipalId: principalId, requestedPrincipalId } });
+        if (!result.allowed)
+            res.status(403).json({
+                error: `principal '${principalId}' is not authorized to read another principal's user-layer value (${result.reason})`,
+                code: "FORBIDDEN", details: { permission: permissions.readOtherUser, reason: result.reason },
+            });
+        return result;
+    };
+    app.get(routes.definitions, wrap(async (_req, res, principalId) => {
+        if (!await check(res, principalId, permissions.readDefinitions, "setting-definition"))
+            return;
+        const definitions = await service.listDefinitions({ workspaceId });
+        const data = definitions.map(({ namespace, key, ownerKind, scopes, status, version }) => ({ namespace, key, ownerKind, scopes, status, version }))
+            .sort((a, b) => a.namespace.localeCompare(b.namespace) || a.key.localeCompare(b.key));
+        res.json({ data });
+    }));
+    app.get(routes.effective, wrap(async (req, res, principalId) => {
+        if (!await check(res, principalId, permissions.read, "setting-value"))
+            return;
+        const namespace = String(req.query.namespace ?? "");
+        if (!namespace) {
+            validation(res, "'namespace' query param is required");
+            return;
+        }
+        const target = await readTarget(res, principalId, req.query.principalId ? String(req.query.principalId) : principalId);
+        if (!target.allowed)
+            return;
+        res.json({ data: await service.effective({ namespace, workspaceId, principalId: target.principalId }) });
+    }));
+    app.get(routes.raw, wrap(async (req, res, principalId) => {
+        if (!await check(res, principalId, permissions.readRaw, "setting-value"))
+            return;
+        const namespace = String(req.query.namespace ?? "");
+        const key = String(req.query.key ?? "");
+        if (!namespace || !key) {
+            validation(res, "'namespace' and 'key' query params are required");
+            return;
+        }
+        const target = await readTarget(res, principalId, req.query.principalId ? String(req.query.principalId) : undefined);
+        if (!target.allowed)
+            return;
+        const result = await service.raw({ namespace, key, workspaceId, principalId: target.principalId });
+        if (!result) {
+            res.status(404).json({ error: `definition '${namespace}.${key}' was not found`, code: "DEFINITION_NOT_FOUND" });
+            return;
+        }
+        res.json(result);
+    }));
+    app.post(routes.definitions, wrap(async (req, res, principalId) => {
+        if (!await check(res, principalId, permissions.manageDefinitions, "setting-definition"))
+            return;
+        const items = bodyOf(req).definitions;
+        if (!Array.isArray(items)) {
+            validation(res, "'definitions' must be an array");
+            return;
+        }
+        const result = await service.definitions({ items, callerPrincipalId: principalId, authWorkspaceId: workspaceId });
+        if ("unknownOp" in result) {
+            validation(res, `unknown op '${result.unknownOp}'`);
+            return;
+        }
+        res.json(result);
+    }, DEFINITION_ERRORS));
+    const mutate = (operation) => async (req, res, callerPrincipalId) => {
+        const body = bodyOf(req);
+        const namespace = String(body.namespace ?? "");
+        const key = String(body.key ?? "");
+        const scope = body.scope;
+        if (!namespace || !key || !scopes.includes(scope) || (operation === "set" && !("valueJson" in body))) {
+            validation(res, operation === "set" ? "namespace, key, scope (global|workspace|user), and valueJson are required" : "namespace, key, and scope (global|workspace|user) are required");
+            return;
+        }
+        const target = resolveTargetWorkspaceId({ workspaceId, input: { bodyWorkspaceId: body.workspaceId, scope } });
+        if (!target.ok) {
+            validation(res, target.error);
+            return;
+        }
+        const principalId = body.principalId ? String(body.principalId) : undefined;
+        const permission = settingsWritePermission({ permissions, scope, callerPrincipalId, targetPrincipalId: principalId });
+        if (!await check(res, callerPrincipalId, permission, "setting-value"))
+            return;
+        const input = { namespace, key, scope, workspaceId: target.workspaceId, principalId, callerPrincipalId, authWorkspaceId: workspaceId };
+        const result = operation === "set" ? await service.set({ ...input, value: body.valueJson }) : await service.clear(input);
+        res.json({ key: `${namespace}.${key}`, scope, value: "value" in result ? result.value : null, revisionSeq: result.revisionSeq });
+    };
+    app.put(routes.value, wrap(mutate("set"), VALUE_ERRORS));
+    app.delete(routes.value, wrap(mutate("clear"), VALUE_ERRORS.filter((m) => m.code !== "VALUE_VALIDATION_FAILED")));
+    app.post(routes.reset, wrap(async (req, res, callerPrincipalId) => {
+        const body = bodyOf(req);
+        const namespace = String(body.namespace ?? "");
+        const scope = body.scope;
+        if (!namespace || !scopes.includes(scope)) {
+            validation(res, "namespace and scope (global|workspace|user) are required");
+            return;
+        }
+        const target = resolveTargetWorkspaceId({ workspaceId, input: { bodyWorkspaceId: body.workspaceId, scope } });
+        if (!target.ok) {
+            validation(res, target.error);
+            return;
+        }
+        if (!await check(res, callerPrincipalId, permissions.reset[scope], "setting-namespace"))
+            return;
+        const result = await service.reset({ namespace, scope, workspaceId: target.workspaceId, callerPrincipalId, authWorkspaceId: workspaceId });
+        res.json({ namespace, ...result });
+    }, RESET_ERRORS));
+    app.get(routes.events, wrap(async (req, res, principalId) => {
+        if (!await check(res, principalId, permissions.read, "setting-value"))
+            return;
+        const close = await openSettingsChangeStream({ request: req, response: res, workspaceId, principalId,
+            changeFeed: required.changeFeed, authorize: required.authorize, permission: permissions.read, scheduler: required.scheduler,
+            onClose: ({ close }) => { streams.delete(close); }, isDisposed: () => disposed }, optional);
+        if (close) {
+            if (disposed)
+                close();
+            else if (!res.destroyed && !res.writableEnded)
+                streams.add(close);
+        }
+    }));
+    return { dispose: () => { disposed = true; for (const close of streams)
+            close(); streams.clear(); } };
+}
+//# sourceMappingURL=http.js.map

package/dist/settings/express/index.d.ts

@@ -0,0 +1,5 @@
+/** @deprecated For one compatibility release: use @jini-ai/core/settings/express.
+ * Re-export the owner so route lifecycle and permission handling cannot drift.
+ */
+export * from "@jini-ai/core/settings/express";
+//# sourceMappingURL=index.d.ts.map

package/dist/settings/express/index.js

@@ -0,0 +1,5 @@
+/** @deprecated For one compatibility release: use @jini-ai/core/settings/express.
+ * Re-export the owner so route lifecycle and permission handling cannot drift.
+ */
+export * from "@jini-ai/core/settings/express";
+//# sourceMappingURL=index.js.map

package/dist/settings/express/shared.d.ts

@@ -0,0 +1,68 @@
+import type { Response } from "express";
+import type { SettingScope } from "../index.js";
+import type { Authorize, SettingsPermissions } from "./contracts.js";
+export type TargetWorkspaceResolution = {
+    ok: true;
+    workspaceId: string | undefined;
+} | {
+    ok: false;
+    error: string;
+};
+/** Pin writes to the authorized workspace, rejecting a conflicting body target.
+ * Global scope has no target workspace. Pure; O(1) time/space for string ids.
+ * @example resolveTargetWorkspaceId({ workspaceId, input: { scope: "workspace", bodyWorkspaceId } });
+ */
+export declare function resolveTargetWorkspaceId(required: {
+    workspaceId: string;
+    input: {
+        bodyWorkspaceId: unknown;
+        scope: SettingScope;
+    };
+}): TargetWorkspaceResolution;
+export type UserLayerReadTarget = {
+    allowed: true;
+    principalId: string | undefined;
+} | {
+    allowed: false;
+    reason: string;
+};
+/** Require the injected cross-principal grant only when a read targets another user.
+ * Returns the denial reason without reading values; one authorization effect at most.
+ * @complexity O(1) excluding the authorizer.
+ * @example resolveUserLayerReadTarget({ deps: { workspaceId, authorize, permission }, input });
+ */
+export declare function resolveUserLayerReadTarget(required: {
+    deps: {
+        workspaceId: string;
+        authorize: Authorize;
+        permission: string;
+    };
+    input: {
+        requestedPrincipalId: string | undefined;
+        callerPrincipalId: string;
+    };
+}): Promise<UserLayerReadTarget>;
+export interface SettingsErrorMapping {
+    readonly matches: (error: unknown) => boolean;
+    readonly status: number;
+    readonly code: string;
+}
+/** Write the first matching status/code, or a fixed 500 that does not disclose unknown errors.
+ * @complexity O(mapping count) time, O(1) space; response write effect.
+ * @example respondToSettingsError({ response, error, mappings });
+ */
+export declare function respondToSettingsError(required: {
+    response: Pick<Response, "status" | "json">;
+    error: unknown;
+    mappings: readonly SettingsErrorMapping[];
+}): void;
+/** Select caller policy for the CMS scope and self/other-user split; pure, O(1).
+ * @example settingsWritePermission({ permissions, scope: "user", callerPrincipalId, targetPrincipalId });
+ */
+export declare function settingsWritePermission(required: {
+    permissions: SettingsPermissions;
+    scope: SettingScope;
+    callerPrincipalId: string;
+    targetPrincipalId: string | undefined;
+}): string;
+//# sourceMappingURL=shared.d.ts.map

package/dist/settings/express/shared.js

@@ -0,0 +1,54 @@
+/** Pin writes to the authorized workspace, rejecting a conflicting body target.
+ * Global scope has no target workspace. Pure; O(1) time/space for string ids.
+ * @example resolveTargetWorkspaceId({ workspaceId, input: { scope: "workspace", bodyWorkspaceId } });
+ */
+export function resolveTargetWorkspaceId(required) {
+    const { workspaceId, input } = required;
+    const named = input.bodyWorkspaceId === undefined || input.bodyWorkspaceId === null || input.bodyWorkspaceId === ""
+        ? undefined : String(input.bodyWorkspaceId);
+    if (named !== undefined && named !== workspaceId) {
+        return { ok: false, error: `workspaceId '${named}' does not match this route's workspace; a settings write cannot target another workspace` };
+    }
+    return { ok: true, workspaceId: input.scope === "global" ? undefined : workspaceId };
+}
+/** Require the injected cross-principal grant only when a read targets another user.
+ * Returns the denial reason without reading values; one authorization effect at most.
+ * @complexity O(1) excluding the authorizer.
+ * @example resolveUserLayerReadTarget({ deps: { workspaceId, authorize, permission }, input });
+ */
+export async function resolveUserLayerReadTarget(required) {
+    const { deps, input } = required;
+    if (!input.requestedPrincipalId || input.requestedPrincipalId === input.callerPrincipalId) {
+        return { allowed: true, principalId: input.requestedPrincipalId };
+    }
+    const result = await deps.authorize({ principalId: input.callerPrincipalId, permission: deps.permission,
+        workspaceId: deps.workspaceId, entityType: "setting-value" });
+    return result.allowed ? { allowed: true, principalId: input.requestedPrincipalId } : { allowed: false, reason: result.reason };
+}
+/** Write the first matching status/code, or a fixed 500 that does not disclose unknown errors.
+ * @complexity O(mapping count) time, O(1) space; response write effect.
+ * @example respondToSettingsError({ response, error, mappings });
+ */
+export function respondToSettingsError(required) {
+    const { response, error, mappings } = required;
+    const message = error instanceof Error ? error.message : String(error);
+    for (const mapping of mappings) {
+        if (mapping.matches(error)) {
+            response.status(mapping.status).json({ error: message, code: mapping.code });
+            return;
+        }
+    }
+    response.status(500).json({ error: "internal error", code: "INTERNAL_ERROR" });
+}
+/** Select caller policy for the CMS scope and self/other-user split; pure, O(1).
+ * @example settingsWritePermission({ permissions, scope: "user", callerPrincipalId, targetPrincipalId });
+ */
+export function settingsWritePermission(required) {
+    const { permissions, scope, callerPrincipalId, targetPrincipalId } = required;
+    if (scope === "global")
+        return permissions.writeGlobal;
+    if (scope === "workspace")
+        return permissions.writeWorkspace;
+    return targetPrincipalId == null || targetPrincipalId === callerPrincipalId ? permissions.writeUserSelf : permissions.writeUserOther;
+}
+//# sourceMappingURL=shared.js.map