@fabrika/auth 0.2.0 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/auth",
-	"version": "0.2.0",
+	"version": "0.3.1",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -26,8 +26,9 @@
 		"test": "bun test"
 	},
 	"dependencies": {
-		"@fabrika/auth-core": "^0.2.0",
-		"@fabrika/jwks": "^0.2.0",
+		"zod": "^3.25.76",
+		"@fabrika/auth-core": "^0.3.1",
+		"@fabrika/jwks": "^0.3.1",
 		"jose": "^5.9.0"
 	}
 }

package/src/app-schema.ts

@@ -0,0 +1,34 @@
+import { type AppSchema, isActionAllowed } from '@fabrika/auth-core'
+import { z } from 'zod'
+
+/** Quote an untrusted fragment for an error message a run log may carry. */
+const quote = (value: string): string => `\`${value.slice(0, 80)}\``
+
+const scopeSchema = z.object({ type: z.string().min(1), label: z.string().min(1).optional() })
+const actionSchema = z.object({ action: z.string().min(1), description: z.string().min(1).optional() })
+const roleSchema = z.object({ name: z.string().min(1), description: z.string().min(1).optional(), permissions: z.array(z.string().min(1)) })
+// `roles[key] = …` would reach the prototype setter, so `__proto__` is refused rather than assigned.
+const roleKeySchema = z.string().min(1).refine((key) => key !== '__proto__')
+
+/**
+ * An app's authz vocabulary, as an app declares it and IAM reconciles it. Every role permission must
+ * name an action the same body declares — IAM's own rule, checked wherever the vocabulary is read.
+ */
+export const appSchemaSchema = z.object({
+	scopes: z.array(scopeSchema),
+	actions: z.array(actionSchema),
+	roles: z.record(roleKeySchema, roleSchema),
+}).superRefine((schema, ctx) => {
+	const catalog = schema.actions.map((action) => action.action)
+	for (const [key, role] of Object.entries(schema.roles)) {
+		for (const [index, pattern] of role.permissions.entries()) {
+			if (!isActionAllowed(pattern, catalog)) {
+				ctx.addIssue({
+					code: 'custom',
+					path: ['roles', key, 'permissions', index],
+					message: `role ${quote(key)} references unknown action: ${quote(pattern)}`,
+				})
+			}
+		}
+	}
+}) satisfies z.ZodType<AppSchema, z.ZodTypeDef, unknown>

package/src/client.ts

@@ -1,26 +1,14 @@
 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'
+import type { AuthContext, ListPrincipalsFailure, PrincipalIdentity, PrincipalList } 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
+ * session / API key) and an ANONYMOUS one (a standalone share link) — the latter has
  * `principal = null`; `audit` then attributes to the credential label + token id, principal null.
  */
 class RealAuthContext implements AuthContext {
@@ -32,9 +20,9 @@ class RealAuthContext implements AuthContext {
 		private readonly permissions: PermissionEntry[],
 		private readonly requestId: string,
 		readonly principal: PrincipalIdentity | null,
-		/** Audit actor label — the principal's label, or the credential/jwt label. */
+		/** Audit actor label — the principal's label, or the credential label. */
 		private readonly auditLabel: string,
-		/** The credential/token id, for the audit linkage of an anonymous caller (null when bound). */
+		/** The credential id, for the audit linkage of an anonymous caller (null when bound). */
 		private readonly anonymousTokenId: string | null,
 	) {}
 
@@ -68,8 +56,8 @@ class RealAuthContext implements AuthContext {
 
 /**
  * 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,
+ * uses (the proxy-injected token). 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`).
  */
@@ -109,85 +97,9 @@ export class IamClient {
 		}
 		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

@@ -7,7 +7,7 @@
  * 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
+ * There is deliberately no login-bounce error here: since ADR-0022 the proxy 302s an unauthenticated
  * browser, so an app never has to produce a login URL of its own.
  */
 

package/src/iam.ts

@@ -1,15 +1,12 @@
 /**
  * `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
+ * Since [ADR-0022](../../../docs/decisions/0022-the-proxy-is-the-only-enforcement-point.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`).
+ *   - `listPrincipals` — the app's people directory.
  *
  * There is NO gate evaluation here, no session→token exchange, and no cookie is ever written.
  *
@@ -19,21 +16,10 @@
  * service that owns identity.
  */
 
-import { API_KEY_PREFIX, type IamRpc, type MintFromKeyResult, PROXY_TOKEN_HEADER, TOKEN_REFRESH_SKEW_SECONDS } from '@fabrika/auth-core'
+import { type IamRpc, PROXY_TOKEN_HEADER } 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 type { AuthContext, ListPrincipalsFailure, PrincipalList } from './types'
 import { TokenVerifier } from './verify'
 
 // ── Public config surfaces ──────────────────────────────────────────────────────
@@ -68,9 +54,9 @@ export type AuthFailureReason =
 	| '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.
+ * The outcome of `authenticate`. 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. `authenticate` throws for neither case.
  */
 export type AuthResult =
 	| { ok: true; context: AuthContext }
@@ -97,46 +83,6 @@ export function anonymousContext(): AuthContext {
 	}
 }
 
-// ── 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. */
@@ -149,8 +95,8 @@ interface IamConfig {
 
 /**
  * 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.
+ * constructor takes an internal config). Bundles token verification and `listPrincipals`, both bound
+ * to the env + app id resolved at construction.
  */
 export class Iam {
 	private readonly management: IamClient
@@ -172,18 +118,6 @@ export class Iam {
 		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 ────────────────────────────────────────────────────────────
 
 	/**
@@ -199,54 +133,6 @@ export class Iam {
 		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`. */

package/src/index.ts

@@ -3,15 +3,15 @@
 // 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.
+// Enforcement lives in @fabrika/proxy (ADR-0022). 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
+// Request-time surface: the single `createIam` entry point (verification + `listPrincipals`) 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'
@@ -30,20 +30,10 @@ 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'
+// The one schema for an app's declared vocabulary; every reader of an `AppSchema` parses with it.
+export { appSchemaSchema } from './app-schema'
 export type { ReconcileSchemaOptions } from './provision'
-export type {
-	AuthContext,
-	IssuedJwt,
-	IssuedKey,
-	IssueFailure,
-	IssueJwtRequest,
-	IssueKeyRequest,
-	ListPrincipalsFailure,
-	PrincipalIdentity,
-	PrincipalList,
-	RevokedKey,
-	RevokeFailure,
-} from './types'
+export type { AuthContext, ListPrincipalsFailure, PrincipalIdentity, PrincipalList } 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'

package/src/middleware.ts

@@ -2,7 +2,7 @@
  * 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).
+ * itself ships no middleware: enforcement is the proxy's job (ADR-0022).
  *
  * A middleware runs in order; it may:
  *   - mutate `ctx` (e.g. set `ctx.auth`),

package/src/provision.ts

@@ -6,7 +6,7 @@
 // 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
+// The same deploy step optionally projects the app's RETURN ORIGINS (ADR-0022) — 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.
@@ -21,6 +21,11 @@
 // re-sending the same return-origin set.
 
 import type { AppSchema } from '@fabrika/auth-core'
+import { z } from 'zod'
+
+const adminErrorSchema = z.object({
+	error: z.union([z.string(), z.object({ message: z.string() }).transform(value => value.message)]),
+})
 
 export interface ReconcileSchemaOptions {
 	/** The IAM Worker's admin origin, e.g. `https://iam.example.com` (trailing slash ok). */
@@ -30,21 +35,18 @@ export interface ReconcileSchemaOptions {
 	/** 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.
+	 * Every origin IAM may hand this app a session at (ADR-0022), 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.
+	 * exists to prevent. An empty array is a caller error: an app is never un-registered by 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.
+	 * An IAM-issued `px_` ADMIN key, sent as `Authorization: Bearer`. Effectively required: IAM's
+	 * `/admin/*` accepts only a bearer and refuses a credential-less call in every environment.
 	 */
 	adminKey?: string
 	/** Cancels the in-flight request when schema reconciliation belongs to a deploy lifecycle. */
@@ -64,17 +66,8 @@ export class ReconcileSchemaError extends 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
+	const result = adminErrorSchema.safeParse(value)
+	return result.success ? result.data.error : null
 }
 
 /**

package/src/request.ts

@@ -1,7 +1,6 @@
 // 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 —
+// `listPrincipals` RPC. Precedence: the token the PROXY injected (the one it already verified), then
+// an `Authorization: Bearer` (a machine `px_` key). 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'
@@ -10,7 +9,7 @@ import { PROXY_TOKEN_HEADER } from '@fabrika/auth-core'
 const RAY_HEADER = 'cf-ray'
 
 export interface ForwardedCredentials {
-	/** The native credential (a `px_` key / passthrough JWT / `px_token`), or null when absent. */
+	/** The native credential (a `px_` key / `px_token`), or null when absent. */
 	credential: string | null
 	/** cf-ray, or a fresh UUID when absent (e.g. local dev). */
 	requestId: string

package/src/rpc-http.ts

@@ -42,26 +42,53 @@
  */
 
 import type {
+	ApproveDeviceAuthorizationInput,
+	ApproveDeviceAuthorizationResult,
 	AuditInput,
+	DenyDeviceAuthorizationResult,
 	IamRpc,
-	IssueJwtInput,
-	IssueJwtResult,
+	InspectDeviceAuthorizationInput,
+	InspectDeviceAuthorizationResult,
 	IssueKeyInput,
 	IssueKeyResult,
 	Jwks,
+	ListOwnDeviceAuthorizationsInput,
+	ListOwnDeviceAuthorizationsResult,
 	ListPrincipalsInput,
 	ListPrincipalsResult,
 	MintFromKeyInput,
 	MintFromKeyResult,
 	MintTokenInput,
 	MintTokenResult,
-	PrincipalListItem,
-	PrincipalType,
-	PublicJwk,
 	RevokeKeyInput,
 	RevokeKeyResult,
 } from '@fabrika/auth-core'
-import { booleanField, numberField, prop, stringField } from './json'
+import {
+	parseApproveDeviceAuthorizationResult,
+	parseDenyDeviceAuthorizationResult,
+	parseInspectDeviceAuthorizationResult,
+	parseListOwnDeviceAuthorizationsResult,
+} from '@fabrika/auth-core'
+import { parseJwks } from '@fabrika/jwks'
+import { z } from 'zod'
+
+const mintSuccessSchema = z.object({ token: z.string().min(1), expiresAt: z.number().finite() })
+const issueKeySuccessSchema = z.object({
+	token: z.string(),
+	id: z.string(),
+	principalId: z.string().optional().catch(undefined),
+}).transform(({ principalId, ...result }) => ({ ...result, ...(principalId === undefined ? {} : { principalId }) }))
+const revokeSuccessSchema = z.object({ revoked: z.boolean() })
+const principalsSuccessSchema = z.object({
+	principals: z.array(z.object({
+		id: z.string(),
+		label: z.string(),
+		type: z.string().transform((value): 'service' | 'user' => value === 'service' ? 'service' : 'user'),
+		email: z.string().nullable().catch(null),
+		disabled: z.boolean().catch(false),
+	})),
+})
+const failureSchema = z.object({ ok: z.literal(false), reason: z.string().catch('') })
 
 /** Default per-call timeout. A hung IAM must fail the request, not hold a connection open forever. */
 const DEFAULT_TIMEOUT_MS = 5_000
@@ -98,6 +125,26 @@ export class IamTransportError extends Error {
 }
 
 export class HttpIamRpc implements IamRpc {
+	async inspectDeviceAuthorization(input: InspectDeviceAuthorizationInput): Promise<InspectDeviceAuthorizationResult> {
+		const result = parseInspectDeviceAuthorizationResult(await this.call('inspectDeviceAuthorization', input))
+		if (!result) throw new IamTransportError('inspectDeviceAuthorization')
+		return result
+	}
+	async approveDeviceAuthorization(input: ApproveDeviceAuthorizationInput): Promise<ApproveDeviceAuthorizationResult> {
+		const result = parseApproveDeviceAuthorizationResult(await this.call('approveDeviceAuthorization', input))
+		if (!result) throw new IamTransportError('approveDeviceAuthorization')
+		return result
+	}
+	async denyDeviceAuthorization(input: InspectDeviceAuthorizationInput): Promise<DenyDeviceAuthorizationResult> {
+		const result = parseDenyDeviceAuthorizationResult(await this.call('denyDeviceAuthorization', input))
+		if (!result) throw new IamTransportError('denyDeviceAuthorization')
+		return result
+	}
+	async listOwnDeviceAuthorizations(input: ListOwnDeviceAuthorizationsInput): Promise<ListOwnDeviceAuthorizationsResult> {
+		const result = parseListOwnDeviceAuthorizationsResult(await this.call('listOwnDeviceAuthorizations', input))
+		if (!result) throw new IamTransportError('listOwnDeviceAuthorizations')
+		return result
+	}
 	private readonly origin: string
 	private readonly key: string
 	private readonly timeoutMs: number
@@ -134,28 +181,11 @@ export class HttpIamRpc implements IamRpc {
 		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) {
+		const result = issueKeySuccessSchema.safeParse(body)
+		if (!result.success) {
 			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 }
+		return { ok: true, ...result.data }
 	}
 
 	async revokeKey(input: RevokeKeyInput): Promise<RevokeKeyResult> {
@@ -164,11 +194,11 @@ export class HttpIamRpc implements IamRpc {
 		if (failure !== null) {
 			return { ok: false, reason: oneOf(failure, [...ISSUE_REASONS, 'not_found'], 'not_allowed') }
 		}
-		const revoked = booleanField(body, 'revoked')
-		if (revoked === undefined) {
+		const result = revokeSuccessSchema.safeParse(body)
+		if (!result.success) {
 			throw new IamTransportError('revokeKey')
 		}
-		return { ok: true, revoked }
+		return { ok: true, ...result.data }
 	}
 
 	async listPrincipals(input: ListPrincipalsInput): Promise<ListPrincipalsResult> {
@@ -177,56 +207,22 @@ export class HttpIamRpc implements IamRpc {
 		if (failure !== null) {
 			return { ok: false, reason: oneOf(failure, ISSUE_REASONS, 'not_allowed') }
 		}
-		const raw = prop(body, 'principals')
-		if (!Array.isArray(raw)) {
+		const result = principalsSuccessSchema.safeParse(body)
+		if (!result.success) {
 			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 }
+		return { ok: true, ...result.data }
 	}
 
 	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)) {
+		const jwks = parseJwks(await this.call('getJwks', {}))
+		if (jwks === null) {
 			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 }
+		return jwks
 	}
 
 	async audit(event: AuditInput): Promise<void> {
@@ -271,32 +267,28 @@ export class HttpIamRpc implements IamRpc {
 	}
 }
 
-/** The five delegation-path failure reasons `issueKey` / `issueJwt` / `listPrincipals` share. */
+/** The five delegation-path failure reasons `issueKey` / `revokeKey` / `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.
+ * Only literal false selects denial; missing or malformed reasons use the operation's deny fallback.
+ * Success fields are decoded independently of `ok`, preserving the SDK's tolerant wire contract.
  */
 function readFailure(body: unknown): string | null {
-	if (prop(body, 'ok') !== false) {
-		return null
-	}
-	return stringField(body, 'reason') ?? ''
+	const result = failureSchema.safeParse(body)
+	return result.success ? result.data.reason : null
 }
 
 /** 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) {
+	const result = mintSuccessSchema.safeParse(body)
+	if (!result.success) {
 		throw new IamTransportError(method)
 	}
-	return { ok: true, token, expiresAt }
+	return { ok: true, ...result.data }
 }
 
 /**
@@ -312,7 +304,3 @@ function oneOf<T extends string>(value: string, allowed: readonly T[], fallback:
 	}
 	return fallback
 }
-
-function principalType(value: string): PrincipalType {
-	return value === 'service' ? 'service' : 'user'
-}

package/src/types.ts

@@ -1,4 +1,4 @@
-import type { DomainEvent, IssueKeyServiceSpec, KeyGrant, PrincipalListItem, PrincipalType, Scope } from '@fabrika/auth-core'
+import type { DomainEvent, PrincipalListItem, PrincipalType, Scope } from '@fabrika/auth-core'
 
 /**
  * The resolved caller's identity — who Access says you are, as the IAM Worker recorded
@@ -19,7 +19,7 @@ export interface PrincipalIdentity {
 //
 // Every method returns a discriminated union whose members all carry an `ok` field,
 // so app code branches once on `result.ok`. The ok:true members are the rich
-// `AuthContext` / `IssuedKey` / `IssuedJwt` surfaces; the ok:false members are
+// `AuthContext` / `PrincipalList` surfaces; the ok:false members are
 // the typed failures below, each carrying the HTTP status the app should return.
 //
 // The ok:true surfaces are modelled as *interfaces* (not concrete classes) so that both
@@ -35,7 +35,7 @@ export interface AuthContext {
 	readonly ok: true
 	/**
 	 * The resolved caller identity (id / type / label), or `null` for an ANONYMOUS credential — a
-	 * passthrough JWT or a standalone (no-principal) share-link/API key. For stamping domain rows and
+	 * standalone (no-principal) share link. For stamping domain rows and
 	 * display — NOT a permission surface (authorization stays `can` / `scopedTo`, which work the same
 	 * either way). Stamp `created_by` with `principal?.id ?? null`.
 	 */
@@ -61,38 +61,6 @@ export interface AuthContext {
 	audit(event: DomainEvent): Promise<void>
 }
 
-/** Successful `issueKey` — the plaintext `px_` token returned ONCE; `id` is the durable revoke handle. */
-export interface IssuedKey {
-	readonly ok: true
-	/** Plaintext `px_` token — show once, never persist. Carry as a bearer or a share-link path token. */
-	token: string
-	/** The credential id (safe to store/reference; pass to `revokeKey`). */
-	id: string
-	/**
-	 * The principal the key is bound to — the freshly-created service principal (`service` mode) or the
-	 * issuer's own id (self-bind); absent for a standalone (anonymous) share link.
-	 */
-	principalId?: string
-}
-
-/** Successful `issueJwt` — the signed passthrough token returned ONCE (audit-only, not revocable). */
-export interface IssuedJwt {
-	readonly ok: true
-	/** The signed JWT — carry it as `Authorization: Bearer`. Verified locally by the app's SDK. */
-	token: string
-	/** Expiry (unix seconds). */
-	expiresAt: number
-	/** The token's audit reference (there is no DB row to revoke). */
-	id: string
-}
-
-/** Successful `revokeKey`. `revoked` is false when the credential was already revoked. */
-export interface RevokedKey {
-	readonly ok: true
-	/** True when this call flipped the credential to revoked; false if it was already revoked (idempotent). */
-	revoked: boolean
-}
-
 /** Successful `listPrincipals` — the app's people directory (user principals). */
 export interface PrincipalList {
 	readonly ok: true
@@ -101,61 +69,9 @@ export interface PrincipalList {
 
 // ── Failures ─────────────────────────────────────────────────────────────────
 
-/** `issueKey` / `issueJwt` failure. missing/invalid → 401; unknown_principal/disabled/not_allowed → 403. */
-export interface IssueFailure {
-	readonly ok: false
-	reason: 'missing_token' | 'invalid_token' | 'unknown_principal' | 'disabled' | 'not_allowed'
-	status: 401 | 403
-}
-
-/** `revokeKey` failure. missing/invalid → 401; unknown/disabled/not_allowed → 403; not_found → 404. */
-export interface RevokeFailure {
-	readonly ok: false
-	reason: 'missing_token' | 'invalid_token' | 'unknown_principal' | 'disabled' | 'not_allowed' | 'not_found'
-	status: 401 | 403 | 404
-}
-
 /** `listPrincipals` failure. missing/invalid → 401; unknown_principal/disabled/not_allowed → 403. */
 export interface ListPrincipalsFailure {
 	readonly ok: false
 	reason: 'missing_token' | 'invalid_token' | 'unknown_principal' | 'disabled' | 'not_allowed'
 	status: 401 | 403
 }
-
-// ── Inputs ───────────────────────────────────────────────────────────────────
-
-/**
- * App-supplied portion of `issueKey` — an opaque, stored, revocable `px_` credential (API key /
- * share link). The SDK fills `app` and the issuer's forwarded credential (the caller's `px_token` /
- * `px_` key + requestId) from the request, so app code can never self-assert the issuer.
- */
-export interface IssueKeyRequest {
-	/**
-	 * Create a NEW machine (service) principal and bind the key to it — the folded service-token
-	 * path. The issuer must hold every `permissions` action on `scope`. When set, `principalId` /
-	 * `permissions` (the bind / standalone modes) are ignored.
-	 */
-	service?: IssueKeyServiceSpec
-	/**
-	 * Bind to a principal (the credential then carries that principal's LIVE perms; inline
-	 * `permissions` downscope it). v1: only the issuer's OWN id. Omit for a standalone share link.
-	 */
-	principalId?: string
-	/** Inline grants — the frozen set (standalone share link) and/or a downscope restriction (bound). */
-	permissions?: KeyGrant[]
-	label?: string
-	/** Absolute credential expiry (unix seconds); omitted = no expiry. */
-	expiresAt?: number
-}
-
-/**
- * App-supplied portion of `issueJwt` — a stateless passthrough access token (audit-only, TTL-bounded,
- * NOT revocable). The SDK fills `app` and the issuer's forwarded credential from the request.
- */
-export interface IssueJwtRequest {
-	/** Inline grants the passthrough token carries (frozen at issue). */
-	permissions: KeyGrant[]
-	label?: string
-	/** Requested lifetime (seconds); capped by the server. Defaults to the standard token TTL. */
-	ttl?: number
-}

package/src/verify.ts

@@ -1,7 +1,7 @@
 /**
  * Local access-token verification — the only thing this SDK still does with a credential.
  *
- * Since [ADR-0007](../../../docs/decisions/0007-proxy-based-auth-enforcement.md) the PROXY is the only
+ * Since [ADR-0022](../../../docs/decisions/0022-the-proxy-is-the-only-enforcement-point.md) the PROXY is the only
  * enforcement point: it matches the app's gates, resolves the credential, and injects the verified
  * token as `PROXY_TOKEN_HEADER`. The app must NOT trust that header blindly, so every token is
  * re-verified here against IAM's published JWKS — signature, `iss`, `aud`, `exp` — before it can

package/src/json.ts

@@ -1,31 +0,0 @@
-/**
- * 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
-}