@propustka/client 0.0.1

package/package.json

@@ -0,0 +1,34 @@
+{
+	"name": "@propustka/client",
+	"version": "0.0.1",
+	"type": "module",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/contember/propustka.git",
+		"directory": "packages/client"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"src",
+		"!src/**/__tests__/**"
+	],
+	"exports": {
+		".": {
+			"bun": "./src/index.ts",
+			"types": "./src/index.ts",
+			"default": "./src/index.ts"
+		}
+	},
+	"scripts": {
+		"typecheck": "tsc --noEmit",
+		"test": "bun test"
+	},
+	"dependencies": {
+		"@propustka/core": "0.0.1"
+	},
+	"devDependencies": {
+		"@cloudflare/workers-types": "^4.20251001.0"
+	}
+}

package/src/client.ts

@@ -0,0 +1,202 @@
+import type { DomainEvent, IamRpc, ResolvedPrincipal } from '@propustka/core'
+import { permits, scopedProjects } from '@propustka/core'
+import { readCredentials } from './request'
+import type {
+	AuthContext,
+	AuthFailure,
+	Capability,
+	CapabilityFailure,
+	IssueCapabilityRequest,
+	IssuedCapability,
+	IssueFailure,
+	PrincipalIdentity,
+	RevokedCapability,
+	RevokeFailure,
+} from './types'
+
+// ── AuthContext (real) ─────────────────────────────────────────────────────────
+
+/**
+ * The real, principal-backed `AuthContext`. `can`/`scopedTo` are pure functions over the
+ * permissions array the IAM Worker already resolved (no per-check round-trip); only `audit`
+ * calls the binding.
+ */
+class RealAuthContext implements AuthContext {
+	readonly ok = true
+	readonly principal: PrincipalIdentity
+
+	constructor(
+		private readonly binding: IamRpc,
+		private readonly appId: string,
+		private readonly resolved: ResolvedPrincipal,
+	) {
+		this.principal = { id: resolved.id, type: resolved.type, label: resolved.label }
+	}
+
+	can(action: string, scope?: { project?: string }): boolean {
+		// `permits` already encodes the scope-less rule: with no project, ONLY global
+		// (projectId === null) entries satisfy.
+		return permits(this.resolved.permissions, action, scope?.project)
+	}
+
+	scopedTo(action: string, _dimension = 'project'): string[] | null {
+		// `dimension` is forward-looking only — v1 has a single scope dimension (project).
+		return scopedProjects(this.resolved.permissions, action)
+	}
+
+	audit(event: DomainEvent): Promise<void> {
+		return this.binding.audit({
+			app: this.appId,
+			requestId: this.resolved.requestId,
+			principalId: this.resolved.id,
+			principalLabel: this.resolved.label,
+			action: event.action,
+			resourceType: event.resourceType,
+			resourceId: event.resourceId,
+			diff: event.diff,
+			metadata: event.metadata,
+		})
+	}
+}
+
+// ── Capability (real) ──────────────────────────────────────────────────────────
+
+/**
+ * A redeemed, anonymous capability token. `can` is EXACT-match (action, resource) — no
+ * wildcards. `audit` attaches the token id + label and a null principal.
+ */
+class RealCapability implements Capability {
+	readonly ok = true
+
+	constructor(
+		private readonly binding: IamRpc,
+		private readonly appId: string,
+		private readonly requestId: string,
+		private readonly tokenId: string,
+		private readonly label: string | null,
+		private readonly capabilities: ReadonlyArray<{ action: string; resource: string }>,
+	) {}
+
+	can(action: string, resource: string): boolean {
+		for (const c of this.capabilities) {
+			if (c.action === action && c.resource === resource) {
+				return true
+			}
+		}
+		return false
+	}
+
+	audit(event: DomainEvent): Promise<void> {
+		return this.binding.audit({
+			app: this.appId,
+			requestId: this.requestId,
+			principalId: null,
+			// Snapshot the token label; fall back to `capability:<id>` when unlabeled.
+			principalLabel: this.label ?? `capability:${this.tokenId}`,
+			capabilityTokenId: this.tokenId,
+			action: event.action,
+			resourceType: event.resourceType,
+			resourceId: event.resourceId,
+			diff: event.diff,
+			metadata: event.metadata,
+		})
+	}
+}
+
+// ── IamClient ──────────────────────────────────────────────────────────────────
+
+/**
+ * Thin, app-facing wrapper over the IAM Worker service binding. Bakes the caller `app` id
+ * into the constructor so app code can never forget or mistype it. Depends ONLY on the
+ * `IamRpc` contract from `@propustka/core` — never on the Worker — which is what keeps the
+ * SDK worker-independent (the binding is the deployed Worker, reached at runtime).
+ */
+export class IamClient {
+	constructor(
+		private readonly binding: IamRpc,
+		private readonly appId: string,
+	) {}
+
+	/**
+	 * Resolve the caller from the forwarded Access credentials. Returns a rich `AuthContext`
+	 * on success, or a typed `AuthFailure` carrying the 401/403 status (missing/invalid → 401;
+	 * unknown_principal/disabled → 403).
+	 */
+	async authenticate(req: Request): Promise<AuthContext | AuthFailure> {
+		const { token, cookie, origin, requestId } = readCredentials(req)
+		const result = await this.binding.authenticate({ app: this.appId, token, cookie, origin, requestId })
+		if (result.ok) {
+			return new RealAuthContext(this.binding, this.appId, result.principal)
+		}
+		return { ok: false, reason: result.reason, status: authFailureStatus(result.reason) }
+	}
+
+	/**
+	 * Redeem a capability token (a share link). No identity. A bad/expired/revoked/exhausted
+	 * token reads as a 404 (the link is "invalid or expired"), never a leaky 401/403.
+	 */
+	async redeemCapability(req: Request, token: string): Promise<Capability | CapabilityFailure> {
+		const { requestId } = readCredentials(req)
+		const result = await this.binding.redeemCapability({ app: this.appId, token, requestId })
+		if (result.ok) {
+			return new RealCapability(this.binding, this.appId, requestId, result.tokenId, result.label, result.capabilities)
+		}
+		return { ok: false, reason: result.reason, status: 404 }
+	}
+
+	/**
+	 * Mint a capability (share link) in-flow. 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). The app supplies only the grants/label/expiry.
+	 */
+	async issueCapability(req: Request, input: IssueCapabilityRequest): Promise<IssuedCapability | IssueFailure> {
+		const { token, cookie, origin, requestId } = readCredentials(req)
+		const result = await this.binding.issueCapability({
+			app: this.appId,
+			token,
+			cookie,
+			origin,
+			requestId,
+			grants: input.grants,
+			label: input.label,
+			expiresAt: input.expiresAt,
+			maxUses: input.maxUses,
+		})
+		if (result.ok) {
+			return { ok: true, token: result.token, id: result.id }
+		}
+		return { ok: false, reason: result.reason, status: issueFailureStatus(result.reason) }
+	}
+
+	/**
+	 * Revoke a capability (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 revokeCapability(req: Request, tokenId: string): Promise<RevokedCapability | RevokeFailure> {
+		const { token, cookie, origin, requestId } = readCredentials(req)
+		const result = await this.binding.revokeCapability({ app: this.appId, token, cookie, origin, requestId, tokenId })
+		if (result.ok) {
+			return { ok: true, revoked: result.revoked }
+		}
+		return { ok: false, reason: result.reason, status: revokeFailureStatus(result.reason) }
+	}
+}
+
+/** missing/invalid token → 401 (not authenticated); unknown/disabled principal → 403. */
+function authFailureStatus(reason: AuthFailure['reason']): 401 | 403 {
+	return reason === 'missing_token' || reason === 'invalid_token' ? 401 : 403
+}
+
+/** 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; 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/fake.ts

@@ -0,0 +1,264 @@
+import type { DomainEvent, PermissionEntry, PrincipalType } from '@propustka/core'
+import { matchAction, permits, scopedProjects } from '@propustka/core'
+import type {
+	AuthContext,
+	AuthFailure,
+	Capability,
+	CapabilityFailure,
+	IssueCapabilityRequest,
+	IssuedCapability,
+	IssueFailure,
+	PrincipalIdentity,
+	RevokedCapability,
+	RevokeFailure,
+} from './types'
+
+/**
+ * A fixed dev persona: an identity plus a real permissions array. When `FakeIamConfig.personas`
+ * is set, the fake resolves one of these per request (by a cookie / header key) and backs
+ * `can()` / `scopedTo()` with the SAME `permits` / `scopedProjects` core logic the real client
+ * uses — so role/scope behaviour (admin vs app-wide vs project-scoped) is exercisable in dev and
+ * browser tests without Cloudflare Access or a running IAM Worker.
+ */
+export interface FakePersona {
+	id: string
+	label: string
+	type?: PrincipalType
+	/** The resolved permission entries — real `permits`/`scopedProjects` semantics (not allow-all). */
+	permissions: PermissionEntry[]
+}
+
+/**
+ * Config for the fake. Two modes:
+ *
+ *  - SIMPLE (default): a single fixed identity, `can()` allows everything except the `deny`
+ *    action patterns (same `*`/`prefix.*` matching as roles) so 403 paths are still testable.
+ *    `principal` overrides the fixed identity (id/label/type).
+ *
+ *  - PERSONA: set `personas` (keyed by an opaque selector, e.g. an email) to make the fake
+ *    impersonate a specific principal per request, with real permission semantics. The active
+ *    persona key is read from the `personaCookie` (default `propustka_dev_principal`) or the
+ *    `personaHeader` (default `X-Dev-Principal`), falling back to `defaultPersona`. A cookie is
+ *    what browser E2E uses (it rides every navigation + fetch); the header suits CLI/fetch. An
+ *    unknown/absent key with no default resolves to `unknown_principal` (403) — the same shape a
+ *    real unrecognised principal gets.
+ */
+export interface FakeIamConfig {
+	deny?: string[]
+	principal?: {
+		id?: string
+		label?: string
+		type?: PrincipalType
+	}
+	personas?: Record<string, FakePersona>
+	/** Cookie carrying the active persona key (browser E2E). Default `propustka_dev_principal`. */
+	personaCookie?: string
+	/** Header carrying the active persona key (fetch/CLI). Default `X-Dev-Principal`. */
+	personaHeader?: string
+	/** Persona key used when neither cookie nor header is present. */
+	defaultPersona?: string
+	/**
+	 * Dynamic per-request persona resolver — the most flexible mode (takes precedence over
+	 * `personas`/`deny`). The app derives the persona however it likes (e.g. a dev cookie →
+	 * a directory lookup), so personas need not be enumerated up front. Returning `null`
+	 * resolves to `unknown_principal` (403), like a real unrecognised principal.
+	 */
+	resolve?: (req: Request) => FakePersona | null | Promise<FakePersona | null>
+}
+
+interface FakeIdentity {
+	id: string
+	label: string
+	type: PrincipalType
+}
+
+const DEFAULT_PERSONA_COOKIE = 'propustka_dev_principal'
+const DEFAULT_PERSONA_HEADER = 'X-Dev-Principal'
+
+function resolveIdentity(config: FakeIamConfig | undefined): FakeIdentity {
+	return {
+		id: config?.principal?.id ?? 'fake-principal',
+		label: config?.principal?.label ?? 'fake@example.com',
+		type: config?.principal?.type ?? 'user',
+	}
+}
+
+/** True when `action` matches any pattern in the deny list. */
+function isDenied(deny: string[], action: string): boolean {
+	for (const pattern of deny) {
+		if (matchAction(pattern, action)) {
+			return true
+		}
+	}
+	return false
+}
+
+/** Read a single cookie value out of a request's Cookie header. Returns null when absent. */
+function readCookie(req: Request, name: string): string | null {
+	const header = req.headers.get('Cookie')
+	if (!header) {
+		return null
+	}
+	for (const part of header.split(';')) {
+		const eq = part.indexOf('=')
+		if (eq === -1) {
+			continue
+		}
+		if (part.slice(0, eq).trim() === name) {
+			return decodeURIComponent(part.slice(eq + 1).trim())
+		}
+	}
+	return null
+}
+
+// ── Fake surfaces ───────────────────────────────────────────────────────────────
+
+/** Allow-all-except-deny context (simple mode). */
+class FakeAuthContext implements AuthContext {
+	readonly ok = true
+	readonly principal: PrincipalIdentity
+
+	constructor(
+		private readonly deny: string[],
+		identity: FakeIdentity,
+	) {
+		this.principal = { id: identity.id, type: identity.type, label: identity.label }
+	}
+
+	can(action: string, _scope?: { project?: string }): boolean {
+		// Allow everything except denied actions — regardless of scope.
+		return !isDenied(this.deny, action)
+	}
+
+	scopedTo(_action: string, _dimension = 'project'): string[] | null {
+		// Unrestricted: the fake identity may see everything.
+		return null
+	}
+
+	audit(_event: DomainEvent): Promise<void> {
+		return Promise.resolve()
+	}
+}
+
+/** Persona-backed context (persona mode) — real `permits` / `scopedProjects` semantics. */
+class PersonaAuthContext implements AuthContext {
+	readonly ok = true
+	readonly principal: PrincipalIdentity
+
+	constructor(private readonly persona: FakePersona) {
+		this.principal = { id: persona.id, type: persona.type ?? 'user', label: persona.label }
+	}
+
+	can(action: string, scope?: { project?: string }): boolean {
+		return permits(this.persona.permissions, action, scope?.project)
+	}
+
+	scopedTo(action: string, _dimension = 'project'): string[] | null {
+		return scopedProjects(this.persona.permissions, action)
+	}
+
+	audit(_event: DomainEvent): Promise<void> {
+		return Promise.resolve()
+	}
+}
+
+class FakeCapability implements Capability {
+	readonly ok = true
+
+	constructor(private readonly deny: string[]) {}
+
+	can(action: string, _resource: string): boolean {
+		return !isDenied(this.deny, action)
+	}
+
+	audit(_event: DomainEvent): Promise<void> {
+		return Promise.resolve()
+	}
+}
+
+// ── FakeIamClient ─────────────────────────────────────────────────────────────
+
+/**
+ * Drop-in for `IamClient` with an identical public interface, selectable by the app via an env
+ * flag for `wrangler dev`. No Access, no IAM Worker. In SIMPLE mode `can()` allows everything
+ * except the `deny` list; in PERSONA mode it impersonates the request's selected persona with
+ * real permission semantics (see `FakeIamConfig`).
+ */
+export class FakeIamClient {
+	private readonly deny: string[]
+	private readonly identity: FakeIdentity
+	private readonly personas?: Record<string, FakePersona>
+	private readonly personaCookie: string
+	private readonly personaHeader: string
+	private readonly defaultPersona?: string
+	private readonly resolve?: (req: Request) => FakePersona | null | Promise<FakePersona | null>
+	// In-memory capability registry so issue → redeem → revoke stay consistent in dev/tests
+	// (no IAM Worker locally). Maps the plaintext token to its id, tracks every issued id,
+	// and the subset that has been revoked — so a redeemed-then-revoked token reads 'revoked'.
+	private readonly issuedTokens = new Map<string, string>()
+	private readonly issuedIds = new Set<string>()
+	private readonly revokedIds = new Set<string>()
+
+	constructor(config?: FakeIamConfig) {
+		this.deny = config?.deny ?? []
+		this.identity = resolveIdentity(config)
+		this.personas = config?.personas
+		this.personaCookie = config?.personaCookie ?? DEFAULT_PERSONA_COOKIE
+		this.personaHeader = config?.personaHeader ?? DEFAULT_PERSONA_HEADER
+		this.defaultPersona = config?.defaultPersona
+		this.resolve = config?.resolve
+	}
+
+	async authenticate(req: Request): Promise<AuthContext | AuthFailure> {
+		// Dynamic resolver wins — the app decides the persona per request.
+		if (this.resolve) {
+			const persona = await this.resolve(req)
+			if (!persona) {
+				return { ok: false, reason: 'unknown_principal', status: 403 }
+			}
+			return new PersonaAuthContext(persona)
+		}
+		if (this.personas) {
+			const key = readCookie(req, this.personaCookie) ?? req.headers.get(this.personaHeader) ?? this.defaultPersona
+			const persona = key ? this.personas[key] : undefined
+			if (!persona) {
+				// Selected an unknown persona (or none, with no default) → behave like a real
+				// authenticated-but-unrecognised principal.
+				return { ok: false, reason: 'unknown_principal', status: 403 }
+			}
+			return new PersonaAuthContext(persona)
+		}
+		return new FakeAuthContext(this.deny, this.identity)
+	}
+
+	redeemCapability(_req: Request, token: string): Promise<Capability | CapabilityFailure> {
+		// A token issued by THIS fake and since revoked reads 'revoked' (404), like the real
+		// Worker. Tokens we never issued (e.g. a hand-written one) still redeem allow-all — the
+		// fake is a dev/test convenience, not a validator.
+		const id = this.issuedTokens.get(token)
+		if (id && this.revokedIds.has(id)) {
+			return Promise.resolve({ ok: false, reason: 'revoked', status: 404 })
+		}
+		return Promise.resolve(new FakeCapability(this.deny))
+	}
+
+	issueCapability(_req: Request, _input: IssueCapabilityRequest): Promise<IssuedCapability | IssueFailure> {
+		const suffix = crypto.randomUUID()
+		const token = `fake-token-${suffix}`
+		const id = `fake-${this.identity.id}-${suffix}`
+		this.issuedTokens.set(token, id)
+		this.issuedIds.add(id)
+		return Promise.resolve({ ok: true, token, id })
+	}
+
+	revokeCapability(_req: Request, tokenId: string): Promise<RevokedCapability | RevokeFailure> {
+		if (!this.issuedIds.has(tokenId)) {
+			return Promise.resolve({ ok: false, reason: 'not_found', status: 404 })
+		}
+		if (this.revokedIds.has(tokenId)) {
+			return Promise.resolve({ ok: true, revoked: false })
+		}
+		this.revokedIds.add(tokenId)
+		return Promise.resolve({ ok: true, revoked: true })
+	}
+}

package/src/index.ts

@@ -0,0 +1,25 @@
+// @propustka/client — the app-facing IAM SDK (the only package published to npm).
+//
+// Depends ONLY on @propustka/core: the binding is typed as the `IamRpc` contract (so the SDK
+// never imports the Worker), and `can()`/`scopedTo()` reuse core's `permits`/`matchAction`.
+
+export { IamClient } from './client'
+export { FakeIamClient } from './fake'
+export type { FakeIamConfig, FakePersona } from './fake'
+export { applyScope } from './scope'
+export type {
+	AuthContext,
+	AuthFailure,
+	Capability,
+	CapabilityFailure,
+	IssueCapabilityRequest,
+	IssuedCapability,
+	IssueFailure,
+	PrincipalIdentity,
+	RevokedCapability,
+	RevokeFailure,
+} from './types'
+
+// Re-export from core so apps need only depend on the SDK: DomainEvent (one event shape) and
+// IamRpc (the binding contract — apps type their `env.IAM` as IamRpc without importing core).
+export type { DomainEvent, IamRpc } from '@propustka/core'

package/src/request.ts

@@ -0,0 +1,53 @@
+// Reading the forwarded Access credentials off the incoming Request. Mirrors the
+// extraction the IAM Worker's admin router does, so both sides agree on exactly which
+// header/cookie carries what. None of this is a security boundary — it's plumbing that
+// hands the verified-at-the-edge token to the IAM Worker, which validates it.
+
+/** Cloudflare Access injects the app token as this header on every request behind Access. */
+const ACCESS_TOKEN_HEADER = 'Cf-Access-Jwt-Assertion'
+/** The browser carries the Access session as this cookie; needed for get-identity (users). */
+const ACCESS_COOKIE_NAME = 'CF_Authorization'
+/** Cloudflare's per-request ray id; we use it as the correlation request id. */
+const RAY_HEADER = 'cf-ray'
+
+export interface ForwardedCredentials {
+	/** Cf-Access-Jwt-Assertion value, or null if absent (no Access in front). */
+	token: string | null
+	/** CF_Authorization cookie value parsed from the Cookie header, or null. */
+	cookie: string | null
+	/** The app's own origin (scheme + host), for the IAM Worker's get-identity call. */
+	origin: string
+	/** cf-ray, or a fresh UUID when absent (e.g. local dev). */
+	requestId: string
+}
+
+/**
+ * Pull the forwarded Access credentials and a correlation id off the request. The token
+ * and cookie may be null (e.g. a Bypass path with no Access in front); the IAM Worker
+ * decides what that means.
+ */
+export function readCredentials(req: Request): ForwardedCredentials {
+	return {
+		token: req.headers.get(ACCESS_TOKEN_HEADER),
+		cookie: parseCookie(req.headers.get('Cookie'), ACCESS_COOKIE_NAME),
+		origin: new URL(req.url).origin,
+		requestId: req.headers.get(RAY_HEADER) ?? crypto.randomUUID(),
+	}
+}
+
+/** Read a single cookie value out of a raw Cookie header. Returns null when absent. */
+function parseCookie(header: string | null, name: string): string | null {
+	if (!header) {
+		return null
+	}
+	for (const part of header.split(';')) {
+		const eq = part.indexOf('=')
+		if (eq === -1) {
+			continue
+		}
+		if (part.slice(0, eq).trim() === name) {
+			return part.slice(eq + 1).trim()
+		}
+	}
+	return null
+}

package/src/scope.ts

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

package/src/types.ts

@@ -0,0 +1,130 @@
+import type { DomainEvent, IssueCapabilityGrant, PrincipalType } from '@propustka/core'
+
+/**
+ * The resolved caller's identity — who Access says you are, as the IAM Worker recorded
+ * the principal. Exposed on `AuthContext` so apps can stamp domain rows (created_by,
+ * activity actor, assignee) and render "signed in as …" without a second lookup. It is
+ * NOT a permission surface — authorization is still `can()` / `scopedTo()`.
+ *  - `id`    — the IAM principal id (UUIDv7); stable, safe to store on domain rows.
+ *  - `type`  — 'user' (Access identity login) or 'service' (Access service token).
+ *  - `label` — human-readable: the user's email, or the service token's name.
+ */
+export interface PrincipalIdentity {
+	readonly id: string
+	readonly type: PrincipalType
+	readonly label: string
+}
+
+// ── Result surfaces ──────────────────────────────────────────────────────────
+//
+// 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` / `Capability` / `IssuedCapability` 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
+// the real (`permits`-backed) and fake (allow-all-except-deny) implementations satisfy a
+// single shared shape without any casts — see the design note in the package README of the
+// spec. The documented surface (`ok` / `can` / `scopedTo` / `audit`) is the interface.
+
+/**
+ * The authenticated, ok:true result. `can`/`scopedTo` are local & pure (no binding call);
+ * only `audit` reaches the IAM Worker.
+ */
+export interface AuthContext {
+	readonly ok: true
+	/**
+	 * The resolved caller identity (id / type / label). For stamping domain rows and
+	 * display — NOT a permission surface (authorization stays `can` / `scopedTo`).
+	 */
+	readonly principal: PrincipalIdentity
+	/**
+	 * Point check: may this principal do `action` (optionally on `scope.project`)?
+	 * Scope-less → satisfied by GLOBAL permissions only; a project-scoped grant never
+	 * widens into a scope-less allow.
+	 */
+	can(action: string, scope?: { project?: string }): boolean
+	/**
+	 * Scoping: which project ids may this principal perform `action` on?
+	 *  - `null`      → unrestricted (holds the action globally — e.g. an admin)
+	 *  - `[]`        → no project access at all
+	 *  - non-empty   → exactly those project ids
+	 * Consume via `applyScope` so the empty-`IN ()` trap is handled once. `dimension`
+	 * defaults to `'project'` and is forward-looking only (v1 has a single scope dimension).
+	 */
+	scopedTo(action: string, dimension?: string): string[] | null
+	/** Emit a domain audit event; app/principal/requestId are auto-attached. Fire-and-forget. */
+	audit(event: DomainEvent): Promise<void>
+}
+
+/**
+ * An anonymous redeemed capability token. Same `can` ergonomics as `AuthContext`, but
+ * EXACT (action, resource) matching — no wildcards, no project scope.
+ */
+export interface Capability {
+	readonly ok: true
+	/** Exact match against the token's (action, resource) list. No wildcards. */
+	can(action: string, resource: string): boolean
+	/** Emit a domain audit event; capabilityTokenId + token label attached, principalId null. */
+	audit(event: DomainEvent): Promise<void>
+}
+
+/** Successful `issueCapability` — plaintext token returned ONCE. */
+export interface IssuedCapability {
+	readonly ok: true
+	/** Plaintext token — show once, never persist. */
+	token: string
+	/** The capability token id (safe to store/reference). */
+	id: string
+}
+
+/** Successful `revokeCapability`. `revoked` is false when the token was already revoked. */
+export interface RevokedCapability {
+	readonly ok: true
+	/** True when this call flipped the token to revoked; false if it was already revoked (idempotent). */
+	revoked: boolean
+}
+
+// ── Failures ─────────────────────────────────────────────────────────────────
+
+/** `authenticate` failure. missing/invalid → 401; unknown_principal/disabled → 403. */
+export interface AuthFailure {
+	readonly ok: false
+	reason: 'missing_token' | 'invalid_token' | 'unknown_principal' | 'disabled'
+	status: 401 | 403
+}
+
+/** `redeemCapability` failure — a bad/expired share link reads as 404. */
+export interface CapabilityFailure {
+	readonly ok: false
+	reason: 'unknown' | 'expired' | 'revoked' | 'exhausted'
+	status: 404
+}
+
+/** `issueCapability` 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
+}
+
+/** `revokeCapability` 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
+}
+
+// ── Inputs ───────────────────────────────────────────────────────────────────
+
+/**
+ * App-supplied portion of `issueCapability` — the grants/label/expiry/maxUses. The SDK
+ * fills `app` and the issuer's forwarded credentials (token/cookie/origin/requestId) from
+ * the request, so app code can never self-assert the issuer.
+ */
+export interface IssueCapabilityRequest {
+	grants: IssueCapabilityGrant[]
+	label?: string
+	expiresAt?: number
+	maxUses?: number
+}