@fabrika/app 0.0.1

package/src/index.ts

@@ -0,0 +1,38 @@
+// @fabrika/app — the first-party server framework for Fabrika applications:
+// Fetch-based HTTP routing, typed RPC, middleware, and object-level authorization.
+
+// ─── RPC ─────────────────────────────────────────────────────────────
+export { initRpc } from './rpc/builder.js'
+export type { InferRpcClient, InferRpcContractClient, RpcProcedureContract, RpcRouterFor } from './rpc/contract.js'
+export type { InferRouter, InferRouterClient } from './rpc/types.js'
+
+// ─── Schema contract (validator-agnostic) ────────────────────────────
+export type { StandardSchemaV1 } from './standard-schema.js'
+
+// ─── Routing ─────────────────────────────────────────────────────────
+export { matchRoutes, route } from './router.js'
+export type { HttpMethod, HttpRoute, Route, RouteOptions, RouteParams, RpcRoute } from './router.js'
+
+// ─── Application ─────────────────────────────────────────────────────
+export { defineApp } from './app.js'
+export type { AppConfig, AssetsLike, FabrikaApp, RequestExecutionContext } from './app.js'
+
+// ─── Errors ──────────────────────────────────────────────────────────
+export {
+	BadRequestError,
+	ConflictError,
+	defaultOnError,
+	ForbiddenError,
+	HttpError,
+	NotFoundError,
+	toErrorResponse,
+	UnauthorizedError,
+} from './errors.js'
+
+// ─── Middleware + auth contract ──────────────────────────────────────
+export type { AuthContext, Scope } from '@fabrika/auth'
+export type { Middleware } from './middleware.js'
+
+// ─── Client ──────────────────────────────────────────────────────────
+export { createRpcClient, RpcError, type RpcFetch } from './client.js'
+export type { RpcClientOptions } from './client.js'

package/src/middleware.ts

@@ -0,0 +1,38 @@
+// ─── Middleware ──────────────────────────────────────────────────────
+//
+// @fabrika/auth owns the request-time contracts. The app framework consumes and
+// re-exports them instead of maintaining a structurally duplicated copy.
+
+import type { Middleware } from '@fabrika/auth'
+
+export type { Middleware } from '@fabrika/auth'
+
+/**
+ * A middleware runs in declared order around the inner dispatch. It may mutate
+ * `ctx` (e.g. set `ctx.auth`), short-circuit by returning a `Response` without
+ * calling `next()`, or wrap `next()` (await it, then mutate the `Response`, e.g.
+ * append a `Set-Cookie`).
+ */
+/**
+ * Fold `middleware` (in declared order) around an innermost `dispatch`. Each
+ * middleware receives a `next` that advances to the following one; the last
+ * `next` calls `dispatch`.
+ */
+export function runChain<Ctx>(
+	request: Request,
+	ctx: Ctx,
+	middleware: ReadonlyArray<Middleware<Ctx>>,
+	dispatch: () => Promise<Response>,
+): Promise<Response> {
+	let lastIndex = -1
+	const run = (index: number): Promise<Response> => {
+		if (index <= lastIndex) {
+			return Promise.reject(new Error('next() called multiple times in a single middleware'))
+		}
+		lastIndex = index
+		const current = middleware[index]
+		if (!current) return dispatch()
+		return current(request, ctx, () => run(index + 1))
+	}
+	return run(0)
+}

package/src/router.ts

@@ -0,0 +1,149 @@
+// ─── HTTP routing ────────────────────────────────────────────────────
+//
+// A tiny method-aware path router. HTTP routes carry a `(ctx, params) => Response`
+// handler; RPC routes carry a `Router`. Params are inferred from the pattern
+// string literal: `/api/:project/envelope` → `{ project: string }`.
+
+import type { Middleware } from './middleware.js'
+import type { AnyRouter } from './rpc/types.js'
+
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
+
+/** Per-route options. `use` middleware run AFTER the global chain, scoped to this route only. */
+export interface RouteOptions<Ctx> {
+	readonly use?: ReadonlyArray<Middleware<Ctx>>
+}
+
+/** Extract `:param` and terminal `*rest` names from a pattern literal. */
+export type RouteParams<Pattern extends string> = Pattern extends `${infer _Head}:${infer Param}/${infer Rest}`
+	? Record<Param, string> & RouteParams<Rest>
+	: Pattern extends `${infer _Head}:${infer Param}` ? Record<Param, string>
+	: Pattern extends `${infer _Head}*${infer Rest}` ? Rest extends '' ? {} : Record<Rest, string>
+	: {}
+
+export type HttpHandler<Ctx, Pattern extends string> = (ctx: Ctx, params: RouteParams<Pattern>) => Response | Promise<Response>
+
+export interface HttpRoute<Ctx, Pattern extends string = string> {
+	readonly kind: 'http'
+	/** `null` matches every method and is intended for mounting an existing Fetch handler. */
+	readonly method: HttpMethod | null
+	readonly pattern: Pattern
+	readonly segments: ReadonlyArray<string>
+	readonly use: ReadonlyArray<Middleware<Ctx>>
+	handler(ctx: Ctx, params: RouteParams<Pattern>): Response | Promise<Response>
+}
+
+export interface RpcRoute<Ctx> {
+	readonly kind: 'rpc'
+	readonly pattern: string
+	readonly segments: ReadonlyArray<string>
+	readonly use: ReadonlyArray<Middleware<Ctx>>
+	readonly router: AnyRouter
+}
+
+export type Route<Ctx> = HttpRoute<Ctx, string> | RpcRoute<Ctx>
+
+function splitPath(path: string): string[] {
+	return path.split('/').filter((segment) => segment.length > 0)
+}
+
+function decodePathSegment(segment: string): string | null {
+	try {
+		return decodeURIComponent(segment)
+	} catch {
+		return null
+	}
+}
+
+function makeHttpRoute<Ctx, Pattern extends string>(
+	method: HttpMethod | null,
+	pattern: Pattern,
+	handler: HttpHandler<Ctx, Pattern>,
+	opts: RouteOptions<Ctx> | undefined,
+): HttpRoute<Ctx, Pattern> {
+	const segments = splitPath(pattern)
+	const wildcard = segments.findIndex((segment) => segment.startsWith('*'))
+	if (wildcard !== -1 && wildcard !== segments.length - 1) {
+		throw new Error('a wildcard route segment must be terminal')
+	}
+	return { kind: 'http', method, pattern, segments, use: opts?.use ?? [], handler }
+}
+
+/**
+ * Route builders. HTTP verbs take `(pattern, handler, opts?)`; `rpc` mounts a
+ * `Router` at a path. Annotate the handler's `ctx` (or place the route in a
+ * `Route<Ctx>[]`) to type the context. `opts.use` adds route-scoped middleware
+ * (run after the global chain) — e.g. a capability/api-key gate on one path group.
+ */
+export const route = {
+	all<Ctx, Pattern extends string>(pattern: Pattern, handler: HttpHandler<Ctx, Pattern>, opts?: RouteOptions<Ctx>): HttpRoute<Ctx, Pattern> {
+		return makeHttpRoute(null, pattern, handler, opts)
+	},
+	get<Ctx, Pattern extends string>(pattern: Pattern, handler: HttpHandler<Ctx, Pattern>, opts?: RouteOptions<Ctx>): HttpRoute<Ctx, Pattern> {
+		return makeHttpRoute('GET', pattern, handler, opts)
+	},
+	post<Ctx, Pattern extends string>(pattern: Pattern, handler: HttpHandler<Ctx, Pattern>, opts?: RouteOptions<Ctx>): HttpRoute<Ctx, Pattern> {
+		return makeHttpRoute('POST', pattern, handler, opts)
+	},
+	put<Ctx, Pattern extends string>(pattern: Pattern, handler: HttpHandler<Ctx, Pattern>, opts?: RouteOptions<Ctx>): HttpRoute<Ctx, Pattern> {
+		return makeHttpRoute('PUT', pattern, handler, opts)
+	},
+	patch<Ctx, Pattern extends string>(pattern: Pattern, handler: HttpHandler<Ctx, Pattern>, opts?: RouteOptions<Ctx>): HttpRoute<Ctx, Pattern> {
+		return makeHttpRoute('PATCH', pattern, handler, opts)
+	},
+	delete<Ctx, Pattern extends string>(pattern: Pattern, handler: HttpHandler<Ctx, Pattern>, opts?: RouteOptions<Ctx>): HttpRoute<Ctx, Pattern> {
+		return makeHttpRoute('DELETE', pattern, handler, opts)
+	},
+	rpc<Ctx>(path: string, router: AnyRouter, opts?: RouteOptions<Ctx>): RpcRoute<Ctx> {
+		return { kind: 'rpc', pattern: path, segments: splitPath(path), use: opts?.use ?? [], router }
+	},
+}
+
+function matchSegments(routeSegments: ReadonlyArray<string>, pathSegments: ReadonlyArray<string>): Record<string, string> | null {
+	const params: Record<string, string> = {}
+	for (let i = 0; i < routeSegments.length; i++) {
+		const routeSegment = routeSegments[i]
+		if (routeSegment === undefined) return null
+		if (routeSegment.startsWith('*')) {
+			const name = routeSegment.slice(1)
+			if (name !== '') {
+				const decoded: string[] = []
+				for (const segment of pathSegments.slice(i)) {
+					const value = decodePathSegment(segment)
+					if (value === null) return null
+					decoded.push(value)
+				}
+				params[name] = decoded.join('/')
+			}
+			return params
+		}
+		const pathSegment = pathSegments[i]
+		if (pathSegment === undefined) return null
+		if (routeSegment.startsWith(':')) {
+			const value = decodePathSegment(pathSegment)
+			if (value === null) return null
+			params[routeSegment.slice(1)] = value
+		} else if (routeSegment !== pathSegment) {
+			return null
+		}
+	}
+	return routeSegments.length === pathSegments.length ? params : null
+}
+
+/** Find the first route matching the request's method + path. RPC routes match POST. */
+export function matchRoutes<Ctx>(
+	routes: ReadonlyArray<Route<Ctx>>,
+	request: Request,
+): { route: Route<Ctx>; params: Record<string, string> } | null {
+	const pathSegments = splitPath(new URL(request.url).pathname)
+	for (const candidate of routes) {
+		if (candidate.kind === 'rpc') {
+			if (request.method !== 'POST') continue
+		} else if (candidate.method !== null && request.method !== candidate.method) {
+			continue
+		}
+		const params = matchSegments(candidate.segments, pathSegments)
+		if (params) return { route: candidate, params }
+	}
+	return null
+}

package/src/rpc/builder.ts

@@ -0,0 +1,128 @@
+// ─── RPC builder ─────────────────────────────────────────────────────
+//
+// `initRpc<Ctx>()` returns a `procedure` builder bound to the context type plus a
+// `router` factory. Builders are immutable — each step returns a fresh builder.
+//
+// Two builder shapes keep the output type honest WITHOUT any cast:
+//   - ProcedureBuilder (no output schema): the terminal infers the output type
+//     from the handler's return — `t.procedure.input(X).query(() => ({ a: 1 }))`
+//     gives the client `{ a: number }`, tRPC-style, no `.output()` needed.
+//   - OutputProcedureBuilder (after `.output(schema)`): the terminal FIXES the
+//     output to the schema type and validates the handler result at runtime.
+
+import type { AuthContext, Scope } from '@fabrika/auth'
+import type { StandardSchemaV1 } from '../standard-schema.js'
+import type { AuthRequirement, Procedure, ProcedureKind, Router, RouterDef } from './types.js'
+
+// The implicit input schema for a procedure with no `.input()` — accepts only "no input".
+const voidSchema: StandardSchemaV1<unknown, void> = {
+	'~standard': {
+		version: 1,
+		vendor: 'fabrika',
+		validate: (input) => (input === undefined || input === null ? { value: undefined } : { issues: [{ message: 'Expected no input' }] }),
+	},
+}
+
+type Handler<TContext, TInput, TOutput> = (args: { ctx: TContext; input: TInput }) => TOutput | Promise<TOutput>
+
+function makeProcedure<TContext, TInput, TOutput>(
+	kind: ProcedureKind,
+	input: StandardSchemaV1<unknown, TInput>,
+	output: StandardSchemaV1<unknown, TOutput> | null,
+	requirements: ReadonlyArray<AuthRequirement<TContext, TInput>>,
+	handler: Handler<TContext, TInput, TOutput>,
+): Procedure<TContext, TInput, TOutput> {
+	return { _tag: 'procedure', kind, input, output, requirements, handler }
+}
+
+/** Builder before an output schema is set — the terminal infers the output type from the handler. */
+export class ProcedureBuilder<TContext, TInput> {
+	constructor(
+		private readonly _input: StandardSchemaV1<unknown, TInput>,
+		private readonly _requirements: ReadonlyArray<AuthRequirement<TContext, TInput>>,
+	) {}
+
+	/** Set the input schema — ANY Standard Schema validator (zod, valibot, arktype, …). Resets requirements. */
+	input<TNewInput>(schema: StandardSchemaV1<unknown, TNewInput>): ProcedureBuilder<TContext, TNewInput> {
+		return new ProcedureBuilder<TContext, TNewInput>(schema, [])
+	}
+
+	/** Set an output schema → switch to the output builder (handler result validated against it). */
+	output<TOutput>(schema: StandardSchemaV1<unknown, TOutput>): OutputProcedureBuilder<TContext, TInput, TOutput> {
+		return new OutputProcedureBuilder<TContext, TInput, TOutput>(this._input, schema, this._requirements)
+	}
+
+	/**
+	 * Record an authz requirement, checked BEFORE the handler runs (all must pass).
+	 * Only available when the context carries `auth: AuthContext`.
+	 */
+	require<TThis extends { auth: AuthContext }>(
+		this: ProcedureBuilder<TThis, TInput>,
+		action: string,
+		scopeResolver?: (input: TInput, ctx: TThis) => Scope | undefined,
+	): ProcedureBuilder<TThis, TInput> {
+		const requirement: AuthRequirement<TThis, TInput> = scopeResolver ? { action, scopeResolver } : { action }
+		return new ProcedureBuilder<TThis, TInput>(this._input, [...this._requirements, requirement])
+	}
+
+	/** Terminal: a neutral handler (tagged `query`). Output type inferred from the return. */
+	handler<TOutput>(fn: Handler<TContext, TInput, TOutput>): Procedure<TContext, TInput, TOutput> {
+		return makeProcedure('query', this._input, null, this._requirements, fn)
+	}
+
+	/** Terminal: a `query`-tagged handler. Output type inferred from the return. */
+	query<TOutput>(fn: Handler<TContext, TInput, TOutput>): Procedure<TContext, TInput, TOutput> {
+		return makeProcedure('query', this._input, null, this._requirements, fn)
+	}
+
+	/** Terminal: a `mutation`-tagged handler. Output type inferred from the return. */
+	mutation<TOutput>(fn: Handler<TContext, TInput, TOutput>): Procedure<TContext, TInput, TOutput> {
+		return makeProcedure('mutation', this._input, null, this._requirements, fn)
+	}
+}
+
+/** Builder after `.output(schema)` — the terminal fixes the output to the schema type + validates it. */
+export class OutputProcedureBuilder<TContext, TInput, TOutput> {
+	constructor(
+		private readonly _input: StandardSchemaV1<unknown, TInput>,
+		private readonly _output: StandardSchemaV1<unknown, TOutput>,
+		private readonly _requirements: ReadonlyArray<AuthRequirement<TContext, TInput>>,
+	) {}
+
+	/** Record an authz requirement, checked BEFORE the handler runs (all must pass). */
+	require<TThis extends { auth: AuthContext }>(
+		this: OutputProcedureBuilder<TThis, TInput, TOutput>,
+		action: string,
+		scopeResolver?: (input: TInput, ctx: TThis) => Scope | undefined,
+	): OutputProcedureBuilder<TThis, TInput, TOutput> {
+		const requirement: AuthRequirement<TThis, TInput> = scopeResolver ? { action, scopeResolver } : { action }
+		return new OutputProcedureBuilder<TThis, TInput, TOutput>(this._input, this._output, [...this._requirements, requirement])
+	}
+
+	/** Terminal: a neutral handler (tagged `query`); result validated against the output schema. */
+	handler(fn: Handler<TContext, TInput, TOutput>): Procedure<TContext, TInput, TOutput> {
+		return makeProcedure('query', this._input, this._output, this._requirements, fn)
+	}
+
+	/** Terminal: a `query`-tagged handler; result validated against the output schema. */
+	query(fn: Handler<TContext, TInput, TOutput>): Procedure<TContext, TInput, TOutput> {
+		return makeProcedure('query', this._input, this._output, this._requirements, fn)
+	}
+
+	/** Terminal: a `mutation`-tagged handler; result validated against the output schema. */
+	mutation(fn: Handler<TContext, TInput, TOutput>): Procedure<TContext, TInput, TOutput> {
+		return makeProcedure('mutation', this._input, this._output, this._requirements, fn)
+	}
+}
+
+export function initRpc<TContext>(): {
+	procedure: ProcedureBuilder<TContext, void>
+	router<TDef extends RouterDef>(def: TDef): Router<TDef>
+} {
+	return {
+		procedure: new ProcedureBuilder<TContext, void>(voidSchema, []),
+		router<TDef extends RouterDef>(def: TDef): Router<TDef> {
+			return { _tag: 'router', _def: def }
+		},
+	}
+}

package/src/rpc/contract.ts

@@ -0,0 +1,34 @@
+// ─── Portable RPC contract ───────────────────────────────────────────
+//
+// Contracts carry only procedure input and output types. A browser-safe contract
+// package can therefore describe an API without importing its server router,
+// validators, handler context, or runtime dependencies.
+
+import type { InferRouterClient, Procedure, Router, RouterDef } from './types.js'
+
+/** A type-only RPC procedure declaration for a portable API contract. */
+export interface RpcProcedureContract<TInput, TOutput> {
+	readonly '~rpc': {
+		readonly input: TInput
+		readonly output: TOutput
+	}
+}
+
+/** Client-facing view of a portable contract. */
+export type InferRpcContractClient<TContract> = TContract extends RpcProcedureContract<infer TInput, infer TOutput>
+	? (input: TInput) => Promise<TOutput>
+	: TContract extends object ? { [K in keyof TContract]: InferRpcContractClient<TContract[K]> }
+	: never
+
+/** Client-facing view of either a server router or a portable contract. */
+export type InferRpcClient<TApi> = TApi extends { readonly _tag: 'router'; readonly _def: RouterDef } ? InferRouterClient<TApi>
+	: InferRpcContractClient<TApi>
+
+type RpcRouterDefinition<TContext, TContract> = {
+	readonly [K in keyof TContract]: TContract[K] extends RpcProcedureContract<infer TInput, infer TOutput> ? Procedure<TContext, TInput, TOutput>
+		: TContract[K] extends object ? RpcRouterFor<TContext, TContract[K]>
+		: never
+}
+
+/** Server router shape required to implement a portable contract. */
+export type RpcRouterFor<TContext, TContract> = Router<RpcRouterDefinition<TContext, TContract>>

package/src/rpc/dispatcher.ts

@@ -0,0 +1,150 @@
+// ─── RPC dispatcher ──────────────────────────────────────────────────
+//
+// Resolves a dotted method path against a router, validates input, enforces
+// authz requirements, runs the handler, and (optionally) validates output. All
+// error mapping goes through the structural contract in `errors.ts`.
+
+import type { AuthContext } from '@fabrika/auth'
+import { ForbiddenError, HttpError, jsonResponse, readStructuralError } from '../errors.js'
+import type { StandardSchemaV1 } from '../standard-schema.js'
+import type { AnyProcedure, AnyRouter, RouterDef } from './types.js'
+
+interface SingleCall {
+	method: string
+	input: unknown
+}
+
+interface SingleResult {
+	result?: unknown
+	error?: { type: string; message: string; issues?: unknown; loginUrl?: string }
+}
+
+interface DispatchOutcome {
+	readonly body: SingleResult
+	readonly status: number
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === 'object'
+}
+
+function hasAuth(ctx: unknown): ctx is { auth: AuthContext } {
+	if (!isRecord(ctx)) return false
+	const auth = ctx['auth']
+	return isRecord(auth) && typeof auth['can'] === 'function' && typeof auth['scopedTo'] === 'function' && typeof auth['audit'] === 'function'
+}
+
+/**
+ * Run a Standard Schema validator and ALWAYS return a Result — a validator that throws (rather than
+ * returning issues, as the spec intends) is folded into a single issue so the dispatcher never leaks
+ * a raw schema error.
+ */
+async function safeValidate<T>(schema: StandardSchemaV1<unknown, T>, value: unknown): Promise<StandardSchemaV1.Result<T>> {
+	try {
+		return await schema['~standard'].validate(value)
+	} catch (err) {
+		return { issues: [{ message: err instanceof Error ? err.message : 'Validation failed' }] }
+	}
+}
+
+/** A short human message from the first issue (path-prefixed); the full list rides in the envelope. */
+function formatIssues(issues: ReadonlyArray<StandardSchemaV1.Issue>): string {
+	const first = issues[0]
+	if (!first) return 'Validation failed'
+	const path = first.path?.map((seg) => (typeof seg === 'object' ? String(seg.key) : String(seg))).join('.')
+	return path ? `${path}: ${first.message}` : first.message
+}
+
+function resolve(router: AnyRouter, methodPath: string): AnyProcedure | null {
+	const parts = methodPath.split('.')
+	let node: AnyProcedure | AnyRouter = router
+	for (const part of parts) {
+		if (node._tag !== 'router') return null
+		const def: RouterDef = node._def
+		const next = def[part]
+		if (!next) return null
+		node = next
+	}
+	return node._tag === 'procedure' ? node : null
+}
+
+async function invokeProcedure(procedure: AnyProcedure, ctx: unknown, rawInput: unknown): Promise<unknown> {
+	// Normalize JSON's `null` to `undefined` for no-input procedures.
+	const normalized = rawInput === null ? undefined : rawInput
+	const inResult = await safeValidate(procedure.input, normalized)
+	if (inResult.issues) {
+		throw new HttpError(400, 'validation', formatIssues(inResult.issues), { issues: inResult.issues })
+	}
+	const input = inResult.value
+
+	for (const requirement of procedure.requirements) {
+		const scope = requirement.scopeResolver?.(input, ctx)
+		if (!hasAuth(ctx) || !ctx.auth.can(requirement.action, scope)) {
+			throw new ForbiddenError(`Forbidden: ${requirement.action}`)
+		}
+	}
+
+	const output = await procedure.handler({ ctx, input })
+	if (!procedure.output) return output
+	const outResult = await safeValidate(procedure.output, output)
+	if (outResult.issues) {
+		throw new HttpError(500, 'internal', `Output validation failed: ${formatIssues(outResult.issues)}`)
+	}
+	return outResult.value
+}
+
+async function dispatchOne(router: AnyRouter, ctx: unknown, call: SingleCall): Promise<DispatchOutcome> {
+	const procedure = resolve(router, call.method)
+	if (!procedure) {
+		return { body: { error: { type: 'method_not_found', message: `Unknown method: ${call.method}` } }, status: 404 }
+	}
+	try {
+		const result = await invokeProcedure(procedure, ctx, call.input)
+		return { body: { result }, status: 200 }
+	} catch (err) {
+		// HTTP status comes from the error's OWN structural httpStatus (ForbiddenError → 403,
+		// BadRequestError → 400, a custom `{ httpStatus: 503 }` → 503, a plain Error → 500) — not a
+		// hardcoded type table — so every error maps correctly without the dispatcher knowing its type.
+		const { httpStatus, type, message, issues, loginUrl } = readStructuralError(err)
+		return {
+			body: { error: { type, message, ...(issues !== undefined ? { issues } : {}), ...(loginUrl !== undefined ? { loginUrl } : {}) } },
+			status: httpStatus,
+		}
+	}
+}
+
+/**
+ * Dispatch an RPC POST. The `ctx` is already built (and decorated by middleware,
+ * e.g. `ctx.auth`) by the server before this is called. Handles a single call
+ * `{ method, input }` or a `{ batch: [...] }`.
+ */
+export async function dispatchRpcRequest(args: { router: AnyRouter; ctx: unknown; request: Request }): Promise<Response> {
+	let rawBody: unknown
+	try {
+		rawBody = await args.request.json()
+	} catch {
+		return jsonResponse({ error: { type: 'validation', message: 'Invalid JSON body' } }, 400)
+	}
+
+	if (isRecord(rawBody) && Array.isArray(rawBody['batch'])) {
+		const results: SingleResult[] = []
+		for (const call of rawBody['batch']) {
+			results.push((await dispatchOne(args.router, args.ctx, normalizeCall(call))).body)
+		}
+		return jsonResponse({ batch: results }, 200)
+	}
+
+	if (!isRecord(rawBody) || typeof rawBody['method'] !== 'string') {
+		return jsonResponse({ error: { type: 'validation', message: 'Body must be { method, input } or { batch: [...] }' } }, 400)
+	}
+
+	const single = await dispatchOne(args.router, args.ctx, { method: rawBody['method'], input: rawBody['input'] })
+	return jsonResponse(single.body, single.status)
+}
+
+function normalizeCall(call: unknown): SingleCall {
+	if (isRecord(call) && typeof call['method'] === 'string') {
+		return { method: call['method'], input: call['input'] }
+	}
+	return { method: '', input: undefined }
+}

package/src/rpc/types.ts

@@ -0,0 +1,77 @@
+// ─── RPC core types ──────────────────────────────────────────────────
+//
+// A minimal tRPC-like engine. A router is a (possibly nested) map of procedures;
+// a procedure carries an input schema, an OPTIONAL output schema, an authz
+// requirement list, and a handler. The server-facing type is `InferRouter`; the
+// client call types are `InferRouterClient`.
+
+import type { AuthContext, Scope } from '@fabrika/auth'
+import type { StandardSchemaV1 } from '../standard-schema.js'
+
+/** `query` and `mutation` are metadata today — the dispatcher treats them identically. */
+export type ProcedureKind = 'query' | 'mutation'
+
+/**
+ * A recorded authorization requirement. `scopeResolver` is declared as a METHOD
+ * (bivariant params) on purpose, so a concrete `Procedure<C, I, O>` stays
+ * assignable to `AnyProcedure`.
+ */
+export interface AuthRequirement<TContext, TInput> {
+	readonly action: string
+	scopeResolver?(input: TInput, ctx: TContext): Scope | undefined
+}
+
+// `TInput` is the schema's PARSED (output) type — what the handler receives and what the client is
+// typed to send. Modeled as `StandardSchemaV1<unknown, TInput>` (output param = TInput); for plain
+// schemas input === output, so the single param is faithful.
+export interface Procedure<TContext, TInput, TOutput> {
+	readonly _tag: 'procedure'
+	readonly kind: ProcedureKind
+	readonly input: StandardSchemaV1<unknown, TInput>
+	readonly output: StandardSchemaV1<unknown, TOutput> | null
+	readonly requirements: ReadonlyArray<AuthRequirement<TContext, TInput>>
+	handler(args: { ctx: TContext; input: TInput }): Promise<TOutput> | TOutput
+}
+
+export interface AnyProcedure {
+	readonly _tag: 'procedure'
+	readonly kind: ProcedureKind
+	readonly input: StandardSchemaV1
+	readonly output: StandardSchemaV1 | null
+	readonly requirements: ReadonlyArray<AuthRequirement<unknown, unknown>>
+	handler(args: { ctx: unknown; input: unknown }): Promise<unknown> | unknown
+}
+
+export type RouterDef = {
+	readonly [key: string]: AnyProcedure | AnyRouter
+}
+
+export interface Router<TDef extends RouterDef> {
+	readonly _tag: 'router'
+	readonly _def: TDef
+}
+
+export type AnyRouter = Router<RouterDef>
+
+/** Re-export the auth contract used by procedure requirements. */
+export type { AuthContext, Scope }
+
+// ─── Inference ───────────────────────────────────────────────────────
+
+/** Server-facing view of a router: each procedure as its handler signature. */
+export type InferRouter<TRouter> = TRouter extends { _tag: 'router'; _def: infer TDef } ? TDef extends RouterDef ? {
+			[K in keyof TDef]: TDef[K] extends Procedure<infer C, infer I, infer O> ? (args: { ctx: C; input: I }) => Promise<O> | O
+				: TDef[K] extends Router<RouterDef> ? InferRouter<TDef[K]>
+				: never
+		}
+	: never
+	: never
+
+/** Client-facing view of a router: each procedure as `(input) => Promise<output>`. */
+export type InferRouterClient<TRouter> = TRouter extends { _tag: 'router'; _def: infer TDef } ? TDef extends RouterDef ? {
+			[K in keyof TDef]: TDef[K] extends Procedure<unknown, infer I, infer O> ? (input: I) => Promise<O>
+				: TDef[K] extends Router<RouterDef> ? InferRouterClient<TDef[K]>
+				: never
+		}
+	: never
+	: never