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

package/src/authorization/json.ts

@@ -0,0 +1,70 @@
+export function assertJsonSafe(
+	value: unknown,
+	ancestors = new Set<object>(),
+): void {
+	if (
+		value === null ||
+		typeof value === "string" ||
+		typeof value === "boolean"
+	) {
+		return;
+	}
+	if (typeof value === "number") {
+		if (Number.isFinite(value)) return;
+		throw new TypeError("Authorization values must be finite numbers.");
+	}
+	if (typeof value !== "object") {
+		throw new TypeError("Authorization values must be JSON-safe.");
+	}
+	if (ancestors.has(value)) {
+		throw new TypeError("Authorization values cannot contain cycles.");
+	}
+	ancestors.add(value);
+	try {
+		if (Array.isArray(value)) {
+			for (let index = 0; index < value.length; index += 1) {
+				if (!(index in value)) {
+					throw new TypeError(
+						"Authorization arrays cannot contain empty slots.",
+					);
+				}
+				assertJsonSafe(value[index], ancestors);
+			}
+			for (const key of Reflect.ownKeys(value)) {
+				if (
+					key !== "length" &&
+					(typeof key !== "string" ||
+						!/^0$|^[1-9]\d*$/.test(key) ||
+						Number(key) >= value.length)
+				) {
+					throw new TypeError(
+						"Authorization arrays cannot contain extra properties.",
+					);
+				}
+			}
+			return;
+		}
+
+		const prototype = Object.getPrototypeOf(value);
+		if (prototype !== Object.prototype && prototype !== null) {
+			throw new TypeError(
+				"Authorization values must contain only plain objects.",
+			);
+		}
+		for (const key of Reflect.ownKeys(value)) {
+			const descriptor = Object.getOwnPropertyDescriptor(value, key);
+			if (
+				typeof key !== "string" ||
+				!descriptor?.enumerable ||
+				!("value" in descriptor)
+			) {
+				throw new TypeError(
+					"Authorization object properties must be JSON-safe.",
+				);
+			}
+			assertJsonSafe(descriptor.value, ancestors);
+		}
+	} finally {
+		ancestors.delete(value);
+	}
+}

package/src/authorization/remote.ts

@@ -0,0 +1,234 @@
+import { z } from "zod";
+import type {
+	AnyAuthorizationContract,
+	AuthorizationContractIdentity,
+	AuthorizationContractPermissionRequest,
+	PermissionRequest,
+} from ".";
+import type { MaybePromise } from "../shared/types";
+import { assertJsonSafe } from "./json";
+
+type WirePermission<TPermission> = TPermission extends PermissionRequest<
+	infer TId,
+	infer TSchema
+>
+	? TSchema extends z.ZodType<any, any>
+		? { readonly id: TId; readonly facts: z.output<TSchema> }
+		: { readonly id: TId }
+	: never;
+
+/** JSON-safe request sent to a managed authorization backend. */
+export interface RemoteAuthorizationRequest<
+	TContract extends AnyAuthorizationContract,
+> {
+	readonly version: string;
+	readonly permission: WirePermission<
+		AuthorizationContractPermissionRequest<TContract>
+	>;
+}
+
+/** Response returned by a managed authorization backend. */
+export interface RemoteAuthorizationResponse {
+	readonly version: string;
+	readonly allowed: boolean;
+}
+
+/** One permission evaluation against either local or remote policy. */
+export interface AuthorizationEvaluation<
+	TIdentity extends { id: string },
+	TPermission,
+> {
+	readonly identity: TIdentity | null;
+	readonly permission: TPermission;
+}
+
+/** Evaluation seam consumed by the bound client authorization hooks. */
+export interface AuthorizationEvaluator<
+	TIdentity extends { id: string } = { id: string },
+	TPermission = unknown,
+> {
+	readonly contract: AnyAuthorizationContract;
+	evaluate(
+		input: AuthorizationEvaluation<TIdentity, TPermission>,
+	): MaybePromise<boolean>;
+}
+
+/** Evaluator type inferred from one portable contract. */
+export type AuthorizationEvaluatorFor<
+	TContract extends AnyAuthorizationContract,
+> = AuthorizationEvaluator<
+	AuthorizationContractIdentity<TContract>,
+	AuthorizationContractPermissionRequest<TContract>
+> & { readonly contract: TContract };
+
+/** Typed transport boundary for a managed authorization backend. */
+export type RemoteAuthorizationTransport<
+	TContract extends AnyAuthorizationContract,
+> = (request: RemoteAuthorizationRequest<TContract>) => MaybePromise<unknown>;
+
+/** A frontend/backend contract version mismatch. This is never a denial. */
+export class AuthorizationContractMismatchError extends Error {
+	readonly code = "AUTHORIZATION_CONTRACT_MISMATCH" as const;
+
+	constructor(
+		readonly expectedVersion: string,
+		readonly receivedVersion: string,
+	) {
+		super(
+			`Authorization contract mismatch: expected "${expectedVersion}", received "${receivedVersion}".`,
+		);
+		this.name = "AuthorizationContractMismatchError";
+	}
+}
+
+/** A malformed request received by a managed authorization backend. */
+export class AuthorizationRequestValidationError extends Error {
+	readonly code = "INVALID_AUTHORIZATION_REQUEST" as const;
+
+	constructor(cause: unknown) {
+		super("Invalid remote authorization request.", { cause });
+		this.name = "AuthorizationRequestValidationError";
+	}
+}
+
+/** A malformed response received from a managed authorization backend. */
+export class AuthorizationResponseValidationError extends Error {
+	readonly code = "INVALID_AUTHORIZATION_RESPONSE" as const;
+
+	constructor(cause: unknown) {
+		super("Invalid remote authorization response.", { cause });
+		this.name = "AuthorizationResponseValidationError";
+	}
+}
+
+const remoteRequestSchema = z
+	.object({
+		version: z.string(),
+		permission: z
+			.object({
+				id: z.string(),
+				facts: z.unknown().optional(),
+			})
+			.strict(),
+	})
+	.strict();
+
+const remoteResponseSchema = z
+	.object({
+		version: z.string(),
+		allowed: z.boolean(),
+	})
+	.strict();
+
+/**
+ * Validate a wire request before an authoritative managed backend evaluates
+ * it. The returned permission is rebuilt from the contract's runtime schema.
+ */
+export function parseRemoteAuthorizationRequest<
+	TContract extends AnyAuthorizationContract,
+>(
+	contract: TContract,
+	input: unknown,
+): {
+	readonly version: string;
+	readonly permission: AuthorizationContractPermissionRequest<TContract>;
+} {
+	try {
+		assertJsonSafe(input);
+	} catch (error) {
+		throw new AuthorizationRequestValidationError(error);
+	}
+	const parsed = remoteRequestSchema.safeParse(input);
+	if (!parsed.success) {
+		throw new AuthorizationRequestValidationError(parsed.error);
+	}
+	if (parsed.data.version !== contract.version) {
+		throw new AuthorizationContractMismatchError(
+			contract.version,
+			parsed.data.version,
+		);
+	}
+	try {
+		const runtimeContract = contract as unknown as {
+			parsePermission: (value: unknown) => unknown;
+		};
+		return {
+			version: parsed.data.version,
+			permission: runtimeContract.parsePermission(
+				parsed.data.permission,
+			) as AuthorizationContractPermissionRequest<TContract>,
+		};
+	} catch (error) {
+		throw new AuthorizationRequestValidationError(error);
+	}
+}
+
+/**
+ * Create an asynchronous evaluator for a managed backend. The transport owns
+ * authentication (for example, credentials on `fetch`) and does not receive
+ * the browser's identity as authoritative input.
+ */
+export function createRemoteAuthorizationEvaluator<
+	TContract extends AnyAuthorizationContract,
+>(config: {
+	contract: TContract;
+	transport: RemoteAuthorizationTransport<TContract>;
+}): AuthorizationEvaluatorFor<TContract> {
+	const runtimeContract = config.contract as unknown as {
+		parsePermission: (value: unknown) => {
+			id: string;
+			facts: unknown;
+			permission: { schema: unknown };
+		};
+	};
+	const transport = config.transport as (request: {
+		version: string;
+		permission: { id: string; facts?: unknown };
+	}) => MaybePromise<unknown>;
+	const evaluator = Object.freeze({
+		contract: config.contract,
+		async evaluate(input: { permission: unknown }) {
+			let parsedPermission: {
+				id: string;
+				facts: unknown;
+				permission: { schema: unknown };
+			};
+			try {
+				parsedPermission = runtimeContract.parsePermission(input.permission);
+			} catch (error) {
+				throw new AuthorizationRequestValidationError(error);
+			}
+
+			const wirePermission =
+				parsedPermission.permission.schema === undefined
+					? { id: parsedPermission.id }
+					: { id: parsedPermission.id, facts: parsedPermission.facts };
+			try {
+				assertJsonSafe(wirePermission);
+			} catch (error) {
+				throw new AuthorizationRequestValidationError(error);
+			}
+			const response = await transport({
+				version: config.contract.version,
+				permission: wirePermission,
+			});
+			try {
+				assertJsonSafe(response);
+			} catch (error) {
+				throw new AuthorizationResponseValidationError(error);
+			}
+			const parsedResponse = remoteResponseSchema.safeParse(response);
+			if (!parsedResponse.success) {
+				throw new AuthorizationResponseValidationError(parsedResponse.error);
+			}
+			if (parsedResponse.data.version !== config.contract.version) {
+				throw new AuthorizationContractMismatchError(
+					config.contract.version,
+					parsedResponse.data.version,
+				);
+			}
+			return parsedResponse.data.allowed;
+		},
+	});
+	return evaluator as unknown as AuthorizationEvaluatorFor<TContract>;
+}

package/src/authorization/server.ts

@@ -0,0 +1,171 @@
+import {
+	type AnyAuthorization,
+	type AuthorizationIdentity,
+	type AuthorizationIdentityInput,
+	type AuthorizationPermissionRequest,
+} from ".";
+import type { StackIdentity } from "../shared/auth-types";
+import type { MaybePromise } from "../shared/types";
+
+/** An ordinary authorization denial with its corresponding HTTP status. */
+export class AuthorizationError extends Error {
+	readonly statusCode: 401 | 403;
+	readonly code: "UNAUTHORIZED" | "FORBIDDEN";
+
+	constructor(statusCode: 401 | 403, message?: string) {
+		super(
+			message ??
+				(statusCode === 401 ? "Authentication required" : "Access denied"),
+		);
+		this.name = "AuthorizationError";
+		this.statusCode = statusCode;
+		this.code = statusCode === 401 ? "UNAUTHORIZED" : "FORBIDDEN";
+	}
+}
+
+/** Server identity adapter bound to one authorization contract. */
+export interface ServerAuth<TAuthorization extends AnyAuthorization> {
+	readonly mode: "one-rule";
+	readonly authorization: TAuthorization;
+	readonly contract: TAuthorization["contract"];
+	getIdentity(
+		request: Request,
+	): Promise<AuthorizationIdentity<TAuthorization> | null>;
+	getIdentity(ctx: {
+		request: Request;
+		headers: Headers;
+	}): Promise<AuthorizationIdentity<TAuthorization> | null>;
+	authorize(
+		request: Request,
+		permission: AuthorizationPermissionRequest<TAuthorization>,
+	): Promise<AuthorizationIdentity<TAuthorization> | null>;
+}
+
+/** A server adapter that can also resolve identity from framework headers alone. */
+export type HeaderServerAuth<TAuthorization extends AnyAuthorization> =
+	ServerAuth<TAuthorization> & {
+		getIdentityFromHeaders(ctx: {
+			headers: Headers;
+		}): Promise<AuthorizationIdentity<TAuthorization> | null>;
+	};
+
+interface RequestServerAuthConfig<TAuthorization extends AnyAuthorization> {
+	authorization: TAuthorization;
+	getIdentity: (ctx: {
+		request: Request;
+		headers: Headers;
+	}) => MaybePromise<AuthorizationIdentityInput<
+		NoInfer<TAuthorization>
+	> | null>;
+	getIdentityFromHeaders?: never;
+}
+
+interface HeaderServerAuthConfig<TAuthorization extends AnyAuthorization> {
+	authorization: TAuthorization;
+	getIdentity?: never;
+	getIdentityFromHeaders: (ctx: {
+		headers: Headers;
+	}) => MaybePromise<AuthorizationIdentityInput<
+		NoInfer<TAuthorization>
+	> | null>;
+}
+
+/** True for the typed server adapter introduced by the one-rule auth path. */
+export function isServerAuth(
+	value: unknown,
+): value is ServerAuth<AnyAuthorization> {
+	return (
+		typeof value === "object" &&
+		value !== null &&
+		(value as { mode?: string }).mode === "one-rule" &&
+		typeof (value as { authorize?: unknown }).authorize === "function"
+	);
+}
+
+/** Bind server identity resolution to the same authorization contract as the browser. */
+export function createServerAuth<TAuthorization extends AnyAuthorization>(
+	config: HeaderServerAuthConfig<TAuthorization>,
+): HeaderServerAuth<TAuthorization>;
+export function createServerAuth<TAuthorization extends AnyAuthorization>(
+	config: RequestServerAuthConfig<TAuthorization>,
+): ServerAuth<TAuthorization>;
+export function createServerAuth<TAuthorization extends AnyAuthorization>(
+	config:
+		| HeaderServerAuthConfig<TAuthorization>
+		| RequestServerAuthConfig<TAuthorization>,
+): HeaderServerAuth<TAuthorization> {
+	const identities = new WeakMap<
+		object,
+		Promise<AuthorizationIdentity<TAuthorization> | null>
+	>();
+	const runtimeAuthorization = config.authorization as unknown as {
+		can: (permission: unknown, identity: unknown) => boolean;
+		parseIdentity: (identity: unknown) => StackIdentity | null;
+	};
+
+	const resolveIdentityContext = (input: {
+		request?: Request;
+		headers: Headers;
+	}): Promise<AuthorizationIdentity<TAuthorization> | null> => {
+		const headers = input.headers;
+		const request = input.request;
+		const cacheKey = request ?? headers;
+		let pending = identities.get(cacheKey);
+		if (!pending) {
+			pending = Promise.resolve()
+				.then(() => {
+					if (config.getIdentityFromHeaders) {
+						return config.getIdentityFromHeaders({ headers });
+					}
+					if (!request) {
+						throw new TypeError(
+							"Header-only identity resolution requires createServerAuth({ getIdentityFromHeaders }).",
+						);
+					}
+					return config.getIdentity({ headers, request });
+				})
+				.then(
+					(identity) =>
+						runtimeAuthorization.parseIdentity(
+							identity,
+						) as AuthorizationIdentity<TAuthorization> | null,
+				);
+			identities.set(cacheKey, pending);
+		}
+		return pending;
+	};
+	const resolveIdentity = (
+		input: Request | { request: Request; headers: Headers },
+	) =>
+		resolveIdentityContext(
+			input instanceof Request
+				? { headers: input.headers, request: input }
+				: input,
+		);
+	const resolveIdentityFromHeaders = (input: { headers: Headers }) => {
+		if (!config.getIdentityFromHeaders) {
+			throw new TypeError(
+				"Header-only identity resolution requires createServerAuth({ getIdentityFromHeaders }).",
+			);
+		}
+		return resolveIdentityContext(input);
+	};
+
+	const serverAuth = {
+		mode: "one-rule",
+		authorization: config.authorization,
+		contract: config.authorization.contract,
+		getIdentity: resolveIdentity,
+		getIdentityFromHeaders: resolveIdentityFromHeaders,
+		async authorize(request: Request, permissionRequest: unknown) {
+			const identity = await resolveIdentity(request);
+			const allowed = runtimeAuthorization.can(permissionRequest, identity);
+			if (!allowed) {
+				throw new AuthorizationError(identity === null ? 401 : 403);
+			}
+			return identity;
+		},
+	};
+
+	return serverAuth as unknown as HeaderServerAuth<TAuthorization>;
+}

package/src/client/__tests__/server-origin.test.ts

@@ -0,0 +1,119 @@
+import { describe, expect, it } from "vitest";
+import {
+	filterCredentialForwardingHeaders,
+	resolveTrustedClientOrigins,
+	resolveTrustedServerOrigin,
+} from "../server";
+
+describe("resolveTrustedServerOrigin", () => {
+	it("uses the configured origin even when an inbound Host-derived origin differs", () => {
+		expect(
+			resolveTrustedServerOrigin({
+				configuredOrigin: "https://api.example.com/",
+				requestOrigin: "https://credentials.example.net",
+				isProduction: true,
+				label: "BTST_API_URL or BASE_URL",
+			}),
+		).toBe("https://api.example.com");
+	});
+
+	it("fails closed when production has no configured origin", () => {
+		expect(() =>
+			resolveTrustedServerOrigin({
+				requestOrigin: "https://app.example.com",
+				isProduction: true,
+				label: "BTST_API_URL or BASE_URL",
+			}),
+		).toThrow("BTST_API_URL or BASE_URL must be configured in production");
+	});
+
+	it("allows only loopback request origins without local configuration", () => {
+		expect(
+			resolveTrustedServerOrigin({
+				requestOrigin: "http://127.0.0.1:4173",
+				isProduction: false,
+			}),
+		).toBe("http://127.0.0.1:4173");
+
+		expect(() =>
+			resolveTrustedServerOrigin({
+				requestOrigin: "https://credentials.example.net",
+				isProduction: false,
+			}),
+		).toThrow("limited to loopback development origins");
+	});
+
+	it("rejects configured values that are not origins", () => {
+		expect(() =>
+			resolveTrustedServerOrigin({
+				configuredOrigin: "https://api.example.com/api/data",
+				isProduction: true,
+				label: "BTST_API_URL",
+			}),
+		).toThrow("BTST_API_URL must be an absolute HTTP(S) origin");
+	});
+});
+
+describe("resolveTrustedClientOrigins", () => {
+	it("preserves a managed API origin distinct from the public site", () => {
+		expect(
+			resolveTrustedClientOrigins({
+				configuredApiOrigin: "https://api.managed.example",
+				configuredSiteOrigin: "https://app.example",
+				requestOrigin: "https://host-header.example",
+				isProduction: true,
+			}),
+		).toEqual({
+			apiOrigin: "https://api.managed.example",
+			siteOrigin: "https://app.example",
+		});
+	});
+
+	it("defaults the API to the trusted site origin", () => {
+		expect(
+			resolveTrustedClientOrigins({
+				configuredSiteOrigin: "https://app.example",
+				isProduction: true,
+			}),
+		).toEqual({
+			apiOrigin: "https://app.example",
+			siteOrigin: "https://app.example",
+		});
+	});
+});
+
+describe("filterCredentialForwardingHeaders", () => {
+	it("preserves identity headers but removes routing and hop-by-hop headers", () => {
+		const headers = filterCredentialForwardingHeaders({
+			authorization: "Bearer secret",
+			cookie: "session=secret",
+			connection: "keep-alive, x-remove-me",
+			forwarded: "host=credentials.example.net",
+			host: "credentials.example.net",
+			"proxy-connection": "keep-alive",
+			"x-forwarded-for": "203.0.113.7",
+			"x-forwarded-host": "credentials.example.net",
+			"x-forwarded-proto": "https",
+			"x-real-ip": "203.0.113.7",
+			"x-remove-me": "hop value",
+			"x-request-id": "request-id",
+		});
+
+		expect(headers.get("authorization")).toBe("Bearer secret");
+		expect(headers.get("cookie")).toBe("session=secret");
+		expect(headers.get("x-request-id")).toBe("request-id");
+		for (const name of [
+			"connection",
+			"forwarded",
+			"host",
+			"proxy-connection",
+			"x-forwarded-for",
+			"x-forwarded-host",
+			"x-forwarded-proto",
+			"x-real-ip",
+			"x-remove-me",
+		]) {
+			expect(headers.has(name)).toBe(false);
+		}
+	});
+});