@plantops/auth-kit 0.1.0

package/README.md

@@ -0,0 +1,7 @@
+# auth-kit
+
+This library was generated with [Nx](https://nx.dev).
+
+## Running unit tests
+
+Run `nx test auth-kit` to execute the unit tests via [Jest](https://jestjs.io).

package/dist/adapters/fetch/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The fetch adapter (roadmap Session 50): authorization for runtimes that
+ * have a Request and no Nest container — Next.js route handlers, workers,
+ * any WinterCG runtime.
+ *
+ * Deliberately smaller than the Nest guard: no decorators, no metadata, no
+ * denial audit. It answers the question a route handler actually has — who is
+ * this, and may they proceed? — and leaves policy to the caller. The pieces it
+ * delegates to are the same framework-free core the Nest guard uses, so a
+ * module and the IAM can never disagree about what a token means.
+ */
+import { type RevocationChecker, type TokenVerifier } from '../../core';
+export interface FetchAuthOptions {
+    /** Verifies the bearer token. JwksVerifier for every non-IAM process. */
+    verifier: TokenVerifier;
+    /**
+     * Answers whether a session is still live. Optional: without one,
+     * revocation is not checked and the decision rests on signature alone.
+     */
+    revocations?: RevocationChecker;
+}
+export type FetchDecision<V extends TokenVerifier = TokenVerifier> = {
+    ok: true;
+    claims: Awaited<ReturnType<V['verify']>>;
+} | {
+    ok: false;
+    status: 401;
+    code: string;
+};
+/**
+ * Verifies the bearer token of a fetch-style Request, and checks its session
+ * against revocations when a checker was provided.
+ *
+ * Every refusal is a bare 401 with the closed error code — the reason stays
+ * server-side (Doc 03 §6), exactly as the Nest guard draws the boundary.
+ */
+export declare function authorizeRequest(request: Request, options: FetchAuthOptions): Promise<FetchDecision>;
+//# sourceMappingURL=index.d.ts.map

package/dist/adapters/fetch/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/adapters/fetch/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAGL,KAAK,iBAAiB,EACtB,KAAK,aAAa,EACnB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,gBAAgB;IAC/B,yEAAyE;IACzE,QAAQ,EAAE,aAAa,CAAC;IACxB;;;OAGG;IACH,WAAW,CAAC,EAAE,iBAAiB,CAAC;CACjC;AAED,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,aAAa,GAAG,aAAa,IAC7D;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAA;CAAE,GACtD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,GAAG,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAS7C;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,aAAa,CAAC,CAuBxB"}

package/dist/adapters/fetch/index.js

@@ -0,0 +1,52 @@
+"use strict";
+/**
+ * The fetch adapter (roadmap Session 50): authorization for runtimes that
+ * have a Request and no Nest container — Next.js route handlers, workers,
+ * any WinterCG runtime.
+ *
+ * Deliberately smaller than the Nest guard: no decorators, no metadata, no
+ * denial audit. It answers the question a route handler actually has — who is
+ * this, and may they proceed? — and leaves policy to the caller. The pieces it
+ * delegates to are the same framework-free core the Nest guard uses, so a
+ * module and the IAM can never disagree about what a token means.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.authorizeRequest = authorizeRequest;
+const core_1 = require("../../core");
+function bearerOf(request) {
+    const header = request.headers.get('authorization');
+    if (header === null)
+        return undefined;
+    const match = /^Bearer (.+)$/.exec(header);
+    return match === null ? undefined : match[1];
+}
+/**
+ * Verifies the bearer token of a fetch-style Request, and checks its session
+ * against revocations when a checker was provided.
+ *
+ * Every refusal is a bare 401 with the closed error code — the reason stays
+ * server-side (Doc 03 §6), exactly as the Nest guard draws the boundary.
+ */
+async function authorizeRequest(request, options) {
+    const token = bearerOf(request);
+    if (token === undefined) {
+        return { ok: false, status: 401, code: "no-bearer-token" };
+    }
+    let claims;
+    try {
+        claims = await options.verifier.verify(token);
+    }
+    catch (error) {
+        if (error instanceof core_1.TokenVerificationError) {
+            void core_1.TokenRejection;
+            return { ok: false, status: 401, code: "invalid-token" };
+        }
+        throw error;
+    }
+    if (options.revocations !== undefined) {
+        const revoked = await options.revocations.isRevoked(claims.sid);
+        if (revoked)
+            return { ok: false, status: 401, code: "session-revoked" };
+    }
+    return { ok: true, claims };
+}

package/dist/adapters/nestjs/auth.guard.d.ts

@@ -0,0 +1,120 @@
+/**
+ * The guard every authenticated request passes through (Doc 03 §6).
+ *
+ * Three checks, in this order, and the order is the design:
+ *
+ * 1. **Signature and claims** — delegated to a {@link TokenVerifier}. The IAM
+ *    verifies with its own keys; a module verifies against the fetched JWKS.
+ * 2. **Revocation** — `sid` against the shared cache, so a force-logout lands
+ *    within seconds without a database round-trip on the happy path.
+ * 3. **Hand-off** — the verified claims are given to a {@link VerifiedClaimsSink},
+ *    which is the *only* way claims reach the RLS context (Doc 07 §5).
+ *
+ * Revocation runs after verification, never before: a `sid` read out of an
+ * unverified token is attacker-chosen, and looking it up would leak whether a
+ * guessed session exists through response timing.
+ *
+ * ## Deny by default
+ *
+ * The guard is registered app-wide and a route is authenticated unless it says
+ * otherwise with {@link Public}. That direction matters. An opt-in guard makes
+ * every new controller unprotected until someone remembers a decorator, and the
+ * symptom of forgetting is a route that works — which is the failure mode no
+ * test ever catches, because working is what tests assert.
+ *
+ * `@Public()` is for the routes that genuinely cannot carry a token: login and
+ * refresh (there is none yet), the JWKS (the thing that verifies tokens), and
+ * the ops probes.
+ *
+ * ## Everything is a bare 401
+ *
+ * A malformed token, a forged `kid`, an expired token and a revoked session all
+ * produce the same `AUTH_REQUIRED`. The reason is kept server-side on
+ * {@link TokenVerificationError} for logs and metrics — telling the caller
+ * which check failed tells an attacker whether a forged `kid` was a near miss,
+ * or whether a guessed `sid` exists.
+ */
+import { type CanActivate, type ExecutionContext } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import type { JwtClaims } from '@plantops/contracts';
+import type { TokenVerifier } from '../../core/jwks-verifier';
+import type { RevocationChecker } from '../../core/revocation-cache';
+/** Marks a route reachable without a bearer token. */
+export declare const IS_PUBLIC_METADATA = "auth-kit:public";
+/**
+ * Opts a route out of authentication.
+ *
+ * Use sparingly and say why at the call site: every one of these is a route
+ * with no subject, and therefore no RLS context and no tenant.
+ */
+export declare const Public: () => import("@nestjs/common").CustomDecorator<string>;
+/**
+ * Receives claims the guard has fully verified.
+ *
+ * The indirection exists because of a boundary: `auth-kit` may not import
+ * `@plantops/db` (Doc 08 §2), and it is `@plantops/db` that owns the branded
+ * `VerifiedClaims` type the RLS context accepts. So the host application
+ * supplies the one adapter that brands them, and that adapter is the single
+ * place in the system where an unverified object could ever become a verified
+ * one — a thing far easier to review in one file than in a guard shared by
+ * every module.
+ */
+export interface VerifiedClaimsSink {
+    accept(request: unknown, claims: JwtClaims): void;
+}
+/** What to do when the revocation cache cannot answer. */
+export interface RevocationFallback {
+    /**
+     * The authoritative answer, from the database.
+     *
+     * Present only in the IAM, which owns the `session` table. A module has no
+     * such table and therefore no fallback — see {@link AuthGuardOptions}.
+     *
+     * It receives the whole claim set, not just `sid`, because the right answer
+     * depends on `sty`: a service token's `sid` is ephemeral and backed by no
+     * row at all (Doc 03 §5), so looking it up would find nothing and read that
+     * absence as revoked — killing every machine identity the moment Redis
+     * blinked.
+     *
+     * @throws when it too cannot answer.
+     */
+    isRevoked(claims: JwtClaims): Promise<boolean>;
+}
+export interface AuthGuardOptions {
+    /**
+     * What a request means when neither the cache nor the fallback can answer.
+     *
+     * `'deny'` (the default) is correct: uncertainty about revocation must fall
+     * to refusal, or a Redis outage becomes a window in which every revoked
+     * session works again. `'allow'` exists for a deployment that would rather
+     * survive a cache outage than hold revocation — a real trade, but one that
+     * has to be made explicitly and written down, never inherited from a default.
+     */
+    onRevocationUnavailable?: 'deny' | 'allow';
+}
+export declare const TOKEN_VERIFIER: unique symbol;
+export declare const REVOCATION_CHECKER: unique symbol;
+export declare const VERIFIED_CLAIMS_SINK: unique symbol;
+export declare const REVOCATION_FALLBACK: unique symbol;
+export declare const AUTH_GUARD_OPTIONS: unique symbol;
+export declare class AuthGuard implements CanActivate {
+    private readonly reflector;
+    private readonly verifier;
+    private readonly revocations;
+    private readonly sink;
+    private readonly fallback;
+    private readonly options;
+    private readonly logger;
+    constructor(reflector: Reflector, verifier: TokenVerifier, revocations: RevocationChecker, sink: VerifiedClaimsSink, fallback?: RevocationFallback | null, options?: AuthGuardOptions);
+    canActivate(context: ExecutionContext): Promise<boolean>;
+    /**
+     * Cache first; database only when the cache could not answer.
+     *
+     * The happy path is one Redis `EXISTS` and no SQL, which is what makes this
+     * affordable on every request (Doc 03 §6).
+     */
+    private isRevoked;
+    /** One shape of refusal, with the reason kept out of the response. */
+    private refuse;
+}
+//# sourceMappingURL=auth.guard.d.ts.map

package/dist/adapters/nestjs/auth.guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.guard.d.ts","sourceRoot":"","sources":["../../../src/adapters/nestjs/auth.guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,gBAAgB,EAOtB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAErE,sDAAsD;AACtD,eAAO,MAAM,kBAAkB,oBAAoB,CAAC;AAEpD;;;;;GAKG;AACH,eAAO,MAAM,MAAM,wDAA8C,CAAC;AAElE;;;;;;;;;;GAUG;AACH,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI,CAAC;CACnD;AAED,0DAA0D;AAC1D,MAAM,WAAW,kBAAkB;IACjC;;;;;;;;;;;;;OAaG;IACH,SAAS,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAChD;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;OAQG;IACH,uBAAuB,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAC5C;AAED,eAAO,MAAM,cAAc,eAAmC,CAAC;AAC/D,eAAO,MAAM,kBAAkB,eAAuC,CAAC;AACvE,eAAO,MAAM,oBAAoB,eAAwC,CAAC;AAC1E,eAAO,MAAM,mBAAmB,eAAwC,CAAC;AACzE,eAAO,MAAM,kBAAkB,eAAsC,CAAC;AAEtE,qBACa,SAAU,YAAW,WAAW;IAIzC,OAAO,CAAC,QAAQ,CAAC,SAAS;IACF,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACrB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC1B,OAAO,CAAC,QAAQ,CAAC,IAAI;IAOnD,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAGzB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAhB1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA8B;gBAGlC,SAAS,EAAE,SAAS,EACI,QAAQ,EAAE,aAAa,EACnB,WAAW,EAAE,iBAAiB,EAC5B,IAAI,EAAE,kBAAkB,EAOtD,QAAQ,GAAE,kBAAkB,GAAG,IAAW,EAG1C,OAAO,GAAE,gBAAqB;IAG3C,WAAW,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC;IAoC9D;;;;;OAKG;YACW,SAAS;IAwBvB,sEAAsE;IACtE,OAAO,CAAC,MAAM;CAQf"}

package/dist/adapters/nestjs/auth.guard.js

@@ -0,0 +1,165 @@
+"use strict";
+/**
+ * The guard every authenticated request passes through (Doc 03 §6).
+ *
+ * Three checks, in this order, and the order is the design:
+ *
+ * 1. **Signature and claims** — delegated to a {@link TokenVerifier}. The IAM
+ *    verifies with its own keys; a module verifies against the fetched JWKS.
+ * 2. **Revocation** — `sid` against the shared cache, so a force-logout lands
+ *    within seconds without a database round-trip on the happy path.
+ * 3. **Hand-off** — the verified claims are given to a {@link VerifiedClaimsSink},
+ *    which is the *only* way claims reach the RLS context (Doc 07 §5).
+ *
+ * Revocation runs after verification, never before: a `sid` read out of an
+ * unverified token is attacker-chosen, and looking it up would leak whether a
+ * guessed session exists through response timing.
+ *
+ * ## Deny by default
+ *
+ * The guard is registered app-wide and a route is authenticated unless it says
+ * otherwise with {@link Public}. That direction matters. An opt-in guard makes
+ * every new controller unprotected until someone remembers a decorator, and the
+ * symptom of forgetting is a route that works — which is the failure mode no
+ * test ever catches, because working is what tests assert.
+ *
+ * `@Public()` is for the routes that genuinely cannot carry a token: login and
+ * refresh (there is none yet), the JWKS (the thing that verifies tokens), and
+ * the ops probes.
+ *
+ * ## Everything is a bare 401
+ *
+ * A malformed token, a forged `kid`, an expired token and a revoked session all
+ * produce the same `AUTH_REQUIRED`. The reason is kept server-side on
+ * {@link TokenVerificationError} for logs and metrics — telling the caller
+ * which check failed tells an attacker whether a forged `kid` was a near miss,
+ * or whether a guessed `sid` exists.
+ */
+var AuthGuard_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthGuard = exports.AUTH_GUARD_OPTIONS = exports.REVOCATION_FALLBACK = exports.VERIFIED_CLAIMS_SINK = exports.REVOCATION_CHECKER = exports.TOKEN_VERIFIER = exports.Public = exports.IS_PUBLIC_METADATA = void 0;
+const tslib_1 = require("tslib");
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const claims_1 = require("../../core/claims");
+/** Marks a route reachable without a bearer token. */
+exports.IS_PUBLIC_METADATA = 'auth-kit:public';
+/**
+ * Opts a route out of authentication.
+ *
+ * Use sparingly and say why at the call site: every one of these is a route
+ * with no subject, and therefore no RLS context and no tenant.
+ */
+const Public = () => (0, common_1.SetMetadata)(exports.IS_PUBLIC_METADATA, true);
+exports.Public = Public;
+exports.TOKEN_VERIFIER = Symbol('auth-kit:TokenVerifier');
+exports.REVOCATION_CHECKER = Symbol('auth-kit:RevocationChecker');
+exports.VERIFIED_CLAIMS_SINK = Symbol('auth-kit:VerifiedClaimsSink');
+exports.REVOCATION_FALLBACK = Symbol('auth-kit:RevocationFallback');
+exports.AUTH_GUARD_OPTIONS = Symbol('auth-kit:AuthGuardOptions');
+let AuthGuard = AuthGuard_1 = class AuthGuard {
+    constructor(reflector, verifier, revocations, sink, fallback = null, options = {}) {
+        this.reflector = reflector;
+        this.verifier = verifier;
+        this.revocations = revocations;
+        this.sink = sink;
+        this.fallback = fallback;
+        this.options = options;
+        this.logger = new common_1.Logger(AuthGuard_1.name);
+    }
+    async canActivate(context) {
+        if (context.getType() !== 'http')
+            return true;
+        const isPublic = this.reflector.getAllAndOverride(exports.IS_PUBLIC_METADATA, [
+            context.getHandler(),
+            context.getClass(),
+        ]);
+        // A public route is let through with **no** claims attached, so the
+        // transaction wrapper applies no RLS context and every tenant policy
+        // matches nothing. Public means unauthenticated, not privileged.
+        if (isPublic)
+            return true;
+        const request = context.switchToHttp().getRequest();
+        const token = bearerTokenOf(request.headers['authorization']);
+        if (token === undefined)
+            throw new common_1.UnauthorizedException('Authentication is required');
+        let claims;
+        try {
+            claims = await this.verifier.verify(token);
+        }
+        catch (error) {
+            throw this.refuse(error);
+        }
+        if (await this.isRevoked(claims)) {
+            throw this.refuse(new claims_1.TokenVerificationError(claims_1.TokenRejection.REVOKED, 'Session has been revoked'));
+        }
+        this.sink.accept(request, claims);
+        return true;
+    }
+    /**
+     * Cache first; database only when the cache could not answer.
+     *
+     * The happy path is one Redis `EXISTS` and no SQL, which is what makes this
+     * affordable on every request (Doc 03 §6).
+     */
+    async isRevoked(claims) {
+        try {
+            return await this.revocations.isRevoked(claims.sid);
+        }
+        catch (cacheError) {
+            this.logger.warn(`Revocation cache unavailable (${messageOf(cacheError)}); ` +
+                (this.fallback ? 'falling back to the database' : 'no database fallback'));
+            if (this.fallback) {
+                try {
+                    return await this.fallback.isRevoked(claims);
+                }
+                catch (dbError) {
+                    this.logger.error(`Revocation fallback also failed (${messageOf(dbError)})`);
+                }
+            }
+            // Both sources are down. Deny unless the deployment said otherwise.
+            return (this.options.onRevocationUnavailable ?? 'deny') === 'deny';
+        }
+    }
+    /** One shape of refusal, with the reason kept out of the response. */
+    refuse(error) {
+        if (error instanceof claims_1.TokenVerificationError) {
+            this.logger.debug(`Token refused: ${error.reason}`);
+        }
+        else {
+            this.logger.warn(`Token verification failed: ${messageOf(error)}`);
+        }
+        return new common_1.UnauthorizedException('Authentication is required');
+    }
+};
+exports.AuthGuard = AuthGuard;
+exports.AuthGuard = AuthGuard = AuthGuard_1 = tslib_1.__decorate([
+    (0, common_1.Injectable)(),
+    tslib_1.__param(1, (0, common_1.Inject)(exports.TOKEN_VERIFIER)),
+    tslib_1.__param(2, (0, common_1.Inject)(exports.REVOCATION_CHECKER)),
+    tslib_1.__param(3, (0, common_1.Inject)(exports.VERIFIED_CLAIMS_SINK)),
+    tslib_1.__param(4, (0, common_1.Optional)()),
+    tslib_1.__param(4, (0, common_1.Inject)(exports.REVOCATION_FALLBACK)),
+    tslib_1.__param(5, (0, common_1.Optional)()),
+    tslib_1.__param(5, (0, common_1.Inject)(exports.AUTH_GUARD_OPTIONS)),
+    tslib_1.__metadata("design:paramtypes", [core_1.Reflector, Object, Object, Object, Object, Object])
+], AuthGuard);
+/**
+ * The token from an `Authorization` header, or `undefined`.
+ *
+ * The scheme is matched case-insensitively (RFC 7235 makes it so) but the token
+ * is taken verbatim: trimming or re-casing it would change the bytes the
+ * signature covers. A repeated header arrives as an array — ambiguous, and
+ * therefore refused rather than resolved by picking one.
+ */
+function bearerTokenOf(header) {
+    if (typeof header !== 'string')
+        return undefined;
+    const [scheme, ...rest] = header.split(' ');
+    if (scheme?.toLowerCase() !== 'bearer' || rest.length !== 1)
+        return undefined;
+    return rest[0] === '' ? undefined : rest[0];
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/adapters/nestjs/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The NestJS adapter: guards, decorators and the injectable resolver,
+ * re-exported exactly as they were before Session 50 split them out of a flat
+ * directory. Consumers import from the package barrel and see no difference.
+ */
+export * from './auth.guard';
+export * from './permission.guard';
+export * from './require-permission.decorator';
+export * from './scope-resolver';
+//# sourceMappingURL=index.d.ts.map

package/dist/adapters/nestjs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/adapters/nestjs/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,kBAAkB,CAAC"}

package/dist/adapters/nestjs/index.js

@@ -0,0 +1,12 @@
+"use strict";
+/**
+ * The NestJS adapter: guards, decorators and the injectable resolver,
+ * re-exported exactly as they were before Session 50 split them out of a flat
+ * directory. Consumers import from the package barrel and see no difference.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./auth.guard"), exports);
+tslib_1.__exportStar(require("./permission.guard"), exports);
+tslib_1.__exportStar(require("./require-permission.decorator"), exports);
+tslib_1.__exportStar(require("./scope-resolver"), exports);

package/dist/adapters/nestjs/permission.guard.d.ts

@@ -0,0 +1,115 @@
+/**
+ * The guard that enforces `@RequirePermission` (Doc 04 §8, Doc 08 §4).
+ *
+ * `AuthGuard` establishes **who** is calling. This one establishes **whether
+ * they may** — the WHO × WHAT × WHERE question of Doc 04 §1, asked once per
+ * request, before the handler and before the transaction that would carry out
+ * whatever it was going to do.
+ *
+ * Four steps, and each one is a line of Doc 04 §8's contract:
+ *
+ * 1. Read the route's requirement. No requirement and no explicit opt-out is a
+ *    refusal — see {@link RequirePermission} for why the direction is that way
+ *    round.
+ * 2. Load the subject's resolved grants, through {@link GrantsSource}.
+ * 3. Confirm the permission is held, and — where the route names a scope node —
+ *    that the subject's grants cover it.
+ * 4. Refuse with `PERMISSION_DENIED` or `SCOPE_DENIED`, and audit the attempt.
+ *
+ * Steps 2 and 3 are {@link ScopeResolver.decide}, which is where the rule lives
+ * and where it is unit-tested. What is left here is the framework adapter: read
+ * metadata, read the request, translate an outcome into an exception. That
+ * split is deliberate — a guard is the one place a test has to build an
+ * `ExecutionContext` to reach, and authorization logic should not be behind
+ * that.
+ *
+ * ## Which connection step 2 runs on
+ *
+ * Not this file's decision, and deliberately not this file's problem.
+ * `docs/adr/0001-permission-guard-connection-strategy.md` settles it: a guard
+ * runs *before* the per-request transaction exists (Nest runs guards ahead of
+ * interceptors), so on a grants-cache miss the IAM's {@link GrantsSource} opens
+ * its own `QueryRunner`, applies the RLS context from the verified claims,
+ * resolves on it, and commits and releases in a `finally`. It does **not** open,
+ * reuse or leave open the request transaction: a guard has no "after" phase in
+ * which to close one, so `TenantContextInterceptor` stays its sole owner.
+ *
+ * `auth-kit` may depend on `@plantops/contracts` and nothing else (Doc 08 §2),
+ * so it could not name a `DataSource` here in any case — which is why the port
+ * exists and why a future module can satisfy it with a cached HTTP call instead.
+ *
+ * ## Every denial is audited, and a failure to audit is not a failure to deny
+ *
+ * Doc 04 §8 step 5 and Doc 10 §3: the attempt is recorded with the permission
+ * that was wanted and the target that was named. The IAM binds
+ * {@link DENIAL_AUDITOR} to `AuditService.recordDenial`, which commits on its
+ * own connection precisely because the request it accompanies is about to be
+ * rolled back by its own 403 — and which never throws, because turning a lost
+ * audit row into a 500 would tell a caller which requests were refused for which
+ * reason.
+ *
+ * The auditor is optional: a downstream module has no `audit_trail` table and
+ * records nothing. Binding it is the IAM's business.
+ *
+ * ## The two refusals say different things, and neither says whether the target
+ * exists
+ *
+ * `PERMISSION_DENIED` means the subject does not hold it anywhere;
+ * `SCOPE_DENIED` means they hold it, but not over the node they named. A node
+ * belonging to another tenant produces `SCOPE_DENIED` too — indistinguishable
+ * from one they simply do not cover, because RLS makes it so and Doc 06 §2
+ * requires that a denial never reveal cross-tenant existence.
+ */
+import { type CanActivate, type ExecutionContext, ForbiddenException } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { IamErrorCode, type PermissionKey } from '@plantops/contracts';
+import { ScopeResolver } from './scope-resolver';
+import { AuthorizationOutcome, type SubjectClaims } from '../../core/scope-resolver';
+/** The two 403 codes of Doc 06 §2, and no others. */
+export type DenialErrorCode = typeof IamErrorCode.PERMISSION_DENIED | typeof IamErrorCode.SCOPE_DENIED;
+/**
+ * A 403 that knows which of Doc 06 §2's two codes it is.
+ *
+ * `ForbiddenException` alone would come back as `PERMISSION_DENIED`, because
+ * that is the less specific of the two and the only one a bare status can imply
+ * (`http-exception.filter.ts`). The distinction is worth carrying: a client that
+ * sees `SCOPE_DENIED` can tell its user *where* they lack access, which is the
+ * one actionable thing about a refusal.
+ *
+ * `IamErrorCode` is a `@plantops/contracts` export, so naming it here crosses no
+ * boundary — the code table is part of the published contract, not of the IAM.
+ */
+export declare class AuthorizationDeniedException extends ForbiddenException {
+    readonly code: DenialErrorCode;
+    constructor(code: DenialErrorCode, message: string);
+    /** The subject does not hold the permission at all. */
+    static permission(): AuthorizationDeniedException;
+    /** They hold it, but not over the node they named. */
+    static scope(): AuthorizationDeniedException;
+}
+/** How the guard reads back the claims `AuthGuard` verified. */
+export interface VerifiedClaimsSource {
+    claimsOf(request: unknown): SubjectClaims | undefined;
+}
+/** Records a refused attempt (Doc 10 §3). Must not throw. */
+export interface DenialAuditor {
+    recordDenial(claims: SubjectClaims, outcome: Exclude<AuthorizationOutcome, 'allowed'>, 
+    /**
+     * The keys the refusal was about — one on all but the routes that admit
+     * either tier's key, and never empty. `AuthorizationDecision` in
+     * `scope-resolver.ts` says which keys a given outcome names.
+     */
+    permissions: readonly PermissionKey[], scopeNodeId?: string): Promise<void>;
+}
+export declare const VERIFIED_CLAIMS_SOURCE: unique symbol;
+export declare const DENIAL_AUDITOR: unique symbol;
+export declare class PermissionGuard implements CanActivate {
+    private readonly reflector;
+    private readonly resolver;
+    private readonly claims;
+    private readonly auditor;
+    private readonly logger;
+    constructor(reflector: Reflector, resolver: ScopeResolver, claims: VerifiedClaimsSource, auditor?: DenialAuditor | null);
+    canActivate(context: ExecutionContext): Promise<boolean>;
+}
+//# sourceMappingURL=permission.guard.d.ts.map

package/dist/adapters/nestjs/permission.guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission.guard.d.ts","sourceRoot":"","sources":["../../../src/adapters/nestjs/permission.guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AAEH,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,kBAAkB,EAKnB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAQvE,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,oBAAoB,EAAE,KAAK,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAErF,qDAAqD;AACrD,MAAM,MAAM,eAAe,GACvB,OAAO,YAAY,CAAC,iBAAiB,GACrC,OAAO,YAAY,CAAC,YAAY,CAAC;AAErC;;;;;;;;;;;GAWG;AACH,qBAAa,4BAA6B,SAAQ,kBAAkB;IAEhE,QAAQ,CAAC,IAAI,EAAE,eAAe;gBAArB,IAAI,EAAE,eAAe,EAC9B,OAAO,EAAE,MAAM;IAMjB,uDAAuD;IACvD,MAAM,CAAC,UAAU,IAAI,4BAA4B;IAOjD,sDAAsD;IACtD,MAAM,CAAC,KAAK,IAAI,4BAA4B;CAM7C;AAED,gEAAgE;AAChE,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,aAAa,GAAG,SAAS,CAAC;CACvD;AAED,6DAA6D;AAC7D,MAAM,WAAW,aAAa;IAC5B,YAAY,CACV,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,OAAO,CAAC,oBAAoB,EAAE,SAAS,CAAC;IACjD;;;;OAIG;IACH,WAAW,EAAE,SAAS,aAAa,EAAE,EACrC,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAED,eAAO,MAAM,sBAAsB,eAA0C,CAAC;AAC9E,eAAO,MAAM,cAAc,eAAmC,CAAC;AAE/D,qBACa,eAAgB,YAAW,WAAW;IAI/C,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACO,OAAO,CAAC,QAAQ,CAAC,MAAM;IAGvD,OAAO,CAAC,QAAQ,CAAC,OAAO;IAR1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoC;gBAGxC,SAAS,EAAE,SAAS,EACpB,QAAQ,EAAE,aAAa,EACS,MAAM,EAAE,oBAAoB,EAG5D,OAAO,GAAE,aAAa,GAAG,IAAW;IAGjD,WAAW,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC;CAiE/D"}