@happyvertical/smrt-core 0.43.10 → 0.44.1

package/dist/generators/preflight-route.js

@@ -0,0 +1,194 @@
+import { ObjectRegistry } from "../registry.js";
+import { PRIVATE_READ_CACHE_CONTROL } from "./conditional-get.js";
+//#region src/generators/preflight-route.ts
+/**
+* Generated `_preflight` HTTP route for browser-plane playbook preflight
+* (issue #2590).
+*
+* Handles `GET {basePath}/_preflight?key=<playbook key>` in the REST generator:
+* an advisory, read-effect, idempotent report of what a caller's playbook would
+* be allowed to do — *predicted*, never granted. Every step is authorized again
+* where it executes; this route is capability **selection**, never
+* authorization (epic #2585 invariant 2).
+*
+* ## `authMiddleware` is never invoked here
+*
+* Generated REST authorization is
+* `authMiddleware?: (objectName, action) => (req) => Promise<Request | Response>`
+* — request-bound, `Response`-returning rather than boolean, and free to consult
+* session stores, rate-limit, or audit. It is not a dry-run predicate, and a
+* synthetic-`Request` dry run of it would be a side effect the caller never
+* asked for.
+*
+* That is enforced **structurally**, not by discipline:
+* {@link PlaybookPreflightRouteOptions} has no `authMiddleware` member and no
+* function-valued auth member of any kind. `rest.ts` passes the boolean
+* `appAuthConfigured` and nothing else, so there is no handle in this module to
+* invoke even by mistake. The app-auth layer is consequently reported as
+* `unknown`, which is the honest answer.
+*
+* ## Why the provider is injected
+*
+* Resolution and verdict shaping live in `@happyvertical/smrt-playbooks`, which
+* depends on this package. Core therefore owns the route and the static-layer
+* facts (`ObjectRegistry` is core's), and takes the evaluator as a seam — the
+* dependency stays one-way.
+*/
+/** Path segment the preflight route is served at, under the API base path. */
+var PLAYBOOK_PREFLIGHT_ROUTE_SEGMENT = "_preflight";
+/**
+* Capability classification of the preflight route: a read, safely repeatable,
+* and closed-world. It is admitted by a default read-only browser exposure
+* policy without an opt-in, because it reports on the system rather than
+* changing it.
+*/
+var PLAYBOOK_PREFLIGHT_CAPABILITY = Object.freeze({
+	effect: "read",
+	idempotent: true,
+	openWorld: false
+});
+function jsonResponse(body, status) {
+	return new Response(JSON.stringify(body), {
+		status,
+		headers: {
+			"Content-Type": "application/json",
+			"Cache-Control": PRIVATE_READ_CACHE_CONTROL
+		}
+	});
+}
+/**
+* Serves `GET {basePath}/_preflight?key=<key>`.
+*
+* Unresolvable keys are the provider's concern: it returns the same uniform
+* "unavailable" body for an unknown key as for an unauthorized one, and this
+* route serves whatever it returns with an unconditional 200, so the HTTP layer
+* adds no way to tell them apart either.
+*/
+async function handlePlaybookPreflightRoute(req, options) {
+	if (!options.provider) return jsonResponse({ error: "Not found" }, 404);
+	if (req.method !== "GET") return jsonResponse({ error: "Method not allowed" }, 405);
+	const key = new URL(req.url).searchParams.get("key");
+	if (!key) return jsonResponse({ error: "Query parameter 'key' is required" }, 400);
+	return jsonResponse(await options.provider({
+		key,
+		plane: "browser",
+		...options.permissions ? { permissions: options.permissions } : {},
+		appAuthConfigured: options.appAuthConfigured,
+		db: options.db
+	}), 200);
+}
+/**
+* Resolves a qualified model reference (`@happyvertical/smrt-commerce:Order`)
+* to the name the registry and the REST generator key configuration by.
+*
+* Returns `undefined` for anything this build does not register, so the caller
+* fails closed rather than reporting on a model that has no route.
+*/
+function resolveRegisteredObjectName(model) {
+	return (model.includes(":") ? ObjectRegistry.getClassByQualifiedName(model) : ObjectRegistry.getClass(model))?.name;
+}
+/**
+* The HTTP method a REST action is served by.
+*
+* CRUD actions map to their fixed verbs. A custom action is served under the
+* method its own route config declares (`api.routes[action].method`, defaulting
+* to `POST` exactly as `dispatchCustomCollectionAction` does), because guessing
+* `POST` for a declared `GET` action would make preflight report a false `deny`
+* on a `public: 'read'` model — hiding a playbook the caller can actually run,
+* which is the tool-listing case this exists to serve. Without an `objectName`
+* to read the declaration from, the fail-closed `POST` remains.
+*/
+function restMethodForApiAction(action, objectName) {
+	switch (action) {
+		case "list":
+		case "get": return "GET";
+		case "create": return "POST";
+		case "update": return "PUT";
+		case "delete": return "DELETE";
+		default: break;
+	}
+	if (!objectName) return "POST";
+	const apiConfig = ObjectRegistry.getConfig(objectName)?.api;
+	if (!apiConfig || typeof apiConfig !== "object" || !apiConfig.routes) return "POST";
+	return (apiConfig.routes[action]?.method ?? "POST").toUpperCase();
+}
+/**
+* Whether `@smrt({ api })` exposes `action` on `objectName`.
+*
+* The generator's own action gate, lifted to a module function so preflight and
+* the live route read the same rule from one place. Accepts any action name so
+* a custom action is gated by the same `include`/`exclude` lists.
+*
+* @remarks An absent `objectName` returns `true` — fail-**open**, because the
+* live route reaches this only after it has already resolved a model, and an
+* unnamed object there means "not gated by this rule". A caller *predicting*
+* rather than serving has no such guarantee and must reject an unresolvable
+* model before asking (see `createRestPreflightLayerSource`).
+*/
+function isApiActionEnabledForObject(objectName, action) {
+	if (!objectName) return true;
+	const apiConfig = ObjectRegistry.getConfig(objectName).api;
+	if (apiConfig === false) return false;
+	if (apiConfig && typeof apiConfig === "object") {
+		if (apiConfig.include && !apiConfig.include.includes(action)) return false;
+		if (apiConfig.exclude?.includes(action)) return false;
+	}
+	return true;
+}
+/**
+* Whether `action` names a route the generated REST surface can actually
+* dispatch on `objectName`.
+*
+* CRUD actions always have a route. A custom action exists only when the
+* decorator declares it in `api.routes` — `dispatchCustomCollectionAction`
+* iterates exactly that map, so an action absent from it can never execute no
+* matter what `include`/`exclude` say. Exposure alone would report a typo'd or
+* removed custom action as `allow`, and an agent would then start the earlier
+* steps of a non-atomic playbook before dying on it — the failure preflight
+* exists to prevent.
+*/
+function isRestActionRoutable(objectName, action) {
+	if (!objectName) return false;
+	if (action === "list" || action === "get" || action === "create" || action === "update" || action === "delete") return true;
+	const apiConfig = ObjectRegistry.getConfig(objectName)?.api;
+	if (!apiConfig || typeof apiConfig !== "object" || !apiConfig.routes) return false;
+	return Object.hasOwn(apiConfig.routes, action);
+}
+/**
+* Fail-closed authorization posture (#1540): true only when the object opts out
+* of auth via `@smrt({ api: { public } })` — `true` for every method, `'read'`
+* for safe (GET) methods only.
+*/
+function isRestRoutePublic(objectName, method) {
+	if (!objectName) return false;
+	const apiConfig = ObjectRegistry.getConfig(objectName)?.api;
+	if (!apiConfig || typeof apiConfig !== "object") return false;
+	const publicAccess = apiConfig.public;
+	if (publicAccess === true) return true;
+	if (publicAccess === "read") return method.toUpperCase() === "GET";
+	return false;
+}
+/**
+* Field-level read-permission slugs declared by `objectName`.
+*
+* Reads the model's own and inherited fields only — deliberately **not** the
+* STI base-plus-descendants union used for cache policy. That union answers
+* "does any variant carry a read-permission field?"; used here it would report
+* a sibling variant's slugs as required for a step naming this concrete model.
+*/
+function restFieldReadPermissions(objectName) {
+	if (!objectName) return [];
+	const registered = ObjectRegistry.getClass(objectName);
+	const className = registered?.qualifiedName ?? registered?.name ?? objectName;
+	const fields = registered?.inheritedFields ?? ObjectRegistry.getFields(className);
+	const slugs = /* @__PURE__ */ new Set();
+	for (const [, def] of fields) {
+		const slug = typeof def?.readPermission === "string" ? def.readPermission : typeof def?._meta?.readPermission === "string" ? def._meta.readPermission : void 0;
+		if (slug) slugs.add(slug);
+	}
+	return [...slugs].sort();
+}
+//#endregion
+export { PLAYBOOK_PREFLIGHT_CAPABILITY, PLAYBOOK_PREFLIGHT_ROUTE_SEGMENT, handlePlaybookPreflightRoute, isApiActionEnabledForObject, isRestActionRoutable, isRestRoutePublic, resolveRegisteredObjectName, restFieldReadPermissions, restMethodForApiAction };
+
+//# sourceMappingURL=preflight-route.js.map

package/dist/generators/preflight-route.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preflight-route.js","names":[],"sources":["../../src/generators/preflight-route.ts"],"sourcesContent":["/**\n * Generated `_preflight` HTTP route for browser-plane playbook preflight\n * (issue #2590).\n *\n * Handles `GET {basePath}/_preflight?key=<playbook key>` in the REST generator:\n * an advisory, read-effect, idempotent report of what a caller's playbook would\n * be allowed to do — *predicted*, never granted. Every step is authorized again\n * where it executes; this route is capability **selection**, never\n * authorization (epic #2585 invariant 2).\n *\n * ## `authMiddleware` is never invoked here\n *\n * Generated REST authorization is\n * `authMiddleware?: (objectName, action) => (req) => Promise<Request | Response>`\n * — request-bound, `Response`-returning rather than boolean, and free to consult\n * session stores, rate-limit, or audit. It is not a dry-run predicate, and a\n * synthetic-`Request` dry run of it would be a side effect the caller never\n * asked for.\n *\n * That is enforced **structurally**, not by discipline:\n * {@link PlaybookPreflightRouteOptions} has no `authMiddleware` member and no\n * function-valued auth member of any kind. `rest.ts` passes the boolean\n * `appAuthConfigured` and nothing else, so there is no handle in this module to\n * invoke even by mistake. The app-auth layer is consequently reported as\n * `unknown`, which is the honest answer.\n *\n * ## Why the provider is injected\n *\n * Resolution and verdict shaping live in `@happyvertical/smrt-playbooks`, which\n * depends on this package. Core therefore owns the route and the static-layer\n * facts (`ObjectRegistry` is core's), and takes the evaluator as a seam — the\n * dependency stays one-way.\n */\n\nimport { ObjectRegistry } from '../registry.js';\nimport { PRIVATE_READ_CACHE_CONTROL } from './conditional-get.js';\n\n/** Path segment the preflight route is served at, under the API base path. */\nexport const PLAYBOOK_PREFLIGHT_ROUTE_SEGMENT = '_preflight';\n\n/**\n * Capability classification of the preflight route: a read, safely repeatable,\n * and closed-world. It is admitted by a default read-only browser exposure\n * policy without an opt-in, because it reports on the system rather than\n * changing it.\n */\nexport const PLAYBOOK_PREFLIGHT_CAPABILITY = Object.freeze({\n  effect: 'read',\n  idempotent: true,\n  openWorld: false,\n} as const);\n\n/**\n * The request handed to a preflight provider. Deliberately carries no request,\n * no headers, and no auth handle — only the caller-scoped facts the static\n * layers need.\n */\nexport interface PlaybookPreflightRouteRequest {\n  /** The requested playbook key. */\n  key: string;\n  /** Always `'browser'` from this route. */\n  plane: 'browser';\n  /** The caller's published permission slugs, when the API context has them. */\n  permissions?: Iterable<string>;\n  /** Whether an app auth middleware is wired. A boolean; never the function. */\n  appAuthConfigured: boolean;\n  /** The generator's `APIContext.db`. */\n  db?: unknown;\n}\n\n/**\n * Host-supplied browser-plane preflight evaluator, wired from\n * `@happyvertical/smrt-playbooks`. Returns a JSON-serializable report.\n */\nexport type PlaybookPreflightProvider = (\n  request: PlaybookPreflightRouteRequest,\n) => Promise<unknown>;\n\n/**\n * Options for {@link handlePlaybookPreflightRoute}.\n *\n * There is intentionally no `authMiddleware` member — see the module docs.\n */\nexport interface PlaybookPreflightRouteOptions {\n  provider?: PlaybookPreflightProvider;\n  permissions?: Iterable<string>;\n  appAuthConfigured: boolean;\n  db?: unknown;\n}\n\nfunction jsonResponse(body: unknown, status: number): Response {\n  return new Response(JSON.stringify(body), {\n    status,\n    headers: {\n      'Content-Type': 'application/json',\n      'Cache-Control': PRIVATE_READ_CACHE_CONTROL,\n    },\n  });\n}\n\n/**\n * Serves `GET {basePath}/_preflight?key=<key>`.\n *\n * Unresolvable keys are the provider's concern: it returns the same uniform\n * \"unavailable\" body for an unknown key as for an unauthorized one, and this\n * route serves whatever it returns with an unconditional 200, so the HTTP layer\n * adds no way to tell them apart either.\n */\nexport async function handlePlaybookPreflightRoute(\n  req: Request,\n  options: PlaybookPreflightRouteOptions,\n): Promise<Response> {\n  if (!options.provider) {\n    // Route not wired for this deployment. Says nothing about any key.\n    return jsonResponse({ error: 'Not found' }, 404);\n  }\n\n  if (req.method !== 'GET') {\n    return jsonResponse({ error: 'Method not allowed' }, 405);\n  }\n\n  const key = new URL(req.url).searchParams.get('key');\n  if (!key) {\n    return jsonResponse({ error: \"Query parameter 'key' is required\" }, 400);\n  }\n\n  const report = await options.provider({\n    key,\n    plane: 'browser',\n    ...(options.permissions ? { permissions: options.permissions } : {}),\n    appAuthConfigured: options.appAuthConfigured,\n    db: options.db,\n  });\n\n  return jsonResponse(report, 200);\n}\n\n/**\n * Resolves a qualified model reference (`@happyvertical/smrt-commerce:Order`)\n * to the name the registry and the REST generator key configuration by.\n *\n * Returns `undefined` for anything this build does not register, so the caller\n * fails closed rather than reporting on a model that has no route.\n */\nexport function resolveRegisteredObjectName(model: string): string | undefined {\n  const registered = model.includes(':')\n    ? ObjectRegistry.getClassByQualifiedName(model)\n    : ObjectRegistry.getClass(model);\n  return registered?.name;\n}\n\n/**\n * The HTTP method a REST action is served by.\n *\n * CRUD actions map to their fixed verbs. A custom action is served under the\n * method its own route config declares (`api.routes[action].method`, defaulting\n * to `POST` exactly as `dispatchCustomCollectionAction` does), because guessing\n * `POST` for a declared `GET` action would make preflight report a false `deny`\n * on a `public: 'read'` model — hiding a playbook the caller can actually run,\n * which is the tool-listing case this exists to serve. Without an `objectName`\n * to read the declaration from, the fail-closed `POST` remains.\n */\nexport function restMethodForApiAction(\n  action: string,\n  objectName?: string,\n): string {\n  switch (action) {\n    case 'list':\n    case 'get':\n      return 'GET';\n    case 'create':\n      return 'POST';\n    case 'update':\n      return 'PUT';\n    case 'delete':\n      return 'DELETE';\n    default:\n      break;\n  }\n\n  if (!objectName) {\n    return 'POST';\n  }\n\n  const apiConfig = ObjectRegistry.getConfig(objectName)?.api;\n  if (!apiConfig || typeof apiConfig !== 'object' || !apiConfig.routes) {\n    return 'POST';\n  }\n\n  const route = (apiConfig.routes as Record<string, { method?: string }>)[\n    action\n  ];\n  return (route?.method ?? 'POST').toUpperCase();\n}\n\n/**\n * Whether `@smrt({ api })` exposes `action` on `objectName`.\n *\n * The generator's own action gate, lifted to a module function so preflight and\n * the live route read the same rule from one place. Accepts any action name so\n * a custom action is gated by the same `include`/`exclude` lists.\n *\n * @remarks An absent `objectName` returns `true` — fail-**open**, because the\n * live route reaches this only after it has already resolved a model, and an\n * unnamed object there means \"not gated by this rule\". A caller *predicting*\n * rather than serving has no such guarantee and must reject an unresolvable\n * model before asking (see `createRestPreflightLayerSource`).\n */\nexport function isApiActionEnabledForObject(\n  objectName: string | undefined,\n  action: string,\n): boolean {\n  if (!objectName) {\n    return true;\n  }\n\n  const apiConfig = ObjectRegistry.getConfig(objectName).api;\n\n  if (apiConfig === false) {\n    return false;\n  }\n\n  if (apiConfig && typeof apiConfig === 'object') {\n    if (apiConfig.include && !apiConfig.include.includes(action)) {\n      return false;\n    }\n\n    if (apiConfig.exclude?.includes(action)) {\n      return false;\n    }\n  }\n\n  return true;\n}\n\n/**\n * Whether `action` names a route the generated REST surface can actually\n * dispatch on `objectName`.\n *\n * CRUD actions always have a route. A custom action exists only when the\n * decorator declares it in `api.routes` — `dispatchCustomCollectionAction`\n * iterates exactly that map, so an action absent from it can never execute no\n * matter what `include`/`exclude` say. Exposure alone would report a typo'd or\n * removed custom action as `allow`, and an agent would then start the earlier\n * steps of a non-atomic playbook before dying on it — the failure preflight\n * exists to prevent.\n */\nexport function isRestActionRoutable(\n  objectName: string | undefined,\n  action: string,\n): boolean {\n  if (!objectName) return false;\n  if (\n    action === 'list' ||\n    action === 'get' ||\n    action === 'create' ||\n    action === 'update' ||\n    action === 'delete'\n  ) {\n    return true;\n  }\n\n  const apiConfig = ObjectRegistry.getConfig(objectName)?.api;\n  if (!apiConfig || typeof apiConfig !== 'object' || !apiConfig.routes) {\n    return false;\n  }\n\n  return Object.hasOwn(apiConfig.routes as Record<string, unknown>, action);\n}\n\n/**\n * Fail-closed authorization posture (#1540): true only when the object opts out\n * of auth via `@smrt({ api: { public } })` — `true` for every method, `'read'`\n * for safe (GET) methods only.\n */\nexport function isRestRoutePublic(\n  objectName: string | undefined,\n  method: string,\n): boolean {\n  if (!objectName) return false;\n  const apiConfig = ObjectRegistry.getConfig(objectName)?.api;\n  if (!apiConfig || typeof apiConfig !== 'object') return false;\n  const publicAccess = (apiConfig as { public?: boolean | 'read' }).public;\n  if (publicAccess === true) return true;\n  if (publicAccess === 'read') return method.toUpperCase() === 'GET';\n  return false;\n}\n\n/**\n * Field-level read-permission slugs declared by `objectName`.\n *\n * Reads the model's own and inherited fields only — deliberately **not** the\n * STI base-plus-descendants union used for cache policy. That union answers\n * \"does any variant carry a read-permission field?\"; used here it would report\n * a sibling variant's slugs as required for a step naming this concrete model.\n */\nexport function restFieldReadPermissions(\n  objectName: string | undefined,\n): string[] {\n  if (!objectName) return [];\n  const registered = ObjectRegistry.getClass(objectName);\n  const className = registered?.qualifiedName ?? registered?.name ?? objectName;\n  const fields =\n    registered?.inheritedFields ?? ObjectRegistry.getFields(className);\n  const slugs = new Set<string>();\n  for (const [, def] of fields) {\n    const slug =\n      typeof def?.readPermission === 'string'\n        ? def.readPermission\n        : typeof def?._meta?.readPermission === 'string'\n          ? (def._meta.readPermission as string)\n          : undefined;\n    if (slug) slugs.add(slug);\n  }\n  return [...slugs].sort();\n}\n"],"mappings":"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"}

package/dist/generators/rest.d.ts

@@ -2,6 +2,7 @@ import { default as http } from 'node:http';
 import { SmrtCollection } from '../collection';
 import { SmrtObject } from '../object';
 import { RegisteredClass } from '../registry/types';
+import { PlaybookPreflightProvider } from './preflight-route';
 export interface APIConfig {
     basePath?: string;
     enableCors?: boolean;
@@ -46,6 +47,17 @@ export interface APIConfig {
      * through this runtime server.
      */
     manifestHash?: string;
+    /**
+     * Browser-plane playbook preflight provider (#2590), wired from
+     * `@happyvertical/smrt-playbooks`. When omitted the `_preflight` route is not
+     * served at all.
+     *
+     * The provider receives only the requested key, the caller's published
+     * permission slugs, the database handle, and the boolean
+     * `appAuthConfigured`. It never receives {@link APIConfig.authMiddleware},
+     * which preflight must never invoke.
+     */
+    playbookPreflight?: PlaybookPreflightProvider;
 }
 export interface APIContext {
     db?: unknown;

package/dist/generators/rest.d.ts.map

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

package/dist/generators/rest.js

@@ -7,6 +7,7 @@ import "../dispatch/index.js";
 import { canonicalReadRepresentation, computeTableVersionEtag, conditionalJsonResponse, ifNoneMatchHasConcreteMatch, ifNoneMatchSatisfied, resolveReadCacheControl, resolveTenantEtagDiscriminator, versionConditionalResponse, warnIfSharedCacheNeutralized, warnIfTenantScopedPublicRead } from "./conditional-get.js";
 import { handleChangesRoute } from "./changes-route.js";
 import { handleEventsRoute } from "./events-route.js";
+import { handlePlaybookPreflightRoute, isApiActionEnabledForObject, isRestRoutePublic } from "./preflight-route.js";
 import { SYNC_APPLY_ROUTE_SEGMENTS, processSyncApplyBatch } from "../sync/apply.js";
 import { computeWebManifestHash } from "../vite-plugin/web-collections.js";
 import { normalizeTypedHttpError } from "./typed-http-error.js";
@@ -245,6 +246,15 @@ var APIGenerator = class {
 			});
 			return this.addCorsHeaders(response, req);
 		}
+		if (url.pathname === `${this.config.basePath}/_preflight`) {
+			const response = await handlePlaybookPreflightRoute(req, {
+				provider: this.config.playbookPreflight,
+				...this.context.permissions ? { permissions: this.context.permissions } : {},
+				appAuthConfigured: Boolean(this.config.authMiddleware),
+				db: this.resolveContextDb()
+			});
+			return this.addCorsHeaders(response, req);
+		}
 		if (url.pathname.startsWith(this.config.basePath || "")) {
 			const response = await this.handleObjectRoute(req, url);
 			return this.addCorsHeaders(response, req);
@@ -333,23 +343,10 @@ var APIGenerator = class {
 	* Everything else requires an `authMiddleware` to be configured.
 	*/
 	isRoutePublic(objectName, method) {
-		if (!objectName) return false;
-		const apiConfig = ObjectRegistry.getConfig(objectName)?.api;
-		if (!apiConfig || typeof apiConfig !== "object") return false;
-		const publicAccess = apiConfig.public;
-		if (publicAccess === true) return true;
-		if (publicAccess === "read") return method.toUpperCase() === "GET";
-		return false;
+		return isRestRoutePublic(objectName, method);
 	}
 	isApiActionEnabled(objectName, action) {
-		if (!objectName) return true;
-		const apiConfig = ObjectRegistry.getConfig(objectName).api;
-		if (apiConfig === false) return false;
-		if (apiConfig && typeof apiConfig === "object") {
-			if (apiConfig.include && !apiConfig.include.includes(action)) return false;
-			if (apiConfig.exclude?.includes(action)) return false;
-		}
-		return true;
+		return isApiActionEnabledForObject(objectName, action);
 	}
 	getCollectionObjectName(collection) {
 		const itemClass = collection._itemClass || collection.constructor?._itemClass;