@plantops/auth-kit 0.1.0

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

@@ -0,0 +1,167 @@
+"use strict";
+/**
+ * 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.
+ */
+var PermissionGuard_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PermissionGuard = exports.DENIAL_AUDITOR = exports.VERIFIED_CLAIMS_SOURCE = exports.AuthorizationDeniedException = void 0;
+const tslib_1 = require("tslib");
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const contracts_1 = require("@plantops/contracts");
+const auth_guard_1 = require("./auth.guard");
+const require_permission_decorator_1 = require("./require-permission.decorator");
+const scope_resolver_1 = require("./scope-resolver");
+const scope_resolver_2 = require("../../core/scope-resolver");
+/**
+ * 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.
+ */
+class AuthorizationDeniedException extends common_1.ForbiddenException {
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'AuthorizationDeniedException';
+    }
+    /** The subject does not hold the permission at all. */
+    static permission() {
+        return new AuthorizationDeniedException(contracts_1.IamErrorCode.PERMISSION_DENIED, 'You do not have permission to perform this action');
+    }
+    /** They hold it, but not over the node they named. */
+    static scope() {
+        return new AuthorizationDeniedException(contracts_1.IamErrorCode.SCOPE_DENIED, 'You do not have permission at the requested scope');
+    }
+}
+exports.AuthorizationDeniedException = AuthorizationDeniedException;
+exports.VERIFIED_CLAIMS_SOURCE = Symbol('auth-kit:VerifiedClaimsSource');
+exports.DENIAL_AUDITOR = Symbol('auth-kit:DenialAuditor');
+let PermissionGuard = PermissionGuard_1 = class PermissionGuard {
+    constructor(reflector, resolver, claims, auditor = null) {
+        this.reflector = reflector;
+        this.resolver = resolver;
+        this.claims = claims;
+        this.auditor = auditor;
+        this.logger = new common_1.Logger(PermissionGuard_1.name);
+    }
+    async canActivate(context) {
+        if (context.getType() !== 'http')
+            return true;
+        const targets = [context.getHandler(), context.getClass()];
+        // A `@Public()` route has no subject, so there are no grants to check. It
+        // is also the one case where stepping aside cannot widen anything: the
+        // request reaches the handler with no RLS context, and every tenant policy
+        // matches nothing (`tenant-context.interceptor.ts`).
+        if (this.reflector.getAllAndOverride(auth_guard_1.IS_PUBLIC_METADATA, targets)) {
+            return true;
+        }
+        const requirement = this.reflector.getAllAndOverride(require_permission_decorator_1.REQUIRE_PERMISSION_METADATA, targets);
+        if (requirement === undefined) {
+            const exemption = this.reflector.getAllAndOverride(require_permission_decorator_1.NO_PERMISSION_METADATA, targets);
+            if (exemption !== undefined)
+                return true;
+            // Deny-by-default, and loudly. Reaching this is a wiring mistake rather
+            // than a caller's, and it must not be silent: the alternative reading —
+            // let an undeclared route through — is the one that produces a working,
+            // ungated endpoint nobody notices (`require-permission.decorator.ts`).
+            this.logger.error(`${context.getClass().name}.${context.getHandler().name} declares neither ` +
+                '@RequirePermission() nor @NoPermissionRequired(); refusing the request');
+            throw AuthorizationDeniedException.permission();
+        }
+        const request = context.switchToHttp().getRequest();
+        const claims = this.claims.claimsOf(request);
+        // Unreachable through `AuthGuard`, which refuses an unauthenticated request
+        // on a non-`@Public()` route. It is the backstop for a route that ever loses
+        // that guard, and refusing is the only safe reading of "no subject".
+        if (claims === undefined)
+            throw AuthorizationDeniedException.permission();
+        const scopeNodeId = requirement.scopeFrom === undefined
+            ? undefined
+            : (0, require_permission_decorator_1.readScopeTarget)(request, requirement.scopeFrom);
+        const decision = await this.resolver.decide(claims, requirement, scopeNodeId);
+        if (decision.outcome === scope_resolver_2.AuthorizationOutcome.ALLOWED)
+            return true;
+        // Best-effort and awaited: the row commits on its own connection, so it
+        // survives the rollback this 403 is about to cause, and the auditor's own
+        // contract is that it never throws (Doc 10 §3).
+        await this.auditor?.recordDenial(claims, decision.outcome, decision.permissions, decision.scopeNodeId);
+        throw decision.outcome === scope_resolver_2.AuthorizationOutcome.PERMISSION_DENIED
+            ? AuthorizationDeniedException.permission()
+            : AuthorizationDeniedException.scope();
+    }
+};
+exports.PermissionGuard = PermissionGuard;
+exports.PermissionGuard = PermissionGuard = PermissionGuard_1 = tslib_1.__decorate([
+    (0, common_1.Injectable)(),
+    tslib_1.__param(2, (0, common_1.Inject)(exports.VERIFIED_CLAIMS_SOURCE)),
+    tslib_1.__param(3, (0, common_1.Optional)()),
+    tslib_1.__param(3, (0, common_1.Inject)(exports.DENIAL_AUDITOR)),
+    tslib_1.__metadata("design:paramtypes", [core_1.Reflector,
+        scope_resolver_1.ScopeResolver, Object, Object])
+], PermissionGuard);

package/dist/adapters/nestjs/require-permission.decorator.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `@RequirePermission` — the WHAT, and optionally the WHERE, of a route
+ * (Doc 04 §8, Doc 08 §4).
+ *
+ * The decision vocabulary — {@link PermissionRequirement},
+ * {@link RequirePermissionOptions}, `readScopeTarget` — lives in the
+ * framework-free core (`core/scope-resolver.ts`); this adapter adds only what
+ * Nest needs: `SetMetadata` for the two decorators, and nothing else.
+ */
+import type { PermissionKey } from '@plantops/contracts';
+import { type RequirePermissionOptions } from '../../core/scope-resolver';
+export { NO_PERMISSION_METADATA, REQUIRE_PERMISSION_METADATA, type PermissionRequirement, type RequirePermissionOptions, readScopeTarget, } from '../../core/scope-resolver';
+/**
+ * Gates a route on `permission`, optionally at the scope node the request
+ * names.
+ *
+ * Applicable to a method or to a whole controller; the method wins where both
+ * carry one, which is Nest getAllAndOverride order and lets a controller state
+ * the common case once.
+ *
+ * Pass an array to admit any one of several keys — see Doc 04 §8 for when that
+ * is legitimate, and for why the others must not.
+ */
+export declare const RequirePermission: (permission: PermissionKey | readonly PermissionKey[], options?: RequirePermissionOptions) => import("@nestjs/common").CustomDecorator<string>;
+/**
+ * Opts a route out of permission gating, with the reason recorded at the call
+ * site. The reason is not decoration — it separates a considered exemption from
+ * a forgotten decorator.
+ */
+export declare const NoPermissionRequired: (reason: string) => import("@nestjs/common").CustomDecorator<string>;
+//# sourceMappingURL=require-permission.decorator.d.ts.map

package/dist/adapters/nestjs/require-permission.decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"require-permission.decorator.d.ts","sourceRoot":"","sources":["../../../src/adapters/nestjs/require-permission.decorator.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAIL,KAAK,wBAAwB,EAC9B,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EACL,sBAAsB,EACtB,2BAA2B,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,wBAAwB,EAC7B,eAAe,GAChB,MAAM,2BAA2B,CAAC;AACnC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,GAC5B,YAAY,aAAa,GAAG,SAAS,aAAa,EAAE,EACpD,UAAS,wBAA6B,qDAKpC,CAAC;AAEL;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,GAAI,QAAQ,MAAM,qDACN,CAAC"}

package/dist/adapters/nestjs/require-permission.decorator.js

@@ -0,0 +1,41 @@
+"use strict";
+/**
+ * `@RequirePermission` — the WHAT, and optionally the WHERE, of a route
+ * (Doc 04 §8, Doc 08 §4).
+ *
+ * The decision vocabulary — {@link PermissionRequirement},
+ * {@link RequirePermissionOptions}, `readScopeTarget` — lives in the
+ * framework-free core (`core/scope-resolver.ts`); this adapter adds only what
+ * Nest needs: `SetMetadata` for the two decorators, and nothing else.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NoPermissionRequired = exports.RequirePermission = exports.readScopeTarget = exports.REQUIRE_PERMISSION_METADATA = exports.NO_PERMISSION_METADATA = void 0;
+const common_1 = require("@nestjs/common");
+const scope_resolver_1 = require("../../core/scope-resolver");
+var scope_resolver_2 = require("../../core/scope-resolver");
+Object.defineProperty(exports, "NO_PERMISSION_METADATA", { enumerable: true, get: function () { return scope_resolver_2.NO_PERMISSION_METADATA; } });
+Object.defineProperty(exports, "REQUIRE_PERMISSION_METADATA", { enumerable: true, get: function () { return scope_resolver_2.REQUIRE_PERMISSION_METADATA; } });
+Object.defineProperty(exports, "readScopeTarget", { enumerable: true, get: function () { return scope_resolver_2.readScopeTarget; } });
+/**
+ * Gates a route on `permission`, optionally at the scope node the request
+ * names.
+ *
+ * Applicable to a method or to a whole controller; the method wins where both
+ * carry one, which is Nest getAllAndOverride order and lets a controller state
+ * the common case once.
+ *
+ * Pass an array to admit any one of several keys — see Doc 04 §8 for when that
+ * is legitimate, and for why the others must not.
+ */
+const RequirePermission = (permission, options = {}) => (0, common_1.SetMetadata)(scope_resolver_1.REQUIRE_PERMISSION_METADATA, {
+    permissions: typeof permission === 'string' ? [permission] : [...permission],
+    ...options,
+});
+exports.RequirePermission = RequirePermission;
+/**
+ * Opts a route out of permission gating, with the reason recorded at the call
+ * site. The reason is not decoration — it separates a considered exemption from
+ * a forgotten decorator.
+ */
+const NoPermissionRequired = (reason) => (0, common_1.SetMetadata)(scope_resolver_1.NO_PERMISSION_METADATA, reason);
+exports.NoPermissionRequired = NoPermissionRequired;

package/dist/adapters/nestjs/scope-resolver.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The Nest binding of the framework-free {@link ScopeResolverCore}: the only
+ * thing this class adds is receiving the `GrantsSource` port through Nest\u2019s
+ * injector (roadmap Session 50). Every decision method is inherited, so the
+ * rule lives in exactly one place — core/scope-resolver.ts — while remaining
+ * injectable anywhere a Nest token is.
+ */
+import { ScopeResolverCore, type GrantsSource } from '../../core/scope-resolver';
+export declare class ScopeResolver extends ScopeResolverCore {
+    constructor(source: GrantsSource);
+}
+//# sourceMappingURL=scope-resolver.d.ts.map

package/dist/adapters/nestjs/scope-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-resolver.d.ts","sourceRoot":"","sources":["../../../src/adapters/nestjs/scope-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAiB,iBAAiB,EAAE,KAAK,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAEhG,qBACa,aAAc,SAAQ,iBAAiB;gBACf,MAAM,EAAE,YAAY;CAGxD"}

package/dist/adapters/nestjs/scope-resolver.js

@@ -0,0 +1,24 @@
+"use strict";
+/**
+ * The Nest binding of the framework-free {@link ScopeResolverCore}: the only
+ * thing this class adds is receiving the `GrantsSource` port through Nest\u2019s
+ * injector (roadmap Session 50). Every decision method is inherited, so the
+ * rule lives in exactly one place — core/scope-resolver.ts — while remaining
+ * injectable anywhere a Nest token is.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScopeResolver = void 0;
+const tslib_1 = require("tslib");
+const common_1 = require("@nestjs/common");
+const scope_resolver_1 = require("../../core/scope-resolver");
+let ScopeResolver = class ScopeResolver extends scope_resolver_1.ScopeResolverCore {
+    constructor(source) {
+        super(source);
+    }
+};
+exports.ScopeResolver = ScopeResolver;
+exports.ScopeResolver = ScopeResolver = tslib_1.__decorate([
+    (0, common_1.Injectable)(),
+    tslib_1.__param(0, (0, common_1.Inject)(scope_resolver_1.GRANTS_SOURCE)),
+    tslib_1.__metadata("design:paramtypes", [Object])
+], ScopeResolver);

package/dist/core/claims.d.ts

@@ -0,0 +1,114 @@
+/**
+ * The closed claim set, and the checks every verifier must apply identically
+ * (Doc 03 §2, §6).
+ *
+ * ## Why this is not in the IAM
+ *
+ * The IAM signs; `admin-web`, `iam-client` and every future operational module
+ * verify — locally, from the published JWKS, without calling the IAM (Doc 06
+ * §11). "Verify the same way" is therefore a property of *separate processes*,
+ * and the only way to hold it is for all of them to run this code. A module
+ * that reimplements the expiry check with a different leeway rejects tokens the
+ * IAM considers live for a whole minute at every token edge; one that skips the
+ * issuer check accepts another deployment's tokens outright.
+ *
+ * ## The claim set is closed, in both directions
+ *
+ * Doc 03 §2 lists exactly seven claims: `iss, sub, sty, cid, sid, iat, exp`.
+ * Not "at least" — permissions, roles and scope nodes are *deliberately* absent
+ * so that a grant change takes effect on cache invalidation (Doc 04 §7) rather
+ * than on token expiry. So {@link assertExactClaims} refuses to sign an eighth,
+ * and {@link readAccessTokenClaims} refuses to accept one: a token this IAM
+ * issued cannot carry extras, so their presence means the payload came from
+ * somewhere else, and silently reading the seven we recognise is how a second
+ * issuer goes unnoticed.
+ *
+ * ## The one exception, and why it is not a hole
+ *
+ * `JWT_TOLERATED_CLAIM_KEYS` — today just `aud` — is accepted on the way in and
+ * dropped, never required and never read (ADR 0005 §5.1). Signing is unchanged,
+ * so this IAM still mints exactly seven claims.
+ *
+ * The asymmetry is deliberate, and it is about which half can be migrated.
+ * Every consumer verifies locally with this published code; the signer is a
+ * single deployment. A claim the IAM adds later is therefore free on the
+ * signing side and catastrophic on the verifying side — an older verifier
+ * rejects **every** token rather than ignoring the field it does not know. So
+ * the tolerance has to be in the field *before* the first publish or it is
+ * worthless, which is the deadline ADR 0005 §5.1 set against #72.
+ *
+ * What it costs is the tamper signal, for exactly one registered claim. What it
+ * buys is that reconsidering ADR 0005 §3.3 does not require a strictly-ordered
+ * upgrade across repositories this one does not control.
+ */
+import { type JwtClaims } from '@plantops/contracts';
+/** Why a token was refused. Never returned to a caller — see the note below. */
+export declare const TokenRejection: {
+    /** Not a compact JWS, or its segments do not decode. */
+    readonly MALFORMED: "malformed";
+    /** Header `alg` is not RS256 (Doc 03 §1). */
+    readonly UNSUPPORTED_ALGORITHM: "unsupported_algorithm";
+    /** `kid` is not in the published set — refetch JWKS, then reject. */
+    readonly UNKNOWN_KEY: "unknown_key";
+    /** Signature does not verify under the selected key. */
+    readonly BAD_SIGNATURE: "bad_signature";
+    /** `exp` has passed, allowing the 60 s leeway. */
+    readonly EXPIRED: "expired";
+    /** `iat` is in the future beyond the leeway — a clock or a forgery. */
+    readonly NOT_YET_VALID: "not_yet_valid";
+    /** `iss` is not the expected issuer. */
+    readonly WRONG_ISSUER: "wrong_issuer";
+    /** Claim set is not the Doc 03 §2 shape. */
+    readonly BAD_CLAIMS: "bad_claims";
+    /** The session behind `sid` has been revoked (Doc 03 §6). */
+    readonly REVOKED: "revoked";
+};
+export type TokenRejection = (typeof TokenRejection)[keyof typeof TokenRejection];
+/**
+ * A refused token, with the reason kept **server-side**.
+ *
+ * The distinction matters at the HTTP boundary: an `unknown_key` and an
+ * `expired` must look identical to the caller (both are a bare 401
+ * `AUTH_REQUIRED`), because the difference tells an attacker whether a forged
+ * `kid` was a near miss. The reason is here for logs, metrics and the
+ * refetch-then-reject decision — not for the response body.
+ */
+export declare class TokenVerificationError extends Error {
+    readonly reason: TokenRejection;
+    constructor(reason: TokenRejection, message: string);
+}
+/**
+ * Guards the closed claim set at signing time (Doc 03 §2).
+ *
+ * Typed input alone does not cover this: a structurally-typed object may carry
+ * extra properties at runtime, and `JSON.stringify` would faithfully sign them.
+ *
+ * Not relaxed by ADR 0005 §5.1: the tolerated claims are accepted on the way
+ * **in** only. This IAM mints seven claims, and a token of its own carrying an
+ * `aud` would mean something upstream put it there.
+ */
+export declare function assertExactClaims(claims: JwtClaims): Record<string, unknown>;
+/**
+ * Validates a **signature-verified** payload against the Doc 03 §2 shape.
+ *
+ * Call this only after the signature checks out. A token signed by a legitimate
+ * key is still attacker-influenced if any upstream path ever let a caller
+ * choose a claim value, which is why every field is re-validated on the way in
+ * and not merely on the way out.
+ *
+ * @throws {TokenVerificationError}
+ */
+export declare function readAccessTokenClaims(payload: Record<string, unknown>): JwtClaims;
+/**
+ * Checks issuer and the time window, with the shared 60 s leeway.
+ *
+ * The leeway is {@link CLOCK_SKEW_LEEWAY_SECONDS}, not a local number: the IAM
+ * and every consuming module must agree, or a token is live in one process and
+ * expired in the next at the edges (Doc 03 §6). Note that the issuer is a claim
+ * like any other and is worthless until the document is known to be genuine —
+ * so this runs after signature verification, never before it.
+ *
+ * @throws {TokenVerificationError}
+ */
+export declare function assertClaimsAcceptable(claims: JwtClaims, expectedIssuer: string, now?: Date): void;
+//# sourceMappingURL=claims.d.ts.map

package/dist/core/claims.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claims.d.ts","sourceRoot":"","sources":["../../src/core/claims.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,OAAO,EAKL,KAAK,SAAS,EACf,MAAM,qBAAqB,CAAC;AAE7B,gFAAgF;AAChF,eAAO,MAAM,cAAc;IACzB,wDAAwD;;IAExD,6CAA6C;;IAE7C,qEAAqE;;IAErE,wDAAwD;;IAExD,kDAAkD;;IAElD,uEAAuE;;IAEvE,wCAAwC;;IAExC,4CAA4C;;IAE5C,6DAA6D;;CAErD,CAAC;AACX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,OAAO,cAAc,CAAC,CAAC;AAElF;;;;;;;;GAQG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;IAE7C,QAAQ,CAAC,MAAM,EAAE,cAAc;gBAAtB,MAAM,EAAE,cAAc,EAC/B,OAAO,EAAE,MAAM;CAKlB;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAW5E;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CA0DjF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,SAAS,EACjB,cAAc,EAAE,MAAM,EACtB,GAAG,GAAE,IAAiB,GACrB,IAAI,CAkBN"}

package/dist/core/claims.js

@@ -0,0 +1,183 @@
+"use strict";
+/**
+ * The closed claim set, and the checks every verifier must apply identically
+ * (Doc 03 §2, §6).
+ *
+ * ## Why this is not in the IAM
+ *
+ * The IAM signs; `admin-web`, `iam-client` and every future operational module
+ * verify — locally, from the published JWKS, without calling the IAM (Doc 06
+ * §11). "Verify the same way" is therefore a property of *separate processes*,
+ * and the only way to hold it is for all of them to run this code. A module
+ * that reimplements the expiry check with a different leeway rejects tokens the
+ * IAM considers live for a whole minute at every token edge; one that skips the
+ * issuer check accepts another deployment's tokens outright.
+ *
+ * ## The claim set is closed, in both directions
+ *
+ * Doc 03 §2 lists exactly seven claims: `iss, sub, sty, cid, sid, iat, exp`.
+ * Not "at least" — permissions, roles and scope nodes are *deliberately* absent
+ * so that a grant change takes effect on cache invalidation (Doc 04 §7) rather
+ * than on token expiry. So {@link assertExactClaims} refuses to sign an eighth,
+ * and {@link readAccessTokenClaims} refuses to accept one: a token this IAM
+ * issued cannot carry extras, so their presence means the payload came from
+ * somewhere else, and silently reading the seven we recognise is how a second
+ * issuer goes unnoticed.
+ *
+ * ## The one exception, and why it is not a hole
+ *
+ * `JWT_TOLERATED_CLAIM_KEYS` — today just `aud` — is accepted on the way in and
+ * dropped, never required and never read (ADR 0005 §5.1). Signing is unchanged,
+ * so this IAM still mints exactly seven claims.
+ *
+ * The asymmetry is deliberate, and it is about which half can be migrated.
+ * Every consumer verifies locally with this published code; the signer is a
+ * single deployment. A claim the IAM adds later is therefore free on the
+ * signing side and catastrophic on the verifying side — an older verifier
+ * rejects **every** token rather than ignoring the field it does not know. So
+ * the tolerance has to be in the field *before* the first publish or it is
+ * worthless, which is the deadline ADR 0005 §5.1 set against #72.
+ *
+ * What it costs is the tamper signal, for exactly one registered claim. What it
+ * buys is that reconsidering ADR 0005 §3.3 does not require a strictly-ordered
+ * upgrade across repositories this one does not control.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TokenVerificationError = exports.TokenRejection = void 0;
+exports.assertExactClaims = assertExactClaims;
+exports.readAccessTokenClaims = readAccessTokenClaims;
+exports.assertClaimsAcceptable = assertClaimsAcceptable;
+const contracts_1 = require("@plantops/contracts");
+/** Why a token was refused. Never returned to a caller — see the note below. */
+exports.TokenRejection = {
+    /** Not a compact JWS, or its segments do not decode. */
+    MALFORMED: 'malformed',
+    /** Header `alg` is not RS256 (Doc 03 §1). */
+    UNSUPPORTED_ALGORITHM: 'unsupported_algorithm',
+    /** `kid` is not in the published set — refetch JWKS, then reject. */
+    UNKNOWN_KEY: 'unknown_key',
+    /** Signature does not verify under the selected key. */
+    BAD_SIGNATURE: 'bad_signature',
+    /** `exp` has passed, allowing the 60 s leeway. */
+    EXPIRED: 'expired',
+    /** `iat` is in the future beyond the leeway — a clock or a forgery. */
+    NOT_YET_VALID: 'not_yet_valid',
+    /** `iss` is not the expected issuer. */
+    WRONG_ISSUER: 'wrong_issuer',
+    /** Claim set is not the Doc 03 §2 shape. */
+    BAD_CLAIMS: 'bad_claims',
+    /** The session behind `sid` has been revoked (Doc 03 §6). */
+    REVOKED: 'revoked',
+};
+/**
+ * A refused token, with the reason kept **server-side**.
+ *
+ * The distinction matters at the HTTP boundary: an `unknown_key` and an
+ * `expired` must look identical to the caller (both are a bare 401
+ * `AUTH_REQUIRED`), because the difference tells an attacker whether a forged
+ * `kid` was a near miss. The reason is here for logs, metrics and the
+ * refetch-then-reject decision — not for the response body.
+ */
+class TokenVerificationError extends Error {
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+        this.name = 'TokenVerificationError';
+    }
+}
+exports.TokenVerificationError = TokenVerificationError;
+/**
+ * Guards the closed claim set at signing time (Doc 03 §2).
+ *
+ * Typed input alone does not cover this: a structurally-typed object may carry
+ * extra properties at runtime, and `JSON.stringify` would faithfully sign them.
+ *
+ * Not relaxed by ADR 0005 §5.1: the tolerated claims are accepted on the way
+ * **in** only. This IAM mints seven claims, and a token of its own carrying an
+ * `aud` would mean something upstream put it there.
+ */
+function assertExactClaims(claims) {
+    const allowed = new Set(contracts_1.JWT_CLAIM_KEYS);
+    const extra = Object.keys(claims).filter((key) => !allowed.has(key));
+    if (extra.length > 0) {
+        throw new Error(`Access token would carry claims outside Doc 03 §2: ${extra.join(', ')}. ` +
+            'Permissions, roles and scopes are resolved separately and must not be ' +
+            'embedded in a token.');
+    }
+    return { ...claims };
+}
+/**
+ * Validates a **signature-verified** payload against the Doc 03 §2 shape.
+ *
+ * Call this only after the signature checks out. A token signed by a legitimate
+ * key is still attacker-influenced if any upstream path ever let a caller
+ * choose a claim value, which is why every field is re-validated on the way in
+ * and not merely on the way out.
+ *
+ * @throws {TokenVerificationError}
+ */
+function readAccessTokenClaims(payload) {
+    const missing = contracts_1.JWT_CLAIM_KEYS.filter((key) => payload[key] === undefined);
+    if (missing.length > 0) {
+        throw new TokenVerificationError(exports.TokenRejection.BAD_CLAIMS, `Token is missing required claims: ${missing.join(', ')}`);
+    }
+    // Accepted, not required, and not returned — see the header. Every other
+    // unrecognised claim is still a refusal, so this widens the door by exactly
+    // one registered name rather than opening it.
+    const allowed = new Set([
+        ...contracts_1.JWT_CLAIM_KEYS,
+        ...contracts_1.JWT_TOLERATED_CLAIM_KEYS,
+    ]);
+    const extra = Object.keys(payload).filter((key) => !allowed.has(key));
+    if (extra.length > 0) {
+        throw new TokenVerificationError(exports.TokenRejection.BAD_CLAIMS, `Token carries claims outside Doc 03 §2: ${extra.join(', ')}`);
+    }
+    for (const key of ['iss', 'sub', 'cid', 'sid']) {
+        if (typeof payload[key] !== 'string' || payload[key] === '') {
+            throw new TokenVerificationError(exports.TokenRejection.BAD_CLAIMS, `Token claim "${key}" is not a non-empty string`);
+        }
+    }
+    for (const key of ['iat', 'exp']) {
+        if (typeof payload[key] !== 'number' || !Number.isInteger(payload[key])) {
+            throw new TokenVerificationError(exports.TokenRejection.BAD_CLAIMS, `Token claim "${key}" is not an integer`);
+        }
+    }
+    if (payload['sty'] !== contracts_1.SubjectType.USER && payload['sty'] !== contracts_1.SubjectType.SERVICE) {
+        throw new TokenVerificationError(exports.TokenRejection.BAD_CLAIMS, 'Token claim "sty" is not a known subject type');
+    }
+    // The seven, and only the seven. A tolerated claim is dropped here rather
+    // than passed through, so no caller downstream can come to depend on a value
+    // this system does not mint and does not validate.
+    return {
+        iss: payload['iss'],
+        sub: payload['sub'],
+        sty: payload['sty'],
+        cid: payload['cid'],
+        sid: payload['sid'],
+        iat: payload['iat'],
+        exp: payload['exp'],
+    };
+}
+/**
+ * Checks issuer and the time window, with the shared 60 s leeway.
+ *
+ * The leeway is {@link CLOCK_SKEW_LEEWAY_SECONDS}, not a local number: the IAM
+ * and every consuming module must agree, or a token is live in one process and
+ * expired in the next at the edges (Doc 03 §6). Note that the issuer is a claim
+ * like any other and is worthless until the document is known to be genuine —
+ * so this runs after signature verification, never before it.
+ *
+ * @throws {TokenVerificationError}
+ */
+function assertClaimsAcceptable(claims, expectedIssuer, now = new Date()) {
+    if (claims.iss !== expectedIssuer) {
+        throw new TokenVerificationError(exports.TokenRejection.WRONG_ISSUER, 'Token was issued by a different issuer');
+    }
+    const seconds = Math.floor(now.getTime() / 1000);
+    if (claims.exp + contracts_1.CLOCK_SKEW_LEEWAY_SECONDS <= seconds) {
+        throw new TokenVerificationError(exports.TokenRejection.EXPIRED, 'Token has expired');
+    }
+    if (claims.iat - contracts_1.CLOCK_SKEW_LEEWAY_SECONDS > seconds) {
+        throw new TokenVerificationError(exports.TokenRejection.NOT_YET_VALID, 'Token was issued in the future');
+    }
+}

package/dist/core/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The framework-free core of `auth-kit` (roadmap Session 50): token
+ * verification (JWS primitives + the JWKS verifier), the closed claim set,
+ * revocation caching, and the pure scope-coverage vocabulary. Nothing in this
+ * directory may import the Nest packages — enforced by
+ * `core/core-is-framework-free.spec.ts`.
+ */
+export * from './claims';
+export * from './jws';
+export * from './jwks-verifier';
+export * from './revocation-cache';
+export * from './scope-resolver';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,cAAc,UAAU,CAAC;AACzB,cAAc,OAAO,CAAC;AACtB,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC"}

package/dist/core/index.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+/**
+ * The framework-free core of `auth-kit` (roadmap Session 50): token
+ * verification (JWS primitives + the JWKS verifier), the closed claim set,
+ * revocation caching, and the pure scope-coverage vocabulary. Nothing in this
+ * directory may import the Nest packages — enforced by
+ * `core/core-is-framework-free.spec.ts`.
+ */
+tslib_1.__exportStar(require("./claims"), exports);
+tslib_1.__exportStar(require("./jws"), exports);
+tslib_1.__exportStar(require("./jwks-verifier"), exports);
+tslib_1.__exportStar(require("./revocation-cache"), exports);
+tslib_1.__exportStar(require("./scope-resolver"), exports);