@fabrika/auth 0.0.1

package/src/json.ts

@@ -0,0 +1,31 @@
+/**
+ * Tiny structural readers for untrusted JSON — here, an IAM HTTP response body. They let the decoders
+ * in `rpc-http.ts` narrow without `as` casts: read a field, check its runtime type, proceed.
+ *
+ * Mirrors `@fabrika/auth-core`'s internal `json.ts` (not exported from its entry point) and
+ * `@fabrika/proxy`'s copy. Three tiny functions duplicated three times is cheaper than widening a
+ * published package's public API to share them.
+ */
+
+/** Read a property off an unknown value (undefined when absent / not an object). */
+export function prop(value: unknown, key: string): unknown {
+	if (typeof value !== 'object' || value === null) {
+		return undefined
+	}
+	return Object.hasOwn(value, key) ? Reflect.get(value, key) : undefined
+}
+
+export function stringField(value: unknown, key: string): string | undefined {
+	const v = prop(value, key)
+	return typeof v === 'string' ? v : undefined
+}
+
+export function numberField(value: unknown, key: string): number | undefined {
+	const v = prop(value, key)
+	return typeof v === 'number' && Number.isFinite(v) ? v : undefined
+}
+
+export function booleanField(value: unknown, key: string): boolean | undefined {
+	const v = prop(value, key)
+	return typeof v === 'boolean' ? v : undefined
+}

package/src/middleware.ts

@@ -0,0 +1,29 @@
+/**
+ * The shared middleware contract consumed by `@fabrika/app`. The auth package owns the shape so an
+ * app's own auth middleware — the one that calls `iam.authenticate(request)` and stores the resolved
+ * context — drops into the request pipeline without a duplicate compatibility interface. The SDK
+ * itself ships no middleware: enforcement is the proxy's job (ADR-0007).
+ *
+ * A middleware runs in order; it may:
+ *   - mutate `ctx` (e.g. set `ctx.auth`),
+ *   - short-circuit by returning a Response WITHOUT calling `next()`,
+ *   - or wrap `next()` — await it, then append headers to the returned Response.
+ */
+
+import type { AuthContext } from './types'
+
+/**
+ * A request-pipeline middleware over a caller-owned context `Ctx`. Runs in registration order. Return
+ * a Response without awaiting `next()` to short-circuit; await `next()` and return its (possibly
+ * header-augmented) Response to continue.
+ */
+export type Middleware<Ctx> = (request: Request, ctx: Ctx, next: () => Promise<Response>) => Promise<Response>
+
+/**
+ * The minimal shape an auth middleware needs of the pipeline context: a writable `auth` slot it sets to
+ * the resolved `AuthContext` (or leaves null/undefined for an unresolved/anonymous caller). The
+ * caller's real context may carry far more — this is only what the auth middlewares touch.
+ */
+export interface AuthCarrier {
+	auth?: AuthContext | null
+}

package/src/provision.ts

@@ -0,0 +1,146 @@
+// Deploy-time schema reconcile — authz-vocabulary as code.
+//
+// Each app OWNS its authz vocabulary (scope dimensions, action catalog, roles) and declares it
+// in its own code as an `AppSchema`. At deploy time the app reconciles that declaration into
+// IAM by PUTting it to the idempotent admin endpoint `PUT /admin/apps/:app/schema`, so the
+// IAM Worker's DB always mirrors what the app actually checks at runtime. An app's FIRST schema
+// reconcile is also how it REGISTERS itself in IAM's app registry.
+//
+// The same deploy step optionally projects the app's RETURN ORIGINS (ADR-0021) — see
+// `returnOrigins` below. That is a SECOND call to a different endpoint, deliberately: the schema is
+// vocabulary the application declares, a return origin is a fact the control plane knows, and the
+// two must never travel in one body.
+//
+// This is a DEPLOY/OPERATOR helper, NOT a runtime one: it talks HTTP to the admin origin (not the
+// `IAM` service binding) and authenticates with an IAM-issued `px_` ADMIN key as a bearer —
+// reconcile is a privileged admin operation. Call it from a deploy step / provisioning script,
+// never from request handling.
+//
+// Idempotent: the endpoint upserts scopes/actions/origin='app' roles and deletes app-origin rows
+// absent from the body; origin='custom' policies are never touched. Re-running is safe, and so is
+// re-sending the same return-origin set.
+
+import type { AppSchema } from '@fabrika/auth-core'
+
+export interface ReconcileSchemaOptions {
+	/** The IAM Worker's admin origin, e.g. `https://iam.example.com` (trailing slash ok). */
+	url: string
+	/** The app id; its FIRST reconcile registers it in IAM's app registry. */
+	app: string
+	/** The app's declared vocabulary. */
+	schema: AppSchema
+	/**
+	 * Every origin IAM may hand this app a session at (ADR-0021), as known by the CONTROL PLANE.
+	 *
+	 * Omit to leave the registry alone; a supplied set REPLACES it, so it must be the complete set for
+	 * the app and not just the environment being deployed. It is NEVER read off the `AppSchema`: an app
+	 * that could name its own return origin could name any origin, which is the thing the registry
+	 * exists to prevent. An empty array is a caller error — clearing the registry is its own admin
+	 * operation, not an accident of having nothing to send.
+	 */
+	returnOrigins?: readonly string[]
+	/**
+	 * An IAM-issued `px_` ADMIN key, sent as `Authorization: Bearer`. Effectively required: IAM's CSRF
+	 * guard exempts BEARER-ONLY callers, and nothing else — a credential-less server-side call sends
+	 * neither `Origin` nor `Referer` and is refused whatever the admin-origin registry holds. The
+	 * exemption rests on one fact, that a browser never attaches `Authorization` by itself; no such
+	 * fact covers a credential-less request, and `resolveAdmin` would read it as a global admin.
+	 */
+	adminKey?: string
+	/** Cancels the in-flight request when schema reconciliation belongs to a deploy lifecycle. */
+	signal?: AbortSignal
+}
+
+/** Thrown when the admin endpoint rejects the reconcile; `status` is the HTTP status. */
+export class ReconcileSchemaError extends Error {
+	constructor(message: string, readonly status: number) {
+		super(message)
+		this.name = 'ReconcileSchemaError'
+	}
+}
+
+/**
+ * Pull a human-readable message out of an admin failure body. REST answers `{ error: "…" }`;
+ * `/admin/rpc` answers `{ error: { type, message } }`. Null when neither shape is present.
+ */
+function errorMessage(value: unknown): string | null {
+	if (typeof value !== 'object' || value === null || !('error' in value)) {
+		return null
+	}
+	const message = value.error
+	if (typeof message === 'string') {
+		return message
+	}
+	if (typeof message === 'object' && message !== null && 'message' in message && typeof message.message === 'string') {
+		return message.message
+	}
+	return null
+}
+
+/**
+ * Reconcile one app's declared `AppSchema` into IAM (idempotent), then — when `returnOrigins` is
+ * supplied — project that set into IAM's return-origin registry. Resolves on success; throws
+ * `ReconcileSchemaError` on a non-2xx response, or `Error` on a half-set service token.
+ */
+export async function reconcileSchema(options: ReconcileSchemaOptions): Promise<void> {
+	const { url, app, schema, returnOrigins, adminKey, signal } = options
+
+	if (returnOrigins !== undefined && returnOrigins.length === 0) {
+		throw new Error('reconcileSchema: returnOrigins must not be empty — omit it to leave the registry untouched')
+	}
+
+	const headers: Record<string, string> = { 'content-type': 'application/json' }
+	if (adminKey !== undefined) {
+		headers['authorization'] = `Bearer ${adminKey}`
+	}
+
+	// Trim a trailing slash so `${base}${path}` never doubles up.
+	const base = url.replace(/\/+$/, '')
+	const schemaPath = `/admin/apps/${encodeURIComponent(app)}/schema`
+	const response = await fetch(`${base}${schemaPath}`, {
+		method: 'PUT',
+		headers,
+		body: JSON.stringify(schema),
+		signal,
+	})
+	if (!response.ok) {
+		throw new ReconcileSchemaError(`PUT /admin/apps/${app}/schema failed (${response.status}): ${await detail(response)}`, response.status)
+	}
+
+	if (returnOrigins === undefined) {
+		return
+	}
+
+	// Second call, second endpoint, and it runs SECOND on purpose: `apps.setReturnOrigins` answers 404
+	// for an app IAM has never heard of, and the schema PUT above is what registers it.
+	const registration = await fetch(`${base}/admin/rpc`, {
+		method: 'POST',
+		headers,
+		body: JSON.stringify({ method: 'apps.setReturnOrigins', input: { app, origins: [...returnOrigins] } }),
+		signal,
+	})
+	const failure = registration.ok ? await rpcError(registration) : await detail(registration)
+	if (failure !== null) {
+		throw new ReconcileSchemaError(
+			`apps.setReturnOrigins for ${app} failed (${registration.status}): ${failure}`,
+			registration.status,
+		)
+	}
+}
+
+/** The admin API's own message for a failed response, falling back to the status text. */
+async function detail(response: Response): Promise<string> {
+	const payload: unknown = await response.json().catch(() => null)
+	return errorMessage(payload) ?? response.statusText
+}
+
+/**
+ * A single `/admin/rpc` call maps its error onto the HTTP status, so a 2xx is already success. Read
+ * the envelope anyway: a body carrying `error` at 200 means the call was answered in a shape this
+ * caller did not ask for (a batch, say), and treating it as success would report a registration that
+ * never happened. Null when the envelope is clean.
+ */
+async function rpcError(response: Response): Promise<string | null> {
+	const payload: unknown = await response.json().catch(() => null)
+	return errorMessage(payload)
+}

package/src/request.ts

@@ -0,0 +1,48 @@
+// Reading the fabrika-native credential off the incoming Request, to forward to the IAM service's
+// management RPCs (issueKey / issueJwt / revokeKey / listPrincipals). Precedence: the token the PROXY
+// injected (the one it already verified), then an `Authorization: Bearer` (a machine `px_` key or a
+// passthrough JWT). None of this is a security boundary —
+// IAM re-resolves and re-authorizes the caller server-side from this credential.
+
+import { PROXY_TOKEN_HEADER } from '@fabrika/auth-core'
+
+/** Cloudflare's per-request ray id; we use it as the correlation request id. */
+const RAY_HEADER = 'cf-ray'
+
+export interface ForwardedCredentials {
+	/** The native credential (a `px_` key / passthrough JWT / `px_token`), or null when absent. */
+	credential: string | null
+	/** cf-ray, or a fresh UUID when absent (e.g. local dev). */
+	requestId: string
+}
+
+/** The correlation id for this request: cf-ray when the platform supplies one, else a fresh UUID. */
+export function readRequestId(req: Request): string {
+	return req.headers.get(RAY_HEADER) ?? crypto.randomUUID()
+}
+
+/** Pull the native credential and a correlation id off the request. `credential` may be null. */
+export function readCredentials(req: Request): ForwardedCredentials {
+	return {
+		credential: nonEmpty(req.headers.get(PROXY_TOKEN_HEADER))
+			?? readBearer(req.headers.get('Authorization')),
+		requestId: readRequestId(req),
+	}
+}
+
+function nonEmpty(value: string | null): string | null {
+	if (value === null) {
+		return null
+	}
+	const trimmed = value.trim()
+	return trimmed === '' ? null : trimmed
+}
+
+/** Read the token out of an `Authorization: Bearer <token>` header. Null when absent/non-bearer. */
+function readBearer(header: string | null): string | null {
+	if (header === null) {
+		return null
+	}
+	const match = /^Bearer\s+(.+)$/i.exec(header.trim())
+	return match ? (match[1]?.trim() ?? null) : null
+}

package/src/rpc-http.ts

@@ -0,0 +1,318 @@
+/**
+ * `IamRpc` over HTTP — the transport an app needs when it has no Cloudflare service binding.
+ *
+ * WHAT THIS IS NOT: it is not a second IAM. `IamRpc` (@fabrika/auth-core) is unchanged and this class
+ * holds no policy — it POSTs the method's input as JSON, reads the result back, and hands it to the
+ * same callers (`Iam`, `IamClient`) the binding serves. Everything downstream of the
+ * contract — local token verification, `can()`/`scopedTo()`, delegation checks inside the IAM
+ * service — is byte-for-byte the same code on both transports. The ONLY difference is how the
+ * call travels.
+ *
+ * THE WIRE IS `@fabrika/iam`'s `src/rpc-http.ts`, and that file is the contract:
+ *
+ *   POST {origin}/rpc/<method>   Authorization: Bearer <key>   body = the method's input
+ *     → 200 with the method's result (INCLUDING a decided `{ ok: false, reason }`)
+ *     → 204 for `audit` (it returns void over the binding, so there is nothing to encode)
+ *     → 401 bad/absent key · 404 no such method OR the surface is disabled (an unset key 404s) ·
+ *       400 undecodable body · 405 not a POST
+ *
+ * A DECIDED NEGATIVE IS A 200, and that distinction is the whole point: `{ ok: false, reason }` means
+ * "IAM answered: no", while a non-200 means "IAM could not be consulted". Only the second is an
+ * incident, and only the second throws here.
+ *
+ * ── Why a transport failure THROWS ────────────────────────────────────────────────────────────────
+ *
+ * Over a service binding an unreachable IAM is not a case a caller has to model: the binding either
+ * resolves or the whole invocation fails. Over HTTP it is a real state, and mapping it onto the
+ * contract's `reason` union would be a lie — `invalid_session` says "we checked, and no", which is not
+ * what happened. So it raises `IamTransportError`, callers see a 5xx, and nothing is ever admitted on
+ * the strength of an answer that never arrived. This is the same split `@fabrika/proxy`'s
+ * `HttpIamGateway` makes with `IamUnavailableError`.
+ *
+ * ── One instance per process, deliberately ────────────────────────────────────────────────────────
+ *
+ * The SDK caches the fetched JWKS and the tokens minted from `px_` share credentials in `WeakMap`s
+ * keyed by THE BINDING OBJECT. A fresh `HttpIamRpc` per request would therefore miss both caches every
+ * time and re-fetch the JWKS on every request. Build one for the process's lifetime and put it in the
+ * env, the way a binding lives for the isolate's lifetime.
+ *
+ * The key is a TRANSPORT credential, never a caller identity: it says "this request came from inside
+ * the deployment", exactly as a binding's unreachability does. Per-caller authorization still happens
+ * inside IAM, from the credential carried in the method's own input. It is never logged.
+ */
+
+import type {
+	AuditInput,
+	IamRpc,
+	IssueJwtInput,
+	IssueJwtResult,
+	IssueKeyInput,
+	IssueKeyResult,
+	Jwks,
+	ListPrincipalsInput,
+	ListPrincipalsResult,
+	MintFromKeyInput,
+	MintFromKeyResult,
+	MintTokenInput,
+	MintTokenResult,
+	PrincipalListItem,
+	PrincipalType,
+	PublicJwk,
+	RevokeKeyInput,
+	RevokeKeyResult,
+} from '@fabrika/auth-core'
+import { booleanField, numberField, prop, stringField } from './json'
+
+/** Default per-call timeout. A hung IAM must fail the request, not hold a connection open forever. */
+const DEFAULT_TIMEOUT_MS = 5_000
+
+/**
+ * Just the call shape this client uses. Narrower than `typeof fetch` on purpose: the global carries
+ * runtime-specific extras (Bun's `preconnect`) that a test double has no business implementing.
+ */
+export type FetchLike = (input: string, init: RequestInit) => Promise<Response>
+
+export interface HttpIamRpcOptions {
+	/** The IAM service origin, e.g. `http://iam:3000` on a private network (trailing slash tolerated). */
+	origin: string
+	/** The shared secret gating `/rpc/*` (`FABRIKA_IAM_RPC_KEY` on the IAM side). NEVER logged. */
+	key: string
+	/** Per-call timeout in milliseconds. */
+	timeoutMs?: number
+	/** Injectable for tests; defaults to the global `fetch`. */
+	fetch?: FetchLike
+}
+
+/**
+ * IAM could not be consulted — network failure, timeout, a non-2xx status, or a body that does not
+ * match the contract. Distinct from a decided denial, which is a normal result.
+ *
+ * Carries NO cause and no response body: a `fetch` error stringifies the request URL, and a body can
+ * quote a credential that was on the way in.
+ */
+export class IamTransportError extends Error {
+	constructor(readonly method: string) {
+		super(`iam unavailable: ${method}`)
+		this.name = 'IamTransportError'
+	}
+}
+
+export class HttpIamRpc implements IamRpc {
+	private readonly origin: string
+	private readonly key: string
+	private readonly timeoutMs: number
+	private readonly fetchImpl: FetchLike
+
+	constructor(options: HttpIamRpcOptions) {
+		this.origin = options.origin.replace(/\/+$/, '')
+		this.key = options.key
+		this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS
+		this.fetchImpl = options.fetch ?? globalThis.fetch
+	}
+
+	async mintToken(input: MintTokenInput): Promise<MintTokenResult> {
+		const body = await this.call('mintToken', input)
+		const failure = readFailure(body)
+		if (failure !== null) {
+			return { ok: false, reason: oneOf(failure, ['no_session', 'invalid_session', 'unknown_principal', 'disabled'], 'invalid_session') }
+		}
+		return readMintSuccess(body, 'mintToken')
+	}
+
+	async mintFromKey(input: MintFromKeyInput): Promise<MintFromKeyResult> {
+		const body = await this.call('mintFromKey', input)
+		const failure = readFailure(body)
+		if (failure !== null) {
+			return { ok: false, reason: oneOf(failure, ['invalid_key', 'unknown_principal', 'disabled'], 'invalid_key') }
+		}
+		return readMintSuccess(body, 'mintFromKey')
+	}
+
+	async issueKey(input: IssueKeyInput): Promise<IssueKeyResult> {
+		const body = await this.call('issueKey', input)
+		const failure = readFailure(body)
+		if (failure !== null) {
+			return { ok: false, reason: oneOf(failure, ISSUE_REASONS, 'not_allowed') }
+		}
+		const token = stringField(body, 'token')
+		const id = stringField(body, 'id')
+		if (token === undefined || id === undefined) {
+			throw new IamTransportError('issueKey')
+		}
+		const principalId = stringField(body, 'principalId')
+		return { ok: true, token, id, ...(principalId === undefined ? {} : { principalId }) }
+	}
+
+	async issueJwt(input: IssueJwtInput): Promise<IssueJwtResult> {
+		const body = await this.call('issueJwt', input)
+		const failure = readFailure(body)
+		if (failure !== null) {
+			return { ok: false, reason: oneOf(failure, ISSUE_REASONS, 'not_allowed') }
+		}
+		const token = stringField(body, 'token')
+		const expiresAt = numberField(body, 'expiresAt')
+		const id = stringField(body, 'id')
+		if (token === undefined || expiresAt === undefined || id === undefined) {
+			throw new IamTransportError('issueJwt')
+		}
+		return { ok: true, token, expiresAt, id }
+	}
+
+	async revokeKey(input: RevokeKeyInput): Promise<RevokeKeyResult> {
+		const body = await this.call('revokeKey', input)
+		const failure = readFailure(body)
+		if (failure !== null) {
+			return { ok: false, reason: oneOf(failure, [...ISSUE_REASONS, 'not_found'], 'not_allowed') }
+		}
+		const revoked = booleanField(body, 'revoked')
+		if (revoked === undefined) {
+			throw new IamTransportError('revokeKey')
+		}
+		return { ok: true, revoked }
+	}
+
+	async listPrincipals(input: ListPrincipalsInput): Promise<ListPrincipalsResult> {
+		const body = await this.call('listPrincipals', input)
+		const failure = readFailure(body)
+		if (failure !== null) {
+			return { ok: false, reason: oneOf(failure, ISSUE_REASONS, 'not_allowed') }
+		}
+		const raw = prop(body, 'principals')
+		if (!Array.isArray(raw)) {
+			throw new IamTransportError('listPrincipals')
+		}
+		const principals: PrincipalListItem[] = []
+		for (const item of raw) {
+			const id = stringField(item, 'id')
+			const label = stringField(item, 'label')
+			const type = stringField(item, 'type')
+			if (id === undefined || label === undefined || type === undefined) {
+				throw new IamTransportError('listPrincipals')
+			}
+			const email = prop(item, 'email')
+			principals.push({
+				id,
+				label,
+				// Anything but the literal 'service' is a user — the same narrowing the binding transport does.
+				type: principalType(type),
+				email: typeof email === 'string' ? email : null,
+				disabled: booleanField(item, 'disabled') ?? false,
+			})
+		}
+		return { ok: true, principals }
+	}
+
+	async getJwks(): Promise<Jwks> {
+		// `getJwks` takes no input, so an empty object body is the natural call (the server tolerates a
+		// wholly empty body too). It goes through `/rpc/*` like every other method rather than the public
+		// `/.well-known/jwks.json`, so ONE key and ONE surface serve the whole contract.
+		const body = await this.call('getJwks', {})
+		const rawKeys = prop(body, 'keys')
+		if (!Array.isArray(rawKeys)) {
+			throw new IamTransportError('getJwks')
+		}
+		const keys: PublicJwk[] = []
+		for (const raw of rawKeys) {
+			const kty = stringField(raw, 'kty')
+			if (kty === undefined) {
+				throw new IamTransportError('getJwks')
+			}
+			const key: PublicJwk = { kty }
+			for (const field of ['crv', 'x', 'y', 'kid', 'alg', 'use'] as const) {
+				const value = stringField(raw, field)
+				if (value !== undefined) {
+					key[field] = value
+				}
+			}
+			keys.push(key)
+		}
+		return { keys }
+	}
+
+	async audit(event: AuditInput): Promise<void> {
+		// 204, no body — `audit` returns void over the binding, so there is nothing to decode. A transport
+		// failure still throws: an audit row that silently never happened is the one loss an audit trail
+		// cannot absorb.
+		await this.send('audit', event)
+	}
+
+	/** POST one method and return its decoded JSON body. Throws `IamTransportError` on any transport fault. */
+	private async call(method: string, input: unknown): Promise<unknown> {
+		const response = await this.send(method, input)
+		const body: unknown = await response.json().catch(() => MALFORMED)
+		if (body === MALFORMED) {
+			throw new IamTransportError(method)
+		}
+		return body
+	}
+
+	private async send(method: string, input: unknown): Promise<Response> {
+		let response: Response
+		try {
+			response = await this.fetchImpl(`${this.origin}/rpc/${method}`, {
+				method: 'POST',
+				headers: {
+					'content-type': 'application/json',
+					accept: 'application/json',
+					authorization: `Bearer ${this.key}`,
+				},
+				body: JSON.stringify(input),
+				signal: AbortSignal.timeout(this.timeoutMs),
+			})
+		} catch {
+			// Swallow the cause deliberately: a fetch error stringifies the request URL and, on some
+			// runtimes, request detail. Only the method name is ever surfaced.
+			throw new IamTransportError(method)
+		}
+		if (!response.ok) {
+			throw new IamTransportError(method)
+		}
+		return response
+	}
+}
+
+/** The five delegation-path failure reasons `issueKey` / `issueJwt` / `listPrincipals` share. */
+const ISSUE_REASONS = ['missing_token', 'invalid_token', 'unknown_principal', 'disabled', 'not_allowed'] as const
+
+/** Distinguishes "the body was not JSON" from a body that decoded to something the readers reject. */
+const MALFORMED = Symbol('malformed')
+
+/**
+ * The `reason` of a decided negative, or null when the body is an `ok: true` result. A body that is
+ * neither (no `ok`, or `ok: false` with no reason) is a contract violation, not a denial — the caller
+ * then fails its own success decode and raises `IamTransportError`, which is the fail-closed answer.
+ */
+function readFailure(body: unknown): string | null {
+	if (prop(body, 'ok') !== false) {
+		return null
+	}
+	return stringField(body, 'reason') ?? ''
+}
+
+/** The `{ ok: true, token, expiresAt }` half both mint methods share. */
+function readMintSuccess(body: unknown, method: string): { ok: true; token: string; expiresAt: number } {
+	const token = stringField(body, 'token')
+	const expiresAt = numberField(body, 'expiresAt')
+	if (token === undefined || token === '' || expiresAt === undefined) {
+		throw new IamTransportError(method)
+	}
+	return { ok: true, token, expiresAt }
+}
+
+/**
+ * Narrow a wire `reason` to the declared union without a cast. An unrecognised reason degrades to the
+ * given fallback, which is ALWAYS a deny reason — an IAM that starts speaking a dialect this client
+ * does not know must not be able to talk it into an allow.
+ */
+function oneOf<T extends string>(value: string, allowed: readonly T[], fallback: T): T {
+	for (const candidate of allowed) {
+		if (candidate === value) {
+			return candidate
+		}
+	}
+	return fallback
+}
+
+function principalType(value: string): PrincipalType {
+	return value === 'service' ? 'service' : 'user'
+}

package/src/scope.ts

@@ -0,0 +1,25 @@
+/**
+ * Resolve the three-state result from `scopedTo(action, dimension)` into a single value the
+ * app controls. This is the SINGLE place the empty-`IN ()` SQL trap is handled: `none`
+ * short-circuits without ever emitting `WHERE col IN ()`.
+ *
+ *   - `null`      → `all()`           — unrestricted (admin / global grant): no filter
+ *   - `[]`        → `none()`          — no access: empty result, DO NOT query
+ *   - non-empty   → `some(values)`    — filter to these scope values (`WHERE col IN (...)`)
+ *
+ * The `values` are the opaque, app-owned scope values for that dimension (the app keys its
+ * rows by them). The app supplies what all/some/none mean for its own query; filtering must
+ * happen at the data layer, never by loading everything and filtering in memory.
+ */
+export function applyScope<T>(
+	scope: string[] | null,
+	branches: { all: () => T; some: (values: string[]) => T; none: () => T },
+): T {
+	if (scope === null) {
+		return branches.all()
+	}
+	if (scope.length === 0) {
+		return branches.none()
+	}
+	return branches.some(scope)
+}