@marinoscar/platform-web 0.1.0-next.3 → 0.1.0-next.5

package/dist/identity/headless/device-credential.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Interpreting the UNTRUSTED `clientInfo` blob that the activation page shows.
+ *
+ * Issue #141. The device authorization flow can now mint one of two very
+ * different credentials, and WHICH ONE is chosen by the device that started the
+ * flow, not by the person approving it:
+ *
+ *   - `session` — the historical behaviour: a short-lived access JWT plus a
+ *     refresh token, roughly a week of life, dies with the session.
+ *   - `pat` — a personal access token with a ~90-day life that authenticates
+ *     against every ordinary guarded endpoint and stays valid until it expires
+ *     or is revoked from Settings, Access Tokens.
+ *
+ * Before this module existed the two approvals rendered IDENTICALLY. That is
+ * the gap: `POST /auth/device/code` is public, so anyone can start a flow that
+ * asks for the 90-day credential, and the user was consenting to something
+ * materially different from what the screen described. Everything here exists
+ * to make the difference legible without trusting the blob that describes it.
+ *
+ * THIS IS THE ONLY PLACE `clientInfo` MAY BE INTERPRETED. Call sites take the
+ * outputs, never the raw fields.
+ */
+/**
+ * The credential kinds the UI knows how to describe.
+ *
+ * @stability stable
+ */
+export type DeviceCredentialKind = 'session' | 'pat';
+/**
+ * The PAT lifetime we tell the user to expect, in days.
+ *
+ * APPROXIMATE ON PURPOSE. The real number is server-side configuration
+ * (`DEVICE_PAT_EXPIRY_DAYS`, defaulting to 90 and clamped to 1..999 by
+ * `DeviceAuthService.resolvePatExpiryDays`) and `GET /auth/device/activate`
+ * does not return it. So the copy hedges — "about 90 days" — rather than
+ * stating a number we cannot actually know, because a confidently wrong
+ * lifetime is worse than an admitted approximation: it is the exact detail the
+ * user would rely on to decide.
+ *
+ * FOLLOW-UP: have the activate response carry the resolved expiry (ideally the
+ * concrete `expiresAt` the token would get), and then this constant and the
+ * hedged wording both go away. Until then, a deployment that overrides
+ * `DEVICE_PAT_EXPIRY_DAYS` shows a number that is off — still the right order
+ * of magnitude, and still unambiguously "not a browser session", which is the
+ * decision this screen actually drives.
+ *
+ * @stability stable
+ */
+export declare const DEVICE_PAT_APPROX_DAYS = 90;
+/**
+ * Which credential is this approval about?
+ *
+ * FAILS TOWARD `session` BY DESIGN, and the asymmetry matters. Saying "session"
+ * for something the server will mint as a PAT under-warns by one step; saying
+ * "PAT" for an ordinary session cries wolf on the common path and trains people
+ * to click through the warning — which destroys its value for the case it
+ * exists for. We therefore claim `pat` ONLY on an exact `'pat'` string, which
+ * is precisely the condition the API's own `readTokenType()` uses to decide
+ * what to mint. The two predicates agreeing character-for-character is what
+ * keeps the screen and the behaviour in sync; loosening this one (case-folding,
+ * `String(x).includes('pat')`) without loosening that one would put them back
+ * out of step, in the direction where the screen lies.
+ *
+ * The shapes this must survive, all of them real:
+ *   - `clientInfo` absent entirely (the API declares the field optional, and
+ *     `null` is what a hand-written or restored row carries).
+ *   - `tokenType` absent — every row written before #141.
+ *   - `tokenType` present but unexpected: a typo'd `'PAT'`, or a probe sending
+ *     `'admin'`. The WRITE path rejects those with a 400, but this is a READ of
+ *     a JSONB column that is never re-validated, so the value is whatever is
+ *     actually in the database. Such a row will mint a session (the API's own
+ *     fallback), and describing it as a session is therefore correct, not just
+ *     conservative.
+ *   - `clientInfo` not an object at all (a string, an array, a number): JSONB
+ *     round-trips any of those, and a property read on them must not throw.
+ *
+ * @param clientInfo - the untrusted `clientInfo` of the activation response.
+ * @returns `'pat'` only for an exact `tokenType: 'pat'`, else `'session'`.
+ *
+ * @stability stable
+ */
+export declare function readCredentialKind(clientInfo: unknown): DeviceCredentialKind;
+/**
+ * Display bounds for the free-text fields, in characters.
+ *
+ * A name is a label, not a payload. Without a bound, a 4KB `deviceName` (the
+ * request body has no per-field length limit on the way in) pushes the
+ * Approve/Deny buttons off a phone screen, or buries the credential warning
+ * under a wall of text the attacker wrote — a layout-level way of hiding the
+ * one thing this screen exists to show. The user agent gets a longer budget
+ * because real ones are genuinely long, and truncating a legitimate UA to 64
+ * characters would hurt recognition, which is the entire reason it is shown.
+ *
+ * @stability stable
+ */
+export declare const DEVICE_NAME_MAX_DISPLAY = 64;
+/**
+ * Display bound for the device's user agent, in characters (see {@link DEVICE_NAME_MAX_DISPLAY}).
+ *
+ * @stability stable
+ */
+export declare const USER_AGENT_MAX_DISPLAY = 180;
+/**
+ * Display bound for the device's IP address, in characters (see {@link DEVICE_NAME_MAX_DISPLAY}).
+ *
+ * @stability stable
+ */
+export declare const IP_ADDRESS_MAX_DISPLAY = 64;
+/**
+ * Turn one untrusted `clientInfo` string into something safe to render.
+ *
+ * React escapes text nodes, so this is NOT about script injection — that is
+ * already handled, and nothing on this page uses `dangerouslySetInnerHTML` or
+ * interpolates these values into an attribute, a `style`, an `href` or a key.
+ * This is about the attacks that survive escaping, all of which end with the
+ * user misreading the screen:
+ *
+ *   - Bidi overrides (U+202E and friends) and zero-width characters let the
+ *     rendered string differ from the stored one. A device that displays as
+ *     "Oscar's laptop" while the token it mints is named something else is
+ *     exactly how someone is talked into approving the wrong thing.
+ *   - Control characters and newline runs let a name draw its own fake UI:
+ *     blank space, then a line that reads like the application's own copy
+ *     ("Verified device", "Session only") sitting inside our card.
+ *   - Unbounded length, per the constants above.
+ *
+ * Deliberately mirrors the sanitisation `DeviceAuthService.buildPatName()`
+ * applies to the token NAME. Same input, same threat — and if the two
+ * disagreed, the user would approve one string and later see a different one in
+ * the Access Tokens list, leaving them unable to tell which row to revoke. The
+ * revocability of a PAT is the thing that makes approving one reasonable, so
+ * anything that blurs which row to revoke takes that back.
+ *
+ * Returns `null` (not `''`) when nothing is left to show, so callers drop the
+ * whole labelled row instead of rendering a label over empty space.
+ *
+ * @param raw - one untrusted `clientInfo` value.
+ * @param maxLength - the display bound, in characters.
+ * @returns the text to render, or `null`.
+ *
+ * @stability stable
+ */
+export declare function sanitizeDeviceText(raw: unknown, maxLength: number): string | null;
+//# sourceMappingURL=device-credential.d.ts.map

package/dist/identity/headless/device-credential.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-credential.d.ts","sourceRoot":"","sources":["../../../src/identity/headless/device-credential.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,SAAS,GAAG,KAAK,CAAC;AAErD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,OAAO,GAAG,oBAAoB,CAY5E;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAC1C;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAC1C;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,OAAO,EACZ,SAAS,EAAE,MAAM,GAChB,MAAM,GAAG,IAAI,CA4Bf"}

package/dist/identity/headless/device-credential.js

@@ -0,0 +1,174 @@
+// Moved from the reference app's `components/device-activation/credential.ts` (issue #727).
+/**
+ * Interpreting the UNTRUSTED `clientInfo` blob that the activation page shows.
+ *
+ * Issue #141. The device authorization flow can now mint one of two very
+ * different credentials, and WHICH ONE is chosen by the device that started the
+ * flow, not by the person approving it:
+ *
+ *   - `session` — the historical behaviour: a short-lived access JWT plus a
+ *     refresh token, roughly a week of life, dies with the session.
+ *   - `pat` — a personal access token with a ~90-day life that authenticates
+ *     against every ordinary guarded endpoint and stays valid until it expires
+ *     or is revoked from Settings, Access Tokens.
+ *
+ * Before this module existed the two approvals rendered IDENTICALLY. That is
+ * the gap: `POST /auth/device/code` is public, so anyone can start a flow that
+ * asks for the 90-day credential, and the user was consenting to something
+ * materially different from what the screen described. Everything here exists
+ * to make the difference legible without trusting the blob that describes it.
+ *
+ * THIS IS THE ONLY PLACE `clientInfo` MAY BE INTERPRETED. Call sites take the
+ * outputs, never the raw fields.
+ */
+/**
+ * The PAT lifetime we tell the user to expect, in days.
+ *
+ * APPROXIMATE ON PURPOSE. The real number is server-side configuration
+ * (`DEVICE_PAT_EXPIRY_DAYS`, defaulting to 90 and clamped to 1..999 by
+ * `DeviceAuthService.resolvePatExpiryDays`) and `GET /auth/device/activate`
+ * does not return it. So the copy hedges — "about 90 days" — rather than
+ * stating a number we cannot actually know, because a confidently wrong
+ * lifetime is worse than an admitted approximation: it is the exact detail the
+ * user would rely on to decide.
+ *
+ * FOLLOW-UP: have the activate response carry the resolved expiry (ideally the
+ * concrete `expiresAt` the token would get), and then this constant and the
+ * hedged wording both go away. Until then, a deployment that overrides
+ * `DEVICE_PAT_EXPIRY_DAYS` shows a number that is off — still the right order
+ * of magnitude, and still unambiguously "not a browser session", which is the
+ * decision this screen actually drives.
+ *
+ * @stability stable
+ */
+export const DEVICE_PAT_APPROX_DAYS = 90;
+/**
+ * Which credential is this approval about?
+ *
+ * FAILS TOWARD `session` BY DESIGN, and the asymmetry matters. Saying "session"
+ * for something the server will mint as a PAT under-warns by one step; saying
+ * "PAT" for an ordinary session cries wolf on the common path and trains people
+ * to click through the warning — which destroys its value for the case it
+ * exists for. We therefore claim `pat` ONLY on an exact `'pat'` string, which
+ * is precisely the condition the API's own `readTokenType()` uses to decide
+ * what to mint. The two predicates agreeing character-for-character is what
+ * keeps the screen and the behaviour in sync; loosening this one (case-folding,
+ * `String(x).includes('pat')`) without loosening that one would put them back
+ * out of step, in the direction where the screen lies.
+ *
+ * The shapes this must survive, all of them real:
+ *   - `clientInfo` absent entirely (the API declares the field optional, and
+ *     `null` is what a hand-written or restored row carries).
+ *   - `tokenType` absent — every row written before #141.
+ *   - `tokenType` present but unexpected: a typo'd `'PAT'`, or a probe sending
+ *     `'admin'`. The WRITE path rejects those with a 400, but this is a READ of
+ *     a JSONB column that is never re-validated, so the value is whatever is
+ *     actually in the database. Such a row will mint a session (the API's own
+ *     fallback), and describing it as a session is therefore correct, not just
+ *     conservative.
+ *   - `clientInfo` not an object at all (a string, an array, a number): JSONB
+ *     round-trips any of those, and a property read on them must not throw.
+ *
+ * @param clientInfo - the untrusted `clientInfo` of the activation response.
+ * @returns `'pat'` only for an exact `tokenType: 'pat'`, else `'session'`.
+ *
+ * @stability stable
+ */
+export function readCredentialKind(clientInfo) {
+    if (clientInfo === null ||
+        typeof clientInfo !== 'object' ||
+        Array.isArray(clientInfo)) {
+        return 'session';
+    }
+    return clientInfo.tokenType === 'pat'
+        ? 'pat'
+        : 'session';
+}
+/**
+ * Display bounds for the free-text fields, in characters.
+ *
+ * A name is a label, not a payload. Without a bound, a 4KB `deviceName` (the
+ * request body has no per-field length limit on the way in) pushes the
+ * Approve/Deny buttons off a phone screen, or buries the credential warning
+ * under a wall of text the attacker wrote — a layout-level way of hiding the
+ * one thing this screen exists to show. The user agent gets a longer budget
+ * because real ones are genuinely long, and truncating a legitimate UA to 64
+ * characters would hurt recognition, which is the entire reason it is shown.
+ *
+ * @stability stable
+ */
+export const DEVICE_NAME_MAX_DISPLAY = 64;
+/**
+ * Display bound for the device's user agent, in characters (see {@link DEVICE_NAME_MAX_DISPLAY}).
+ *
+ * @stability stable
+ */
+export const USER_AGENT_MAX_DISPLAY = 180;
+/**
+ * Display bound for the device's IP address, in characters (see {@link DEVICE_NAME_MAX_DISPLAY}).
+ *
+ * @stability stable
+ */
+export const IP_ADDRESS_MAX_DISPLAY = 64;
+/**
+ * Turn one untrusted `clientInfo` string into something safe to render.
+ *
+ * React escapes text nodes, so this is NOT about script injection — that is
+ * already handled, and nothing on this page uses `dangerouslySetInnerHTML` or
+ * interpolates these values into an attribute, a `style`, an `href` or a key.
+ * This is about the attacks that survive escaping, all of which end with the
+ * user misreading the screen:
+ *
+ *   - Bidi overrides (U+202E and friends) and zero-width characters let the
+ *     rendered string differ from the stored one. A device that displays as
+ *     "Oscar's laptop" while the token it mints is named something else is
+ *     exactly how someone is talked into approving the wrong thing.
+ *   - Control characters and newline runs let a name draw its own fake UI:
+ *     blank space, then a line that reads like the application's own copy
+ *     ("Verified device", "Session only") sitting inside our card.
+ *   - Unbounded length, per the constants above.
+ *
+ * Deliberately mirrors the sanitisation `DeviceAuthService.buildPatName()`
+ * applies to the token NAME. Same input, same threat — and if the two
+ * disagreed, the user would approve one string and later see a different one in
+ * the Access Tokens list, leaving them unable to tell which row to revoke. The
+ * revocability of a PAT is the thing that makes approving one reasonable, so
+ * anything that blurs which row to revoke takes that back.
+ *
+ * Returns `null` (not `''`) when nothing is left to show, so callers drop the
+ * whole labelled row instead of rendering a label over empty space.
+ *
+ * @param raw - one untrusted `clientInfo` value.
+ * @param maxLength - the display bound, in characters.
+ * @returns the text to render, or `null`.
+ *
+ * @stability stable
+ */
+export function sanitizeDeviceText(raw, maxLength) {
+    // JSONB happily stores objects, numbers and null under these keys; `.trim()`
+    // on any of them throws and takes the whole activation page down with it.
+    if (typeof raw !== 'string')
+        return null;
+    const cleaned = raw
+        // NFKC first, so fullwidth and other compatibility disguises of the
+        // characters stripped below cannot survive by wearing a different codepoint.
+        .normalize('NFKC')
+        // C0 controls, DEL and C1 controls -> space. Replaced rather than deleted:
+        // deleting would splice the text on either side into a single word.
+        .replace(/[\u0000-\u001F\u007F-\u009F]/g, ' ')
+        // Zero-width and bidirectional formatting characters: invisible on screen,
+        // so their only purpose is to make stored and displayed text disagree.
+        .replace(/[\u200B-\u200F\u202A-\u202E\u2066-\u2069\uFEFF]/g, '')
+        // Collapse the runs the two substitutions above just created.
+        .replace(/\s+/g, ' ')
+        .trim();
+    if (cleaned.length === 0)
+        return null;
+    if (cleaned.length > maxLength) {
+        // One character reserved for the ellipsis, so the result lands ON the
+        // budget rather than one over it.
+        return `${cleaned.slice(0, maxLength - 1)}…`;
+    }
+    return cleaned;
+}
+//# sourceMappingURL=device-credential.js.map

package/dist/identity/headless/device-credential.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-credential.js","sourceRoot":"","sources":["../../../src/identity/headless/device-credential.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F;;;;;;;;;;;;;;;;;;;;;GAqBG;AASH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,EAAE,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,kBAAkB,CAAC,UAAmB;IACpD,IACE,UAAU,KAAK,IAAI;QACnB,OAAO,UAAU,KAAK,QAAQ;QAC9B,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,EACzB,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,OAAQ,UAAsC,CAAC,SAAS,KAAK,KAAK;QAChE,CAAC,CAAC,KAAK;QACP,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,EAAE,CAAC;AAC1C;;;;GAIG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,GAAG,CAAC;AAC1C;;;;GAIG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,EAAE,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,UAAU,kBAAkB,CAChC,GAAY,EACZ,SAAiB;IAEjB,6EAA6E;IAC7E,0EAA0E;IAC1E,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAEzC,MAAM,OAAO,GAAG,GAAG;QACjB,oEAAoE;QACpE,6EAA6E;SAC5E,SAAS,CAAC,MAAM,CAAC;QAClB,2EAA2E;QAC3E,oEAAoE;SACnE,OAAO,CAAC,+BAA+B,EAAE,GAAG,CAAC;QAC9C,2EAA2E;QAC3E,uEAAuE;SACtE,OAAO,CAAC,kDAAkD,EAAE,EAAE,CAAC;QAChE,8DAA8D;SAC7D,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC;SACpB,IAAI,EAAE,CAAC;IAEV,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAEtC,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,EAAE,CAAC;QAC/B,sEAAsE;QACtE,kCAAkC;QAClC,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,GAAG,CAAC,CAAC,GAAG,CAAC;IAC/C,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/identity/headless/guards.d.ts

@@ -0,0 +1,122 @@
+import type { ReactElement, ReactNode } from 'react';
+/**
+ * What {@link RequireAuth} takes.
+ *
+ * @stability stable
+ */
+export interface RequireAuthProps {
+    /** Rendered while the boot-time session probe runs (the app's full-screen spinner). Default nothing. */
+    loading?: ReactNode;
+    /**
+     * Where a signed-out visitor is sent, with `state.from` so the login page
+     * can send them back.
+     *
+     * @defaultValue `'/login'`
+     */
+    loginPath?: string;
+    /** The protected content; defaults to the nested routes (`<Outlet />`). */
+    children?: ReactNode;
+}
+/**
+ * Route guard: the nested routes (or `children`) for a signed-in user; a
+ * replace-redirect to the login page, carrying `state.from`, otherwise.
+ *
+ * @param props - see {@link RequireAuthProps}.
+ * @returns the guarded element.
+ *
+ * @example
+ * ```tsx
+ * <Route element={<RequireAuth loading={<LoadingSpinner fullScreen />} />}>
+ *   <Route path="/" element={<HomePage />} />
+ * </Route>
+ * ```
+ *
+ * @extensionPoint component
+ * @stability stable
+ */
+export declare function RequireAuth({ loading, loginPath, children }: RequireAuthProps): ReactElement;
+/**
+ * What {@link RequirePermission} takes. Every condition given must hold.
+ *
+ * @stability stable
+ */
+export interface RequirePermissionProps {
+    /** One permission the viewer must hold. */
+    permission?: string;
+    /** Several permissions: any of them, or all with `requireAll`. */
+    permissions?: string[];
+    /**
+     * With `permissions`: require all of them instead of any.
+     *
+     * @defaultValue `false`
+     */
+    requireAll?: boolean;
+    /** One role the viewer must have. */
+    role?: string;
+    /** Several roles: any of them. */
+    roles?: string[];
+    /** Rendered when the conditions hold. */
+    children: ReactNode;
+    /** Rendered otherwise (a route passes `<Navigate to="/" replace />`). Default nothing. */
+    fallback?: ReactNode;
+}
+/**
+ * Render `children` only when the viewer holds the permissions and roles
+ * named; `fallback` otherwise. Pass the exact permission string the API route
+ * enforces.
+ *
+ * @param props - see {@link RequirePermissionProps}.
+ * @returns the guarded element.
+ *
+ * @example
+ * ```tsx
+ * <RequirePermission permission="users:read" fallback={<Navigate to="/" replace />}>
+ *   <UsersPage />
+ * </RequirePermission>
+ * ```
+ *
+ * @extensionPoint component
+ * @stability stable
+ */
+export declare function RequirePermission({ permission, permissions, requireAll, role, roles, children, fallback, }: RequirePermissionProps): ReactElement;
+/**
+ * Whether ORGANIZATION management exists in this deployment: true iff
+ * `GET /api/auth/me` reports `tenancyMode: 'multi'`. In single-org mode the
+ * Organization and Organizations cards, their routes and the org switcher are
+ * absent ("org management hidden").
+ *
+ * Reads the auth context without `useAuth()`, so it answers "off" outside an
+ * `AuthProvider` or with nobody signed in (fail closed), and never fetches.
+ *
+ * @returns `true` in a multi-organization deployment.
+ *
+ * @extensionPoint hook
+ * @stability stable
+ */
+export declare function useOrgsFeature(): boolean;
+/**
+ * What {@link RequireMultiOrg} takes.
+ *
+ * @stability stable
+ */
+export interface RequireMultiOrgProps {
+    /** Rendered in a multi-organization deployment. */
+    children: ReactNode;
+    /** Rendered in single-org mode. Defaults to a replace-redirect to `/`, like every settings route. */
+    fallback?: ReactNode;
+}
+/**
+ * Route guard: render `children` only in a multi-organization deployment
+ * ({@link useOrgsFeature}). The FEATURE half of an org-administration route's
+ * gate; {@link RequirePermission} is the permission half. No loading state:
+ * the mode arrives with the signed-in user, which {@link RequireAuth} has
+ * already waited for.
+ *
+ * @param props - see {@link RequireMultiOrgProps}.
+ * @returns the guarded element.
+ *
+ * @extensionPoint component
+ * @stability stable
+ */
+export declare function RequireMultiOrg({ children, fallback }: RequireMultiOrgProps): ReactElement;
+//# sourceMappingURL=guards.d.ts.map

package/dist/identity/headless/guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../../src/identity/headless/guards.tsx"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAMrD;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,wGAAwG;IACxG,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CAAC,EAAE,OAAc,EAAE,SAAoB,EAAE,QAAQ,EAAE,EAAE,gBAAgB,GAAG,YAAY,CAa9G;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,2CAA2C;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,qCAAqC;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kCAAkC;IAClC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,yCAAyC;IACzC,QAAQ,EAAE,SAAS,CAAC;IACpB,0FAA0F;IAC1F,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,UAAU,EACV,WAAW,EACX,UAAkB,EAClB,IAAI,EACJ,KAAK,EACL,QAAQ,EACR,QAAe,GAChB,EAAE,sBAAsB,GAAG,YAAY,CA2BvC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,IAAI,OAAO,CAGxC;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,mDAAmD;IACnD,QAAQ,EAAE,SAAS,CAAC;IACpB,qGAAqG;IACrG,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,EAAE,QAAQ,EAAE,QAAsC,EAAE,EAAE,oBAAoB,GAAG,YAAY,CAGxH"}

package/dist/identity/headless/guards.js

@@ -0,0 +1,115 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+// Route and content guards (issue #727, PP-6.6), moved from the reference
+// app's `components/common/{ProtectedRoute,RequirePermission,RequireMultiOrg}.tsx`
+// and `hooks/useOrgsFeature.ts`. Headless: no markup of their own beyond what
+// the caller passes. They decide REACHABILITY and visibility only; the API
+// enforces every permission.
+import { useContext } from 'react';
+import { Navigate, Outlet, useLocation } from 'react-router-dom';
+import { AuthContext, useAuth } from './auth-context.js';
+import { usePermissions } from './use-permissions.js';
+/**
+ * Route guard: the nested routes (or `children`) for a signed-in user; a
+ * replace-redirect to the login page, carrying `state.from`, otherwise.
+ *
+ * @param props - see {@link RequireAuthProps}.
+ * @returns the guarded element.
+ *
+ * @example
+ * ```tsx
+ * <Route element={<RequireAuth loading={<LoadingSpinner fullScreen />} />}>
+ *   <Route path="/" element={<HomePage />} />
+ * </Route>
+ * ```
+ *
+ * @extensionPoint component
+ * @stability stable
+ */
+export function RequireAuth({ loading = null, loginPath = '/login', children }) {
+    const { user, isLoading } = useAuth();
+    const location = useLocation();
+    if (isLoading) {
+        return _jsx(_Fragment, { children: loading });
+    }
+    if (!user) {
+        return _jsx(Navigate, { to: loginPath, state: { from: location }, replace: true });
+    }
+    return children === undefined ? _jsx(Outlet, {}) : _jsx(_Fragment, { children: children });
+}
+/**
+ * Render `children` only when the viewer holds the permissions and roles
+ * named; `fallback` otherwise. Pass the exact permission string the API route
+ * enforces.
+ *
+ * @param props - see {@link RequirePermissionProps}.
+ * @returns the guarded element.
+ *
+ * @example
+ * ```tsx
+ * <RequirePermission permission="users:read" fallback={<Navigate to="/" replace />}>
+ *   <UsersPage />
+ * </RequirePermission>
+ * ```
+ *
+ * @extensionPoint component
+ * @stability stable
+ */
+export function RequirePermission({ permission, permissions, requireAll = false, role, roles, children, fallback = null, }) {
+    const { hasPermission, hasAnyPermission, hasAllPermissions, hasRole, hasAnyRole } = usePermissions();
+    // Check single permission
+    if (permission && !hasPermission(permission)) {
+        return _jsx(_Fragment, { children: fallback });
+    }
+    // Check multiple permissions
+    if (permissions && permissions.length > 0) {
+        const hasPerms = requireAll ? hasAllPermissions(...permissions) : hasAnyPermission(...permissions);
+        if (!hasPerms) {
+            return _jsx(_Fragment, { children: fallback });
+        }
+    }
+    // Check single role
+    if (role && !hasRole(role)) {
+        return _jsx(_Fragment, { children: fallback });
+    }
+    // Check multiple roles
+    if (roles && roles.length > 0 && !hasAnyRole(...roles)) {
+        return _jsx(_Fragment, { children: fallback });
+    }
+    return _jsx(_Fragment, { children: children });
+}
+/**
+ * Whether ORGANIZATION management exists in this deployment: true iff
+ * `GET /api/auth/me` reports `tenancyMode: 'multi'`. In single-org mode the
+ * Organization and Organizations cards, their routes and the org switcher are
+ * absent ("org management hidden").
+ *
+ * Reads the auth context without `useAuth()`, so it answers "off" outside an
+ * `AuthProvider` or with nobody signed in (fail closed), and never fetches.
+ *
+ * @returns `true` in a multi-organization deployment.
+ *
+ * @extensionPoint hook
+ * @stability stable
+ */
+export function useOrgsFeature() {
+    const auth = useContext(AuthContext);
+    return auth?.user?.tenancyMode === 'multi';
+}
+/**
+ * Route guard: render `children` only in a multi-organization deployment
+ * ({@link useOrgsFeature}). The FEATURE half of an org-administration route's
+ * gate; {@link RequirePermission} is the permission half. No loading state:
+ * the mode arrives with the signed-in user, which {@link RequireAuth} has
+ * already waited for.
+ *
+ * @param props - see {@link RequireMultiOrgProps}.
+ * @returns the guarded element.
+ *
+ * @extensionPoint component
+ * @stability stable
+ */
+export function RequireMultiOrg({ children, fallback = _jsx(Navigate, { to: "/", replace: true }) }) {
+    const orgs = useOrgsFeature();
+    return _jsx(_Fragment, { children: orgs ? children : fallback });
+}
+//# sourceMappingURL=guards.js.map

package/dist/identity/headless/guards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.js","sourceRoot":"","sources":["../../../src/identity/headless/guards.tsx"],"names":[],"mappings":"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"}

package/dist/identity/headless/hooks/use-allowlist.d.ts

@@ -0,0 +1,39 @@
+import type { AllowedEmailEntry, AllowlistParams, IdentityApi } from '../api.js';
+/**
+ * What {@link useAllowlist} returns.
+ *
+ * @stability stable
+ */
+export interface UseAllowlistReturn {
+    /** This page's entries. */
+    entries: AllowedEmailEntry[];
+    /** Entries across all pages. */
+    total: number;
+    /** The page the API answered with (one-based). */
+    page: number;
+    /** The page size the API answered with. */
+    pageSize: number;
+    /** The number of pages. */
+    totalPages: number;
+    /** A list request is in flight. */
+    isLoading: boolean;
+    /** The last failure's message, or `null`. */
+    error: string | null;
+    /** Read a page of entries. Never rejects; a failure lands in `error`. */
+    fetchAllowlist: (params?: AllowlistParams) => Promise<void>;
+    /** Allow an address, then re-read the current page. Rethrows on failure. */
+    addEmail: (email: string, notes?: string) => Promise<void>;
+    /** Remove an entry, then re-read the current page. Rethrows on failure. */
+    removeEmail: (id: string) => Promise<void>;
+}
+/**
+ * The email allowlist, over `/api/allowlist`.
+ *
+ * @param api - the identity client; default {@link useIdentityApi}'s.
+ * @returns see {@link UseAllowlistReturn}.
+ *
+ * @extensionPoint hook
+ * @stability stable
+ */
+export declare function useAllowlist(api?: IdentityApi): UseAllowlistReturn;
+//# sourceMappingURL=use-allowlist.d.ts.map

package/dist/identity/headless/hooks/use-allowlist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-allowlist.d.ts","sourceRoot":"","sources":["../../../../src/identity/headless/hooks/use-allowlist.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAqB,WAAW,EAAE,MAAM,WAAW,CAAC;AAEpG;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,2BAA2B;IAC3B,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAC7B,gCAAgC;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,2BAA2B;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,mCAAmC;IACnC,SAAS,EAAE,OAAO,CAAC;IACnB,6CAA6C;IAC7C,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,yEAAyE;IACzE,cAAc,EAAE,CAAC,MAAM,CAAC,EAAE,eAAe,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D,4EAA4E;IAC5E,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3D,2EAA2E;IAC3E,WAAW,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5C;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,GAAG,CAAC,EAAE,WAAW,GAAG,kBAAkB,CAoElE"}