@fabrika/auth 0.3.3 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/auth",
-	"version": "0.3.3",
+	"version": "0.4.0",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -27,8 +27,8 @@
 	},
 	"dependencies": {
 		"zod": "^3.25.76",
-		"@fabrika/auth-core": "^0.3.3",
-		"@fabrika/jwks": "^0.3.3",
+		"@fabrika/auth-core": "^0.4.0",
+		"@fabrika/jwks": "^0.4.0",
 		"jose": "^5.9.0"
 	}
 }

package/src/app-schema.ts

@@ -1,25 +1,236 @@
-import { type AppSchema, isActionAllowed } from '@fabrika/auth-core'
+import {
+	type AppSchema,
+	BUILTIN_ROLE_KEYS,
+	displayNameProblem,
+	isActionAllowed,
+	LOCALES,
+	mailTemplateProblems,
+	type MessageKind,
+} 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() })
+// `record[key] = …` would reach the prototype setter, so `__proto__` is refused rather than assigned.
+const keySchema = z.string().min(1).refine((key) => key !== '__proto__')
+
+const scopeSchema = z.object({
+	type: z.string().min(1),
+	label: z.string().min(1).optional(),
+	in: z.string().min(1).optional(),
+	creator: z.string().min(1).optional(),
+	members: z.object({ manage: z.string().min(1), list: z.string().min(1) }).optional(),
+	directory: z.literal('labels').optional(),
+	lookups: z.array(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__')
+const roleSchema = z.object({
+	name: z.string().min(1),
+	description: z.string().min(1).optional(),
+	permissions: z.array(z.string().min(1)),
+	member: z.object({ scope: z.string().min(1), assignableBy: z.array(z.string().min(1)).optional() }).optional(),
+	external: z.literal(true).optional(),
+})
+/** A link lives at most a year; the mount's `maxDays` is the bound a contract states below that. */
+const MAX_LINK_DAYS = 365
+const linkSchema = z.object({
+	dimension: z.string().min(1),
+	grants: z.array(z.string().min(1)).min(1),
+	issuedBy: z.string().min(1),
+	maxDays: z.number().int().min(1).max(MAX_LINK_DAYS),
+})
+const delegationSchema = z.object({
+	action: z.string().min(1),
+	dimension: z.string().min(1),
+	purpose: z.enum(['members', 'creates']),
+})
+
+/** A job or webhook name of a contract; an `app` workload is named by the consuming application's id. */
+const WORKLOAD_NAME = /^[A-Za-z][A-Za-z0-9_]{0,63}$/
+const APP_ID = /^[a-z0-9][a-z0-9-]{0,63}$/
+const workloadSchema = z.discriminatedUnion('kind', [
+	z.object({
+		kind: z.literal('job'),
+		name: z.string().regex(WORKLOAD_NAME),
+		actions: z.array(z.string().min(1)),
+		issues: z.string().min(1).optional(),
+	}),
+	z.object({ kind: z.literal('webhook'), name: z.string().regex(WORKLOAD_NAME), actions: z.array(z.string().min(1)) }),
+	z.object({ kind: z.literal('app'), name: z.string().regex(APP_ID), actions: z.array(z.string().min(1)) }),
+])
+
+type Issue = { path: (string | number)[]; message: string }
+
+/** The membership and link declarations IAM acts on. Every name must resolve inside the same body. */
+function membershipIssues(schema: z.infer<typeof appSchemaShape>): Issue[] {
+	const issues: Issue[] = []
+	const catalog = new Set(schema.actions.map((action) => action.action))
+	const dimensions = new Map(schema.scopes.map((scope) => [scope.type, scope]))
+	const exactAction = (path: (string | number)[], action: string): void => {
+		if (!catalog.has(action)) issues.push({ path, message: `${quote(action)} is not an exact action of the catalog` })
+	}
+	const membershipRoleOf = (key: string, dimension: string): boolean => {
+		const role = Object.hasOwn(schema.roles, key) ? schema.roles[key] : undefined
+		return role?.member?.scope === dimension
+	}
+	// IAM counts an application-wide role (no `member`) held globally as an assigner in every value (ADR-0022 rule 6).
+	const assignerOf = (key: string, dimension: string): boolean => {
+		const role = Object.hasOwn(schema.roles, key) ? schema.roles[key] : undefined
+		return role !== undefined && !BUILTIN_ROLE_KEYS.includes(key) && (role.member === undefined || role.member.scope === dimension)
+	}
+
+	for (const [index, scope] of schema.scopes.entries()) {
+		if (scope.in !== undefined && (scope.in === scope.type || !dimensions.has(scope.in))) {
+			issues.push({ path: ['scopes', index, 'in'], message: `scope ${quote(scope.type)} is in an undeclared scope: ${quote(scope.in)}` })
+		}
+		if (scope.creator !== undefined && !membershipRoleOf(scope.creator, scope.type)) {
+			issues.push({
+				path: ['scopes', index, 'creator'],
+				message: `the creator of scope ${quote(scope.type)} must be a membership role of that scope: ${quote(scope.creator)}`,
+			})
+		}
+		if (scope.members !== undefined) {
+			exactAction(['scopes', index, 'members', 'manage'], scope.members.manage)
+			exactAction(['scopes', index, 'members', 'list'], scope.members.list)
+		}
+		if (scope.lookups !== undefined && scope.members === undefined) {
+			issues.push({ path: ['scopes', index, 'lookups'], message: `scope ${quote(scope.type)} declares lookups without members` })
+		}
+		for (const [lookup, action] of (scope.lookups ?? []).entries()) {
+			exactAction(['scopes', index, 'lookups', lookup], action)
+		}
+	}
+	if (schema.members !== undefined) {
+		exactAction(['members', 'manage'], schema.members.manage)
+		exactAction(['members', 'list'], schema.members.list)
+	}
+	if (schema.directory !== undefined && schema.members === undefined) {
+		issues.push({ path: ['directory'], message: 'the application declares a directory without members' })
+	}
+	for (const scope of schema.scopes) {
+		const seen = new Set<string>([scope.type])
+		for (let next = scope.in; next !== undefined; next = dimensions.get(next)?.in) {
+			if (seen.has(next)) {
+				issues.push({ path: ['scopes'], message: `scope ${quote(scope.type)} contains itself` })
+				break
+			}
+			seen.add(next)
+		}
+	}
+	for (const [key, role] of Object.entries(schema.roles)) {
+		if (BUILTIN_ROLE_KEYS.includes(key) && (role.member !== undefined || schema.contract === true)) {
+			issues.push({
+				path: ['roles', key, 'name'],
+				message: `role ${quote(key)} is a built-in IAM role; a membership role or a contract application role needs another key`,
+			})
+		}
+		if (role.external === true && role.member === undefined) {
+			issues.push({ path: ['roles', key, 'external'], message: `role ${quote(key)} is declared external and is not a membership role` })
+		}
+		for (const [index, assigner] of (role.member?.assignableBy ?? []).entries()) {
+			if (role.member !== undefined && !assignerOf(assigner, role.member.scope)) {
+				issues.push({
+					path: ['roles', key, 'member', 'assignableBy', index],
+					message: `role ${quote(key)} is assignable only by a membership role of its scope or an application-wide role, not ${quote(assigner)}`,
+				})
+			}
+		}
+	}
+	for (const [mount, link] of Object.entries(schema.links ?? {})) {
+		if (!dimensions.has(link.dimension)) {
+			issues.push({ path: ['links', mount, 'dimension'], message: `link mount ${quote(mount)} names an undeclared scope: ${quote(link.dimension)}` })
+		}
+		for (const [index, grant] of link.grants.entries()) exactAction(['links', mount, 'grants', index], grant)
+		exactAction(['links', mount, 'issuedBy'], link.issuedBy)
+	}
+	const workloads = new Set<string>()
+	for (const [index, workload] of (schema.workloads ?? []).entries()) {
+		if (schema.contract !== true) {
+			issues.push({ path: ['workloads', index, 'kind'], message: 'only a contract application declares workloads' })
+		}
+		const key = `${workload.kind}:${workload.name}`
+		if (workloads.has(key)) issues.push({ path: ['workloads', index, 'name'], message: `workload ${quote(key)} is declared twice` })
+		workloads.add(key)
+		for (const [position, action] of workload.actions.entries()) exactAction(['workloads', index, 'actions', position], action)
+		if (workload.kind === 'job' && workload.issues !== undefined) {
+			const link = Object.hasOwn(schema.links ?? {}, workload.issues) ? schema.links?.[workload.issues] : undefined
+			if (link === undefined) {
+				issues.push({
+					path: ['workloads', index, 'issues'],
+					message: `job ${quote(workload.name)} issues an undeclared link mount: ${quote(workload.issues)}`,
+				})
+			} else if (![link.issuedBy, ...link.grants].every((action) => workload.actions.includes(action))) {
+				issues.push({
+					path: ['workloads', index, 'issues'],
+					message: `job ${quote(workload.name)} issues links of ${quote(workload.issues)} without holding its issuedBy and every grant`,
+				})
+			}
+		}
+	}
+	for (const [endpoint, delegation] of Object.entries(schema.delegations ?? {})) {
+		const dimension = dimensions.get(delegation.dimension)
+		exactAction(['delegations', endpoint, 'action'], delegation.action)
+		if (dimension === undefined) {
+			issues.push({
+				path: ['delegations', endpoint, 'dimension'],
+				message: `endpoint ${quote(endpoint)} names an undeclared scope: ${quote(delegation.dimension)}`,
+			})
+		} else if (delegation.purpose === 'members' && dimension.members?.manage !== delegation.action) {
+			issues.push({
+				path: ['delegations', endpoint, 'action'],
+				message: `endpoint ${quote(endpoint)} manages members only with the members.manage action of ${quote(delegation.dimension)}`,
+			})
+		} else if (delegation.purpose === 'creates' && (dimension.creator === undefined || dimension.in !== undefined)) {
+			issues.push({
+				path: ['delegations', endpoint, 'dimension'],
+				message: `endpoint ${quote(endpoint)} creates ${quote(delegation.dimension)}, which needs a creator role and no containing scope`,
+			})
+		}
+	}
+	return issues
+}
+
+const appSchemaShape = z.object({
+	scopes: z.array(scopeSchema),
+	actions: z.array(actionSchema),
+	roles: z.record(keySchema, roleSchema),
+	contract: z.boolean().optional(),
+	links: z.record(keySchema, linkSchema).optional(),
+	delegations: z.record(keySchema, delegationSchema).optional(),
+	workloads: z.array(workloadSchema).optional(),
+	locale: z.enum(LOCALES).optional(),
+	displayName: z.string().superRefine((value, ctx) => {
+		const problem = displayNameProblem(value)
+		if (problem !== null) ctx.addIssue({ code: 'custom', message: `the display name ${problem}` })
+	}).optional(),
+	mail: z.object({ invitation: mailLocales('invitation'), enrollment: mailLocales('enrollment'), reset: mailLocales('reset') }).strict().partial()
+		.optional(),
+	members: z.object({ manage: z.string().min(1), list: z.string().min(1) }).optional(),
+	directory: z.literal('labels').optional(),
+})
+
+/** One message's templates by language, each refused with the same rule the contract build applies. */
+function mailLocales(kind: MessageKind) {
+	const template = z.object({ subject: z.string(), text: z.string(), html: z.string().optional() }).strict()
+	return z.record(z.enum(LOCALES), template).superRefine((templates, ctx) => {
+		for (const [locale, value] of Object.entries(templates)) {
+			for (const problem of mailTemplateProblems(kind, value)) {
+				ctx.addIssue({ code: 'custom', path: [locale], message: `mail.${kind}.${locale}: ${problem}` })
+			}
+		}
+	})
+}
 
 /**
  * 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.
+ * name an action the same body declares — IAM's own rule, checked wherever the vocabulary is read. A
+ * contract application's roles list exact actions, and a membership role names a declared scope. The
+ * membership and link declarations name only scopes, roles and exact actions of the same body.
  */
-export const appSchemaSchema = z.object({
-	scopes: z.array(scopeSchema),
-	actions: z.array(actionSchema),
-	roles: z.record(roleKeySchema, roleSchema),
-}).superRefine((schema, ctx) => {
+export const appSchemaSchema = appSchemaShape.superRefine((schema, ctx) => {
 	const catalog = schema.actions.map((action) => action.action)
+	const scopes = schema.scopes.map((scope) => scope.type)
 	for (const [key, role] of Object.entries(schema.roles)) {
 		for (const [index, pattern] of role.permissions.entries()) {
 			if (!isActionAllowed(pattern, catalog)) {
@@ -28,7 +239,23 @@ export const appSchemaSchema = z.object({
 					path: ['roles', key, 'permissions', index],
 					message: `role ${quote(key)} references unknown action: ${quote(pattern)}`,
 				})
+			} else if (schema.contract === true && pattern.includes('*')) {
+				ctx.addIssue({
+					code: 'custom',
+					path: ['roles', key, 'permissions', index],
+					message: `role ${quote(key)} of a contract application lists the wildcard ${quote(pattern)}; list exact actions`,
+				})
 			}
 		}
+		if (role.member !== undefined && !scopes.includes(role.member.scope)) {
+			ctx.addIssue({
+				code: 'custom',
+				path: ['roles', key, 'member', 'scope'],
+				message: `membership role ${quote(key)} names an undeclared scope: ${quote(role.member.scope)}`,
+			})
+		}
+	}
+	for (const issue of membershipIssues(schema)) {
+		ctx.addIssue({ code: 'custom', ...issue })
 	}
 }) satisfies z.ZodType<AppSchema, z.ZodTypeDef, unknown>

package/src/client.ts

@@ -1,7 +1,7 @@
-import type { AccessTokenClaims, DomainEvent, IamRpc, PermissionEntry, Scope } from '@fabrika/auth-core'
-import { permits, scopedValues } from '@fabrika/auth-core'
+import type { AccessTokenClaims, DomainEvent, LinkTokenClaims, OAuthTokenClaims, PermissionEntry, Scope } from '@fabrika/auth-core'
+import { isWorkloadKind, permits, scopedValues } from '@fabrika/auth-core'
 import { readCredentials } from './request'
-import type { AuthContext, ListPrincipalsFailure, PrincipalIdentity, PrincipalList } from './types'
+import type { AuthContext, IamBinding, ListPrincipalsFailure, PrincipalIdentity, PrincipalList } from './types'
 
 // ── AuthContext (real) ─────────────────────────────────────────────────────────
 
@@ -15,8 +15,9 @@ class RealAuthContext implements AuthContext {
 	readonly ok = true
 
 	constructor(
-		private readonly binding: IamRpc,
-		private readonly appId: string,
+		private readonly binding: IamBinding,
+		/** The verified token this context was built from — IAM reads the audit event's app from it. */
+		private readonly token: string,
 		private readonly permissions: PermissionEntry[],
 		private readonly requestId: string,
 		readonly principal: PrincipalIdentity | null,
@@ -24,6 +25,8 @@ class RealAuthContext implements AuthContext {
 		private readonly auditLabel: string,
 		/** The credential id, for the audit linkage of an anonymous caller (null when bound). */
 		private readonly anonymousTokenId: string | null,
+		readonly oauth: OAuthTokenClaims | undefined,
+		readonly link: LinkTokenClaims | undefined,
 	) {}
 
 	can(action: string, scope?: Scope): boolean {
@@ -40,7 +43,7 @@ class RealAuthContext implements AuthContext {
 
 	audit(event: DomainEvent): Promise<void> {
 		return this.binding.audit({
-			app: this.appId,
+			credential: this.token,
 			requestId: this.requestId,
 			principalId: this.principal?.id ?? null,
 			principalLabel: this.auditLabel,
@@ -55,18 +58,30 @@ class RealAuthContext implements AuthContext {
 }
 
 /**
- * Build an `AuthContext` from a verified access token's claims — the seam every authentication path
- * uses (the proxy-injected token). The SDK has verified the token LOCALLY; this wraps its claims in the
+ * Build an `AuthContext` from a verified access token and its claims — the seam every authentication
+ * path 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`).
  */
-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 }
+export function buildAuthContext(binding: IamBinding, token: string, claims: AccessTokenClaims, requestId: string): AuthContext {
+	const type = claims.ptype
+	if (isWorkloadKind(type)) {
+		throw new Error('a workload token has no AuthContext')
+	}
+	const principal: PrincipalIdentity | null = type === undefined ? null : { id: claims.sub, type, 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)
+	return new RealAuthContext(
+		binding,
+		token,
+		claims.perms,
+		requestId,
+		principal,
+		auditLabel,
+		principal === null ? claims.sub : null,
+		claims.oauth,
+		claims.link,
+	)
 }
 
 // ── IamClient ──────────────────────────────────────────────────────────────────
@@ -79,7 +94,7 @@ export function buildAuthContext(binding: IamRpc, appId: string, claims: AccessT
  */
 export class IamClient {
 	constructor(
-		private readonly binding: IamRpc,
+		private readonly binding: IamBinding,
 		private readonly appId: string,
 	) {}
 

package/src/iam.ts

@@ -2,13 +2,13 @@
  * `createIam` — the single request-time entry point apps use instead of hand-rolling auth.
  *
  * 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
+ * thing that enforces: it selects the endpoint, 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.
  *   - `listPrincipals` — the app's people directory.
  *
- * There is NO gate evaluation here, no session→token exchange, and no cookie is ever written.
+ * There is NO access decision 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
@@ -16,35 +16,40 @@
  * service that owns identity.
  */
 
-import { type IamRpc, PROXY_TOKEN_HEADER } from '@fabrika/auth-core'
+import { isOAuthResourceUri, isWorkloadKind, PROXY_TOKEN_HEADER, type TokenAudienceProfile } from '@fabrika/auth-core'
 import { buildAuthContext, IamClient } from './client'
 import { readRequestId } from './request'
-import type { AuthContext, ListPrincipalsFailure, PrincipalList } from './types'
+import type { AuthContext, IamBinding, ListPrincipalsFailure, PrincipalList } 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
+	/** The IAM service binding, or `HttpIamRpc` off Cloudflare. Typed by the contract — never the IAM Worker. */
+	IAM?: IamBinding
 	/** IAM origin — the token `iss` this SDK verifies against. Canonicalized once in `createIam`. */
 	FABRIKA_IAM_ISSUER?: string
-	/** Fallback app id when `opts.appId` is omitted. */
-	FABRIKA_APP_ID?: string
+	/** The IAM app id `<app>@<env>` every deploy writes (`FABRIKA_IAM_APP_ID`); the fallback for `opts.appId`. */
+	FABRIKA_IAM_APP_ID?: string
 }
 
-/** Options for `createIam`. `appId` falls back to `env.FABRIKA_APP_ID`. */
+/** Options for `createIam`. `appId` falls back to `env.FABRIKA_IAM_APP_ID`. */
 export interface CreateIamOptions {
-	/** The IAM app id (baked in so it can never be mistyped). Falls back to `env.FABRIKA_APP_ID`. */
+	/** The IAM app id: a platform service bakes its own in; an application reads `env.FABRIKA_IAM_APP_ID`. */
 	appId?: string
+	/**
+	 * Which tokens `authenticate` accepts. Defaults to the app's native tokens; a resource server
+	 * passes `{ kind: 'resource', app, resource }` to accept OAuth tokens minted for that resource.
+	 */
+	tokenAudience?: TokenAudienceProfile
 }
 
 // ── 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 proxy-injected token on the request — an anonymous endpoint, 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'
@@ -69,7 +74,7 @@ export type AuthFailure = Extract<AuthResult, { ok: false }>
 
 /**
  * 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
+ * `audit` a no-op. What an app sets on a request the proxy admitted through an anonymous endpoint: 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.
  */
@@ -88,9 +93,10 @@ export function anonymousContext(): AuthContext {
 /** Internal construction config — `createIam` assembles this; apps never build it directly. */
 interface IamConfig {
 	management: IamClient
-	binding: IamRpc
+	binding: IamBinding
 	verifier: TokenVerifier
 	appId: string
+	tokenAudience: TokenAudienceProfile
 }
 
 /**
@@ -100,9 +106,10 @@ interface IamConfig {
  */
 export class Iam {
 	private readonly management: IamClient
-	private readonly binding: IamRpc
+	private readonly binding: IamBinding
 	private readonly verifier: TokenVerifier
 	private readonly appId: string
+	private readonly tokenAudience: TokenAudienceProfile
 
 	/** @internal — use `createIam`. */
 	constructor(config: IamConfig) {
@@ -110,6 +117,7 @@ export class Iam {
 		this.binding = config.binding
 		this.verifier = config.verifier
 		this.appId = config.appId
+		this.tokenAudience = config.tokenAudience
 	}
 
 	// ── Management surface (delegated to the real client) ─────────────────────────
@@ -137,13 +145,17 @@ export class Iam {
 
 	/** 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)
+		const verified = await this.verifier.verify(token, this.tokenAudience)
 		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) }
+		// A workload token is accepted by no mount (ADR-0022 "Principal kinds"), so no request carries one.
+		if (isWorkloadKind(verified.claims.ptype)) {
+			return { ok: false, reason: 'invalid_token', status: 401 }
+		}
+		return { ok: true, context: buildAuthContext(this.binding, token, verified.claims, requestId) }
 	}
 }
 
@@ -155,9 +167,9 @@ export class Iam {
  * 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
+	const appId = opts.appId ?? env.FABRIKA_IAM_APP_ID
 	if (appId === undefined || appId === '') {
-		throw new Error('createIam: app id is required — pass opts.appId or set env.FABRIKA_APP_ID')
+		throw new Error('createIam: app id is required — pass opts.appId or set env.FABRIKA_IAM_APP_ID')
 	}
 
 	const binding = env.IAM
@@ -165,11 +177,16 @@ export function createIam(env: IamEnv, opts: CreateIamOptions = {}): Iam {
 		throw new Error('createIam: the IAM service binding is missing (env.IAM) — check the IAM ServiceReference.')
 	}
 	const issuer = canonicalIssuer(env.FABRIKA_IAM_ISSUER)
+	const tokenAudience = opts.tokenAudience ?? { kind: 'app', app: appId }
+	if (tokenAudience.app !== appId || (tokenAudience.kind === 'resource' && !isOAuthResourceUri(tokenAudience.resource))) {
+		throw new Error('createIam: tokenAudience must name this app and, for a resource, a valid OAuth resource URI.')
+	}
 	return new Iam({
 		management: new IamClient(binding, appId),
 		binding,
 		verifier: new TokenVerifier(binding, issuer, appId),
 		appId,
+		tokenAudience,
 	})
 }
 

package/src/index.ts

@@ -3,25 +3,27 @@
 // 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-0022). Nothing exported here can evaluate a gate.
+// Enforcement lives in the proxy (ADR-0022). Nothing exported here decides whether a request reaches the app.
 
 export { IamClient } from './client'
 export { applyScope } from './scope'
-// The typed HTTP errors + the per-resource authorization helper a per-path gate cannot express.
+// The typed HTTP errors + the per-resource authorization helper the endpoint table cannot express.
 export { ForbiddenError, requirePermission, UnauthenticatedError } from './errors'
 export type { HttpError } from './errors'
 // 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.
+// through an anonymous endpoint.
 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'
+export type { AuthCarrier } from './types'
 // 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 { DecodedIamMembership, HttpIamMembership, HttpIamRpc, IamTransportError } from './rpc-http'
+export type { IamMembershipMethod } from './rpc-http'
+// The membership operations an application requests on its caller's behalf (scopes, members, share links).
+export { createIamMembership, IamMembership } from './membership'
+export type { IamMembershipEnv, MembershipRequestCaller } from './membership'
 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.
@@ -33,27 +35,27 @@ 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, ListPrincipalsFailure, PrincipalIdentity, PrincipalList } from './types'
+export type { AuthContext, IamBinding, 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'
 
 // 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.
+// IamRpc (the whole binding contract; an app types its `env.IAM` as the narrower `IamBinding`),
+// Scope (the `{ type, value }` coordinate apps pass to `can()`), and the AppSchema vocabulary types
+// apps DECLARE in `fabrika.schema.ts` for `reconcileSchema()`.
 export type {
 	AppActionDef,
-	AppGates,
 	AppSchema,
 	AppScopeDef,
-	CredentialLocation,
 	DomainEvent,
-	GateKind,
-	GateRule,
+	IamMembershipRpc,
 	IamRpc,
+	LinkTokenClaims,
+	MembershipFailure,
+	OAuthTokenClaims,
 	PrincipalListItem,
 	RoleDef,
 	Scope,
+	TokenAudienceProfile,
 } from '@fabrika/auth-core'

package/src/membership.ts

@@ -0,0 +1,110 @@
+import type {
+	AssignMemberResult,
+	CreateScopeResult,
+	FindMemberResult,
+	IamMembershipRpc,
+	InvitationOptions,
+	IssueLinkResult,
+	ListAppMembersResult,
+	ListMembersResult,
+	MemberTarget,
+	RequestDelegationResult,
+	RevokeLinkResult,
+	RevokeMemberInput,
+	RevokeMemberResult,
+	Scope,
+} from '@fabrika/auth-core'
+
+/**
+ * The caller a membership request is made for: the verified token the proxy injected on THIS request, and
+ * the request's correlation id. IAM resolves the caller from the token and checks its live permissions; a
+ * delegation grant is bound to the request id, so both calls of one request carry the same one.
+ */
+export interface MembershipRequestCaller {
+	readonly credential: string
+	readonly requestId: string
+}
+
+/** The env `createIamMembership` reads; an application's `env` satisfies it structurally. */
+export interface IamMembershipEnv {
+	/** IAM's application entrypoint on Cloudflare, or `HttpIamRpc` off it. */
+	IAM?: IamMembershipRpc
+	FABRIKA_IAM_APP_ID?: string
+}
+
+/**
+ * The SDK half of the membership operations. It REQUESTS, on the caller's behalf: IAM decides, generates
+ * every value, writes every grant and issues every key. Nothing here mints, signs or names an actor, and
+ * every result is IAM's answer as it came.
+ */
+export class IamMembership {
+	constructor(
+		private readonly binding: IamMembershipRpc,
+		private readonly appId: string,
+	) {}
+
+	/** A single-use grant for one request to `endpoint`, which the app's schema lists as a membership endpoint. */
+	requestDelegation(caller: MembershipRequestCaller, endpoint: string): Promise<RequestDelegationResult> {
+		return this.binding.requestDelegation({ ...this.caller(caller), endpoint })
+	}
+
+	/** A new value of `dimension`, with the caller granted the dimension's creator role in it. */
+	createScope(caller: MembershipRequestCaller, delegation: string, dimension: string): Promise<CreateScopeResult> {
+		return this.binding.createScope({ ...this.caller(caller), delegation, dimension })
+	}
+
+	/** `invitation` goes with an address only: its label, message and resend (`InvitationOptions`). */
+	assignMember(
+		caller: MembershipRequestCaller,
+		delegation: string,
+		scope: Scope,
+		role: string,
+		member: MemberTarget,
+		invitation?: InvitationOptions,
+	): Promise<AssignMemberResult> {
+		return this.binding.assignMember({ ...this.caller(caller), delegation, scope, role, member, ...(invitation === undefined ? {} : { invitation }) })
+	}
+
+	revokeMember(caller: MembershipRequestCaller, delegation: string, scope: Scope, member: RevokeMemberInput['member']): Promise<RevokeMemberResult> {
+		return this.binding.revokeMember({ ...this.caller(caller), delegation, scope, member })
+	}
+
+	listMembers(caller: MembershipRequestCaller, scope: Scope): Promise<ListMembersResult> {
+		return this.binding.listMembers({ ...this.caller(caller), scope })
+	}
+
+	/** One page of the application's own people; `after` is the previous page's `next`. */
+	listAppMembers(caller: MembershipRequestCaller, after?: string): Promise<ListAppMembersResult> {
+		return this.binding.listAppMembers({ ...this.caller(caller), ...(after === undefined ? {} : { after }) })
+	}
+
+	/** One principal among the members of `scope`, for an endpoint of `action` on, in or below its dimension. */
+	findMember(caller: MembershipRequestCaller, scope: Scope, principalId: string, action: string): Promise<FindMemberResult> {
+		return this.binding.findMember({ ...this.caller(caller), scope, principalId, action })
+	}
+
+	/** A share link of `mount` for `chain[0]`; `chain` is the object and every value containing it, outward. */
+	issueLink(caller: MembershipRequestCaller, mount: string, chain: Scope[], days: number): Promise<IssueLinkResult> {
+		return this.binding.issueLink({ ...this.caller(caller), mount, chain, days })
+	}
+
+	revokeLink(caller: MembershipRequestCaller, id: string): Promise<RevokeLinkResult> {
+		return this.binding.revokeLink({ ...this.caller(caller), id })
+	}
+
+	private caller(caller: MembershipRequestCaller): { app: string; credential: string; requestId: string } {
+		return { app: this.appId, credential: caller.credential, requestId: caller.requestId }
+	}
+}
+
+/** Build the membership client from the env. Throws when the app id or the binding is missing. */
+export function createIamMembership(env: IamMembershipEnv, opts: { appId?: string } = {}): IamMembership {
+	const appId = opts.appId ?? env.FABRIKA_IAM_APP_ID
+	if (appId === undefined || appId === '') {
+		throw new Error('createIamMembership: app id is required — pass opts.appId or set env.FABRIKA_IAM_APP_ID')
+	}
+	if (env.IAM === undefined) {
+		throw new Error('createIamMembership: the IAM binding is missing (env.IAM)')
+	}
+	return new IamMembership(env.IAM, appId)
+}

package/src/rpc-http.ts

@@ -44,24 +44,44 @@
 import type {
 	ApproveDeviceAuthorizationInput,
 	ApproveDeviceAuthorizationResult,
+	AssignMemberInput,
+	AssignMemberResult,
 	AuditInput,
+	CreateScopeInput,
+	CreateScopeResult,
 	DenyDeviceAuthorizationResult,
+	FindMemberInput,
+	FindMemberResult,
+	IamMembershipRpc,
 	IamRpc,
 	InspectDeviceAuthorizationInput,
 	InspectDeviceAuthorizationResult,
 	IssueKeyInput,
 	IssueKeyResult,
+	IssueLinkInput,
+	IssueLinkResult,
 	Jwks,
+	ListAppMembersInput,
+	ListAppMembersResult,
+	ListMembersInput,
+	ListMembersResult,
 	ListOwnDeviceAuthorizationsInput,
 	ListOwnDeviceAuthorizationsResult,
 	ListPrincipalsInput,
 	ListPrincipalsResult,
+	MembershipFailure,
 	MintFromKeyInput,
 	MintFromKeyResult,
 	MintTokenInput,
 	MintTokenResult,
+	RequestDelegationInput,
+	RequestDelegationResult,
 	RevokeKeyInput,
 	RevokeKeyResult,
+	RevokeLinkInput,
+	RevokeLinkResult,
+	RevokeMemberInput,
+	RevokeMemberResult,
 } from '@fabrika/auth-core'
 import {
 	parseApproveDeviceAuthorizationResult,
@@ -89,6 +109,50 @@ const principalsSuccessSchema = z.object({
 	})),
 })
 const failureSchema = z.object({ ok: z.literal(false), reason: z.string().catch('') })
+const scopeSchema = z.object({ type: z.string(), value: z.string() })
+// Every membership success is a `{ ok: true, … }` envelope; a body without one is not an answer.
+const okEnvelope = { ok: z.literal(true) }
+const delegationSuccessSchema = z.object({ ...okEnvelope, grant: z.string().min(1), expiresAt: z.number().finite() })
+const createScopeSuccessSchema = z.object({ ...okEnvelope, scope: scopeSchema, role: z.string() })
+const assignSuccessSchema = z.union([
+	z.object({ ...okEnvelope, assigned: z.object({ principalId: z.string(), role: z.string() }) }),
+	z.object({ ...okEnvelope, invited: z.object({ invitationId: z.string(), role: z.string(), expiresAt: z.number().finite() }) }),
+])
+const affiliationSchema = z.enum(['internal', 'external'])
+const listMembersSuccessSchema = z.object({
+	...okEnvelope,
+	members: z.array(z.object({
+		principalId: z.string(),
+		label: z.string().nullable(),
+		email: z.string().nullable(),
+		// An IAM from before the field answers none: the member's last sign-in is then unknown.
+		lastSignInAt: z.number().finite().nullable().default(null),
+		roles: z.array(z.string()),
+		disabled: z.boolean(),
+		affiliation: affiliationSchema,
+	})),
+	invitations: z.array(z.object({ id: z.string(), email: z.string(), role: z.string(), expiresAt: z.number().finite() })),
+})
+const listAppMembersSuccessSchema = z.object({
+	...okEnvelope,
+	members: z.array(z.object({
+		principalId: z.string(),
+		label: z.string().nullable(),
+		email: z.string().nullable(),
+		lastSignInAt: z.number().finite().nullable(),
+		roles: z.array(z.object({ role: z.string(), scope: scopeSchema.nullable() })),
+		disabled: z.boolean(),
+		affiliation: affiliationSchema,
+	})),
+	next: z.string().nullable(),
+})
+const findMemberSuccessSchema = z.object({
+	...okEnvelope,
+	member: z.object({ principalId: z.string(), label: z.string().nullable(), disabled: z.boolean(), affiliation: affiliationSchema }).nullable(),
+})
+const issueLinkSuccessSchema = z.object({ ...okEnvelope, key: z.string().min(1), id: z.string(), expiresAt: z.number().finite() })
+const revokedSuccessSchema = z.object(okEnvelope)
+const membershipMessageSchema = z.object({ message: 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
@@ -102,7 +166,10 @@ 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. */
+	/**
+	 * The bearer: the installation's shared secret gating `/rpc/*` for `HttpIamRpc`, or an application's own
+	 * membership transport key for `HttpIamMembership` (`FABRIKA_IAM_RPC_KEY` in each). NEVER logged.
+	 */
 	key: string
 	/** Per-call timeout in milliseconds. */
 	timeoutMs?: number
@@ -124,7 +191,7 @@ export class IamTransportError extends Error {
 	}
 }
 
-export class HttpIamRpc implements IamRpc {
+export class HttpIamRpc implements IamRpc, IamMembershipRpc {
 	async inspectDeviceAuthorization(input: InspectDeviceAuthorizationInput): Promise<InspectDeviceAuthorizationResult> {
 		const result = parseInspectDeviceAuthorizationResult(await this.call('inspectDeviceAuthorization', input))
 		if (!result) throw new IamTransportError('inspectDeviceAuthorization')
@@ -145,23 +212,20 @@ export class HttpIamRpc implements IamRpc {
 		if (!result) throw new IamTransportError('listOwnDeviceAuthorizations')
 		return result
 	}
-	private readonly origin: string
-	private readonly key: string
-	private readonly timeoutMs: number
-	private readonly fetchImpl: FetchLike
+	private readonly endpoint: TransportEndpoint
 
 	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
+		this.endpoint = transportEndpoint(options, '/rpc/')
 	}
 
 	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 {
+				ok: false,
+				reason: oneOf(failure, ['no_session', 'invalid_session', 'unknown_principal', 'disabled', 'token_too_large'], 'invalid_session'),
+			}
 		}
 		return readMintSuccess(body, 'mintToken')
 	}
@@ -170,7 +234,7 @@ export class HttpIamRpc implements IamRpc {
 		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 { ok: false, reason: oneOf(failure, ['invalid_key', 'unknown_principal', 'disabled', 'token_too_large'], 'invalid_key') }
 		}
 		return readMintSuccess(body, 'mintFromKey')
 	}
@@ -214,6 +278,44 @@ export class HttpIamRpc implements IamRpc {
 		return { ok: true, ...result.data }
 	}
 
+	readonly #membership = new DecodedIamMembership((method, input) => this.call(method, input))
+
+	requestDelegation(input: RequestDelegationInput): Promise<RequestDelegationResult> {
+		return this.#membership.requestDelegation(input)
+	}
+
+	createScope(input: CreateScopeInput): Promise<CreateScopeResult> {
+		return this.#membership.createScope(input)
+	}
+
+	assignMember(input: AssignMemberInput): Promise<AssignMemberResult> {
+		return this.#membership.assignMember(input)
+	}
+
+	revokeMember(input: RevokeMemberInput): Promise<RevokeMemberResult> {
+		return this.#membership.revokeMember(input)
+	}
+
+	listMembers(input: ListMembersInput): Promise<ListMembersResult> {
+		return this.#membership.listMembers(input)
+	}
+
+	listAppMembers(input: ListAppMembersInput): Promise<ListAppMembersResult> {
+		return this.#membership.listAppMembers(input)
+	}
+
+	findMember(input: FindMemberInput): Promise<FindMemberResult> {
+		return this.#membership.findMember(input)
+	}
+
+	issueLink(input: IssueLinkInput): Promise<IssueLinkResult> {
+		return this.#membership.issueLink(input)
+	}
+
+	revokeLink(input: RevokeLinkInput): Promise<RevokeLinkResult> {
+		return this.#membership.revokeLink(input)
+	}
+
 	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
@@ -232,38 +334,138 @@ export class HttpIamRpc implements IamRpc {
 		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
+	private call(method: string, input: unknown): Promise<unknown> {
+		return callJson(this.endpoint, method, input)
+	}
+
+	private send(method: string, input: unknown): Promise<Response> {
+		return post(this.endpoint, method, input)
+	}
+}
+
+/** Where one transport POSTs: `{origin}{prefix}<method>` with the key as the bearer. */
+interface TransportEndpoint {
+	readonly origin: string
+	readonly prefix: string
+	readonly key: string
+	readonly timeoutMs: number
+	readonly fetch: FetchLike
+}
+
+function transportEndpoint(options: HttpIamRpcOptions, prefix: string): TransportEndpoint {
+	return {
+		origin: options.origin.replace(/\/+$/, ''),
+		prefix,
+		key: options.key,
+		timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+		fetch: options.fetch ?? globalThis.fetch,
+	}
+}
+
+/** POST one method and return its decoded JSON body. Throws `IamTransportError` on any transport fault. */
+async function callJson(endpoint: TransportEndpoint, method: string, input: unknown): Promise<unknown> {
+	const response = await post(endpoint, method, input)
+	const body: unknown = await response.json().catch(() => MALFORMED)
+	if (body === MALFORMED) {
+		throw new IamTransportError(method)
+	}
+	return body
+}
+
+async function post(endpoint: TransportEndpoint, method: string, input: unknown): Promise<Response> {
+	let response: Response
+	try {
+		response = await endpoint.fetch(`${endpoint.origin}${endpoint.prefix}${method}`, {
+			method: 'POST',
+			headers: {
+				'content-type': 'application/json',
+				accept: 'application/json',
+				authorization: `Bearer ${endpoint.key}`,
+			},
+			body: JSON.stringify(input),
+			signal: AbortSignal.timeout(endpoint.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 membership operations, by name, as a transport carries them. */
+export type IamMembershipMethod = keyof IamMembershipRpc
+
+/**
+ * `IamMembershipRpc` over any transport that answers each call with a JSON-shaped body: `HttpIamRpc`, or a Workers
+ * binding to IAM's application entrypoint. Every answer is decoded here, so a body that breaks the contract is
+ * `IamTransportError`, never a value of the declared type.
+ */
+export class DecodedIamMembership implements IamMembershipRpc {
+	readonly #call: (method: IamMembershipMethod, input: unknown) => Promise<unknown>
+
+	constructor(call: (method: IamMembershipMethod, input: unknown) => Promise<unknown>) {
+		this.#call = call
+	}
+
+	async requestDelegation(input: RequestDelegationInput): Promise<RequestDelegationResult> {
+		const body = await this.#call('requestDelegation', input)
+		return readMembershipFailure(body) ?? decode(delegationSuccessSchema, body, 'requestDelegation')
+	}
+
+	async createScope(input: CreateScopeInput): Promise<CreateScopeResult> {
+		const body = await this.#call('createScope', input)
+		return readMembershipFailure(body) ?? decode(createScopeSuccessSchema, body, 'createScope')
+	}
+
+	async assignMember(input: AssignMemberInput): Promise<AssignMemberResult> {
+		const body = await this.#call('assignMember', input)
+		return readMembershipFailure(body) ?? decode(assignSuccessSchema, body, 'assignMember')
+	}
+
+	async revokeMember(input: RevokeMemberInput): Promise<RevokeMemberResult> {
+		const body = await this.#call('revokeMember', input)
+		return readMembershipFailure(body) ?? decode(revokedSuccessSchema, body, 'revokeMember')
+	}
+
+	async listMembers(input: ListMembersInput): Promise<ListMembersResult> {
+		const body = await this.#call('listMembers', input)
+		return readMembershipFailure(body) ?? decode(listMembersSuccessSchema, body, 'listMembers')
+	}
+
+	async listAppMembers(input: ListAppMembersInput): Promise<ListAppMembersResult> {
+		const body = await this.#call('listAppMembers', input)
+		return readMembershipFailure(body) ?? decode(listAppMembersSuccessSchema, body, 'listAppMembers')
+	}
+
+	async findMember(input: FindMemberInput): Promise<FindMemberResult> {
+		const body = await this.#call('findMember', input)
+		return readMembershipFailure(body) ?? decode(findMemberSuccessSchema, body, 'findMember')
+	}
+
+	async issueLink(input: IssueLinkInput): Promise<IssueLinkResult> {
+		const body = await this.#call('issueLink', input)
+		return readMembershipFailure(body) ?? decode(issueLinkSuccessSchema, body, 'issueLink')
+	}
+
+	async revokeLink(input: RevokeLinkInput): Promise<RevokeLinkResult> {
+		const body = await this.#call('revokeLink', input)
+		return readMembershipFailure(body) ?? decode(revokedSuccessSchema, body, 'revokeLink')
+	}
+}
+
+/**
+ * `IamMembershipRpc` over IAM's membership transport, `POST {origin}/membership/<method>` (`@fabrika/iam`'s
+ * `src/membership-http.ts`): what an application without an IAM binding calls, with its own membership transport key.
+ * IAM serves no `requestDelegation` there, because only the proxy obtains a grant; calling it is `IamTransportError`.
+ */
+export class HttpIamMembership extends DecodedIamMembership {
+	constructor(options: HttpIamRpcOptions) {
+		const endpoint = transportEndpoint(options, '/membership/')
+		super((method, input) => callJson(endpoint, method, input))
 	}
 }
 
@@ -282,6 +484,42 @@ function readFailure(body: unknown): string | null {
 	return result.success ? result.data.reason : null
 }
 
+const MEMBERSHIP_REASONS = [
+	'missing_token',
+	'invalid_token',
+	'unknown_principal',
+	'disabled',
+	'not_allowed',
+	'invalid_delegation',
+	'not_found',
+	'last_creator',
+	'invitations_disabled',
+	'delivery_failed',
+	'internal_mailbox',
+] as const
+
+/** A membership refusal off the wire. An unknown reason degrades to `not_allowed`, never to an allow. */
+function readMembershipFailure(body: unknown): MembershipFailure | null {
+	const reason = readFailure(body)
+	if (reason === null) {
+		return null
+	}
+	if (reason === 'invalid_request') {
+		const message = membershipMessageSchema.safeParse(body)
+		return { ok: false, reason, message: message.success ? message.data.message : '' }
+	}
+	return { ok: false, reason: oneOf(reason, MEMBERSHIP_REASONS, 'not_allowed') }
+}
+
+/** Decode a success body, or treat IAM as unreachable: a body that breaks the contract is not an answer. */
+function decode<T>(schema: z.ZodType<T, z.ZodTypeDef, unknown>, body: unknown, method: string): T {
+	const result = schema.safeParse(body)
+	if (!result.success) {
+		throw new IamTransportError(method)
+	}
+	return result.data
+}
+
 /** The `{ ok: true, token, expiresAt }` half both mint methods share. */
 function readMintSuccess(body: unknown, method: string): { ok: true; token: string; expiresAt: number } {
 	const result = mintSuccessSchema.safeParse(body)

package/src/types.ts

@@ -1,4 +1,10 @@
-import type { DomainEvent, PrincipalListItem, PrincipalType, Scope } from '@fabrika/auth-core'
+import type { DomainEvent, IamRpc, LinkTokenClaims, OAuthTokenClaims, PrincipalListItem, PrincipalType, Scope } from '@fabrika/auth-core'
+
+/**
+ * The `IamRpc` members the SDK calls. A Cloudflare application's `IAM` binding is IAM's
+ * `PropustkaApplication` entrypoint, which serves these and has no `issueKey` or `revokeKey`.
+ */
+export type IamBinding = Pick<IamRpc, 'getJwks' | 'listPrincipals' | 'audit'>
 
 /**
  * The resolved caller's identity — who Access says you are, as the IAM Worker recorded
@@ -40,6 +46,16 @@ export interface AuthContext {
 	 * either way). Stamp `created_by` with `principal?.id ?? null`.
 	 */
 	readonly principal: PrincipalIdentity | null
+	/**
+	 * The OAuth client, consented scopes and grant behind an OAuth resource token; absent for every
+	 * native credential. `perms` are already narrowed by the scopes, so `can()` stays the authority.
+	 */
+	readonly oauth?: OAuthTokenClaims
+	/**
+	 * The share link behind a link key's token — its mount and the containment chain it is bound to —
+	 * absent for every other credential. `principal` is then null.
+	 */
+	readonly link?: LinkTokenClaims
 	/**
 	 * Point check: may this principal do `action` (optionally within `scope`, an opaque
 	 * `{ type, value }` coordinate)? Scope-less → satisfied by GLOBAL permissions only; a
@@ -75,3 +91,8 @@ export interface ListPrincipalsFailure {
 	reason: 'missing_token' | 'invalid_token' | 'unknown_principal' | 'disabled' | 'not_allowed'
 	status: 401 | 403
 }
+
+/** A request context with a writable `auth` slot, set to the resolved `AuthContext` (or null for an anonymous caller). */
+export interface AuthCarrier {
+	auth?: AuthContext | null
+}

package/src/verify.ts

@@ -2,7 +2,7 @@
  * Local access-token verification — the only thing this SDK still does with a credential.
  *
  * 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
+ * enforcement point: it selects the endpoint, 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
  * become an `AuthContext`.
@@ -10,19 +10,20 @@
  * The verification itself is `@fabrika/jwks`, shared byte-for-byte with the proxy's enforcement path.
  * What this file owns is the SDK's construction shape: the audience is fixed at construction, and the
  * key set plus the unknown-`kid` cooldown are cached PER BINDING in a module-level WeakMap rather than
- * per instance — `@fabrika/app` calls its `middleware(env)` factory on every request, so an SDK object
+ * per instance — a service may build one on every request, so an SDK object
  * built there is per-request while the binding lives for the isolate/process.
  */
 
-import type { IamRpc } from '@fabrika/auth-core'
+import type { TokenAudienceProfile } from '@fabrika/auth-core'
 import { createJwksCache, type JwksCache, TokenVerifier as JwksVerifier, type VerifyResult } from '@fabrika/jwks'
+import type { IamBinding } from './types'
 
 export type { VerifyResult }
 
 /** Key set + cooldown cached per binding, so they survive the per-request SDK objects built over them. */
-const jwksCache = new WeakMap<IamRpc, JwksCache>()
+const jwksCache = new WeakMap<IamBinding, JwksCache>()
 
-function cacheFor(binding: IamRpc): JwksCache {
+function cacheFor(binding: IamBinding): JwksCache {
 	let cache = jwksCache.get(binding)
 	if (cache === undefined) {
 		cache = createJwksCache()
@@ -31,20 +32,23 @@ function cacheFor(binding: IamRpc): JwksCache {
 	return cache
 }
 
-/** Verifies tokens for ONE (binding, issuer, audience) triple. Cheap to construct; the cache is shared. */
+/**
+ * Verifies tokens for ONE (binding, issuer, audience) triple. A bare string audience is an app id. Cheap to
+ * construct; the cache is shared.
+ */
 export class TokenVerifier {
 	private readonly inner: JwksVerifier
 
 	constructor(
-		binding: IamRpc,
+		binding: IamBinding,
 		issuer: string,
-		private readonly audience: string,
+		private readonly audience: string | TokenAudienceProfile,
 		now: () => number = () => Math.floor(Date.now() / 1000),
 	) {
 		this.inner = new JwksVerifier({ getJwks: () => binding.getJwks(), issuer, now, cache: cacheFor(binding) })
 	}
 
-	verify(token: string): Promise<VerifyResult> {
-		return this.inner.verify(token, this.audience)
+	verify(token: string, audience: string | TokenAudienceProfile = this.audience): Promise<VerifyResult> {
+		return this.inner.verify(token, audience)
 	}
 }

package/src/middleware.ts

@@ -1,29 +0,0 @@
-/**
- * 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-0022).
- *
- * 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
-}