@c9up/warden 0.1.0

package/src/TokenBlacklist.ts

@@ -0,0 +1,58 @@
+/**
+ * TokenBlacklist — revoke JWT tokens before expiry.
+ *
+ * Stores JTI (JWT ID) with expiry. Supports Memory and Redis drivers.
+ *
+ * @implements MISS-6
+ */
+
+export interface BlacklistDriver {
+	add(jti: string, expiresAt: number): Promise<void>;
+	has(jti: string): Promise<boolean>;
+	cleanup(): Promise<void>;
+}
+
+/** In-memory blacklist for development. */
+export class MemoryBlacklistDriver implements BlacklistDriver {
+	private entries: Map<string, number> = new Map();
+
+	async add(jti: string, expiresAt: number): Promise<void> {
+		this.entries.set(jti, expiresAt);
+	}
+
+	async has(jti: string): Promise<boolean> {
+		const expiresAt = this.entries.get(jti);
+		if (expiresAt === undefined) return false;
+		if (expiresAt < Date.now()) {
+			this.entries.delete(jti);
+			return false;
+		}
+		return true;
+	}
+
+	async cleanup(): Promise<void> {
+		const now = Date.now();
+		for (const [jti, exp] of this.entries) {
+			if (exp < now) this.entries.delete(jti);
+		}
+	}
+}
+
+export class TokenBlacklist {
+	constructor(private driver: BlacklistDriver) {}
+
+	/** Revoke a token by its JTI claim. */
+	async revoke(jti: string, expiresAt: number): Promise<void> {
+		await this.driver.add(jti, expiresAt);
+	}
+
+	/** Check if a token JTI is blacklisted. */
+	async isRevoked(jti: string): Promise<boolean> {
+		return this.driver.has(jti);
+	}
+
+	/** Remove expired entries. */
+	async cleanup(): Promise<void> {
+		return this.driver.cleanup();
+	}
+}

package/src/WardenProvider.ts

@@ -0,0 +1,84 @@
+import { AuthManager } from "./AuthManager.js";
+import type { WardenConfig } from "./config.js";
+import { WardenError } from "./errors.js";
+import { MemoryRightsStore } from "./rights/MemoryRightsStore.js";
+import { RightsResolver } from "./rights/RightsResolver.js";
+import { _setAuth } from "./services/main.js";
+import { JwtStrategy } from "./strategies/JwtStrategy.js";
+
+interface WardenContainer {
+	singleton(token: unknown, factory: () => unknown): void;
+	resolve(token: unknown): unknown;
+}
+
+interface WardenConfigStore {
+	get<T = unknown>(key: string): T | undefined;
+}
+
+export interface WardenAppContext {
+	container: WardenContainer;
+	config: WardenConfigStore;
+}
+
+export default class WardenProvider {
+	constructor(protected app: WardenAppContext) {}
+
+	register() {
+		// Register JwtStrategy first so it's available before AuthManager resolves.
+		// The previous version nested the JwtStrategy registration inside the
+		// AuthManager factory — that was order-dependent and fragile.
+		const config = this.app.config.get<WardenConfig>("auth");
+
+		// Fail-fast at register-time so the operator gets a clear actionable
+		// error during boot instead of an opaque runtime crash on the first
+		// protected request. Previously, missing `config.auth` produced an
+		// AuthManager with `strategies: {}` and `defaultStrategy: 'jwt'`,
+		// passing the (then-permissive) constructor and erroring deep in the
+		// middleware loop.
+		if (!config?.jwt) {
+			throw new WardenError(
+				"WARDEN_NO_AUTH_CONFIG",
+				`@c9up/warden: no authentication strategies configured. Set config.warden.auth.jwt (or another strategy) in your reamrc.ts before registering WardenProvider.`,
+			);
+		}
+
+		const jwt = new JwtStrategy(config.jwt);
+		this.app.container.singleton(JwtStrategy, () => jwt);
+
+		// Rights layer (Epic 56): one resolver singleton backs BOTH the coarse
+		// RBAC helpers (injected into AuthManager below) and — once 56.6 lands —
+		// the Bouncer construction, so a coarse question and a policy question
+		// resolve through the SAME instance (single unification point, AC-E3).
+		// The store defaults to an in-memory driver and is exposed (by class)
+		// so an app can seed roles/grants at boot, or supply its own via
+		// `config.auth.rights.store` (AD5).
+		const rightsStore = config.rights?.store ?? new MemoryRightsStore();
+		const rightsResolver = new RightsResolver(rightsStore);
+		this.app.container.singleton(RightsResolver, () => rightsResolver);
+		if (rightsStore instanceof MemoryRightsStore) {
+			this.app.container.singleton(MemoryRightsStore, () => rightsStore);
+		}
+
+		this.app.container.singleton(AuthManager, () => {
+			const strategies: Record<string, JwtStrategy> = { jwt };
+			return new AuthManager({
+				defaultStrategy: config.defaultStrategy ?? "jwt",
+				strategies,
+				rights: rightsResolver,
+			});
+		});
+		// String alias so consumers that can't import the AuthManager class
+		// (e.g. @c9up/station, which stays agnostic of warden) can resolve
+		// it by name. Mirrors the convention other providers follow
+		// (events → "bus", rosetta → "i18n"). Without this, Station's
+		// `container.resolve("auth")` threw and its admin auth gate
+		// silently fell back to open-mode.
+		this.app.container.singleton("auth", () =>
+			this.app.container.resolve(AuthManager),
+		);
+	}
+
+	async boot() {
+		_setAuth(this.app.container.resolve(AuthManager) as AuthManager);
+	}
+}

package/src/bouncer/AuthorizationResponse.ts

@@ -0,0 +1,38 @@
+/**
+ * AuthorizationResponse — the value type every Bouncer check resolves to.
+ *
+ * Layer 2 (EVALUATION) of Warden's unified authorization (Epic 56). Faithful
+ * to AdonisJS Bouncer's `AuthorizationResponse`: instances are produced only by
+ * the `allow()` / `deny()` static constructors (the constructor is private), a
+ * denial defaults to HTTP 403, and a `translation` field is carried for shape
+ * parity with Adonis's i18n hook (always `undefined` in 56.2 — D6).
+ */
+export class AuthorizationResponse {
+	readonly authorized: boolean;
+	readonly message?: string;
+	readonly status?: number;
+	/** Parity placeholder for an i18n binding (always undefined in 56.2 — D6). */
+	readonly translation?: { identifier: string; data?: Record<string, unknown> };
+
+	private constructor(
+		authorized: boolean,
+		message?: string,
+		status?: number,
+		translation?: { identifier: string; data?: Record<string, unknown> },
+	) {
+		this.authorized = authorized;
+		this.message = message;
+		this.status = status;
+		this.translation = translation;
+	}
+
+	/** Authorized response (no status). */
+	static allow(): AuthorizationResponse {
+		return new AuthorizationResponse(true);
+	}
+
+	/** Denied response; `status` defaults to 403 (D6). */
+	static deny(message?: string, status = 403): AuthorizationResponse {
+		return new AuthorizationResponse(false, message, status);
+	}
+}

package/src/bouncer/BasePolicy.ts

@@ -0,0 +1,66 @@
+/**
+ * BasePolicy — extend it to group authorization checks for a resource. Action
+ * methods are positional `(user, resource?) => AuthorizerResponse` (D3); decorate
+ * a method with `@allowGuest()` / `@action({ allowGuest: true })` to let a guest
+ * (null user) reach it. The optional `before` / `after` hooks run around every
+ * action in the Adonis evaluation order (D5 — see PolicyAuthorizer).
+ */
+
+import type { UserPayload } from "../AuthManager.js";
+import type { EffectivePermissions, Scope } from "../rights/types.js";
+import type { AuthorizationResponse } from "./AuthorizationResponse.js";
+import { emptyPermissions, getPolicyContext } from "./policyContext.js";
+import type { HookResponse } from "./types.js";
+
+export abstract class BasePolicy {
+	/**
+	 * Runs before the action. A non-`undefined` return short-circuits the action
+	 * (a `boolean`/`AuthorizationResponse` becomes the result) — this is how a
+	 * moderator bypass or an early `deny('not found', 404)` works, including for
+	 * a guest. `undefined`/`void` falls through to the action.
+	 */
+	before?(
+		user: UserPayload | null,
+		action: string,
+		...args: unknown[]
+	): HookResponse;
+
+	/**
+	 * Runs after the action (or after a `before` short-circuit), receiving the
+	 * resolved response. A non-`undefined` return overrides it; `undefined`
+	 * keeps it.
+	 */
+	after?(
+		user: UserPayload | null,
+		action: string,
+		result: AuthorizationResponse,
+	): HookResponse;
+
+	/**
+	 * The Bouncer's active scope for the in-flight check (56.3). Defaults to
+	 * `"global"` when the policy is used without a Bouncer context.
+	 */
+	protected get scope(): Scope {
+		return getPolicyContext(this)?.scope ?? "global";
+	}
+
+	/**
+	 * The resolved `EffectivePermissions` for the Bouncer's `(user, scope)` (56.3):
+	 * role-derived ∪ ACL grants with global→tenant inheritance (per 56.1). A guest,
+	 * a no-resolver Bouncer, or a standalone policy ⇒ empty permissions.
+	 */
+	protected get permissions(): EffectivePermissions {
+		return getPolicyContext(this)?.permissions ?? emptyPermissions("global");
+	}
+
+	/**
+	 * Tenant-isolation helper (D5 — enforceable, not automatic). `true` under the
+	 * `global` scope (single-tenant — no boundary); under `{ tenant: T }` it is
+	 * `resource.tenantId === T`. A policy enforces explicitly, e.g.
+	 * `if (!this.sameTenant(post)) return false`.
+	 */
+	protected sameTenant(resource: { tenantId?: string | null }): boolean {
+		const scope = this.scope;
+		return scope === "global" ? true : resource.tenantId === scope.tenant;
+	}
+}

package/src/bouncer/Bouncer.ts

@@ -0,0 +1,236 @@
+/**
+ * Bouncer — Layer 2 (EVALUATION) of Warden's unified authorization (Epic 56).
+ *
+ * A Bouncer-faithful evaluation core (verified context7 `/adonisjs/bouncer`,
+ * 2026-06-01): standalone abilities via `Bouncer.ability`, class-based policies
+ * via `with(Policy)`, the four verbs `allows`/`denies`/`authorize`/`execute`,
+ * and guest-denied-by-default. The user is `UserPayload | null` (guest = null,
+ * D3); `authorize` throws `WARDEN_AUTHORIZATION_FAILURE` carrying `status: 403`
+ * (D2). 56.2 ships PURE mechanics — it does NOT consult the Layer-1
+ * `RightsResolver` (D4); abilities/policy methods receive `(user, ...args)` and
+ * the developer writes the predicate, exactly as Adonis does.
+ */
+
+import type { UserPayload } from "../AuthManager.js";
+import { WardenError } from "../errors.js";
+import type { RightsResolver } from "../rights/RightsResolver.js";
+import type { EffectivePermissions, Scope } from "../rights/types.js";
+import { AuthorizationResponse } from "./AuthorizationResponse.js";
+import type { BasePolicy } from "./BasePolicy.js";
+import { evaluate, isAction, throwAuthorizationFailure } from "./evaluate.js";
+import { PolicyAuthorizer } from "./PolicyAuthorizer.js";
+import { emptyPermissions } from "./policyContext.js";
+import type {
+	Ability,
+	AbilityOptions,
+	AuthorizerResponse,
+	BouncerContext,
+} from "./types.js";
+
+export class Bouncer {
+	readonly #user: UserPayload | null;
+	readonly #abilities: Record<string, Ability<never[]>>;
+	readonly #policies: Record<string, new () => BasePolicy>;
+	readonly #scope: Scope;
+	readonly #resolver: RightsResolver | undefined;
+	/** Memoized resolution — a Bouncer is fixed per `(user, scope)`, so resolve once (D3). */
+	#resolved: Promise<EffectivePermissions> | undefined;
+
+	constructor(
+		user: UserPayload | null,
+		abilities?: Record<string, Ability<never[]>>,
+		policies?: Record<string, new () => BasePolicy>,
+		context?: BouncerContext,
+	) {
+		this.#user = user;
+		this.#abilities = abilities ?? {};
+		this.#policies = policies ?? {};
+		this.#scope = context?.scope ?? "global";
+		this.#resolver = context?.resolver;
+	}
+
+	/** The active resolution scope (default `"global"`). */
+	get scope(): Scope {
+		return this.#scope;
+	}
+
+	/**
+	 * Resolve this Bouncer's `(user, scope)` to `EffectivePermissions`, memoized
+	 * once per instance (D3). Guest (`user === null`) or no resolver ⇒ empty
+	 * permissions — `resolve()` is never called for a guest (D9). 56.6 relocates
+	 * this cache to the request context without changing the policy-facing API.
+	 */
+	#resolvePermissions(): Promise<EffectivePermissions> {
+		if (this.#resolved === undefined) {
+			this.#resolved =
+				this.#resolver !== undefined && this.#user !== null
+					? this.#resolver.resolve(this.#user, this.#scope)
+					: Promise.resolve(emptyPermissions(this.#scope));
+		}
+		return this.#resolved;
+	}
+
+	/**
+	 * Define a standalone ability. Guest (null user) denied by default; pass
+	 * `{ allowGuest: true }` to let the callback run for a guest (D5 step 2).
+	 */
+	static ability<Args extends unknown[]>(
+		callback: (user: UserPayload, ...args: Args) => AuthorizerResponse,
+	): Ability<Args>;
+	static ability<Args extends unknown[]>(
+		options: AbilityOptions,
+		callback: (user: UserPayload | null, ...args: Args) => AuthorizerResponse,
+	): Ability<Args>;
+	static ability(
+		optionsOrCallback:
+			| AbilityOptions
+			| ((...args: never[]) => AuthorizerResponse),
+		maybeCallback?: (...args: never[]) => AuthorizerResponse,
+	): Ability {
+		let allowGuest = false;
+		let raw: unknown;
+		if (typeof optionsOrCallback === "function") {
+			raw = optionsOrCallback;
+		} else {
+			allowGuest = optionsOrCallback.allowGuest ?? false;
+			raw = maybeCallback;
+		}
+		// The typed overloads above carry the real callback signature for the
+		// caller; the impl param is the universal-function supertype so both
+		// overloads are accepted. `isAction` reinterprets it as the invokable
+		// `Action` shape (a type guard, not a cast — a function's parameter types
+		// are not observable at runtime).
+		if (!isAction(raw)) {
+			throw new WardenError(
+				"INVALID_ABILITY",
+				"Bouncer.ability requires a callback alongside the options object.",
+				{ hint: "Bouncer.ability({ allowGuest: true }, (user) => ...)" },
+			);
+		}
+		const callback = raw;
+		const execute = (
+			user: UserPayload | null,
+			...args: unknown[]
+		): AuthorizerResponse => callback(user, ...args);
+		return { allowGuest, execute };
+	}
+
+	/** Convenience — equivalent to `AuthorizationResponse.deny` (Adonis `bouncer.deny`). */
+	deny(message?: string, status?: number): AuthorizationResponse {
+		return AuthorizationResponse.deny(message, status);
+	}
+
+	/** Open a policy for checks (D8 — fresh `new PolicyClass()` per check). */
+	with(policy: (new () => BasePolicy) | string): PolicyAuthorizer {
+		const factory =
+			typeof policy === "string"
+				? this.#resolvePolicyClass(policy)
+				: () => new policy();
+		// The PolicyAuthorizer inherits the Bouncer's scope + the shared memoized
+		// resolve so every policy check sees the active `(user, scope)` (AC1/AC3).
+		return new PolicyAuthorizer(this.#user, factory, this.#scope, () =>
+			this.#resolvePermissions(),
+		);
+	}
+
+	/** Run an ability check and resolve to the full response. */
+	execute<Args extends unknown[]>(
+		ability: Ability<Args>,
+		...args: Args
+	): Promise<AuthorizationResponse>;
+	execute(ability: string, ...args: unknown[]): Promise<AuthorizationResponse>;
+	execute(
+		ability: string | Ability<never[]>,
+		...args: unknown[]
+	): Promise<AuthorizationResponse> {
+		return this.#evaluateAbility(ability, args);
+	}
+
+	/** True iff the ability is authorized. Never throws on denial. */
+	allows<Args extends unknown[]>(
+		ability: Ability<Args>,
+		...args: Args
+	): Promise<boolean>;
+	allows(ability: string, ...args: unknown[]): Promise<boolean>;
+	async allows(
+		ability: string | Ability<never[]>,
+		...args: unknown[]
+	): Promise<boolean> {
+		return (await this.#evaluateAbility(ability, args)).authorized;
+	}
+
+	/** Boolean negation of {@link allows}. Never throws on denial. */
+	denies<Args extends unknown[]>(
+		ability: Ability<Args>,
+		...args: Args
+	): Promise<boolean>;
+	denies(ability: string, ...args: unknown[]): Promise<boolean>;
+	async denies(
+		ability: string | Ability<never[]>,
+		...args: unknown[]
+	): Promise<boolean> {
+		return !(await this.#evaluateAbility(ability, args)).authorized;
+	}
+
+	/** Resolves on allow; throws `WARDEN_AUTHORIZATION_FAILURE` on deny (D2). */
+	authorize<Args extends unknown[]>(
+		ability: Ability<Args>,
+		...args: Args
+	): Promise<void>;
+	authorize(ability: string, ...args: unknown[]): Promise<void>;
+	async authorize(
+		ability: string | Ability<never[]>,
+		...args: unknown[]
+	): Promise<void> {
+		const response = await this.#evaluateAbility(ability, args);
+		if (!response.authorized) {
+			throwAuthorizationFailure(response);
+		}
+	}
+
+	async #evaluateAbility(
+		ability: string | Ability<never[]>,
+		args: unknown[],
+	): Promise<AuthorizationResponse> {
+		const resolved =
+			typeof ability === "string" ? this.#resolveAbility(ability) : ability;
+		return evaluate({
+			user: this.#user,
+			action: typeof ability === "string" ? ability : "(ability)",
+			allowGuest: resolved.allowGuest,
+			run: (user) => resolved.execute(user, ...args),
+			args,
+		});
+	}
+
+	#resolveAbility(name: string): Ability<never[]> {
+		const found = this.#abilities[name];
+		if (found === undefined) {
+			throw new WardenError(
+				"UNKNOWN_ABILITY",
+				`No ability "${name}" is registered on this Bouncer.`,
+				{ hint: "Register it via new Bouncer(user, { [name]: ability })." },
+			);
+		}
+		return found;
+	}
+
+	#resolvePolicyClass(name: string): () => BasePolicy {
+		// Lazy: the lookup runs when a verb constructs the policy, so an unknown
+		// name surfaces as a promise rejection (like every other verb error),
+		// not a synchronous throw at `with()` time.
+		return () => {
+			const ctor = this.#policies[name];
+			if (ctor === undefined) {
+				throw new WardenError(
+					"UNKNOWN_POLICY",
+					`No policy "${name}" is registered on this Bouncer.`,
+					{
+						hint: "Register it via new Bouncer(user, abilities, { [name]: Policy }).",
+					},
+				);
+			}
+			return new ctor();
+		};
+	}
+}

package/src/bouncer/PolicyAuthorizer.ts

@@ -0,0 +1,125 @@
+/**
+ * PolicyAuthorizer — the object returned by `bouncer.with(Policy)`. Exposes the
+ * same four verbs as the Bouncer, dispatched to a named action method on a
+ * freshly-constructed policy instance (D8 — `new PolicyClass()` per check). The
+ * `before`/`after` hooks and the per-method `@allowGuest` rule run through the
+ * shared D5 pipeline.
+ */
+
+import type { UserPayload } from "../AuthManager.js";
+import { WardenError } from "../errors.js";
+import type { EffectivePermissions, Scope } from "../rights/types.js";
+import type { AuthorizationResponse } from "./AuthorizationResponse.js";
+import { BasePolicy } from "./BasePolicy.js";
+import { getActionMetadata } from "./decorators.js";
+import {
+	type Action,
+	evaluate,
+	isAction,
+	throwAuthorizationFailure,
+} from "./evaluate.js";
+import { emptyPermissions, setPolicyContext } from "./policyContext.js";
+
+/**
+ * Resolve a named action method declared anywhere on the policy's own subclass
+ * chain (so an action inherited from an intermediate policy base class still
+ * dispatches). Rejects `constructor`, the `before`/`after` hooks, and any
+ * `BasePolicy`/`Object.prototype` member so a verb call can never dispatch to a
+ * non-action method — a guard the adversarial review specifically probes.
+ */
+function resolveActionMethod(policy: BasePolicy, action: string): Action {
+	// Reject the hooks + constructor by name, then accept an action declared
+	// anywhere on the policy's own subclass chain — the immediate prototype up to
+	// (but not including) BasePolicy.prototype / Object.prototype — so a method
+	// inherited from an intermediate policy base class (`class A extends B`) still
+	// dispatches, while BasePolicy's own members (scope/permissions getters) and
+	// Object.prototype members stay unreachable.
+	const isHookOrCtor =
+		action === "constructor" || action === "before" || action === "after";
+	let declaredHere = false;
+	for (
+		let proto: object | null = Object.getPrototypeOf(policy);
+		proto !== null &&
+		proto !== BasePolicy.prototype &&
+		proto !== Object.prototype;
+		proto = Object.getPrototypeOf(proto)
+	) {
+		if (Object.hasOwn(proto, action)) {
+			declaredHere = true;
+			break;
+		}
+	}
+	const candidate: unknown = Reflect.get(policy, action);
+	if (isHookOrCtor) {
+		declaredHere = false;
+	}
+	if (!declaredHere || !isAction(candidate)) {
+		throw new WardenError(
+			"UNKNOWN_POLICY_ACTION",
+			`Policy "${policy.constructor.name}" has no action "${action}"`,
+			{ hint: "Declare the action as a method on the policy class." },
+		);
+	}
+	return candidate.bind(policy);
+}
+
+export class PolicyAuthorizer {
+	readonly #user: UserPayload | null;
+	readonly #factory: () => BasePolicy;
+	readonly #scope: Scope;
+	readonly #resolvePermissions: () => Promise<EffectivePermissions>;
+
+	constructor(
+		user: UserPayload | null,
+		factory: () => BasePolicy,
+		scope: Scope = "global",
+		resolvePermissions: () => Promise<EffectivePermissions> = () =>
+			Promise.resolve(emptyPermissions(scope)),
+	) {
+		this.#user = user;
+		this.#factory = factory;
+		this.#scope = scope;
+		this.#resolvePermissions = resolvePermissions;
+	}
+
+	/** Run a check and resolve to the full response (D8 — fresh policy per check). */
+	async execute(
+		action: string,
+		...args: unknown[]
+	): Promise<AuthorizationResponse> {
+		const policy = this.#factory();
+		// Attach the active scope + resolved permissions BEFORE dispatch so the
+		// before/method/after pipeline all read `this.scope` / `this.permissions`.
+		const permissions = await this.#resolvePermissions();
+		setPolicyContext(policy, { scope: this.#scope, permissions });
+		const method = resolveActionMethod(policy, action);
+		const options = getActionMetadata(policy, action);
+		return evaluate({
+			user: this.#user,
+			action,
+			allowGuest: options.allowGuest ?? false,
+			run: (user) => method(user, ...args),
+			args,
+			before: policy.before?.bind(policy),
+			after: policy.after?.bind(policy),
+		});
+	}
+
+	/** True iff the action is authorized. Never throws on denial. */
+	async allows(action: string, ...args: unknown[]): Promise<boolean> {
+		return (await this.execute(action, ...args)).authorized;
+	}
+
+	/** Boolean negation of {@link allows}. Never throws on denial. */
+	async denies(action: string, ...args: unknown[]): Promise<boolean> {
+		return !(await this.execute(action, ...args)).authorized;
+	}
+
+	/** Resolves on allow; throws `WARDEN_AUTHORIZATION_FAILURE` on deny (D2). */
+	async authorize(action: string, ...args: unknown[]): Promise<void> {
+		const response = await this.execute(action, ...args);
+		if (!response.authorized) {
+			throwAuthorizationFailure(response);
+		}
+	}
+}

package/src/bouncer/decorators.ts

@@ -0,0 +1,44 @@
+/**
+ * Bouncer policy decorators — `@allowGuest()` / `@action()` mark policy methods
+ * that a guest (null user) may reach. Mirrors the `Guard.ts` idiom (D9):
+ * `reflect-metadata` side-effect import, a `Symbol.for` key, the legacy
+ * `MethodDecorator` signature, and a `getActionMetadata` reader.
+ */
+
+// Side-effect import: registers `Reflect.defineMetadata` / `getMetadata`. Pulled
+// in here (not transitively) so warden stays self-sufficient when published.
+import "reflect-metadata";
+import type { AbilityOptions } from "./types.js";
+
+/** Action metadata key — Symbol.for ensures cross-module accessibility. */
+const ACTION_KEY = Symbol.for("warden:bouncer:action");
+
+/**
+ * `@action({ allowGuest })` — configure a policy method's evaluation options.
+ */
+export function action(options: AbilityOptions): MethodDecorator {
+	return (target, propertyKey) => {
+		Reflect.defineMetadata(ACTION_KEY, options, target, propertyKey);
+	};
+}
+
+/**
+ * `@allowGuest()` — let a guest (null user) reach this policy method.
+ * Equivalent to `@action({ allowGuest: true })`.
+ */
+export function allowGuest(): MethodDecorator {
+	return action({ allowGuest: true });
+}
+
+/**
+ * Read a policy method's action metadata. Walks the prototype chain
+ * (`Reflect.getMetadata`) so it resolves from a policy INSTANCE — legacy
+ * decorators write metadata onto the class prototype, where the instance
+ * inherits it. Absent ⇒ `{}` (⇒ `allowGuest` falsy ⇒ guest denied).
+ */
+export function getActionMetadata(
+	target: object,
+	propertyKey: string | symbol,
+): AbilityOptions {
+	return Reflect.getMetadata(ACTION_KEY, target, propertyKey) ?? {};
+}