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

package/src/api/index.ts

@@ -1,88 +1,78 @@
 import { createRouter } from "better-call";
 import type {
-	BackendLibConfig,
-	BackendLib,
+	BackendStackConfig,
+	BackendStack,
 	PrefixedPluginRoutes,
-	PluginApis,
+	PluginRaw,
+	PluginOperations,
 	StackContext,
+	BackendPlugin,
+	CompatibleStackAuth,
 } from "../types";
-import type {
-	StackIdentity,
-	StackServerAuthProvider,
-} from "../shared/auth-types";
+import type { AnyAuthorization } from "../authorization";
+import { isServerAuth, type ServerAuth } from "../authorization/server";
 import { defineDb } from "@btst/db";
+import { AuthorizationError } from "../authorization/server";
+import {
+	bindRouteOperationHandler,
+	isOperationInputValidationError,
+	OperationHttpError,
+	runAuthorizedOperation,
+	runTrustedOperation,
+	type AnyOperation,
+	type RouteOperation,
+} from "../plugins/api/operation";
+import {
+	composeEndpointInventory,
+	type ComposedEndpointInventoryEntry,
+} from "../plugins/api/endpoint-inventory";
+import { serializeValidationIssues } from "../plugins/api/create-endpoint";
+import { resolvePluginRegistrationIds } from "../plugin-registration";
 
 export { toNodeHandler } from "better-call/node";
 
-/**
- * Lazy, memoized identity resolvers keyed by the request's `Headers`
- * instance. better-call passes the same `Headers` object from the incoming
- * `Request` into every endpoint context, so lifecycle hooks can look the
- * identity up via `getRequestIdentity(ctx.headers)`. Entries are
- * garbage-collected with the request.
- */
-const identityResolvers = new WeakMap<
-	Headers,
-	() => Promise<StackIdentity | null>
->();
-
-function registerIdentityResolver(
-	request: Request,
-	auth: StackServerAuthProvider,
-): void {
-	let cached: Promise<StackIdentity | null> | undefined;
-	identityResolvers.set(request.headers, () => {
-		// Mirror the client-side StackAuthBoundary: a failing getIdentity is
-		// treated as unauthenticated (null) rather than rejecting, so hooks
-		// written without try/catch can't fail the whole request.
-		cached ??= Promise.resolve()
-			.then(() => auth.getIdentity({ headers: request.headers, request }))
-			.then((identity) => identity ?? null)
-			.catch((error) => {
-				console.error("[btst/auth] getIdentity() failed:", error);
-				return null;
+function throwHttpOperationError(
+	cause: unknown,
+	error: (...args: any[]) => Error,
+): never {
+	if (isOperationInputValidationError(cause)) {
+		throw error(400, {
+			message: cause.message,
+			code: "VALIDATION_ERROR",
+			issues: serializeValidationIssues(cause.issues),
+		});
+	}
+	if (
+		cause instanceof AuthorizationError ||
+		cause instanceof OperationHttpError
+	) {
+		const candidate = cause;
+		if (
+			typeof candidate.statusCode === "number" &&
+			Number.isInteger(candidate.statusCode) &&
+			candidate.statusCode >= 400 &&
+			candidate.statusCode <= 599 &&
+			typeof candidate.code === "string"
+		) {
+			throw error(candidate.statusCode, {
+				message: candidate.message,
+				code: candidate.code,
+				...(candidate instanceof OperationHttpError &&
+				Array.isArray(candidate.issues)
+					? { issues: candidate.issues }
+					: {}),
 			});
-		return cached;
-	});
-}
-
-/**
- * Returns the identity of the request that carried these headers, as resolved
- * by the `auth` provider configured on `stack()`.
- *
- * The provider's `getIdentity` runs at most once per request (memoized), no
- * matter how many hooks call this. Returns `null` when no auth provider is
- * configured, when called outside a request handled by `stack().handler`, or
- * when the user is unauthenticated.
- *
- * @example
- * ```ts
- * import { getRequestIdentity } from "@btst/stack/api";
- *
- * const blogBackend = blogBackendPlugin({
- *   hooks: {
- *     onBeforeCreatePost: async (data, ctx) => {
- *       const identity = await getRequestIdentity(ctx.headers);
- *       if (!identity) throw new Error("Unauthorized");
- *     },
- *   },
- * });
- * ```
- */
-export async function getRequestIdentity(
-	// Optional because better-call types endpoint `ctx.headers` as optional.
-	headers: Headers | undefined,
-): Promise<StackIdentity | null> {
-	const resolve = headers ? identityResolvers.get(headers) : undefined;
-	return resolve ? resolve() : null;
+		}
+	}
+	throw cause;
 }
 
 /**
- * Creates the backend library with plugin support
+ * Creates the backend stack with plugin support
  *
  * @example
  * ```ts
- * const api = stack({
+ * const api = createBackendStack({
  *   plugins: {
  *     messages: messagesPlugin.backend
  *   },
@@ -97,17 +87,29 @@ export async function getRequestIdentity(
  * @template TPlugins - The exact plugins map (inferred from config)
  * @template TRoutes - All routes with prefixed keys like "pluginName_routeName" (computed automatically)
  */
-export function stack<
-	TPlugins extends Record<string, any>,
+export function createBackendStack<
+	const TPlugins extends Record<string, BackendPlugin<any, any, any>>,
+	const TAuth extends ServerAuth<AnyAuthorization> | undefined,
 	TRoutes extends
 		PrefixedPluginRoutes<TPlugins> = PrefixedPluginRoutes<TPlugins>,
 >(
-	config: BackendLibConfig<TPlugins>,
-): BackendLib<TRoutes, PluginApis<TPlugins>> {
-	const { plugins, adapter, dbSchema, basePath, auth } = config;
+	config: BackendStackConfig<TPlugins, TAuth> & {
+		auth?: CompatibleStackAuth<TPlugins, TAuth>;
+	},
+): BackendStack<TRoutes, PluginRaw<TPlugins>, PluginOperations<TPlugins>> {
+	const { plugins, adapter, dbSchema, basePath } = config;
+	const registrationIds = resolvePluginRegistrationIds(plugins, "backend");
+	const runtimeAuth = (
+		config as unknown as { auth?: ServerAuth<AnyAuthorization> }
+	).auth;
+	if (runtimeAuth && !isServerAuth(runtimeAuth)) {
+		throw new TypeError(
+			"createBackendStack({ auth }) requires an adapter created by createServerAuth().",
+		);
+	}
 
 	// Collect all routes from all plugins with type-safe prefixed keys
-	const allRoutes = {} as TRoutes;
+	const allRoutes = Object.create(null) as TRoutes;
 
 	let betterDbSchema = dbSchema ?? defineDb({});
 
@@ -119,67 +121,170 @@ export function stack<
 	// Create the adapter instance once
 	const adapterInstance = adapter(betterDbSchema);
 
+	// Keep the constructed route maps on the shared context so introspection
+	// plugins inspect the real routes instead of invoking factories a second time.
+	const pluginRoutesByName: Record<string, Record<string, any>> = Object.create(
+		null,
+	);
+
 	// Create context for plugins that need access to all plugins (e.g., openAPI)
+	const pluginOperations: Record<string, Record<string, any>> = Object.create(
+		null,
+	);
+	const endpointInventory: ComposedEndpointInventoryEntry[] = [];
 	const context: StackContext = {
 		plugins,
 		basePath,
 		adapter: adapterInstance,
-		auth,
+		auth: runtimeAuth,
+		pluginRoutes: pluginRoutesByName,
 	};
 
+	for (const [pluginKey, plugin] of Object.entries(plugins)) {
+		if (plugin.operations) {
+			pluginOperations[pluginKey] = plugin.operations(adapterInstance, context);
+		}
+	}
+
+	const routeOperationApis: Record<
+		string,
+		Record<string, RouteOperation<AnyOperation>>
+	> = Object.create(null);
+	for (const [pluginKey, operations] of Object.entries(pluginOperations)) {
+		routeOperationApis[pluginKey] = Object.create(null);
+		for (const [operationKey, operation] of Object.entries(operations)) {
+			const invoke = (input: unknown, request: Request) =>
+				runAuthorizedOperation(operation, input, {
+					request,
+					...(runtimeAuth ? { auth: runtimeAuth } : {}),
+				});
+			Object.defineProperty(invoke, "route", {
+				value: (resolveInput: (context: any) => unknown) => {
+					const handler = async (context: {
+						request: Request;
+						error: (...args: any[]) => Error;
+					}) => {
+						try {
+							const input = await resolveInput(context);
+							return await invoke(input, context.request);
+						} catch (cause) {
+							throwHttpOperationError(cause, context.error);
+						}
+					};
+					return bindRouteOperationHandler(handler, {
+						pluginKey,
+						operationKey,
+						operation,
+					});
+				},
+			});
+			routeOperationApis[pluginKey]![operationKey] =
+				invoke as RouteOperation<AnyOperation>;
+		}
+	}
+
 	for (const [pluginKey, plugin] of Object.entries(plugins)) {
 		// Pass both adapter and context to plugin routes
-		const pluginRoutes = plugin.routes(adapterInstance, context);
+		const pluginRoutes = plugin.routes(
+			adapterInstance,
+			context,
+			routeOperationApis[pluginKey] ?? Object.create(null),
+		);
+		pluginRoutesByName[pluginKey] = pluginRoutes;
+		endpointInventory.push(
+			...composeEndpointInventory(
+				pluginKey,
+				registrationIds[pluginKey]!,
+				pluginRoutes,
+				pluginOperations[pluginKey] ?? Object.create(null),
+				plugin.operations !== undefined || runtimeAuth !== undefined,
+				plugin.infrastructureRoutes,
+				plugin.operationRouteMap,
+			),
+		);
 
-		// Prefix route keys with plugin name to avoid collisions
+		// Prefix route keys with the canonical plugin ID to avoid collisions
 		for (const [routeKey, endpoint] of Object.entries(pluginRoutes)) {
 			const compositeKey = `${pluginKey}_${routeKey}` as keyof TRoutes;
 			(allRoutes as any)[compositeKey] = endpoint;
 		}
 	}
+	Object.defineProperty(context, "endpointInventory", {
+		value: Object.freeze(endpointInventory),
+		enumerable: true,
+	});
 
-	// Build the typed api surface by calling each plugin's api factory
-	const pluginApis = {} as PluginApis<TPlugins>;
+	// Build the typed raw surface by calling each plugin's lower-level factory.
+	const pluginRaw = Object.create(null) as PluginRaw<TPlugins>;
 	for (const [pluginKey, plugin] of Object.entries(plugins)) {
-		if (plugin.api) {
-			(pluginApis as any)[pluginKey] = plugin.api(adapterInstance);
+		if (plugin.raw) {
+			(pluginRaw as any)[pluginKey] = plugin.raw(adapterInstance);
 		}
 	}
 
 	// Create the composed router
 	const router = createRouter(allRoutes, {
 		basePath: basePath,
+		openapi: { disabled: true },
 	});
 
-	// With an auth provider, register a per-request identity resolver before
-	// dispatch so hooks can call getRequestIdentity(ctx.headers). Without one,
-	// the handler is returned untouched.
-	const handler = auth
-		? (request: Request) => {
-				registerIdentityResolver(request, auth);
-				return router.handler(request);
+	const handler = router.handler;
+
+	const createRequestOperationApi = (request: Request) => {
+		const result: Record<
+			string,
+			Record<string, (input: unknown) => unknown>
+		> = Object.create(null);
+		for (const [pluginKey, operations] of Object.entries(pluginOperations)) {
+			result[pluginKey] = Object.create(null);
+			for (const [operationKey, operation] of Object.entries(operations)) {
+				result[pluginKey]![operationKey] = (input: unknown) =>
+					runAuthorizedOperation(operation, input, {
+						request,
+						...(runtimeAuth ? { auth: runtimeAuth } : {}),
+					});
 			}
-		: router.handler;
+		}
+		return result;
+	};
+
+	const trustedResult: Record<
+		string,
+		Record<string, (input: unknown) => unknown>
+	> = Object.create(null);
+	for (const [pluginKey, operations] of Object.entries(pluginOperations)) {
+		trustedResult[pluginKey] = Object.create(null);
+		for (const [operationKey, operation] of Object.entries(operations)) {
+			trustedResult[pluginKey]![operationKey] = (input: unknown) =>
+				runTrustedOperation(operation, input);
+		}
+	}
+	const trusted = trustedResult as PluginOperations<TPlugins>;
 
 	return {
 		handler,
 		router,
 		dbSchema: betterDbSchema,
 		adapter: adapterInstance,
-		api: pluginApis,
+		raw: pluginRaw,
+		trusted,
+		forRequest: (request: Request) => {
+			return {
+				operations: createRequestOperationApi(
+					request,
+				) as PluginOperations<TPlugins>,
+			};
+		},
 	};
 }
 
 export type {
 	BackendPlugin,
-	BackendLibConfig,
-	BackendLib,
-	PluginApis,
+	BackendStackConfig,
+	BackendStack,
+	PluginRaw,
+	PluginOperations,
 	StackContext,
 } from "../types";
 
-export type {
-	CanParams,
-	StackIdentity,
-	StackServerAuthProvider,
-} from "../shared/auth-types";
+export type { StackIdentity } from "../shared/auth-types";

package/src/authorization/client.tsx

@@ -0,0 +1,310 @@
+"use client";
+
+import { useEffect, useRef, useState, type ReactNode } from "react";
+import {
+	type AuthorizationIdentity,
+	type AuthorizationIdentityInput,
+	type AuthorizationPermissionRequest,
+	type AuthorizationContractIdentity,
+	type AuthorizationContractIdentityInput,
+	type AuthorizationContractPermissionRequest,
+	type AnyAuthorization,
+	type AnyAuthorizationContract,
+} from ".";
+import {
+	AuthorizationRequestValidationError,
+	type AuthorizationEvaluatorFor,
+} from "./remote";
+import { assertJsonSafe } from "./json";
+import {
+	useAuthContext,
+	useIdentity as useStackIdentity,
+} from "../context/auth";
+import type { StackClientAuth } from "../shared/auth-types";
+import type { MaybePromise } from "../shared/types";
+
+/** Result returned by a bound browser permission check. */
+export interface AuthorizationCanState {
+	can: boolean;
+	isPending: boolean;
+	error?: Error;
+}
+
+/** Validated identity state returned by the bound browser identity hook. */
+export interface AuthorizationIdentityState<TIdentity> {
+	identity: TIdentity | null;
+	isPending: boolean;
+	error?: Error;
+	refetch: () => Promise<void>;
+}
+
+/** Browser identity adapter and hooks bound to synchronous local rules. */
+export interface ClientAuth<TAuthorization extends AnyAuthorization>
+	extends StackClientAuth {
+	readonly mode: "one-rule";
+	readonly authorization: TAuthorization;
+	readonly contract: TAuthorization["contract"];
+	getIdentity: () => Promise<AuthorizationIdentity<TAuthorization> | null>;
+	useIdentity: () => AuthorizationIdentityState<
+		AuthorizationIdentity<TAuthorization>
+	>;
+	useCan: (
+		permission: AuthorizationPermissionRequest<TAuthorization>,
+	) => AuthorizationCanState;
+	/** Generic runtime hook used by descriptor-aware built-in plugin UI. */
+	usePermission: (permission: unknown) => AuthorizationCanState;
+	CanAccess: (props: {
+		permission: AuthorizationPermissionRequest<TAuthorization>;
+		fallback?: ReactNode;
+		loading?: ReactNode;
+		children?: ReactNode;
+	}) => ReactNode;
+}
+
+/** Browser identity adapter and hooks bound to an evaluator such as remote auth. */
+export interface EvaluatedClientAuth<
+	TIdentity extends { id: string },
+	TPermission,
+	TContract extends AnyAuthorizationContract = AnyAuthorizationContract,
+> extends StackClientAuth {
+	readonly mode: "one-rule";
+	readonly contract: TContract;
+	getIdentity: () => Promise<TIdentity | null>;
+	useIdentity: () => AuthorizationIdentityState<TIdentity>;
+	useCan: (permission: TPermission) => AuthorizationCanState;
+	/** Generic runtime hook used by descriptor-aware built-in plugin UI. */
+	usePermission: (permission: unknown) => AuthorizationCanState;
+	CanAccess: (props: {
+		permission: TPermission;
+		fallback?: ReactNode;
+		loading?: ReactNode;
+		children?: ReactNode;
+	}) => ReactNode;
+}
+
+function toError(error: unknown): Error {
+	return error instanceof Error ? error : new Error(String(error));
+}
+
+/**
+ * Bind browser identity resolution and type-safe hooks to one authorization
+ * contract. Local rules remain synchronous; remote evaluators resolve within
+ * each mounted hook and are not stored in a reusable authorization cache.
+ */
+type ResolvedEvaluation = {
+	can: boolean;
+	forIdentity: unknown;
+	forPermission: string;
+	error?: Error;
+};
+
+function permissionKey(permission: unknown): string {
+	const request = permission as {
+		id?: unknown;
+		facts?: unknown;
+		permission?: { schema?: unknown };
+	};
+	const wirePermission =
+		request?.permission?.schema === undefined
+			? { id: request?.id }
+			: { id: request.id, facts: request.facts };
+	assertJsonSafe(wirePermission);
+	return JSON.stringify(wirePermission);
+}
+
+export function createClientAuth<
+	TAuthorization extends AnyAuthorization,
+>(config: {
+	authorization: TAuthorization;
+	evaluator?: never;
+	getIdentity: () => MaybePromise<AuthorizationIdentityInput<TAuthorization> | null>;
+	loginPath?: string;
+}): ClientAuth<TAuthorization>;
+export function createClientAuth<
+	TContract extends AnyAuthorizationContract,
+>(config: {
+	authorization?: never;
+	evaluator: AuthorizationEvaluatorFor<TContract>;
+	getIdentity: () => MaybePromise<AuthorizationContractIdentityInput<TContract> | null>;
+	loginPath?: string;
+}): EvaluatedClientAuth<
+	AuthorizationContractIdentity<TContract>,
+	AuthorizationContractPermissionRequest<TContract>,
+	TContract
+>;
+export function createClientAuth(config: any): any {
+	const contractValue =
+		config.authorization?.contract ?? config.evaluator?.contract;
+	if (!contractValue) {
+		throw new TypeError(
+			"createClientAuth requires an authorization or evaluator.",
+		);
+	}
+	const contract = contractValue as unknown as {
+		parseIdentity: (identity: unknown) => { id: string } | null;
+	};
+	const runtimeAuthorization = config.authorization as unknown as
+		| {
+				can: (permission: unknown, identity: unknown) => boolean;
+		  }
+		| undefined;
+	const runtimeEvaluator = config.evaluator as unknown as
+		| {
+				evaluate: (input: {
+					identity: unknown;
+					permission: unknown;
+				}) => MaybePromise<boolean>;
+		  }
+		| undefined;
+	let clientAuth: StackClientAuth;
+
+	const useIdentity = (): AuthorizationIdentityState<{ id: string }> => {
+		const context = useAuthContext();
+		if (context && context.provider !== clientAuth) {
+			throw new Error(
+				"This bound useIdentity hook must be used with its createClientAuth instance on StackProvider.",
+			);
+		}
+		return useStackIdentity() as AuthorizationIdentityState<{ id: string }>;
+	};
+
+	const useCanRuntime = (permissionRequest: unknown): AuthorizationCanState => {
+		const context = useAuthContext();
+		const contextProvider = context?.provider;
+		const contextError = context?.error;
+		const identity = context?.identity ?? null;
+		const identityPending = context?.isPending ?? true;
+		let key = "local";
+		let permissionError: AuthorizationRequestValidationError | undefined;
+		if (runtimeEvaluator) {
+			try {
+				key = permissionKey(permissionRequest);
+			} catch (error) {
+				permissionError = new AuthorizationRequestValidationError(error);
+				key = "invalid-remote-permission";
+			}
+		}
+		const permissionRef = useRef(permissionRequest);
+		permissionRef.current = permissionRequest;
+		const [resolved, setResolved] = useState<ResolvedEvaluation | null>(null);
+
+		useEffect(() => {
+			if (
+				!runtimeEvaluator ||
+				permissionError ||
+				!contextProvider ||
+				contextProvider !== clientAuth ||
+				identityPending ||
+				contextError
+			) {
+				return;
+			}
+
+			let cancelled = false;
+			void (async () => {
+				try {
+					const can = await runtimeEvaluator.evaluate({
+						identity,
+						permission: permissionRef.current,
+					});
+					if (typeof can !== "boolean") {
+						throw new TypeError(
+							"Authorization evaluators must return a boolean.",
+						);
+					}
+					if (!cancelled) {
+						setResolved({
+							can,
+							forIdentity: identity,
+							forPermission: key,
+						});
+					}
+				} catch (error) {
+					if (!cancelled) {
+						setResolved({
+							can: false,
+							forIdentity: identity,
+							forPermission: key,
+							error: toError(error),
+						});
+					}
+				}
+			})();
+
+			return () => {
+				cancelled = true;
+			};
+		}, [contextError, contextProvider, identity, identityPending, key]);
+
+		if (!context || context.provider !== clientAuth) {
+			throw new Error(
+				"This bound useCan hook must be used with its createClientAuth instance on StackProvider.",
+			);
+		}
+		if (context.isPending) return { can: false, isPending: true };
+		if (context.error) {
+			return { can: false, isPending: false, error: context.error };
+		}
+		if (permissionError) {
+			return { can: false, isPending: false, error: permissionError };
+		}
+
+		if (runtimeAuthorization) {
+			try {
+				return {
+					can: runtimeAuthorization.can(permissionRequest, context.identity),
+					isPending: false,
+				};
+			} catch (error) {
+				return { can: false, isPending: false, error: toError(error) };
+			}
+		}
+
+		if (
+			!resolved ||
+			resolved.forIdentity !== identity ||
+			resolved.forPermission !== key
+		) {
+			return { can: false, isPending: true };
+		}
+		return {
+			can: resolved.can,
+			isPending: false,
+			...(resolved.error ? { error: resolved.error } : {}),
+		};
+	};
+
+	const CanAccessRuntime = ({
+		permission: permissionRequest,
+		fallback = null,
+		loading = null,
+		children,
+	}: {
+		permission: unknown;
+		fallback?: ReactNode;
+		loading?: ReactNode;
+		children?: ReactNode;
+	}): ReactNode => {
+		const state = useCanRuntime(permissionRequest);
+		if (state.error) throw state.error;
+		if (state.isPending) return loading;
+		return state.can ? children : fallback;
+	};
+
+	clientAuth = {
+		mode: "one-rule",
+		contract: contractValue,
+		...(config.authorization ? { authorization: config.authorization } : {}),
+		async getIdentity() {
+			const identity = await config.getIdentity();
+			return contract.parseIdentity(identity);
+		},
+		...(config.loginPath ? { loginPath: config.loginPath } : {}),
+		useIdentity,
+		useCan: useCanRuntime,
+		usePermission: useCanRuntime,
+		CanAccess: CanAccessRuntime,
+	} as unknown as StackClientAuth;
+
+	return clientAuth;
+}