@btst/stack 3.0.0-rc.2 → 3.0.0-rc.3

package/src/plugins/media/db.ts

@@ -48,6 +48,10 @@ export const mediaSchema = createDbPlugin("media", {
 				type: "date",
 				defaultValue: () => new Date(),
 			},
+			updatedAt: {
+				type: "date",
+				defaultValue: () => new Date(),
+			},
 		},
 	},
 	folder: {
@@ -73,6 +77,10 @@ export const mediaSchema = createDbPlugin("media", {
 				type: "date",
 				defaultValue: () => new Date(),
 			},
+			updatedAt: {
+				type: "date",
+				defaultValue: () => new Date(),
+			},
 		},
 	},
 });

package/src/plugins/media/permissions.ts

@@ -0,0 +1,61 @@
+import { definePermissions, permission } from "@btst/stack/authorization";
+import { z } from "zod";
+
+const tenantFact = { tenantId: z.string().optional() };
+const folderFact = {
+	folderId: z.string(),
+	parentId: z.string().optional(),
+	...tenantFact,
+};
+const assetFact = {
+	assetId: z.string(),
+	folderId: z.string().optional(),
+	mimeType: z.string(),
+	...tenantFact,
+};
+
+/** Browser-safe, schema-backed permissions published by Media. */
+export const mediaPermissions = definePermissions("media", {
+	library: {
+		/** Read the server-scoped asset/folder collection used by the library and picker. */
+		read: permission(),
+	},
+	asset: {
+		/** Receive, present, or select one asset from an authorized collection read. */
+		read: permission(z.object(assetFact)),
+		/**
+		 * Start or finish an upload. `callback` is reserved for a provider-verified
+		 * completion callback whose context was bound into the server-issued token.
+		 */
+		upload: permission(
+			z.object({
+				phase: z.enum(["initialize", "direct", "finalize", "callback"]),
+				folderId: z.string().optional(),
+				/** Omitted by pre-file browser gates; server operations always derive it. */
+				mimeType: z.string().optional(),
+				...tenantFact,
+			}),
+		),
+		/** Update a server-resolved asset. */
+		update: permission(
+			z.object({
+				...assetFact,
+				/** `null` means moving to root; omitted means the folder is unchanged. */
+				targetFolderId: z.string().nullable().optional(),
+			}),
+		),
+		/** Delete a server-resolved asset and its storage object. */
+		delete: permission(z.object(assetFact)),
+	},
+	folder: {
+		/** Create a folder beneath a server-resolved parent. */
+		create: permission(
+			z.object({
+				parentId: z.string().optional(),
+				...tenantFact,
+			}),
+		),
+		/** Delete a server-resolved folder after authorizing every folder in its subtree. */
+		delete: permission(z.object(folderFact)),
+	},
+});

package/src/plugins/media/query-keys.ts

@@ -8,7 +8,11 @@ import type { AssetListParams } from "./api/getters";
 import {
 	assetListDiscriminator,
 	folderListDiscriminator,
+	mediaQueryScope,
+	type MediaEndpointPartition,
+	type MediaIdentityPartition,
 } from "./api/query-key-defs";
+import { resolveMediaAsset } from "./asset-url";
 import { ROOT_FOLDER_QUERY_VALUE } from "./schemas";
 import type { SerializedAsset, SerializedFolder } from "./types";
 
@@ -54,22 +58,49 @@ export const mediaResources = {
 		queries: {
 			list: {
 				path: "/media/assets",
-				query: (params: AssetListParams = {}) => ({
-					folderId: params.folderId,
-					mimeType: params.mimeType,
-					query: normalizeSearch(params.query),
-					limit: params.limit ?? 20,
+				query: (
+					params: AssetListParams | undefined,
+					_identityPartition: MediaIdentityPartition | undefined,
+					_endpoint: MediaEndpointPartition,
+				) => ({
+					folderId: params?.folderId,
+					mimeType: params?.mimeType,
+					query: normalizeSearch(params?.query),
+					limit: params?.limit ?? 20,
 				}),
-				key: (params: AssetListParams = {}) => [assetListDiscriminator(params)],
-				select: (data: any) =>
-					data as {
+				key: (
+					params: AssetListParams | undefined,
+					identityPartition: MediaIdentityPartition | undefined,
+					endpoint: MediaEndpointPartition,
+				) => [
+					assetListDiscriminator(params),
+					mediaQueryScope(identityPartition, endpoint),
+				],
+				select: (
+					data: any,
+					_params: AssetListParams | undefined,
+					_identityPartition: MediaIdentityPartition | undefined,
+					endpoint: MediaEndpointPartition,
+				) => {
+					const result = data as {
 						items: SerializedAsset[];
 						total: number;
 						limit?: number;
 						offset?: number;
-					},
+					};
+					return {
+						...result,
+						items: result.items.map((asset) =>
+							resolveMediaAsset(asset, endpoint.baseURL),
+						),
+					};
+				},
 				infinite: true,
-				pageSize: (params: AssetListParams = {}) => params.limit ?? 20,
+				pageSize: (
+					params: AssetListParams | undefined,
+					_identityPartition: MediaIdentityPartition | undefined,
+					_endpoint: MediaEndpointPartition,
+				) => params?.limit ?? 20,
 				nextPageParam: paginatedNextPageParam,
 			},
 		},
@@ -88,8 +119,9 @@ export const mediaResources = {
 					},
 				}),
 				select: (data: any) => data as SerializedAsset,
-				invalidates: ["mediaAssets.list"],
-				refetchType: "all",
+				// Public Media wrappers refresh only the current identity partition.
+				// A broad generated invalidation could refetch an inactive old account
+				// with the current account's request headers.
 				refresh: false,
 			},
 			delete: {
@@ -97,8 +129,6 @@ export const mediaResources = {
 				method: "DELETE" as const,
 				input: (id: string) => ({ params: { id } }),
 				select: (data: any) => data as { success: boolean },
-				invalidates: ["mediaAssets.list"],
-				refetchType: "all",
 				refresh: false,
 			},
 		},
@@ -108,12 +138,28 @@ export const mediaResources = {
 		queries: {
 			list: {
 				path: "/media/folders",
-				query: (parentId?: string | null) =>
+				query: (
+					parentId: string | null | undefined,
+					_identityPartition: MediaIdentityPartition | undefined,
+					_endpoint: MediaEndpointPartition,
+				) =>
 					parentId === undefined
 						? {}
 						: { parentId: parentId ?? ROOT_FOLDER_QUERY_VALUE },
-				key: (parentId?: string | null) => [folderListDiscriminator(parentId)],
-				select: (data: any) => data as SerializedFolder[],
+				key: (
+					parentId: string | null | undefined,
+					identityPartition: MediaIdentityPartition | undefined,
+					endpoint: MediaEndpointPartition,
+				) => [
+					folderListDiscriminator(parentId),
+					mediaQueryScope(identityPartition, endpoint),
+				],
+				select: (
+					data: any,
+					_parentId: string | null | undefined,
+					_identityPartition: MediaIdentityPartition | undefined,
+					_endpoint: MediaEndpointPartition,
+				) => data as SerializedFolder[],
 			},
 		},
 		mutations: {
@@ -122,7 +168,6 @@ export const mediaResources = {
 				method: "POST" as const,
 				input: (input: CreateMediaFolderInput) => ({ body: input }),
 				select: (data: any) => data as SerializedFolder,
-				invalidates: ["mediaFolders.list"],
 				refresh: false,
 			},
 			delete: {
@@ -130,7 +175,6 @@ export const mediaResources = {
 				method: "DELETE" as const,
 				input: (id: string) => ({ params: { id } }),
 				select: (data: any) => data as { success: boolean },
-				invalidates: ["mediaFolders.list"],
 				refresh: false,
 			},
 		},

package/src/plugins/media/types.ts

@@ -9,6 +9,8 @@ export type Asset = {
 	alt?: string;
 	tenantId?: string | null;
 	createdAt: Date;
+	/** Mutation version used for authoritative compare-and-swap checks. */
+	updatedAt?: Date;
 };
 
 export type Folder = {
@@ -17,12 +19,16 @@ export type Folder = {
 	parentId?: string;
 	tenantId?: string | null;
 	createdAt: Date;
+	/** Mutation version used for authoritative compare-and-swap checks. */
+	updatedAt?: Date;
 };
 
-export interface SerializedAsset extends Omit<Asset, "createdAt"> {
+export interface SerializedAsset
+	extends Omit<Asset, "createdAt" | "updatedAt"> {
 	createdAt: string;
 }
 
-export interface SerializedFolder extends Omit<Folder, "createdAt"> {
+export interface SerializedFolder
+	extends Omit<Folder, "createdAt" | "updatedAt"> {
 	createdAt: string;
 }

package/src/plugins/open-api/__tests__/route-introspection.test.ts

@@ -0,0 +1,277 @@
+import { createMemoryAdapter } from "@btst/adapter-memory";
+import type { DatabaseDefinition } from "@btst/db";
+import { describe, expect, it, vi } from "vitest";
+import { z } from "zod";
+import { createBackendStack } from "../../../api";
+import {
+	defineAuthorization,
+	definePermissions,
+	permission,
+} from "../../../authorization";
+import { createServerAuth } from "../../../authorization/server";
+import {
+	createDbPlugin,
+	createEndpoint,
+	defineBackendPlugin,
+	defineOperation,
+} from "../../api";
+import { openApiBackendPlugin } from "../api";
+
+describe("OpenAPI route introspection", () => {
+	it("declares the schema and reference handlers as the exact public infrastructure allowlist", () => {
+		const plugin = openApiBackendPlugin();
+		expect(plugin.infrastructureRoutes).toEqual({
+			generateSchema: {
+				access: "public",
+				rationale:
+					"Serves deterministic API metadata and does not execute an application business operation.",
+			},
+			reference: {
+				access: "public",
+				rationale:
+					"Serves the documentation UI for the same public schema without executing an application business operation.",
+			},
+		});
+	});
+
+	it("reuses constructed routes instead of forging an operation transport", async () => {
+		const permissions = definePermissions("introspection", {
+			read: permission(),
+		});
+		const read = defineOperation({
+			input: z.object({ id: z.string() }),
+			permission: permissions.read,
+			facts: () => undefined,
+			execute: ({ input }) => input.id,
+		});
+		const routes = vi.fn((_adapter, _context, operations) => {
+			if (typeof operations.read !== "function") {
+				throw new Error("bound operation is required");
+			}
+			return {
+				read: createEndpoint(
+					"/records/:id",
+					{ method: "GET", requireRequest: true },
+					operations.read.route((ctx: any) => ({ id: ctx.params.id })),
+				),
+			};
+		});
+		const feature = defineBackendPlugin({
+			id: "feature",
+			dbPlugin: createDbPlugin("introspection", {}),
+			operations: () => ({ read }),
+			routes,
+		});
+		const backend = createBackendStack({
+			basePath: "/api",
+			plugins: {
+				openApi: openApiBackendPlugin(),
+				feature,
+			},
+			adapter: (db: DatabaseDefinition) => createMemoryAdapter(db)({}),
+		});
+
+		expect(routes).toHaveBeenCalledTimes(1);
+		const response = await backend.handler(
+			new Request("http://localhost/api/open-api/schema"),
+		);
+
+		expect(response.status).toBe(200);
+		expect(routes).toHaveBeenCalledTimes(1);
+		await expect(response.json()).resolves.toMatchObject({
+			openapi: "3.1.0",
+			paths: {
+				"/records/{id}": {
+					get: {
+						"x-btst-access": "permission",
+						"x-btst-permission": "introspection:read",
+					},
+				},
+			},
+		});
+	});
+
+	it("keeps schema and reference explicitly public without resolving identity", async () => {
+		const permissions = definePermissions("documented", {
+			read: permission(),
+		});
+		const read = defineOperation({
+			input: z.object({}),
+			permission: permissions.read,
+			facts: () => undefined,
+			execute: () => ({ ok: true as const }),
+		});
+		const feature = defineBackendPlugin({
+			id: "documented",
+			dbPlugin: createDbPlugin("documented", {}),
+			operations: () => ({ read }),
+			routes: (_adapter, _context, operations) => ({
+				read: createEndpoint(
+					"/documented",
+					{ method: "GET", requireRequest: true },
+					operations.read.route(() => ({})),
+				),
+			}),
+		});
+		const authorization = defineAuthorization({
+			identity: z.object({ id: z.string() }),
+			permissions: [permissions] as const,
+			rules: ({ documented }) => [documented.read.allow()],
+		});
+		const getIdentity = vi.fn(() => {
+			throw new Error("public infrastructure must not resolve identity");
+		});
+		const backend = createBackendStack({
+			basePath: "/api",
+			plugins: { openApi: openApiBackendPlugin(), documented: feature },
+			adapter: (db: DatabaseDefinition) => createMemoryAdapter(db)({}),
+			auth: createServerAuth({ authorization, getIdentity }),
+		});
+
+		const schema = await backend.handler(
+			new Request("http://localhost/api/open-api/schema"),
+		);
+		const reference = await backend.handler(
+			new Request("http://localhost/api/reference"),
+		);
+		expect(schema.status).toBe(200);
+		expect(reference.status).toBe(200);
+		expect(reference.headers.get("content-type")).toContain("text/html");
+		expect(getIdentity).not.toHaveBeenCalled();
+
+		const disabled = createBackendStack({
+			basePath: "/api",
+			plugins: {
+				openApi: openApiBackendPlugin({ disableDefaultReference: true }),
+				documented: feature,
+			},
+			adapter: (db: DatabaseDefinition) => createMemoryAdapter(db)({}),
+		});
+		expect(
+			(await disabled.handler(new Request("http://localhost/api/reference")))
+				.status,
+		).toBe(404);
+	});
+
+	it("emits deterministic safe access metadata without exposing trusted operations or rule inputs", async () => {
+		const permissions = definePermissions("metadata", {
+			read: permission(z.object({ authoritativeSecret: z.string() })),
+			publicRead: permission(),
+			internalOnly: permission(),
+		});
+		const protectedRead = defineOperation({
+			input: z.object({ id: z.string() }),
+			permission: permissions.read,
+			facts: () => ({ authoritativeSecret: "server-only" }),
+			execute: ({ input }) => input.id,
+		});
+		const publicRead = defineOperation({
+			input: z.object({}),
+			permission: permissions.publicRead,
+			access: "public",
+			facts: () => undefined,
+			execute: () => ({ ok: true as const }),
+		});
+		const internalOnly = defineOperation({
+			input: z.object({}),
+			permission: permissions.internalOnly,
+			facts: () => undefined,
+			execute: () => "internal",
+		});
+		const feature = defineBackendPlugin({
+			id: "feature",
+			dbPlugin: createDbPlugin("metadata", {}),
+			operations: () => ({ protectedRead, publicRead, internalOnly }),
+			routes: (_adapter, _context, operations) => ({
+				protectedRead: createEndpoint(
+					"/z-protected/:id",
+					{ method: "GET", requireRequest: true },
+					operations.protectedRead.route((ctx) => ctx.params),
+				),
+				publicRead: createEndpoint(
+					"/a-public",
+					{ method: "GET", requireRequest: true },
+					operations.publicRead.route(() => ({})),
+				),
+			}),
+		});
+		const build = (plugins: Record<string, any>) =>
+			createBackendStack({
+				basePath: "/api",
+				plugins,
+				adapter: (db: DatabaseDefinition) => createMemoryAdapter(db)({}),
+			});
+		const first = build({ openApi: openApiBackendPlugin(), feature });
+		const second = build({
+			feature,
+			openApi: openApiBackendPlugin(),
+		});
+		const readSchema = async (backend: typeof first) => {
+			const response = await backend.handler(
+				new Request("http://localhost/api/open-api/schema"),
+			);
+			expect(response.status).toBe(200);
+			return response.json();
+		};
+		const firstSchema = await readSchema(first);
+		const secondSchema = await readSchema(second);
+
+		expect(firstSchema).toEqual(secondSchema);
+		expect(firstSchema.paths).toEqual({
+			"/a-public": {
+				get: expect.objectContaining({
+					operationId: "feature_publicRead",
+					"x-btst-access": "public",
+				}),
+			},
+			"/z-protected/{id}": {
+				get: expect.objectContaining({
+					operationId: "feature_protectedRead",
+					"x-btst-access": "permission",
+					"x-btst-permission": "metadata:read",
+				}),
+			},
+		});
+		expect(
+			Object.fromEntries(
+				Object.entries(firstSchema.paths).map(([path, methods]) => [
+					path,
+					Object.fromEntries(
+						Object.entries(methods as Record<string, any>).map(
+							([method, operation]) => [
+								method,
+								{
+									operationId: operation.operationId,
+									access: operation["x-btst-access"],
+									permission: operation["x-btst-permission"],
+								},
+							],
+						),
+					),
+				]),
+			),
+		).toMatchInlineSnapshot(`
+			{
+			  "/a-public": {
+			    "get": {
+			      "access": "public",
+			      "operationId": "feature_publicRead",
+			      "permission": undefined,
+			    },
+			  },
+			  "/z-protected/{id}": {
+			    "get": {
+			      "access": "permission",
+			      "operationId": "feature_protectedRead",
+			      "permission": "metadata:read",
+			    },
+			  },
+			}
+		`);
+		const serialized = JSON.stringify(firstSchema);
+		expect(serialized).not.toContain("internalOnly");
+		expect(serialized).not.toContain("authoritativeSecret");
+		expect(serialized).not.toContain("server-only");
+		expect(serialized).not.toContain("rules");
+	});
+});

package/src/plugins/open-api/api/generator.ts

@@ -20,6 +20,10 @@ export interface PathOperation {
 		};
 	};
 	responses: Record<string, any>;
+	/** Safe BTST operation access state; omitted only for legacy custom routes. */
+	"x-btst-access"?: "permission" | "public";
+	/** Stable schema-backed permission id for protected operations. */
+	"x-btst-permission"?: string;
 }
 
 export interface OpenAPIParameter {
@@ -30,6 +34,10 @@ export interface OpenAPIParameter {
 	description?: string;
 }
 
+function compareStable(left: string, right: string): number {
+	return left < right ? -1 : left > right ? 1 : 0;
+}
+
 /**
  * Convert :param to {param} for OpenAPI path format
  */
@@ -332,15 +340,26 @@ export function generateOpenAPISchema(
 	const paths: Record<string, Record<string, PathOperation>> = {};
 	const tags: Array<{ name: string; description: string }> = [];
 
-	// Iterate over all plugins
-	for (const [pluginKey, plugin] of Object.entries(context.plugins)) {
-		// Skip the open-api plugin itself
-		if (pluginKey === "openApi" || plugin.name === "open-api") {
+	const inventory = new Map(
+		(context.endpointInventory ?? []).map((entry) => [
+			`${entry.pluginKey}\0${entry.routeKey}`,
+			entry,
+		]),
+	);
+
+	// Sort plugin and route keys so registration order cannot change the schema.
+	for (const [pluginKey, plugin] of Object.entries(context.plugins).sort(
+		([left], [right]) => compareStable(left, right),
+	)) {
+		const pluginId = plugin.id;
+		// Skip the OpenAPI plugin itself.
+		if (pluginId === "openApi") {
 			continue;
 		}
 
-		// Get plugin routes
-		const pluginRoutes = plugin.routes(context.adapter, context);
+		// Stack composition records the real route map. Reusing it avoids invoking
+		// plugin factories with a forged operation transport during introspection.
+		const pluginRoutes = context.pluginRoutes[pluginKey] ?? {};
 
 		// Create tag for this plugin
 		const tagName = pluginKey.charAt(0).toUpperCase() + pluginKey.slice(1);
@@ -350,7 +369,9 @@ export function generateOpenAPISchema(
 		});
 
 		// Process each endpoint
-		for (const [routeKey, endpoint] of Object.entries(pluginRoutes)) {
+		for (const [routeKey, endpoint] of Object.entries(pluginRoutes).sort(
+			([left], [right]) => compareStable(left, right),
+		)) {
 			const ep = endpoint as Endpoint;
 
 			// Access endpoint properties
@@ -386,6 +407,13 @@ export function generateOpenAPISchema(
 					...getErrorResponses(),
 				},
 			};
+			const declaration = inventory.get(`${pluginKey}\0${routeKey}`);
+			if (declaration) {
+				operation["x-btst-access"] = declaration.access;
+				if (declaration.permissionId) {
+					operation["x-btst-permission"] = declaration.permissionId;
+				}
+			}
 
 			// Add request body for POST/PUT/PATCH
 			if (["post", "put", "patch"].includes(method)) {
@@ -399,6 +427,19 @@ export function generateOpenAPISchema(
 		}
 	}
 
+	const deterministicPaths = Object.fromEntries(
+		Object.entries(paths)
+			.sort(([left], [right]) => compareStable(left, right))
+			.map(([path, methods]) => [
+				path,
+				Object.fromEntries(
+					Object.entries(methods).sort(([left], [right]) =>
+						compareStable(left, right),
+					),
+				),
+			]),
+	);
+
 	return {
 		openapi: "3.1.0",
 		info: {
@@ -414,7 +455,7 @@ export function generateOpenAPISchema(
 			},
 		],
 		tags,
-		paths,
+		paths: deterministicPaths,
 		components: {
 			securitySchemes: {
 				bearerAuth: {