@fabrika/auth 0.0.1

package/package.json

@@ -0,0 +1,32 @@
+{
+	"name": "@fabrika/auth",
+	"version": "0.0.1",
+	"type": "module",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/contember/fabrika-platform.git",
+		"directory": "packages/auth"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"src",
+		"!src/**/__tests__/**"
+	],
+	"exports": {
+		".": {
+			"bun": "./src/index.ts",
+			"types": "./src/index.ts",
+			"default": "./src/index.ts"
+		}
+	},
+	"scripts": {
+		"typecheck": "tsc --noEmit",
+		"test": "bun test"
+	},
+	"dependencies": {
+		"@fabrika/auth-core": "^0.0.1",
+		"jose": "^5.9.0"
+	}
+}

package/src/client.ts

@@ -0,0 +1,193 @@
+import type { AccessTokenClaims, DomainEvent, IamRpc, PermissionEntry, Scope } from '@fabrika/auth-core'
+import { permits, scopedValues } from '@fabrika/auth-core'
+import { readCredentials } from './request'
+import type {
+	AuthContext,
+	IssuedJwt,
+	IssuedKey,
+	IssueFailure,
+	IssueJwtRequest,
+	IssueKeyRequest,
+	ListPrincipalsFailure,
+	PrincipalIdentity,
+	PrincipalList,
+	RevokedKey,
+	RevokeFailure,
+} from './types'
+
+// ── AuthContext (real) ─────────────────────────────────────────────────────────
+
+/**
+ * The real `AuthContext`. `can`/`scopedTo` are pure functions over the resolved permission array (no
+ * per-check round-trip); only `audit` calls the binding. Backs BOTH a principal-bound caller (cookie
+ * session / API key) and an ANONYMOUS one (passthrough JWT / standalone share link) — the latter has
+ * `principal = null`; `audit` then attributes to the credential label + token id, principal null.
+ */
+class RealAuthContext implements AuthContext {
+	readonly ok = true
+
+	constructor(
+		private readonly binding: IamRpc,
+		private readonly appId: string,
+		private readonly permissions: PermissionEntry[],
+		private readonly requestId: string,
+		readonly principal: PrincipalIdentity | null,
+		/** Audit actor label — the principal's label, or the credential/jwt label. */
+		private readonly auditLabel: string,
+		/** The credential/token id, for the audit linkage of an anonymous caller (null when bound). */
+		private readonly anonymousTokenId: string | null,
+	) {}
+
+	can(action: string, scope?: Scope): boolean {
+		// `permits` already encodes the scope-less rule: with no scope, ONLY global
+		// (scope === null) entries satisfy.
+		return permits(this.permissions, action, scope)
+	}
+
+	scopedTo(action: string, dimension: string): string[] | null {
+		// `dimension` picks the scope type — scopes are flat & independent, so a value
+		// list is always relative to one dimension.
+		return scopedValues(this.permissions, action, dimension)
+	}
+
+	audit(event: DomainEvent): Promise<void> {
+		return this.binding.audit({
+			app: this.appId,
+			requestId: this.requestId,
+			principalId: this.principal?.id ?? null,
+			principalLabel: this.auditLabel,
+			...(this.anonymousTokenId === null ? {} : { credentialId: this.anonymousTokenId }),
+			action: event.action,
+			resourceType: event.resourceType,
+			resourceId: event.resourceId,
+			diff: event.diff,
+			metadata: event.metadata,
+		})
+	}
+}
+
+/**
+ * Build an `AuthContext` from a verified access token's claims — the seam every authentication path
+ * uses (the proxy-injected token, a redeemed share credential, a passthrough JWT). The SDK has verified
+ * the token LOCALLY; this wraps its claims in the same `permits`-backed context the RPC path returns,
+ * so `can()` / `scopedTo()` / `audit()` behave identically. A token with no `ptype` is anonymous
+ * (`principal: null`).
+ */
+export function buildAuthContext(binding: IamRpc, appId: string, claims: AccessTokenClaims, requestId: string): AuthContext {
+	const principal: PrincipalIdentity | null = claims.ptype === undefined
+		? null
+		: { id: claims.sub, type: claims.ptype, label: claims.label ?? claims.sub }
+	const auditLabel = claims.label ?? (principal === null ? `credential:${claims.sub}` : claims.sub)
+	return new RealAuthContext(binding, appId, claims.perms, requestId, principal, auditLabel, principal === null ? claims.sub : null)
+}
+
+// ── IamClient ──────────────────────────────────────────────────────────────────
+
+/**
+ * Thin, app-facing wrapper over the IAM Worker service binding. Bakes the caller `app` id
+ * into the constructor so app code can never forget or mistype it. Depends ONLY on the
+ * `IamRpc` contract from `@fabrika/auth-core` — never on the Worker — which is what keeps the
+ * SDK worker-independent (the binding is the deployed Worker, reached at runtime).
+ */
+export class IamClient {
+	constructor(
+		private readonly binding: IamRpc,
+		private readonly appId: string,
+	) {}
+
+	/**
+	 * List the app's people directory — the USER principals who can access this app. Forwards the
+	 * CALLER's credential; the IAM Worker resolves the caller and scopes the roster to the
+	 * verified app (you only ever see your own app's people). For an assignee picker / actor
+	 * label list. Authorized for any member with a permission on the app; a zero-grant user → 403.
+	 */
+	async listPrincipals(req: Request): Promise<PrincipalList | ListPrincipalsFailure> {
+		const { credential, requestId } = readCredentials(req)
+		const result = await this.binding.listPrincipals({ app: this.appId, credential, requestId })
+		if (result.ok) {
+			return { ok: true, principals: result.principals }
+		}
+		return { ok: false, reason: result.reason, status: listPrincipalsStatus(result.reason) }
+	}
+
+	/**
+	 * Mint an opaque, stored, revocable `px_` credential (API key / share link). Forwards the
+	 * REQUESTER's credentials as the issuer — the IAM Worker resolves the issuer server-side and
+	 * enforces the delegation rule (you can only delegate what you can do). Returns the plaintext
+	 * `px_` token ONCE; persist only the `id` (the handle for `revokeKey`). The transport — bearer
+	 * header for a machine, URL-path token for a share link — is the app's choice. With `service`
+	 * set it instead creates a NEW machine principal and binds the key to it (the folded service
+	 * token); `principalId` is then the new principal's durable handle.
+	 */
+	async issueKey(req: Request, input: IssueKeyRequest): Promise<IssuedKey | IssueFailure> {
+		const { credential, requestId } = readCredentials(req)
+		const result = await this.binding.issueKey({
+			app: this.appId,
+			credential,
+			requestId,
+			service: input.service,
+			principalId: input.principalId,
+			permissions: input.permissions,
+			label: input.label,
+			expiresAt: input.expiresAt,
+		})
+		if (result.ok) {
+			return { ok: true, token: result.token, id: result.id, ...(result.principalId === undefined ? {} : { principalId: result.principalId }) }
+		}
+		return { ok: false, reason: result.reason, status: issueFailureStatus(result.reason) }
+	}
+
+	/**
+	 * Sign a stateless passthrough access token (audit-only, TTL-bounded, NOT revocable). Forwards the
+	 * REQUESTER's credentials as the issuer (same delegation rule as `issueKey`). The holder carries the
+	 * returned JWT directly as `Authorization: Bearer`; apps verify it locally with no propustka
+	 * round-trip. There is nothing to revoke — it is TTL-only by design.
+	 */
+	async issueJwt(req: Request, input: IssueJwtRequest): Promise<IssuedJwt | IssueFailure> {
+		const { credential, requestId } = readCredentials(req)
+		const result = await this.binding.issueJwt({
+			app: this.appId,
+			credential,
+			requestId,
+			permissions: input.permissions,
+			label: input.label,
+			ttl: input.ttl,
+		})
+		if (result.ok) {
+			return { ok: true, token: result.token, expiresAt: result.expiresAt, id: result.id }
+		}
+		return { ok: false, reason: result.reason, status: issueFailureStatus(result.reason) }
+	}
+
+	/**
+	 * Revoke an opaque `px_` credential (API key / share link) by its id. Forwards the CALLER's
+	 * credentials as the authorizer — the IAM Worker resolves the caller server-side and enforces the
+	 * rule (the original issuer, or anyone who could re-issue the grants, may revoke). Idempotent: a
+	 * second revoke returns `{ ok: true, revoked: false }`. An unknown id → 404.
+	 */
+	async revokeKey(req: Request, id: string): Promise<RevokedKey | RevokeFailure> {
+		const { credential, requestId } = readCredentials(req)
+		const result = await this.binding.revokeKey({ app: this.appId, credential, requestId, id })
+		if (result.ok) {
+			return { ok: true, revoked: result.revoked }
+		}
+		return { ok: false, reason: result.reason, status: revokeFailureStatus(result.reason) }
+	}
+}
+
+/** missing/invalid → 401; unknown_principal/disabled/not_allowed → 403. */
+function issueFailureStatus(reason: IssueFailure['reason']): 401 | 403 {
+	return reason === 'missing_token' || reason === 'invalid_token' ? 401 : 403
+}
+
+/** missing/invalid → 401; unknown_principal/disabled/not_allowed → 403. */
+function listPrincipalsStatus(reason: ListPrincipalsFailure['reason']): 401 | 403 {
+	return reason === 'missing_token' || reason === 'invalid_token' ? 401 : 403
+}
+
+/** missing/invalid → 401; not_found → 404; unknown_principal/disabled/not_allowed → 403. */
+function revokeFailureStatus(reason: RevokeFailure['reason']): 401 | 403 | 404 {
+	if (reason === 'missing_token' || reason === 'invalid_token') return 401
+	if (reason === 'not_found') return 404
+	return 403
+}

package/src/errors.ts

@@ -0,0 +1,60 @@
+/**
+ * Typed request-time errors + a small authorization helper.
+ *
+ * These are the shared structural HTTP-error contract `@fabrika/app` maps without any
+ * cross-package `instanceof`: each error exposes `{ httpStatus, type, message }` plus an optional
+ * `issues` (validation detail). A mapper reads those fields structurally — it never imports these
+ * classes — so these shapes and the framework reader are the single contract. They live in
+ * `@fabrika/auth` because `requirePermission` consumes an `AuthContext` (a client type).
+ *
+ * There is deliberately no login-bounce error here: since ADR-0007 the proxy 302s an unauthenticated
+ * browser, so an app never has to produce a login URL of its own.
+ */
+
+import type { Scope } from '@fabrika/auth-core'
+import type { AuthContext } from './types'
+
+/**
+ * The structural HTTP-error shape. Anything thrown through a request pipeline that satisfies this can be
+ * mapped to a Response without an `instanceof` check: `httpStatus` → the status, `type` → the error
+ * envelope's `type`, `message` → its `message`, `issues` → optional detail.
+ */
+export interface HttpError {
+	readonly httpStatus: number
+	readonly type: string
+	readonly message: string
+	readonly issues?: unknown
+}
+
+/** A caller is unauthenticated. `type: 'auth'`, status 401. */
+export class UnauthenticatedError extends Error implements HttpError {
+	readonly httpStatus = 401
+	readonly type = 'auth'
+
+	constructor(message = 'authentication required') {
+		super(message)
+		this.name = 'UnauthenticatedError'
+	}
+}
+
+/** A resolved caller lacks the required permission. `type: 'forbidden'`, status 403. */
+export class ForbiddenError extends Error implements HttpError {
+	readonly httpStatus = 403
+	readonly type = 'forbidden'
+
+	constructor(message = 'forbidden') {
+		super(message)
+		this.name = 'ForbiddenError'
+	}
+}
+
+/**
+ * Assert the caller may perform `action` (optionally within `scope`). Throws `ForbiddenError` when
+ * `auth.can(action, scope)` is false; otherwise returns. The thrown error satisfies the structural
+ * `HttpError` contract, so a pipeline maps it to a 403 without importing this module.
+ */
+export function requirePermission(auth: AuthContext, action: string, scope?: Scope): void {
+	if (!auth.can(action, scope)) {
+		throw new ForbiddenError(`missing permission: ${action}`)
+	}
+}

package/src/iam.ts

@@ -0,0 +1,309 @@
+/**
+ * `createIam` — the single request-time entry point apps use instead of hand-rolling auth.
+ *
+ * Since [ADR-0007](../../../docs/decisions/0007-proxy-based-auth-enforcement.md) the PROXY is the only
+ * thing that enforces: it matches the app's gates, resolves the credential, and injects a verified
+ * access token as `PROXY_TOKEN_HEADER`. What is left for an app is small and fixed:
+ *   - `authenticate(request)` — read that header and verify it LOCALLY against IAM's published JWKS
+ *     (signature, `iss`, `aud`, `exp`), then build an `AuthContext`. The header is never trusted blindly.
+ *   - `redeemKey(token)` — redeem a share-link capability OFF the gate path. Those requests arrive
+ *     through a `public`/`service` gate and the app redeems the capability itself; there is no proxy
+ *     equivalent by design.
+ *   - the MANAGEMENT surface (`listPrincipals` / `issueKey` / `issueJwt` / `revokeKey`).
+ *
+ * There is NO gate evaluation here, no session→token exchange, and no cookie is ever written.
+ *
+ * There is also NO local mode. The SDK verifies IAM-issued tokens and nothing else, everywhere. Local
+ * development runs the real stack (`bun run local:up`), where the proxy fronts each service and IAM
+ * authenticates through its own `LOCAL_DEV_LOGIN` bypass — one dev bypass in the system, owned by the
+ * service that owns identity.
+ */
+
+import { API_KEY_PREFIX, type IamRpc, type MintFromKeyResult, PROXY_TOKEN_HEADER, TOKEN_REFRESH_SKEW_SECONDS } from '@fabrika/auth-core'
+import { buildAuthContext, IamClient } from './client'
+import { readRequestId } from './request'
+import type {
+	AuthContext,
+	IssuedJwt,
+	IssuedKey,
+	IssueFailure,
+	IssueJwtRequest,
+	IssueKeyRequest,
+	ListPrincipalsFailure,
+	PrincipalList,
+	RevokedKey,
+	RevokeFailure,
+} from './types'
+import { TokenVerifier } from './verify'
+
+// ── Public config surfaces ──────────────────────────────────────────────────────
+
+/** The env `createIam` reads. An app's Worker `Env` satisfies it structurally (extra fields are fine). */
+export interface IamEnv {
+	/** The IAM service binding. Typed as the `IamRpc` contract — never the IAM Worker. */
+	IAM?: IamRpc
+	/** IAM origin — the token `iss` this SDK verifies against. Canonicalized once in `createIam`. */
+	FABRIKA_IAM_URL?: string
+	/** Fallback app id when `opts.appId` is omitted. */
+	FABRIKA_APP_ID?: string
+}
+
+/** Options for `createIam`. `appId` falls back to `env.FABRIKA_APP_ID`. */
+export interface CreateIamOptions {
+	/** The IAM app id (baked in so it can never be mistyped). Falls back to `env.FABRIKA_APP_ID`. */
+	appId?: string
+}
+
+// ── Authentication result ────────────────────────────────────────────────────────
+
+/** Why an authentication attempt produced no `AuthContext`. */
+export type AuthFailureReason =
+	/** No proxy-injected token on the request — a `public` gate, or nothing is in front of the app. */
+	| 'no_token'
+	/** A token was presented and did not verify: signature, `iss`, `aud`, `exp` or claim shape. */
+	| 'invalid_token'
+	/** The credential resolved to nobody — IAM says the principal is gone or disabled. */
+	| 'unknown_principal'
+	/** IAM could not be consulted at all. NOT a decided negative — an incident, and never a 401. */
+	| 'unavailable'
+
+/**
+ * The outcome of `authenticate` / `redeemKey`. A DECIDED NEGATIVE (`invalid_token`,
+ * `unknown_principal`) is not the same as "could not consult IAM" (`unavailable`, 503) — the same
+ * three-state rule `@fabrika/proxy` implements. Neither method throws for either case.
+ */
+export type AuthResult =
+	| { ok: true; context: AuthContext }
+	| { ok: false; reason: AuthFailureReason; status: 401 | 403 | 503 }
+
+/** Failure half of `AuthResult` — what a caller maps to its own error envelope. */
+export type AuthFailure = Extract<AuthResult, { ok: false }>
+
+// ── Synthetic contexts ───────────────────────────────────────────────────────────
+
+/**
+ * The ANONYMOUS context — no principal, NO permissions (`can` → false, `scopedTo` → [] = none),
+ * `audit` a no-op. What an app sets on a request the proxy admitted through a `public` gate: there is
+ * no token to verify, and nothing about the caller is known. An RPC procedure's `.require` on such a
+ * request would (correctly) 403.
+ */
+export function anonymousContext(): AuthContext {
+	return {
+		ok: true,
+		principal: null,
+		can: () => false,
+		scopedTo: () => [],
+		audit: () => Promise.resolve(),
+	}
+}
+
+// ── Small helpers ────────────────────────────────────────────────────────────────
+
+/** Hex SHA-256 — the key-cache index, so no plaintext credential is ever held in memory as a map key. */
+async function digest(value: string): Promise<string> {
+	const bytes = new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(value)))
+	let hex = ''
+	for (const byte of bytes) {
+		hex += byte.toString(16).padStart(2, '0')
+	}
+	return hex
+}
+
+/**
+ * Per-binding cache of the access token minted from a `px_` share credential, keyed by the credential's
+ * SHA-256 digest and bounded — a share link redeemed on every request would otherwise pin an unbounded
+ * number of plaintext credentials for the process lifetime.
+ */
+const KEY_CACHE_MAX_ENTRIES = 256
+const keyTokenCache = new WeakMap<IamRpc, Map<string, { token: string; expiresAt: number }>>()
+
+function keyCacheFor(binding: IamRpc): Map<string, { token: string; expiresAt: number }> {
+	let cache = keyTokenCache.get(binding)
+	if (cache === undefined) {
+		cache = new Map()
+		keyTokenCache.set(binding, cache)
+	}
+	return cache
+}
+
+/** Insert with a hard bound, evicting the oldest entry (Map preserves insertion order). */
+function rememberKey(cache: Map<string, { token: string; expiresAt: number }>, key: string, entry: { token: string; expiresAt: number }): void {
+	if (!cache.has(key) && cache.size >= KEY_CACHE_MAX_ENTRIES) {
+		const oldest = cache.keys().next()
+		if (oldest.done !== true) {
+			cache.delete(oldest.value)
+		}
+	}
+	cache.set(key, entry)
+}
+
+// ── Iam ──────────────────────────────────────────────────────────────────────────
+
+/** Internal construction config — `createIam` assembles this; apps never build it directly. */
+interface IamConfig {
+	management: IamClient
+	binding: IamRpc
+	verifier: TokenVerifier
+	appId: string
+}
+
+/**
+ * The request-time IAM surface. Build it with `createIam` (the only intended entry point — the
+ * constructor takes an internal config). Bundles the management methods, token verification and
+ * share-link redemption, all bound to the env + app id resolved at construction.
+ */
+export class Iam {
+	private readonly management: IamClient
+	private readonly binding: IamRpc
+	private readonly verifier: TokenVerifier
+	private readonly appId: string
+
+	/** @internal — use `createIam`. */
+	constructor(config: IamConfig) {
+		this.management = config.management
+		this.binding = config.binding
+		this.verifier = config.verifier
+		this.appId = config.appId
+	}
+
+	// ── Management surface (delegated to the real client) ─────────────────────────
+
+	listPrincipals(req: Request): Promise<PrincipalList | ListPrincipalsFailure> {
+		return this.management.listPrincipals(req)
+	}
+
+	issueKey(req: Request, input: IssueKeyRequest): Promise<IssuedKey | IssueFailure> {
+		return this.management.issueKey(req, input)
+	}
+
+	issueJwt(req: Request, input: IssueJwtRequest): Promise<IssuedJwt | IssueFailure> {
+		return this.management.issueJwt(req, input)
+	}
+
+	revokeKey(req: Request, id: string): Promise<RevokedKey | RevokeFailure> {
+		return this.management.revokeKey(req, id)
+	}
+
+	// ── Authentication ────────────────────────────────────────────────────────────
+
+	/**
+	 * Resolve the caller from the token the PROXY injected, verifying it locally against the JWKS.
+	 * Never throws: an absent token, a token that does not verify, and an unreachable IAM are three
+	 * distinct `ok: false` results.
+	 */
+	authenticate(request: Request): Promise<AuthResult> {
+		const token = request.headers.get(PROXY_TOKEN_HEADER)?.trim() ?? ''
+		if (token === '') {
+			return Promise.resolve({ ok: false, reason: 'no_token', status: 401 })
+		}
+		return this.contextFor(token, readRequestId(request))
+	}
+
+	/**
+	 * Redeem an opaque `px_` share credential (or a passthrough JWT) into an `AuthContext` OFF the gate
+	 * path — the seam a capability/share link uses, where the token rides a query param or a cookie
+	 * rather than satisfying a gate. A `px_` key is exchanged once via `mintFromKey` and cached per
+	 * binding; anything else is verified locally with no IAM call. Never throws — map a failure to a 404
+	 * so the surface does not reveal whether the resource exists.
+	 */
+	async redeemKey(token: string): Promise<AuthResult> {
+		const requestId = crypto.randomUUID()
+		if (!token.startsWith(API_KEY_PREFIX)) {
+			// A passthrough JWT — verify locally, no IAM call.
+			return await this.contextFor(token, requestId)
+		}
+
+		const cache = keyCacheFor(this.binding)
+		const index = await digest(token)
+		const now = Math.floor(Date.now() / 1000)
+		const cached = cache.get(index)
+		if (cached !== undefined && cached.expiresAt - now > TOKEN_REFRESH_SKEW_SECONDS) {
+			const result = await this.contextFor(cached.token, requestId)
+			if (result.ok || result.reason === 'unavailable') {
+				// Unverifiable because IAM is down is NOT evidence against the cached token — say so and stop.
+				return result
+			}
+			// A cached token that no longer verifies (rotated key, revoked issuer) is dropped, not trusted.
+			cache.delete(index)
+		}
+
+		let minted: MintFromKeyResult
+		try {
+			minted = await this.binding.mintFromKey({ app: this.appId, key: token, requestId })
+		} catch {
+			// A transport failure is "we could not consult IAM", never a decided negative. Never log the
+			// error object: it can carry the credential or a request URL.
+			return { ok: false, reason: 'unavailable', status: 503 }
+		}
+		if (!minted.ok) {
+			return minted.reason === 'invalid_key'
+				? { ok: false, reason: 'invalid_token', status: 401 }
+				: { ok: false, reason: 'unknown_principal', status: 403 }
+		}
+		const result = await this.contextFor(minted.token, requestId)
+		if (result.ok) {
+			rememberKey(cache, index, { token: minted.token, expiresAt: minted.expiresAt })
+		}
+		return result
+	}
+
+	// ── Internals ─────────────────────────────────────────────────────────────────
+
+	/** Verify one token and wrap its claims in the `permits`-backed `AuthContext`. */
+	private async contextFor(token: string, requestId: string): Promise<AuthResult> {
+		const verified = await this.verifier.verify(token)
+		if (!verified.ok) {
+			return verified.reason === 'unavailable'
+				? { ok: false, reason: 'unavailable', status: 503 }
+				: { ok: false, reason: 'invalid_token', status: 401 }
+		}
+		return { ok: true, context: buildAuthContext(this.binding, this.appId, verified.claims, requestId) }
+	}
+}
+
+// ── createIam ──────────────────────────────────────────────────────────────────
+
+/**
+ * The single request-time entry point. Reads `env.IAM` and the IAM environment names, and returns an
+ * `Iam` bound to them. Throws if the app id, the binding or the issuer is missing or unusable —
+ * there is no mode in which any of the three is optional.
+ */
+export function createIam(env: IamEnv, opts: CreateIamOptions = {}): Iam {
+	const appId = opts.appId ?? env.FABRIKA_APP_ID
+	if (appId === undefined || appId === '') {
+		throw new Error('createIam: app id is required — pass opts.appId or set env.FABRIKA_APP_ID')
+	}
+
+	const binding = env.IAM
+	if (binding === undefined) {
+		throw new Error('createIam: the IAM service binding is missing (env.IAM) — check the IAM ServiceReference.')
+	}
+	const issuer = canonicalIssuer(env.FABRIKA_IAM_URL)
+	return new Iam({
+		management: new IamClient(binding, appId),
+		binding,
+		verifier: new TokenVerifier(binding, issuer, appId),
+		appId,
+	})
+}
+
+/**
+ * Canonicalize the issuer ONCE, at the boundary. It is a byte-exact contract — it is the token's `iss`,
+ * and jose compares it verbatim — so `https://iam.test/` and `https://iam.test` must not be two
+ * different issuers depending on which call site happened to trim.
+ */
+function canonicalIssuer(raw: string | undefined): string {
+	if (raw === undefined || raw.trim() === '') {
+		throw new Error('createIam: FABRIKA_IAM_URL is missing — it is the issuer every token is verified against.')
+	}
+	let url: URL
+	try {
+		url = new URL(raw.trim())
+	} catch {
+		throw new Error('createIam: FABRIKA_IAM_URL is not an absolute URL.')
+	}
+	if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+		throw new Error('createIam: FABRIKA_IAM_URL must be an http(s) origin.')
+	}
+	return url.origin
+}

package/src/index.ts

@@ -0,0 +1,69 @@
+// @fabrika/auth — the app-facing IAM SDK (the only package published to npm).
+//
+// Depends ONLY on @fabrika/auth-core: the binding is typed as the `IamRpc` contract (so the SDK
+// never imports the IAM service), and `can()`/`scopedTo()` reuse core's `permits`/`matchAction`.
+//
+// Enforcement lives in @fabrika/proxy (ADR-0007). Nothing exported here can evaluate a gate.
+
+export { IamClient } from './client'
+export { applyScope } from './scope'
+// The typed HTTP errors + the per-resource authorization helper a per-path gate cannot express.
+export { ForbiddenError, requirePermission, UnauthenticatedError } from './errors'
+export type { HttpError } from './errors'
+// Request-time surface: the single `createIam` entry point (verification + share-link redemption +
+// the management methods) and the anonymous context an app sets on a request the proxy admitted
+// through a `public` gate.
+export { anonymousContext, createIam, Iam } from './iam'
+export type { AuthFailure, AuthFailureReason, AuthResult, CreateIamOptions, IamEnv } from './iam'
+// The shared middleware contract consumed by `@fabrika/app`. Owned here so an app pipeline needs no
+// duplicate compatibility interface; the SDK itself no longer ships any middleware.
+export type { AuthCarrier, Middleware } from './middleware'
+// The HTTP transport for the SAME `IamRpc` contract, for a runtime with no Cloudflare service binding
+// (a long-running Bun/Node process). Drops into anywhere a binding goes — `createIam`, `IamClient`,
+// `env.IAM` — because the contract is unchanged and only the transport differs.
+export { HttpIamRpc, IamTransportError } from './rpc-http'
+export type { FetchLike, HttpIamRpcOptions } from './rpc-http'
+// Local verification of the proxy-injected access token. `createIam` wires it for you; it is exported
+// for an app that resolves a token outside the `Iam` surface.
+export { TokenVerifier } from './verify'
+export type { VerifyResult } from './verify'
+// Deploy-time helper: reconcile an app's declared AppSchema (authz vocabulary) into IAM (an
+// HTTP admin call, NOT over the service binding). Import from a deploy/provisioning step.
+export { reconcileSchema, ReconcileSchemaError } from './provision'
+export type { ReconcileSchemaOptions } from './provision'
+export type {
+	AuthContext,
+	IssuedJwt,
+	IssuedKey,
+	IssueFailure,
+	IssueJwtRequest,
+	IssueKeyRequest,
+	ListPrincipalsFailure,
+	PrincipalIdentity,
+	PrincipalList,
+	RevokedKey,
+	RevokeFailure,
+} from './types'
+
+// The header the proxy injects its verified token on. Re-exported so an app never spells it out.
+export { PROXY_TOKEN_HEADER } from '@fabrika/auth-core'
+
+// Re-export from core so apps need only depend on the SDK: DomainEvent (one event shape),
+// IamRpc (the binding contract — apps type their `env.IAM` as IamRpc without importing core),
+// Scope (the `{ type, value }` coordinate apps pass to `can()`), the AppSchema vocabulary types
+// apps DECLARE in `fabrika.schema.ts` for `reconcileSchema()`, and the per-path gate types
+// (`AppGates` & co.) apps DECLARE for the PROXY manifest — never for in-process enforcement.
+export type {
+	AppActionDef,
+	AppGates,
+	AppSchema,
+	AppScopeDef,
+	CredentialLocation,
+	DomainEvent,
+	GateKind,
+	GateRule,
+	IamRpc,
+	PrincipalListItem,
+	RoleDef,
+	Scope,
+} from '@fabrika/auth-core'