@plantops/auth-kit 0.1.0

package/dist/core/revocation-cache.js

@@ -0,0 +1,68 @@
+"use strict";
+/**
+ * The revoked-`sid` cache (Doc 03 §6).
+ *
+ * Access tokens are verified by signature, which means a revoked session's
+ * token keeps verifying until it expires. That is unacceptable for the case the
+ * spec singles out — a shared gate terminal logged out at shift end — so every
+ * request also asks whether its `sid` has been killed. The answer has to be
+ * cheap enough to ask on every request, which rules out the database.
+ *
+ * ## One key per revocation, not one set
+ *
+ * Doc 03 §6 says "a Redis set / short-TTL cache". A set is the wrong half of
+ * that: it grows forever and has no per-member expiry, so it must be pruned by
+ * something, and the day that something stops running is the day the set is
+ * either unbounded or silently emptied. One key per revoked `sid`, with a TTL,
+ * prunes itself.
+ *
+ * The TTL is the **remaining exposure**, not the session lifetime. Once every
+ * token bearing a `sid` has expired, the revocation entry protects nothing:
+ * such a token is already refused for `exp`. So the entry lives for one access
+ * token lifetime plus the clock-skew leeway, and then disappears. This is what
+ * keeps the cache proportional to *recent* revocations rather than to all of
+ * them.
+ *
+ * ## What a cache miss means, and what an outage means
+ *
+ * A miss means "not revoked" — that is the happy path and it is DB-free, which
+ * is the whole design. An *error* means something different and must not be
+ * confused with it: a Redis outage that reads as "not revoked" silently
+ * un-revokes every session in the system for the duration. So this class throws
+ * on failure rather than returning `false`, and {@link AuthGuard} decides —
+ * with the database as the authority where one is reachable.
+ *
+ * There remains one honest gap: if Redis is *up* but has lost the key (an
+ * eviction, a flush, a restart without persistence), a revoked session works
+ * until its access token expires. Doc 03 §6 accepts exactly that bound —
+ * "because access tokens are short-lived, the revocation window is bounded even
+ * without a per-request DB hit". The database row stays authoritative, and the
+ * next refresh (Session 9) consults it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RevocationCache = void 0;
+const contracts_1 = require("@plantops/contracts");
+class RevocationCache {
+    constructor(store, options) {
+        this.store = store;
+        this.options = options;
+    }
+    /**
+     * Marks a session dead for every verifier sharing this cache.
+     *
+     * Call **after** the database write commits. Publishing first would let a
+     * concurrent reader see a revoked session that a rollback then restores — the
+     * same post-commit ordering the scope-move invalidation requires (Doc 07 §7).
+     */
+    async revoke(sessionId) {
+        // The value is a marker; only the key's existence carries meaning. `EX`
+        // rather than a separate `EXPIRE` so a connection lost between two commands
+        // cannot leave an immortal entry behind.
+        await this.store.set((0, contracts_1.revokedSessionKey)(sessionId), '1', 'EX', this.options.ttlSeconds);
+    }
+    /** @throws when the store cannot answer — see the class comment. */
+    async isRevoked(sessionId) {
+        return (await this.store.exists((0, contracts_1.revokedSessionKey)(sessionId))) > 0;
+    }
+}
+exports.RevocationCache = RevocationCache;

package/dist/core/scope-resolver.d.ts

@@ -0,0 +1,235 @@
+/**
+ * The WHERE dimension, as functions — coverage, query narrowing, and the
+ * decision {@link PermissionGuard} enforces (Doc 04 §3–5, §9, Doc 08 §4).
+ *
+ * ## Why the algorithm lives in a library and not in the IAM
+ *
+ * Doc 08 §7 singles this out: *"`auth-kit`: unit tests for coverage/scope logic
+ * (the highest-risk code — test the `covers()` prefix logic and deny-by-default
+ * thoroughly)"*. The reason is that the IAM is not the only process that runs
+ * it. `apps/gatepass-api` will answer "may this guard approve at this gate?"
+ * from a `ResolvedGrants` it fetched over HTTP, with no database and no IAM code
+ * in the request path — and if it re-implements coverage, the two disagree about
+ * what lies beneath what, and the artefact of the disagreement is a subject
+ * reaching a gate nobody granted them.
+ *
+ * So the prefix test, the point check and the `allowedPaths` projection are
+ * here, as pure functions over the published {@link ResolvedGrants} shape, and
+ * everything that needs a database sits behind {@link GrantsSource}.
+ *
+ * ## Coverage is label-wise, always
+ *
+ * `covers(N_b, N_t) ⇔ N_t.path <@ N_b.path` (Doc 04 §3). A character-wise
+ * `startsWith` would report `n_ab.n_cd` as living under `n_a` — the class of bug
+ * that grants access to a sibling subtree — so {@link pathIsWithin} compares on
+ * the separator, exactly as ltree's `<@` and migration 0006's GiST index do.
+ * `apps/iam-api`'s `scopes/path.util.ts` delegates to this function rather than
+ * carrying a second copy.
+ *
+ * ## The asymmetry of Doc 04 §9 is visible in the code that implements it
+ *
+ * {@link coversPath} asks two questions in the order the spec asks them: the
+ * permission dimension by **exact membership** (holding `dc.approve` says
+ * nothing about `dc.create`), and only then the scope dimension, which
+ * **inherits** (an ancestor covers its subtree). Merging them into one pass over
+ * `scopes` would return the same booleans and would stop the asymmetry being
+ * legible — which is how it gets simplified away later.
+ *
+ * ## Deny-by-default is the absence of a special case
+ *
+ * A subject with no bindings resolves to `{ permissions: [], scopes: {} }`, and
+ * every function below answers `false` or `[]` for it without a branch that says
+ * so. That is deliberate: a deny-by-default written as an explicit early return
+ * is a deny-by-default somebody can delete.
+ */
+import type { JwtClaims, PermissionKey, ResolvedGrants, ScopePath } from '@plantops/contracts';
+/**
+ * The part of a token authorization actually reads: who, of what type, in which
+ * tenant, on which session.
+ *
+ * Narrower than {@link JwtClaims} on purpose. `iss`, `iat` and `exp` are the
+ * verifier's business and are finished with by the time this runs, and a port
+ * that asked for them would oblige a host to carry them further than it needs
+ * to — the IAM in particular hands its RLS layer exactly these four fields
+ * (Doc 07 §5) and nothing else.
+ */
+export type SubjectClaims = Pick<JwtClaims, 'sub' | 'sty' | 'cid' | 'sid'>;
+/**
+ * `path <@ prefix` — is `path` the prefix itself, or a descendant of it?
+ *
+ * The one definition of "beneath" in the workspace.
+ */
+export declare function pathIsWithin(path: ScopePath, prefix: ScopePath): boolean;
+/** Does the subject hold `permission` at all — the WHAT, on its own? */
+export declare function holdsPermission(grants: ResolvedGrants, permission: PermissionKey): boolean;
+/**
+ * `can(subject, permissionKey, targetPath)` — Doc 04 §4.2's point check.
+ *
+ * O(covering paths for that permission), which the minimization Doc 04 §4.1
+ * requires keeps small.
+ */
+export declare function coversPath(grants: ResolvedGrants, permission: PermissionKey, targetPath: ScopePath): boolean;
+/**
+ * The covered subtree roots for one permission — Doc 04 §5's query narrowing.
+ *
+ * ```sql
+ * WHERE visitor.gate_path <@ ANY($1)
+ * ```
+ *
+ * This is the practical payoff of storing scope as a path: a module filters a
+ * list endpoint with one predicate instead of asking the IAM per row. The array
+ * is already minimal (Doc 04 §4.1), so it is short even for a subject with many
+ * bindings, and an empty one is the honest answer for a subject who may see
+ * nothing — a module must treat `[]` as "no rows", never as "no filter".
+ */
+export declare function allowedPathsFor(grants: ResolvedGrants, permission: PermissionKey): ScopePath[];
+/** What the resolver concluded about one request. */
+export declare const AuthorizationOutcome: {
+    readonly ALLOWED: "allowed";
+    /** The subject does not hold the permission anywhere. */
+    readonly PERMISSION_DENIED: "permission_denied";
+    /** They hold it, but not over the node the request named. */
+    readonly SCOPE_DENIED: "scope_denied";
+};
+export type AuthorizationOutcome = (typeof AuthorizationOutcome)[keyof typeof AuthorizationOutcome];
+export interface AuthorizationDecision {
+    outcome: AuthorizationOutcome;
+    /**
+     * What was asked for — carried through so the denial audit can name it.
+     *
+     * A list because a route may admit any one of several keys
+     * (`require-permission.decorator.ts`), which on this surface is Doc 06 §12
+     * and nothing else. Which keys are named depends on where the decision was
+     * reached, and the difference is what makes the trail readable:
+     *
+     * - **`permission_denied`** — every key the route would have accepted, since
+     *   the subject held none of them and all of them are the answer to "what
+     *   would have let this through".
+     * - **`scope_denied`** — only the keys the subject actually *holds*, because
+     *   those are the ones the coverage test ran against; listing a key they
+     *   never held would misreport a scope refusal as being about a permission
+     *   that was never in play.
+     * - **`allowed`** — the key that admitted, alone.
+     */
+    permissions: readonly PermissionKey[];
+    /** The scope node the request named, where it named one. */
+    scopeNodeId?: string;
+}
+/**
+ * A subject's grants, and the path of the node a request named.
+ *
+ * Both come back from one call because they come from one connection: in the
+ * IAM the grants may need a resolve against Postgres and the path always does,
+ * and opening two connections for one authorization decision is two acquisitions
+ * on the hot path (`docs/adr/0001-permission-guard-connection-strategy.md`).
+ */
+export interface AuthorizationSnapshot {
+    grants: ResolvedGrants;
+    /**
+     * Present only when a `scopeNodeId` was asked for. `null` means no such node
+     * is visible to this subject — which is deliberately the same answer for a
+     * node that does not exist and a node belonging to another tenant, so that a
+     * 403 cannot be used as a cross-tenant existence oracle (Doc 06 §2).
+     */
+    targetPath?: ScopePath | null;
+}
+/**
+ * Where resolved grants come from.
+ *
+ * The IAM binds the resolution engine of Doc 04 §4 directly; a future module
+ * binds a cached `iam-client` call to `/iam/permissions/resolve` (Doc 08 §4).
+ * Neither shape is visible from here, which is the whole point of the port —
+ * `auth-kit` may depend on `@plantops/contracts` and nothing else (Doc 08 §2),
+ * so it cannot name a `DataSource` or an HTTP client even if it wanted to.
+ */
+export interface GrantsSource {
+    /**
+     * @param claims the verified claims of the request being authorized.
+     * @param scopeNodeId when given, also resolve this node's path under the
+     * subject's own tenant.
+     */
+    authorize(claims: SubjectClaims, scopeNodeId?: string): Promise<AuthorizationSnapshot>;
+}
+export declare const GRANTS_SOURCE: unique symbol;
+/**
+ * The authorization decisions Doc 04 §8 orders, answerable without any
+ * framework: construct it with anything that satisfies {@link GrantsSource}
+ * — the IAM\u2019s Nest binding, an HTTP call to `/iam/permissions/resolve`, a
+ * fixture in a test — and every method behaves identically.
+ *
+ * The NestJS adapter (`adapters/nestjs`) subclasses this only to receive its
+ * dependency through Nest\u2019s injector; the rule itself lives here, where it
+ * can be exercised by a plain Node script.
+ */
+export declare class ScopeResolverCore {
+    private readonly source;
+    constructor(source: GrantsSource);
+    /** The subject\u2019s complete grant set (Doc 04 §4.1). */
+    grantsFor(claims: SubjectClaims): Promise<ResolvedGrants>;
+    /** Doc 04 §5\u2019s `allowedPaths`, for query narrowing. */
+    allowedPaths(claims: SubjectClaims, permission: PermissionKey): Promise<ScopePath[]>;
+    /** Doc 04 §4.2\u2019s point check against a node named by id. */
+    covers(claims: SubjectClaims, permission: PermissionKey, scopeNodeId: string): Promise<boolean>;
+    /**
+     * Hold the permission first, then cover the node — Doc 04 §8\u2019s order, which
+     * decides which denial the caller gets: PERMISSION_DENIED for a subject who
+     * holds nothing, SCOPE_DENIED for one who holds it elsewhere.
+     *
+     * A node invisible under this subject\u2019s own RLS context reports
+     * `targetPath: null`, and the decision is ALLOWED: invisibility is the
+     * handler\u2019s 404/409 to give, not a 403 that turns every scoped route into
+     * a cross-tenant existence oracle. What the guard refuses is exactly what
+     * only it can see — a reachable node that is not covered.
+     */
+    decide(claims: SubjectClaims, requirement: PermissionRequirement, scopeNodeId?: string): Promise<AuthorizationDecision>;
+}
+/** Where {@link PermissionGuard} reads a route\u2019s requirement from. */
+export declare const REQUIRE_PERMISSION_METADATA = "auth-kit:require-permission";
+/** Where it reads a route\u2019s deliberate opt-out from. */
+export declare const NO_PERMISSION_METADATA = "auth-kit:no-permission";
+export interface RequirePermissionOptions {
+    /**
+     * Dotted path to the target **scope node id** in the request, e.g.
+     * `params.id`, `body.scope_node_id`. Omitted where the route names no node.
+     */
+    scopeFrom?: string;
+    /**
+     * Treat an absent value at `scopeFrom` as "no node named" rather than as a
+     * denial.
+     *
+     * Off by default, and the default is the safe one: a route that says it takes
+     * a target and then receives none has nothing to run the coverage test
+     * against, and letting it through would silently downgrade a scoped check to
+     * an unscoped one. Turn it on only where absence is a legitimate shape of the
+     * request — `POST /iam/scopes` creating a tenant\u2019s first root has no parent
+     * to be covered by, and there is no other node it could name.
+     */
+    scopeOptional?: boolean;
+}
+/** What a route declares about itself. */
+export interface PermissionRequirement extends RequirePermissionOptions {
+    /**
+     * The keys that admit, any one of which is enough. One on all but a single
+     * route — the decorator\u2019s header has the full argument.
+     *
+     * Normalized to an array by the decorator so that everything downstream —
+     * `ScopeResolver.decide`, the guard, the denial audit — has one shape to
+     * handle rather than a union it must narrow at each step.
+     */
+    permissions: readonly PermissionKey[];
+}
+/**
+ * Reads `path` out of `request`, one segment at a time.
+ *
+ * Traversal stops at anything that is not a plain object, and the well-known
+ * prototype keys are refused outright: `scopeFrom` is authored in a controller
+ * rather than sent by a caller, but a decorator string is still a string, and a
+ * lookup that could walk into `__proto__` is one that would resolve to
+ * something no request contains.
+ *
+ * Returns `undefined` for anything that is not a non-empty string, so a missing
+ * parameter and a `null` body field are the same "no node named" — the caller
+ * chose neither.
+ */
+export declare function readScopeTarget(request: unknown, path: string): string | undefined;
+//# sourceMappingURL=scope-resolver.d.ts.map

package/dist/core/scope-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-resolver.d.ts","sourceRoot":"","sources":["../../src/core/scope-resolver.ts"],"names":[],"mappings":"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"}

package/dist/core/scope-resolver.js

@@ -0,0 +1,206 @@
+"use strict";
+/**
+ * The WHERE dimension, as functions — coverage, query narrowing, and the
+ * decision {@link PermissionGuard} enforces (Doc 04 §3–5, §9, Doc 08 §4).
+ *
+ * ## Why the algorithm lives in a library and not in the IAM
+ *
+ * Doc 08 §7 singles this out: *"`auth-kit`: unit tests for coverage/scope logic
+ * (the highest-risk code — test the `covers()` prefix logic and deny-by-default
+ * thoroughly)"*. The reason is that the IAM is not the only process that runs
+ * it. `apps/gatepass-api` will answer "may this guard approve at this gate?"
+ * from a `ResolvedGrants` it fetched over HTTP, with no database and no IAM code
+ * in the request path — and if it re-implements coverage, the two disagree about
+ * what lies beneath what, and the artefact of the disagreement is a subject
+ * reaching a gate nobody granted them.
+ *
+ * So the prefix test, the point check and the `allowedPaths` projection are
+ * here, as pure functions over the published {@link ResolvedGrants} shape, and
+ * everything that needs a database sits behind {@link GrantsSource}.
+ *
+ * ## Coverage is label-wise, always
+ *
+ * `covers(N_b, N_t) ⇔ N_t.path <@ N_b.path` (Doc 04 §3). A character-wise
+ * `startsWith` would report `n_ab.n_cd` as living under `n_a` — the class of bug
+ * that grants access to a sibling subtree — so {@link pathIsWithin} compares on
+ * the separator, exactly as ltree's `<@` and migration 0006's GiST index do.
+ * `apps/iam-api`'s `scopes/path.util.ts` delegates to this function rather than
+ * carrying a second copy.
+ *
+ * ## The asymmetry of Doc 04 §9 is visible in the code that implements it
+ *
+ * {@link coversPath} asks two questions in the order the spec asks them: the
+ * permission dimension by **exact membership** (holding `dc.approve` says
+ * nothing about `dc.create`), and only then the scope dimension, which
+ * **inherits** (an ancestor covers its subtree). Merging them into one pass over
+ * `scopes` would return the same booleans and would stop the asymmetry being
+ * legible — which is how it gets simplified away later.
+ *
+ * ## Deny-by-default is the absence of a special case
+ *
+ * A subject with no bindings resolves to `{ permissions: [], scopes: {} }`, and
+ * every function below answers `false` or `[]` for it without a branch that says
+ * so. That is deliberate: a deny-by-default written as an explicit early return
+ * is a deny-by-default somebody can delete.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NO_PERMISSION_METADATA = exports.REQUIRE_PERMISSION_METADATA = exports.ScopeResolverCore = exports.GRANTS_SOURCE = exports.AuthorizationOutcome = void 0;
+exports.pathIsWithin = pathIsWithin;
+exports.holdsPermission = holdsPermission;
+exports.coversPath = coversPath;
+exports.allowedPathsFor = allowedPathsFor;
+exports.readScopeTarget = readScopeTarget;
+/** The ltree label separator. Spelled once. */
+const SEPARATOR = '.';
+/**
+ * `path <@ prefix` — is `path` the prefix itself, or a descendant of it?
+ *
+ * The one definition of "beneath" in the workspace.
+ */
+function pathIsWithin(path, prefix) {
+    return path === prefix || path.startsWith(`${prefix}${SEPARATOR}`);
+}
+/** Does the subject hold `permission` at all — the WHAT, on its own? */
+function holdsPermission(grants, permission) {
+    return grants.permissions.includes(permission);
+}
+/**
+ * `can(subject, permissionKey, targetPath)` — Doc 04 §4.2's point check.
+ *
+ * O(covering paths for that permission), which the minimization Doc 04 §4.1
+ * requires keeps small.
+ */
+function coversPath(grants, permission, targetPath) {
+    if (!holdsPermission(grants, permission))
+        return false;
+    const covering = grants.scopes[permission];
+    return covering !== undefined && covering.some((path) => pathIsWithin(targetPath, path));
+}
+/**
+ * The covered subtree roots for one permission — Doc 04 §5's query narrowing.
+ *
+ * ```sql
+ * WHERE visitor.gate_path <@ ANY($1)
+ * ```
+ *
+ * This is the practical payoff of storing scope as a path: a module filters a
+ * list endpoint with one predicate instead of asking the IAM per row. The array
+ * is already minimal (Doc 04 §4.1), so it is short even for a subject with many
+ * bindings, and an empty one is the honest answer for a subject who may see
+ * nothing — a module must treat `[]` as "no rows", never as "no filter".
+ */
+function allowedPathsFor(grants, permission) {
+    return grants.scopes[permission] ?? [];
+}
+/** What the resolver concluded about one request. */
+exports.AuthorizationOutcome = {
+    ALLOWED: 'allowed',
+    /** The subject does not hold the permission anywhere. */
+    PERMISSION_DENIED: 'permission_denied',
+    /** They hold it, but not over the node the request named. */
+    SCOPE_DENIED: 'scope_denied',
+};
+exports.GRANTS_SOURCE = Symbol('auth-kit:GrantsSource');
+/**
+ * The authorization decisions Doc 04 §8 orders, answerable without any
+ * framework: construct it with anything that satisfies {@link GrantsSource}
+ * — the IAM\u2019s Nest binding, an HTTP call to `/iam/permissions/resolve`, a
+ * fixture in a test — and every method behaves identically.
+ *
+ * The NestJS adapter (`adapters/nestjs`) subclasses this only to receive its
+ * dependency through Nest\u2019s injector; the rule itself lives here, where it
+ * can be exercised by a plain Node script.
+ */
+class ScopeResolverCore {
+    constructor(source) {
+        this.source = source;
+    }
+    /** The subject\u2019s complete grant set (Doc 04 §4.1). */
+    async grantsFor(claims) {
+        const { grants } = await this.source.authorize(claims);
+        return grants;
+    }
+    /** Doc 04 §5\u2019s `allowedPaths`, for query narrowing. */
+    async allowedPaths(claims, permission) {
+        return allowedPathsFor(await this.grantsFor(claims), permission);
+    }
+    /** Doc 04 §4.2\u2019s point check against a node named by id. */
+    async covers(claims, permission, scopeNodeId) {
+        const snapshot = await this.source.authorize(claims, scopeNodeId);
+        const targetPath = snapshot.targetPath ?? null;
+        return targetPath !== null && coversPath(snapshot.grants, permission, targetPath);
+    }
+    /**
+     * Hold the permission first, then cover the node — Doc 04 §8\u2019s order, which
+     * decides which denial the caller gets: PERMISSION_DENIED for a subject who
+     * holds nothing, SCOPE_DENIED for one who holds it elsewhere.
+     *
+     * A node invisible under this subject\u2019s own RLS context reports
+     * `targetPath: null`, and the decision is ALLOWED: invisibility is the
+     * handler\u2019s 404/409 to give, not a 403 that turns every scoped route into
+     * a cross-tenant existence oracle. What the guard refuses is exactly what
+     * only it can see — a reachable node that is not covered.
+     */
+    async decide(claims, requirement, scopeNodeId) {
+        const scoped = requirement.scopeFrom !== undefined && scopeNodeId !== undefined;
+        const snapshot = await this.source.authorize(claims, scoped ? scopeNodeId : undefined);
+        const at = (scoped ? { scopeNodeId } : {});
+        // Held first, covered second — Doc 04 §9\u2019s asymmetry, over however many
+        // keys the route admits.
+        const held = requirement.permissions.filter((permission) => holdsPermission(snapshot.grants, permission));
+        if (held.length === 0) {
+            return {
+                ...at,
+                permissions: requirement.permissions,
+                outcome: exports.AuthorizationOutcome.PERMISSION_DENIED,
+            };
+        }
+        if (requirement.scopeFrom !== undefined && scopeNodeId === undefined) {
+            return requirement.scopeOptional
+                ? { ...at, permissions: [held[0]], outcome: exports.AuthorizationOutcome.ALLOWED }
+                : { ...at, permissions: held, outcome: exports.AuthorizationOutcome.SCOPE_DENIED };
+        }
+        if (!scoped) {
+            return { ...at, permissions: [held[0]], outcome: exports.AuthorizationOutcome.ALLOWED };
+        }
+        const targetPath = snapshot.targetPath ?? null;
+        if (targetPath === null) {
+            return { ...at, permissions: [held[0]], outcome: exports.AuthorizationOutcome.ALLOWED };
+        }
+        const covering = held.find((permission) => coversPath(snapshot.grants, permission, targetPath));
+        return covering === undefined
+            ? { ...at, permissions: held, outcome: exports.AuthorizationOutcome.SCOPE_DENIED }
+            : { ...at, permissions: [covering], outcome: exports.AuthorizationOutcome.ALLOWED };
+    }
+}
+exports.ScopeResolverCore = ScopeResolverCore;
+/** Where {@link PermissionGuard} reads a route\u2019s requirement from. */
+exports.REQUIRE_PERMISSION_METADATA = 'auth-kit:require-permission';
+/** Where it reads a route\u2019s deliberate opt-out from. */
+exports.NO_PERMISSION_METADATA = 'auth-kit:no-permission';
+/**
+ * Reads `path` out of `request`, one segment at a time.
+ *
+ * Traversal stops at anything that is not a plain object, and the well-known
+ * prototype keys are refused outright: `scopeFrom` is authored in a controller
+ * rather than sent by a caller, but a decorator string is still a string, and a
+ * lookup that could walk into `__proto__` is one that would resolve to
+ * something no request contains.
+ *
+ * Returns `undefined` for anything that is not a non-empty string, so a missing
+ * parameter and a `null` body field are the same "no node named" — the caller
+ * chose neither.
+ */
+function readScopeTarget(request, path) {
+    const segments = path.split('.');
+    let current = request;
+    for (const segment of segments) {
+        if (segment === '__proto__' || segment === 'constructor' || segment === 'prototype') {
+            return undefined;
+        }
+        if (typeof current !== 'object' || current === null)
+            return undefined;
+        current = current[segment];
+    }
+    return typeof current === 'string' && current.trim() !== '' ? current : undefined;
+}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `@plantops/auth-kit` — authorization for everything that talks to the IAM
+ * (Doc 08 §4), in three layers after roadmap Session 50:
+ *
+ * - **`core/**`** — framework-free. Token verification, the closed claim set,
+ *   revocation caching and the pure scope-coverage vocabulary. Runs in Nest,
+ *   in a plain Node script, in a Next.js route handler — anywhere.
+ * - **`adapters/nestjs`** — the guards, decorators and injectable resolver,
+ *   byte-for-byte the surface the IAM has always had.
+ * - **`adapters/fetch`** — a `Request`-in, decision-out helper for Next.js
+ *   route handlers and any WinterCG runtime.
+ */
+export * from './core';
+export * from './adapters/nestjs';
+export * from './adapters/fetch';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,cAAc,QAAQ,CAAC;AACvB,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,18 @@
+"use strict";
+/**
+ * `@plantops/auth-kit` — authorization for everything that talks to the IAM
+ * (Doc 08 §4), in three layers after roadmap Session 50:
+ *
+ * - **`core/**`** — framework-free. Token verification, the closed claim set,
+ *   revocation caching and the pure scope-coverage vocabulary. Runs in Nest,
+ *   in a plain Node script, in a Next.js route handler — anywhere.
+ * - **`adapters/nestjs`** — the guards, decorators and injectable resolver,
+ *   byte-for-byte the surface the IAM has always had.
+ * - **`adapters/fetch`** — a `Request`-in, decision-out helper for Next.js
+ *   route handlers and any WinterCG runtime.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./core"), exports);
+tslib_1.__exportStar(require("./adapters/nestjs"), exports);
+tslib_1.__exportStar(require("./adapters/fetch"), exports);