fix(rest,runtime): datasource metadata writes require the same capability as the datasource admin door

A /meta write (PUT, POST, PATCH, DELETE: save, reset, publish, rollback)
of a `datasource` definition is admitted only for a caller holding
`manage_platform_settings`, the capability the datasource admin door
requires for the same create / update / remove. Judged once per type at
each transport's /meta entry (RestServer's guarded registrar and the
runtime dispatcher's handleMetadataRequest), beside the read-side
admission, before the door's own authoring admission runs.

Claude-Session: https://claude.ai/code/session_01MRdbfpy4sQT8bUjmMhxsN7
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

packages/rest/src/index.ts

@@ -118,6 +118,11 @@ export { refuseRepeatedQueryParams, repeatedQueryParamMessage } from './query-mu
 // `/meta` entry, before any store read (`metaTypeReadRefusal` over
 // `META_TYPE_READ_CAPABILITIES`): a datasource-family type is read under the
 // capability its own door requires.
+//
+// [#21124] …and its write-side twin (`metaTypeWriteRefusal` over
+// `META_TYPE_WRITE_CAPABILITIES`), asked at the same two entries before any
+// store write: a datasource definition is written under the capability the
+// datasource admin door requires.
 export {
     createMetaBookTreeAnswer,
     createMetaItemAnswer,
@@ -127,11 +132,13 @@ export {
     createMetaListAnswer,
     isPublicAudienceRead,
     META_TYPE_READ_CAPABILITIES,
+    META_TYPE_WRITE_CAPABILITIES,
     metaCallerOrganizationId,
     metaItemLayersDeprecationHeaders,
     metaReadOrganizationId,
     metaRequestLocale,
     metaTypeReadRefusal,
+    metaTypeWriteRefusal,
     projectMetaObjectSchema,
     refuseUnknownMetaListType,
     STORED_VERSION_DOOR_POLICY,
@@ -159,4 +166,5 @@ export type {
     MetaReadGatePolicy,
     MetaRequestHttp,
     MetaTypeReadRefusal,
+    MetaTypeWriteRefusal,
 } from './meta-item-read-gate.js';

packages/rest/src/meta-item-read-gate.ts

@@ -1684,7 +1684,9 @@ export function isPublicAudienceRead(
  * Uniform, for the reason the datasource admin door gives for gating even its
  * static driver catalog: a family whose floor has one hole has to be read
  * route by route. Writes are not judged here — the save door keeps its own
- * admission (`metaWriteCapabilityVerdict`).
+ * admission (`metaWriteCapabilityVerdict`), and a write of a type whose own
+ * write door requires more is judged by the twin below
+ * ({@link metaTypeWriteRefusal}, #21124).
  *
  * Both transports ask {@link metaTypeReadRefusal} at their single `/meta`
  * entry, right after the anonymous deny: `RestServer`'s guarded registrar
@@ -1761,6 +1763,110 @@ export function metaTypeReadRefusal(
     };
 }
 
+// ── The type-level write capability ───────────────────────────────────────────
+
+/**
+ * [#21124] The metadata types whose `/meta` WRITES require a platform
+ * capability beyond the authoring admission every write door already asks
+ * (`metaWriteCapabilityVerdict`) — the write-side twin of
+ * {@link META_TYPE_READ_CAPABILITIES}, judged the same way: per TYPE, once, at
+ * each transport's `/meta` entry, before any handler resolves the protocol or
+ * writes the store; never per document.
+ *
+ * ## The row, and why the capability
+ *
+ *  - `datasource` → `manage_platform_settings`. The datasource family's own
+ *    write doors — `POST /api/v1/datasources`, `PATCH` and `DELETE
+ *    /api/v1/datasources/:name` (`admin-routes.ts` in
+ *    `@objectstack/service-datasource`, `DATASOURCE_ADMIN_CAPABILITY`) —
+ *    create, update and remove the same stored definition a `/meta` write of
+ *    this type persists, and admit only this capability. One operation reached
+ *    through two mounted doors cannot admit two different sets of callers.
+ *
+ * ## Why `external_catalog` has no row here
+ *
+ * Its READ row exists because its read door requires
+ * `manage_platform_settings`. Its WRITE door — `POST
+ * /datasources/:name/external/refresh-catalog` — requires
+ * `FEDERATION_WRITE_CAPABILITY` (`manage_metadata`, in
+ * `./external-datasource-routes.ts`), which every `/meta` write door already
+ * demands. ⛔ A row here names the capability the type's own WRITE door
+ * requires — matched, never minted; a type whose write door asks nothing beyond
+ * the authoring admission has no row.
+ *
+ * ## Which requests
+ *
+ * Every write verb — `PUT`, `POST`, `PATCH`, `DELETE` — whose `:type` segment
+ * folds to a listed type, on every route shape: the item save in each of its
+ * modes (a draft included), the reset, `/publish` and `/rollback`, and any
+ * write verb a transport answers on a read route. A route with no `:type`
+ * segment (`POST /meta/_migrate-stored`) is not judged here. The authoring
+ * admission still runs after this one: a holder of the capability is also
+ * asked for `manage_metadata` by the door itself, as before.
+ */
+export const META_TYPE_WRITE_CAPABILITIES: Readonly<Record<string, string>> = Object.freeze({
+    datasource: 'manage_platform_settings',
+});
+
+/** The verbs {@link metaTypeWriteRefusal} judges. */
+const META_WRITE_VERBS: ReadonlySet<string> = new Set(['PUT', 'POST', 'PATCH', 'DELETE']);
+
+/**
+ * [#21124] Why a `/meta` write of a {@link META_TYPE_WRITE_CAPABILITIES} type is
+ * not taken — the same two arms, envelope and codes as
+ * {@link MetaTypeReadRefusal}.
+ */
+export type MetaTypeWriteRefusal = MetaTypeReadRefusal;
+
+/**
+ * [#21124] THE type-level write admission of the `/meta` surface — see
+ * {@link META_TYPE_WRITE_CAPABILITIES} for the row and the reason.
+ *
+ * Same inputs and same folding as {@link metaTypeReadRefusal}: `method` the
+ * request's verb, `type` the RAW `:type` segment (folded here through
+ * `canonicalMetaUrlType` and `pluralToSingular`, so `/meta/datasources`
+ * cannot fall outside the row `/meta/datasource` is in), `caller` the
+ * request's resolved execution context.
+ *
+ * Answers `undefined` — go on, nothing sent — for a read verb, for an unlisted
+ * type, and for a caller whose resolved `systemPermissions` hold the row's
+ * capability. Otherwise the refusal, decided before the door resolves the
+ * protocol, so nothing is written and the answer is the same whether or not
+ * the named item exists. The message names the capability and nothing else.
+ *
+ * ⛔ No `isSystem` arm, for the reason {@link metaTypeReadRefusal} gives:
+ * inbound HTTP never carries `isSystem`, and the datasource admin door reads
+ * the held set alone.
+ */
+export function metaTypeWriteRefusal(
+    method: unknown,
+    type: unknown,
+    caller: unknown,
+): MetaTypeWriteRefusal | undefined {
+    const verb = String(method ?? '').toUpperCase();
+    if (!META_WRITE_VERBS.has(verb)) return undefined;
+    if (typeof type !== 'string' || type.length === 0) return undefined;
+    const canonical = canonicalMetaUrlType(type);
+    const folded = Object.prototype.hasOwnProperty.call(META_TYPE_WRITE_CAPABILITIES, canonical)
+        ? canonical
+        : pluralToSingular(type);
+    if (!Object.prototype.hasOwnProperty.call(META_TYPE_WRITE_CAPABILITIES, folded)) return undefined;
+    const capability = META_TYPE_WRITE_CAPABILITIES[folded];
+    const ctx = caller && typeof caller === 'object'
+        ? caller as { userId?: unknown; systemPermissions?: unknown }
+        : undefined;
+    if (!ctx?.userId) {
+        return { status: ANONYMOUS_DENY_STATUS, code: ANONYMOUS_DENY_CODE, message: ANONYMOUS_DENY_MESSAGE };
+    }
+    const held = Array.isArray(ctx.systemPermissions) ? ctx.systemPermissions : [];
+    if (held.includes(capability)) return undefined;
+    return {
+        status: 403,
+        code: 'PERMISSION_DENIED',
+        message: `Writing ${folded} metadata requires the \`${capability}\` capability.`,
+    };
+}
+
 // ── The list route's unknown-type refusal ─────────────────────────────────────
 
 /**

packages/rest/src/rest-server.ts

@@ -5319,6 +5319,26 @@ export class RestServer {
                             sendEnvelopeError(res, typeRefusal.status, typeRefusal.code, typeRefusal.message);
                             return;
                         }
+                        // [#21124] …and its write-side twin: a write of a
+                        // datasource definition is admitted on the capability
+                        // the datasource admin door requires for the same
+                        // create / update / remove. Asked here, before the
+                        // door's own authoring admission resolves the protocol,
+                        // so a refused caller writes nothing and is told the
+                        // same thing whether or not the name exists. The verb
+                        // judged is the ROUTE's declared one (`RouteEntry.method`
+                        // is required) — the door being entered. The decision
+                        // is `metaTypeWriteRefusal`, which the runtime
+                        // dispatcher's `/meta` entry asks too.
+                        const writeRefusal = metaReadGate.metaTypeWriteRefusal(
+                            entry.method,
+                            req?.params?.type,
+                            context,
+                        );
+                        if (writeRefusal) {
+                            sendEnvelopeError(res, writeRefusal.status, writeRefusal.code, writeRefusal.message);
+                            return;
+                        }
                         return (inner as (rq: any, rs: any) => unknown)(req, res);
                     },
                 } as any);

packages/runtime/src/domains/meta.ts

@@ -71,6 +71,7 @@ import {
     metaReadOrganizationId,
     metaRequestLocale,
     metaTypeReadRefusal,
+    metaTypeWriteRefusal,
     projectMetaObjectSchema,
     refuseUnknownMetaListType,
     STORED_VERSION_DOOR_POLICY,
@@ -933,6 +934,22 @@ export async function handleMetadataRequest(deps: DomainHandlerDeps, path: strin
         };
     }
 
+    // [#21124] …and the write-side twin, asked at the same point of the same
+    // predicate `RestServer`'s registrar asks: a write verb on a `/meta` path
+    // whose type is a datasource definition is admitted on the capability the
+    // datasource admin door requires for the same create / update / remove —
+    // before the `PUT` branch's own authoring admission resolves the protocol,
+    // so a refused caller writes nothing, whatever route shape the request
+    // took and whether or not the name exists. A request that names no verb is
+    // a read (see above), so it is never judged here.
+    const typeWriteRefusal = metaTypeWriteRefusal(method, parts[0], _context.executionContext);
+    if (typeWriteRefusal) {
+        return {
+            handled: true,
+            response: deps.error(typeWriteRefusal.message, typeWriteRefusal.status, { code: typeWriteRefusal.code }),
+        };
+    }
+
     // GET /metadata/types
     if (parts[0] === 'types') {
         // PRIORITY 1: Try protocol service — it returns BOTH legacy