@plantops/web-kit 0.1.0

package/dist/iam-provider.js

@@ -0,0 +1,188 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * The one provider a PlantOps console mounts to become an IAM client.
+ *
+ * It owns the `IamClient`, the browser token store, and the answer to "is
+ * someone signed in". Everything else in this library — grants, permissions,
+ * navigation — reads from it.
+ *
+ * ## Why the client and the session state live in one component
+ *
+ * They are one thing wearing two hats. `IamClient` already performs the token
+ * lifecycle: it renews an access token before it lapses, it retries a `401`
+ * after a single shared refresh, and it drops the pair when a refresh is
+ * refused (`libs/iam-client/src/auth.ts`). React needs to *know* when that
+ * happens, and splitting the client into one provider and the session state
+ * into another means wiring a callback from the first into the second and
+ * hoping neither remounts. Instead the store is observable, both providers'
+ * jobs happen here, and the two can never disagree.
+ *
+ * ## Three ways a session ends, all handled the same way
+ *
+ * The user signs out; a refresh is refused because the token was revoked,
+ * expired or replayed (Doc 03 §4.1); or another tab does either. All three end
+ * as a `null` write to the token store, and the store's subscription is what
+ * flips this provider to `unauthenticated` — so the console reacts identically
+ * whether the reason was local, remote or in a different tab.
+ *
+ * ## Silent refresh
+ *
+ * `IamClient` renews on demand: the renewal happens when a request asks for a
+ * token. A console that has been sitting on a dashboard for twenty minutes
+ * makes no requests, so its access token lapses and the *next* click pays for a
+ * refresh — or fails, if the refresh token has expired meanwhile. The keepalive
+ * below asks for the token on a timer and when the tab regains focus, which
+ * turns that into a renewal nobody sees. It is not a second refresh mechanism:
+ * it calls the same single-flight `accessToken()` every request calls.
+ */
+import { IamClient, } from '@plantops/iam-client';
+import * as React from 'react';
+import { readTokenClaims } from './claims';
+import { BrowserTokenStore, TOKEN_STORAGE_KEY, } from './token-store';
+/** How often the keepalive asks for a token. Well inside the 15-minute TTL. */
+const KEEPALIVE_INTERVAL_MS = 60_000;
+const IamClientContext = React.createContext(null);
+const AuthContext = React.createContext(null);
+/** The typed IAM client. Throws outside an {@link IamProvider}. */
+export function useIam() {
+    const client = React.useContext(IamClientContext);
+    if (client === null) {
+        throw new Error('useIam() requires an <IamProvider> above it in the tree.');
+    }
+    return client;
+}
+/** Session state and the sign-in/sign-out actions. */
+export function useAuth() {
+    const auth = React.useContext(AuthContext);
+    if (auth === null) {
+        throw new Error('useAuth() requires an <IamProvider> above it in the tree.');
+    }
+    return auth;
+}
+/** Where the remembered tenant lives. Not a credential; see `lastClientSlug`. */
+const CLIENT_SLUG_STORAGE_KEY = 'plantops.last-client-slug';
+function readLocal(key) {
+    try {
+        return globalThis.localStorage?.getItem(key) ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function writeLocal(key, value) {
+    try {
+        globalThis.localStorage?.setItem(key, value);
+    }
+    catch {
+        /* storage unavailable; the field simply will not pre-fill */
+    }
+}
+function subjectFrom(session) {
+    const claims = readTokenClaims(session?.tokens.accessToken ?? null);
+    if (claims === null)
+        return null;
+    return {
+        id: claims.sub,
+        type: claims.sty,
+        clientId: claims.cid,
+        sessionId: claims.sid,
+        expiresAt: claims.exp * 1000,
+        email: session?.identity?.email ?? null,
+        clientSlug: session?.identity?.clientSlug ?? null,
+    };
+}
+export function IamProvider({ baseUrl, children, storageKey = TOKEN_STORAGE_KEY, clientSlugStorageKey = CLIENT_SLUG_STORAGE_KEY, timeoutMs, fetch, }) {
+    // Why the session ended, reported by the client.
+    //
+    // Routed through a ref because the client is constructed once, before the
+    // setter it needs exists, and because the ordering matters: `TokenSession`
+    // clears the store *first* and calls this *second* (`auth.ts`'s `forget`), so
+    // the store subscription below has already run by the time the reason
+    // arrives. Both writes land in one React batch and the reason wins, which is
+    // what makes "your session expired" distinguishable from "you signed out".
+    const reportSessionEnd = React.useRef(() => {
+        /* replaced below, before any request can fail */
+    });
+    const [{ client, store }] = React.useState(() => {
+        const tokenStore = new BrowserTokenStore(storageKey);
+        return {
+            store: tokenStore,
+            client: new IamClient({
+                baseUrl,
+                tokenStore,
+                timeoutMs,
+                fetch,
+                onSessionEnded: (reason) => reportSessionEnd.current(reason),
+            }),
+        };
+    });
+    const [status, setStatus] = React.useState('initializing');
+    const [subject, setSubject] = React.useState(null);
+    const [endedReason, setEndedReason] = React.useState(null);
+    const [lastClientSlug, setLastClientSlug] = React.useState(null);
+    reportSessionEnd.current = setEndedReason;
+    React.useEffect(() => {
+        const apply = (session) => {
+            const next = subjectFrom(session);
+            setSubject(next);
+            setStatus(next === null ? 'unauthenticated' : 'authenticated');
+            // Only cleared on the way *in*. On the way out the reason is the client's
+            // to report, and overwriting it here with `null` would erase it.
+            if (next !== null)
+                setEndedReason(null);
+        };
+        // The first read is what turns `initializing` into a real answer. It runs
+        // in an effect rather than during render because `localStorage` does not
+        // exist on the server, and rendering "signed in" on the client while the
+        // server rendered "signed out" would discard the tree.
+        apply(store.readSession());
+        // Unsubscribing also detaches the store's `storage` listener when this is
+        // the last subscriber, so there is nothing further to tear down — and
+        // nothing that React's development double-mount can tear down permanently.
+        return store.subscribe(apply);
+    }, [store]);
+    React.useEffect(() => {
+        setLastClientSlug(readLocal(clientSlugStorageKey));
+    }, [clientSlugStorageKey]);
+    // The keepalive. `accessToken()` renews when the token is within its leeway
+    // and is otherwise free, so this costs one function call a minute.
+    React.useEffect(() => {
+        if (status !== 'authenticated')
+            return;
+        const touch = () => {
+            void client.session.accessToken();
+        };
+        const timer = setInterval(touch, KEEPALIVE_INTERVAL_MS);
+        const onVisible = () => {
+            if (globalThis.document?.visibilityState === 'visible')
+                touch();
+        };
+        globalThis.addEventListener?.('visibilitychange', onVisible);
+        globalThis.addEventListener?.('online', touch);
+        return () => {
+            clearInterval(timer);
+            globalThis.removeEventListener?.('visibilitychange', onVisible);
+            globalThis.removeEventListener?.('online', touch);
+        };
+    }, [client, status]);
+    const login = React.useCallback(async (input) => {
+        await client.auth.login(input);
+        // Written after the login lands, so a failed attempt does not overwrite
+        // the tenant that worked yesterday.
+        store.writeIdentity({
+            email: input.email,
+            clientSlug: input.client_slug,
+        });
+        writeLocal(clientSlugStorageKey, input.client_slug);
+        setLastClientSlug(input.client_slug);
+    }, [client, store, clientSlugStorageKey]);
+    const logout = React.useCallback(async () => {
+        // `IamClient.auth.logout()` revokes server-side and clears locally even if
+        // the revocation call fails — and clearing calls `onSessionEnded('logout')`,
+        // so the reason and the status both arrive without further help here.
+        await client.auth.logout();
+    }, [client]);
+    const auth = React.useMemo(() => ({ status, subject, endedReason, login, logout, lastClientSlug }), [status, subject, endedReason, login, logout, lastClientSlug]);
+    return (_jsx(IamClientContext.Provider, { value: client, children: _jsx(AuthContext.Provider, { value: auth, children: children }) }));
+}

package/dist/index.d.ts

@@ -0,0 +1,51 @@
+/**
+ * `@plantops/web-kit` — the React runtime a PlantOps console needs to talk to
+ * the IAM.
+ *
+ * The stateful counterpart to `@plantops/ui`. Where that library renders,
+ * this one *knows things*: which client to call, where the tokens live, who is
+ * signed in, what they may do, and what their menu is. Between them they are
+ * everything a new console needs that is not its own screens — which is the
+ * point, because gatepass and visitor management are next (Doc 00 §9) and
+ * neither should reimplement sign-in.
+ *
+ * ```tsx
+ * // The whole of a console's setup.
+ * <PlantOpsProvider baseUrl={process.env.NEXT_PUBLIC_IAM_API_URL ?? '/api'}>
+ *   <RequireAuth onUnauthenticated={(next) => router.replace(`/login?next=${next}`)}>
+ *     <AppShell nav={<NavMenu tree={useNavigation().tree} … />}>…</AppShell>
+ *   </RequireAuth>
+ * </PlantOpsProvider>
+ * ```
+ *
+ * The base is a *path* there rather than an origin, and deliberately so: `/api`
+ * resolves against whatever origin served the page, so one build of a console
+ * runs at any hostname and nothing customer-specific is inlined into its bundle
+ * (Doc 11 §3). `HttpTransport` composes a request URL as `baseUrl + path`, so
+ * nothing under this provider can tell which of the two forms it was handed.
+ *
+ * ## What it deliberately does not do
+ *
+ * - **No router.** Redirects are callbacks. A `next/navigation` import would
+ *   pin every future console to one framework and make the components
+ *   untestable without it.
+ * - **No authorisation.** `usePermission` hides controls the subject cannot
+ *   use; the server decides (Doc 09 §4). Nothing here is a security boundary,
+ *   and `claims.ts` says so at the one place that reads a token.
+ * - **No data-fetching framework.** `useAsync` is forty lines and covers what an
+ *   admin console does. The two genuinely shared reads — grants and navigation
+ *   — are fetched once by their own providers.
+ */
+export * from './claims';
+export * from './errors';
+export * from './grants-provider';
+export * from './iam-provider';
+export * from './plantops-provider';
+export * from './require-auth';
+export * from './scope-coverage';
+export * from './token-store';
+export * from './use-async';
+export * from './use-navigation';
+export * from './use-notices';
+export * from './use-permission';
+//# 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,50 @@
+/**
+ * `@plantops/web-kit` — the React runtime a PlantOps console needs to talk to
+ * the IAM.
+ *
+ * The stateful counterpart to `@plantops/ui`. Where that library renders,
+ * this one *knows things*: which client to call, where the tokens live, who is
+ * signed in, what they may do, and what their menu is. Between them they are
+ * everything a new console needs that is not its own screens — which is the
+ * point, because gatepass and visitor management are next (Doc 00 §9) and
+ * neither should reimplement sign-in.
+ *
+ * ```tsx
+ * // The whole of a console's setup.
+ * <PlantOpsProvider baseUrl={process.env.NEXT_PUBLIC_IAM_API_URL ?? '/api'}>
+ *   <RequireAuth onUnauthenticated={(next) => router.replace(`/login?next=${next}`)}>
+ *     <AppShell nav={<NavMenu tree={useNavigation().tree} … />}>…</AppShell>
+ *   </RequireAuth>
+ * </PlantOpsProvider>
+ * ```
+ *
+ * The base is a *path* there rather than an origin, and deliberately so: `/api`
+ * resolves against whatever origin served the page, so one build of a console
+ * runs at any hostname and nothing customer-specific is inlined into its bundle
+ * (Doc 11 §3). `HttpTransport` composes a request URL as `baseUrl + path`, so
+ * nothing under this provider can tell which of the two forms it was handed.
+ *
+ * ## What it deliberately does not do
+ *
+ * - **No router.** Redirects are callbacks. A `next/navigation` import would
+ *   pin every future console to one framework and make the components
+ *   untestable without it.
+ * - **No authorisation.** `usePermission` hides controls the subject cannot
+ *   use; the server decides (Doc 09 §4). Nothing here is a security boundary,
+ *   and `claims.ts` says so at the one place that reads a token.
+ * - **No data-fetching framework.** `useAsync` is forty lines and covers what an
+ *   admin console does. The two genuinely shared reads — grants and navigation
+ *   — are fetched once by their own providers.
+ */
+export * from './claims';
+export * from './errors';
+export * from './grants-provider';
+export * from './iam-provider';
+export * from './plantops-provider';
+export * from './require-auth';
+export * from './scope-coverage';
+export * from './token-store';
+export * from './use-async';
+export * from './use-navigation';
+export * from './use-notices';
+export * from './use-permission';

package/dist/plantops-provider.d.ts

@@ -0,0 +1,48 @@
+/**
+ * One component that turns a React tree into a PlantOps console.
+ *
+ * Theme, antd's feedback hooks, the IAM client, the session, and the resolved
+ * grants — in the order they depend on each other, which is the part that is
+ * easy to get wrong and impossible to notice: mount `GrantsProvider` above
+ * `IamProvider` and every permission answers `false` with no error anywhere.
+ *
+ * ```tsx
+ * // apps/gatepass-web/src/app/providers.tsx
+ * <PlantOpsProvider baseUrl={API_URL} applicationId={GATEPASS_APP_ID}>
+ *   {children}
+ * </PlantOpsProvider>
+ * ```
+ *
+ * The composition also keeps the two libraries' seam honest. `@plantops/ui`
+ * knows nothing about the IAM and `@plantops/web-kit` renders nothing of its
+ * own; this file is the only place the two meet, and it meets them by nesting
+ * rather than by either importing the other's internals.
+ */
+import type { FetchLike } from '@plantops/iam-client';
+import { type ColorMode } from '@plantops/ui';
+import * as React from 'react';
+export interface PlantOpsProviderProps {
+    /** The IAM's origin, without the `/iam` or `/auth` prefix. */
+    baseUrl: string;
+    children: React.ReactNode;
+    /**
+     * Narrows resolved grants to one application (Doc 06 §11).
+     *
+     * Set it in a single-application console. The admin console leaves it unset:
+     * it spans the whole `iam.platform.*` / `iam.client.*` namespace and renders
+     * the cross-application shell.
+     */
+    applicationId?: string;
+    /** Fixes the colour mode, disabling the stored preference. */
+    colorMode?: ColorMode;
+    /** Initial mode before the stored preference is read. */
+    defaultColorMode?: ColorMode;
+    /** `localStorage` slot for the token pair. */
+    tokenStorageKey?: string;
+    /** Abort a request that has taken this long. */
+    timeoutMs?: number;
+    /** Overrides the runtime's `fetch` — for a test, or for instrumentation. */
+    fetch?: FetchLike;
+}
+export declare function PlantOpsProvider({ baseUrl, children, applicationId, colorMode, defaultColorMode, tokenStorageKey, timeoutMs, fetch, }: PlantOpsProviderProps): React.ReactElement;
+//# sourceMappingURL=plantops-provider.d.ts.map

package/dist/plantops-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plantops-provider.d.ts","sourceRoot":"","sources":["../src/plantops-provider.tsx"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAyB,KAAK,SAAS,EAAE,MAAM,cAAc,CAAC;AACrE,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAK/B,MAAM,WAAW,qBAAqB;IACpC,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,8DAA8D;IAC9D,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,yDAAyD;IACzD,gBAAgB,CAAC,EAAE,SAAS,CAAC;IAC7B,8CAA8C;IAC9C,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gDAAgD;IAChD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4EAA4E;IAC5E,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB;AAED,wBAAgB,gBAAgB,CAAC,EAC/B,OAAO,EACP,QAAQ,EACR,aAAa,EACb,SAAS,EACT,gBAAgB,EAChB,eAAe,EACf,SAAS,EACT,KAAK,GACN,EAAE,qBAAqB,GAAG,KAAK,CAAC,YAAY,CAa5C"}

package/dist/plantops-provider.js

@@ -0,0 +1,8 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { PlantOpsThemeProvider } from '@plantops/ui';
+import { GrantsProvider } from './grants-provider';
+import { IamProvider } from './iam-provider';
+export function PlantOpsProvider({ baseUrl, children, applicationId, colorMode, defaultColorMode, tokenStorageKey, timeoutMs, fetch, }) {
+    return (_jsx(PlantOpsThemeProvider, { mode: colorMode, defaultMode: defaultColorMode, children: _jsx(IamProvider, { baseUrl: baseUrl, storageKey: tokenStorageKey, timeoutMs: timeoutMs, fetch: fetch, children: _jsx(GrantsProvider, { applicationId: applicationId, children: children }) }) }));
+}

package/dist/require-auth.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The gate in front of every authenticated screen.
+ *
+ * Three states, three behaviours: while the browser is still working out
+ * whether a session exists it renders `fallback` (a session almost certainly
+ * *does* exist — the tokens are one synchronous `localStorage` read away — so
+ * flashing the login screen here would be a lie); with a session it renders the
+ * screen; without one it calls `onUnauthenticated` and renders nothing.
+ *
+ * Routing is a callback rather than an import. This library has no router: a
+ * `next/navigation` import here would tie the gatepass and visitor consoles to
+ * the Next app router forever, and would make this component untestable without
+ * one. The caller passes `(target) => router.replace(...)` and keeps the
+ * decision about *where* the login screen lives.
+ *
+ * ## The `next` parameter
+ *
+ * `onUnauthenticated` receives where the user was going. A deep link into a
+ * screen — from a bookmark, from a colleague's message — must survive the
+ * sign-in, or the link is only useful to someone already signed in. The caller
+ * decides how to carry it; a query parameter is the usual answer.
+ *
+ * ## This is not authorisation
+ *
+ * It answers "is anyone signed in", not "may they see this". Permission is the
+ * server's answer, arriving as a 403 the screen renders with `<ScreenError>`
+ * (Doc 09 §4). A component that hid screens by permission would be re-deriving
+ * the pruning the navigation endpoint already did, and would still have to
+ * handle the 403 for the deep link it got wrong.
+ */
+import * as React from 'react';
+export interface RequireAuthProps {
+    children: React.ReactNode;
+    /**
+     * Called once, when the browser has established that nobody is signed in.
+     *
+     * @param target The path the user was trying to reach, or `null` when it
+     *   could not be determined (server rendering).
+     */
+    onUnauthenticated: (target: string | null) => void;
+    /** Rendered while the session is being established. */
+    fallback?: React.ReactNode;
+}
+export declare function RequireAuth({ children, onUnauthenticated, fallback, }: RequireAuthProps): React.ReactNode;
+//# sourceMappingURL=require-auth.d.ts.map

package/dist/require-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"require-auth.d.ts","sourceRoot":"","sources":["../src/require-auth.tsx"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAI/B,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B;;;;;OAKG;IACH,iBAAiB,EAAE,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;IACnD,uDAAuD;IACvD,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC5B;AAED,wBAAgB,WAAW,CAAC,EAC1B,QAAQ,EACR,iBAAiB,EACjB,QAAe,GAChB,EAAE,gBAAgB,GAAG,KAAK,CAAC,SAAS,CA0BpC"}

package/dist/require-auth.js

@@ -0,0 +1,58 @@
+'use client';
+/**
+ * The gate in front of every authenticated screen.
+ *
+ * Three states, three behaviours: while the browser is still working out
+ * whether a session exists it renders `fallback` (a session almost certainly
+ * *does* exist — the tokens are one synchronous `localStorage` read away — so
+ * flashing the login screen here would be a lie); with a session it renders the
+ * screen; without one it calls `onUnauthenticated` and renders nothing.
+ *
+ * Routing is a callback rather than an import. This library has no router: a
+ * `next/navigation` import here would tie the gatepass and visitor consoles to
+ * the Next app router forever, and would make this component untestable without
+ * one. The caller passes `(target) => router.replace(...)` and keeps the
+ * decision about *where* the login screen lives.
+ *
+ * ## The `next` parameter
+ *
+ * `onUnauthenticated` receives where the user was going. A deep link into a
+ * screen — from a bookmark, from a colleague's message — must survive the
+ * sign-in, or the link is only useful to someone already signed in. The caller
+ * decides how to carry it; a query parameter is the usual answer.
+ *
+ * ## This is not authorisation
+ *
+ * It answers "is anyone signed in", not "may they see this". Permission is the
+ * server's answer, arriving as a 403 the screen renders with `<ScreenError>`
+ * (Doc 09 §4). A component that hid screens by permission would be re-deriving
+ * the pruning the navigation endpoint already did, and would still have to
+ * handle the 403 for the deep link it got wrong.
+ */
+import * as React from 'react';
+import { useAuth } from './iam-provider';
+export function RequireAuth({ children, onUnauthenticated, fallback = null, }) {
+    const { status } = useAuth();
+    // Held in a ref so a re-render — a colour-mode change, a resize — cannot fire
+    // a second redirect while the first is still in flight.
+    const redirected = React.useRef(false);
+    const redirect = React.useRef(onUnauthenticated);
+    redirect.current = onUnauthenticated;
+    React.useEffect(() => {
+        if (status !== 'unauthenticated' || redirected.current)
+            return;
+        redirected.current = true;
+        const location = globalThis.location;
+        const target = location === undefined ? null : `${location.pathname}${location.search}`;
+        redirect.current(target);
+    }, [status]);
+    React.useEffect(() => {
+        if (status === 'authenticated')
+            redirected.current = false;
+    }, [status]);
+    if (status === 'authenticated')
+        return children;
+    if (status === 'initializing')
+        return fallback;
+    return null;
+}

package/dist/scope-coverage.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Does a grant at *this* node reach *that* node? (Doc 04 §4.2)
+ *
+ * A binding at Plant B covers Plant B and everything under it — its
+ * departments, its gates — because scope paths are `ltree` materialized paths
+ * and coverage is the ancestor test `<@`. In Postgres that is one operator; in
+ * a browser it is a string prefix on `.`-separated labels, which is what these
+ * functions are.
+ *
+ * ## This is a copy, and that is deliberate
+ *
+ * `libs/auth-kit`'s `ScopeResolver` performs the same test server-side, and the
+ * boundary rules keep it out of a browser bundle on purpose: `auth-kit` is
+ * NestJS code, `scope:auth` is importable only by `iam-api` and future module
+ * APIs (Doc 08 §2). Rather than widen that boundary to share thirty lines, the
+ * predicate is restated here — with the understanding that **this copy decides
+ * nothing**. It hides a button (Doc 09 §4: "client-side hiding is UX; server
+ * enforces"). If the two ever disagree, the server wins and the user sees a
+ * 403, which is a cosmetic bug rather than a security one. Widening the
+ * boundary to avoid it would trade a cosmetic risk for a structural one.
+ *
+ * The label alphabet is what keeps the prefix test honest: labels are
+ * `n_<uuid-hex>` (Doc 01 §3.5), all the same length, containing no `.`. There
+ * is no `n_abc` / `n_abcdef` sibling pair for a naive `startsWith` to confuse —
+ * but the separator check below does not rely on that.
+ */
+import type { PermissionKey, ResolvedGrants, ScopePath } from '@plantops/contracts';
+/**
+ * True when `grantedPath` is `targetPath` or an ancestor of it.
+ *
+ * The `.` in the prefix test is load-bearing: without it `n_aa` would appear to
+ * cover `n_aab`, which is a different subtree.
+ */
+export declare function pathCovers(grantedPath: ScopePath, targetPath: ScopePath): boolean;
+/** True when any granted path covers the target. */
+export declare function anyPathCovers(grantedPaths: readonly ScopePath[], targetPath: ScopePath): boolean;
+/** True when the subject holds the permission anywhere at all. */
+export declare function holdsPermission(grants: ResolvedGrants | undefined, permission: PermissionKey): boolean;
+/**
+ * True when the subject holds the permission at a node covering `scopePath`.
+ *
+ * The narrower question, and the one a scope-specific control asks — "may I
+ * approve *this* gate's pass", not "may I approve passes".
+ */
+export declare function holdsPermissionAt(grants: ResolvedGrants | undefined, permission: PermissionKey, scopePath: ScopePath): boolean;
+/**
+ * The minimal set of paths the subject holds this permission at (Doc 04 §4.1).
+ *
+ * Already minimized by the server — a descendant is dropped when an ancestor is
+ * present — so a consumer narrowing a query by these paths needs no further
+ * reduction.
+ */
+export declare function permissionScopes(grants: ResolvedGrants | undefined, permission: PermissionKey): readonly ScopePath[];
+//# sourceMappingURL=scope-coverage.d.ts.map

package/dist/scope-coverage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-coverage.d.ts","sourceRoot":"","sources":["../src/scope-coverage.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAEpF;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,GAAG,OAAO,CAGjF;AAED,oDAAoD;AACpD,wBAAgB,aAAa,CAC3B,YAAY,EAAE,SAAS,SAAS,EAAE,EAClC,UAAU,EAAE,SAAS,GACpB,OAAO,CAET;AAED,kEAAkE;AAClE,wBAAgB,eAAe,CAC7B,MAAM,EAAE,cAAc,GAAG,SAAS,EAClC,UAAU,EAAE,aAAa,GACxB,OAAO,CAET;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,cAAc,GAAG,SAAS,EAClC,UAAU,EAAE,aAAa,EACzB,SAAS,EAAE,SAAS,GACnB,OAAO,CAGT;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,cAAc,GAAG,SAAS,EAClC,UAAU,EAAE,aAAa,GACxB,SAAS,SAAS,EAAE,CAEtB"}

package/dist/scope-coverage.js

@@ -0,0 +1,41 @@
+'use client';
+/**
+ * True when `grantedPath` is `targetPath` or an ancestor of it.
+ *
+ * The `.` in the prefix test is load-bearing: without it `n_aa` would appear to
+ * cover `n_aab`, which is a different subtree.
+ */
+export function pathCovers(grantedPath, targetPath) {
+    if (grantedPath === '' || targetPath === '')
+        return false;
+    return targetPath === grantedPath || targetPath.startsWith(`${grantedPath}.`);
+}
+/** True when any granted path covers the target. */
+export function anyPathCovers(grantedPaths, targetPath) {
+    return grantedPaths.some((granted) => pathCovers(granted, targetPath));
+}
+/** True when the subject holds the permission anywhere at all. */
+export function holdsPermission(grants, permission) {
+    return grants?.permissions.includes(permission) ?? false;
+}
+/**
+ * True when the subject holds the permission at a node covering `scopePath`.
+ *
+ * The narrower question, and the one a scope-specific control asks — "may I
+ * approve *this* gate's pass", not "may I approve passes".
+ */
+export function holdsPermissionAt(grants, permission, scopePath) {
+    if (grants === undefined)
+        return false;
+    return anyPathCovers(grants.scopes[permission] ?? [], scopePath);
+}
+/**
+ * The minimal set of paths the subject holds this permission at (Doc 04 §4.1).
+ *
+ * Already minimized by the server — a descendant is dropped when an ancestor is
+ * present — so a consumer narrowing a query by these paths needs no further
+ * reduction.
+ */
+export function permissionScopes(grants, permission) {
+    return grants?.scopes[permission] ?? [];
+}

package/dist/token-store.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Where a browser keeps its tokens, and how the tabs agree about them.
+ *
+ * `@plantops/iam-client` deliberately names no storage mechanism — its
+ * `TokenStore` is a two-method port and its default keeps tokens in memory,
+ * which is right for a service process and useless for a console, where a page
+ * reload would sign the user out. This is the browser half of that port.
+ *
+ * ## Why `localStorage`, and what that costs
+ *
+ * The console and the API are separate origins (Doc 08 §6 — Vercel and
+ * Railway), so a cookie would have to be `SameSite=None; Secure` on a shared
+ * parent domain, and the IAM would need CSRF defences for every mutating route
+ * because the browser would then attach it automatically. The IAM is a bearer-
+ * token API by design (Doc 03): nothing it exposes is authorised by ambient
+ * credentials, so there is no CSRF surface to defend — and putting the token
+ * back into a cookie would create one.
+ *
+ * The honest cost is XSS: script running on this origin can read the tokens.
+ * That is mitigated rather than eliminated — short access tokens (15 min,
+ * `ACCESS_TOKEN_TTL_SECONDS`), rotating refresh tokens with reuse detection
+ * (Doc 03 §4), and revocation that takes effect within seconds (Doc 03 §6) —
+ * and the residual risk is accepted knowingly here rather than by default. A
+ * deployment that disagrees implements this interface differently; nothing else
+ * changes.
+ *
+ * ## Cross-tab
+ *
+ * Two tabs share one origin and therefore one store. Without the `storage`
+ * listener, signing out in one tab leaves the other showing a console whose
+ * every request now fails, and signing *in* in one tab leaves the other on the
+ * login screen. The listener makes both immediate. It fires only in the *other*
+ * tabs — the writing tab never hears its own event — so a local change notifies
+ * through {@link BrowserTokenStore.write} instead.
+ */
+import type { StoredTokens, TokenStore } from '@plantops/iam-client';
+/** Default slot. Namespaced so two PlantOps consoles on one host can differ. */
+export declare const TOKEN_STORAGE_KEY = "plantops.tokens";
+/**
+ * Display-only facts about the signed-in person, kept beside the tokens.
+ *
+ * The access token carries `sub`/`cid`/`sid` and nothing human-readable
+ * (Doc 03 §2 — exactly seven claims), so after a reload the console knows *who*
+ * in the sense of a uuid and cannot put a name in the header. These two strings
+ * come from what the user typed at the login screen and exist purely so the
+ * header can say something true. Nothing is authorised from them.
+ */
+export interface IdentityHint {
+    email: string;
+    clientSlug: string;
+}
+export interface StoredSession {
+    tokens: StoredTokens;
+    identity: IdentityHint | null;
+}
+export type TokenStoreListener = (session: StoredSession | null) => void;
+/**
+ * A `TokenStore` backed by `localStorage`, with change notification.
+ *
+ * Safe to construct during server rendering: every method tolerates the absence
+ * of `window`, answering "no session", which is the correct answer on a server
+ * that has no user.
+ */
+export declare class BrowserTokenStore implements TokenStore {
+    private readonly storageKey;
+    private readonly listeners;
+    private readonly onStorage;
+    constructor(storageKey?: string);
+    /**
+     * Notified on every change, in this tab and in others.
+     *
+     * The `storage` listener is attached with the first subscriber and detached
+     * with the last, rather than in the constructor. That is what makes the store
+     * survive React's development double-mount: a listener attached at
+     * construction and removed on unmount is gone for good after the first
+     * remount — cross-tab sign-out then silently stops working, in development
+     * only, which is the worst place for it to hide.
+     */
+    subscribe(listener: TokenStoreListener): () => void;
+    /** Drops every subscriber and the window listener with them. */
+    dispose(): void;
+    read(): StoredTokens | null;
+    write(tokens: StoredTokens | null): void;
+    readSession(): StoredSession | null;
+    /** Records who signed in, for the header. Never used to authorise anything. */
+    writeIdentity(identity: IdentityHint | null): void;
+    clear(): void;
+    private writeSession;
+    private storage;
+    private emit;
+}
+//# sourceMappingURL=token-store.d.ts.map