handoff-app 2.0.0-2 → 2.0.0-4

package/src/app/lib/auth/config.ts

@@ -0,0 +1,175 @@
+import type { NextApiRequest, NextApiResponse } from 'next';
+import type { NextAuthOptions, Session } from 'next-auth';
+import { getServerSession } from 'next-auth';
+import CredentialsProvider from 'next-auth/providers/credentials';
+import {
+  authenticateRegistryCredentials,
+  clearAuthRateLimit,
+  consumeAuthRateLimit,
+  getRegistryInstallationState,
+  getRegistryUserById,
+  normalizeEmail,
+  type RegistryUser,
+} from '@handoff/registry/auth';
+import { getRegistryConnection } from '../registry-connection';
+import { getServerRuntimeConfig } from '../docs-api/runtime-config';
+
+export const registryAuthSecret = (): string => process.env.AUTH_SECRET?.trim() || process.env.NEXTAUTH_SECRET?.trim() || '';
+
+/** The canonical public registry URL (base path included), read from the documented AUTH_URL. */
+export const canonicalRegistryUrl = (): URL | null => {
+  const value = process.env.AUTH_URL?.trim() || process.env.NEXTAUTH_URL?.trim();
+  if (!value) return null;
+  try {
+    const url = new URL(value);
+    return url.protocol === 'http:' || url.protocol === 'https:' ? url : null;
+  } catch {
+    return null;
+  }
+};
+
+// NextAuth v4 only reads NEXTAUTH_URL to resolve callback origins and set the Secure cookie flag,
+// but deployments configure the documented AUTH_URL (the way registryAuthSecret bridges AUTH_SECRET).
+// Mirror it onto NEXTAUTH_URL, keeping the base path and adding the /api/auth mount NextAuth expects,
+// so self-hosted registries get https callbacks and Secure cookies instead of falling back to localhost.
+if (!process.env.NEXTAUTH_URL?.trim()) {
+  const canonical = canonicalRegistryUrl();
+  if (canonical) {
+    canonical.pathname = `${canonical.pathname.replace(/\/+$/, '')}/api/auth`;
+    canonical.search = '';
+    process.env.NEXTAUTH_URL = canonical.toString();
+  }
+}
+
+const appBasePath = process.env.HANDOFF_APP_BASE_PATH ?? '';
+
+const requestIdentifier = (request: { headers?: Record<string, string | string[] | undefined> }, email: string): string => {
+  const forwarded = request.headers?.['x-forwarded-for'];
+  const forwardedValue = Array.isArray(forwarded) ? forwarded[0] : forwarded;
+  const address = forwardedValue?.split(',')[0]?.trim() || request.headers?.['x-real-ip'] || 'unknown';
+  return `${String(address)}:${normalizeEmail(email)}`;
+};
+
+const clearUserToken = (token: Record<string, unknown>): Record<string, unknown> => {
+  delete token.sub;
+  delete token.userId;
+  delete token.role;
+  delete token.authVersion;
+  token.authInvalid = true;
+  return token;
+};
+
+export const registryAuthOptions: NextAuthOptions = {
+  secret: registryAuthSecret() || 'registry-auth-is-not-configured',
+  session: {
+    strategy: 'jwt',
+    maxAge: 30 * 24 * 60 * 60,
+    updateAge: 5 * 60,
+  },
+  pages: {
+    signIn: `${appBasePath}/login`,
+    error: `${appBasePath}/login`,
+  },
+  providers: [
+    CredentialsProvider({
+      id: 'handoff-credentials',
+      name: 'Handoff Registry',
+      credentials: {
+        email: { label: 'Email', type: 'email' },
+        password: { label: 'Password', type: 'password' },
+      },
+      async authorize(credentials, request) {
+        if (getServerRuntimeConfig().mode !== 'registry' || !registryAuthSecret()) return null;
+        const email = credentials?.email ?? '';
+        const password = credentials?.password ?? '';
+        if (!email || !password) return null;
+
+        try {
+          const { db } = await getRegistryConnection();
+          const installation = await getRegistryInstallationState(db);
+          if (installation.status !== 'installed') return null;
+
+          const identifier = requestIdentifier(request, email);
+          const throttle = await consumeAuthRateLimit(db, {
+            bucket: 'login',
+            identifier,
+            limit: 10,
+            windowMs: 15 * 60 * 1000,
+          });
+          if (!throttle.allowed) return null;
+
+          const user = await authenticateRegistryCredentials(db, email, password);
+          if (!user) return null;
+          await clearAuthRateLimit(db, 'login', identifier);
+          return {
+            id: user.id,
+            email: user.email,
+            name: user.name,
+            image: user.image,
+            role: user.role,
+            status: user.status,
+            authVersion: user.authVersion,
+          };
+        } catch {
+          return null;
+        }
+      },
+    }),
+  ],
+  callbacks: {
+    async jwt({ token, user }) {
+      const mutable = token as Record<string, unknown>;
+      const userId = (user?.id as string | undefined) || (mutable.userId as string | undefined) || token.sub;
+      const issuedAuthVersion = user ? (user as { authVersion?: number }).authVersion : (mutable.authVersion as number | undefined);
+      if (!userId || getServerRuntimeConfig().mode !== 'registry') return clearUserToken(mutable);
+
+      try {
+        const { db } = await getRegistryConnection();
+        const current = await getRegistryUserById(db, userId);
+        if (!current || current.status !== 'active') return clearUserToken(mutable);
+        if (!user && issuedAuthVersion !== current.authVersion) return clearUserToken(mutable);
+        mutable.userId = current.id;
+        mutable.email = current.email;
+        mutable.name = current.name;
+        mutable.picture = current.image;
+        mutable.role = current.role;
+        mutable.authVersion = current.authVersion;
+        mutable.authInvalid = false;
+      } catch {
+        // Don't invalidate a good session over a transient failure (database down, pool exhausted).
+        // Stripping identity here would strand the user in an unrecoverable "authenticated but no
+        // user" state that only clearing cookies fixes, so keep the last-known token and re-validate
+        // next request. Genuine invalidation (missing/inactive user, authVersion) is handled above.
+        return token;
+      }
+      return token;
+    },
+    async session({ session, token }) {
+      const values = token as Record<string, unknown>;
+      if (values.authInvalid || !values.userId) {
+        session.user = undefined as unknown as Session['user'];
+        return session;
+      }
+      session.user = {
+        id: values.userId as string,
+        email: (values.email as string) || '',
+        name: (values.name as string | null) ?? null,
+        image: (values.picture as string | null) ?? null,
+        role: values.role as RegistryUser['role'],
+        authVersion: values.authVersion as number,
+      };
+      return session;
+    },
+  },
+};
+
+/** Resolve the current session and re-read its user so every protected request sees live account state. */
+export const getRegistrySessionUser = async (req: NextApiRequest, res: NextApiResponse): Promise<RegistryUser | null> => {
+  if (getServerRuntimeConfig().mode !== 'registry' || !registryAuthSecret()) return null;
+  const session = await getServerSession(req, res, registryAuthOptions);
+  const userId = (session?.user as { id?: string } | undefined)?.id;
+  if (!userId) return null;
+  const { db } = await getRegistryConnection();
+  const user = await getRegistryUserById(db, userId);
+  return user?.status === 'active' ? user : null;
+};

package/src/app/lib/auth/email.ts

@@ -0,0 +1,34 @@
+export const registryEmailIsConfigured = (): boolean => Boolean(process.env.RESEND_API_KEY?.trim() && process.env.AUTH_FROM_EMAIL?.trim());
+
+const escapeHtml = (value: string): string =>
+  value.replace(/[&<>"']/g, (character) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[character]!);
+
+export const sendRegistryAuthEmail = async (input: {
+  to: string;
+  subject: string;
+  heading: string;
+  message: string;
+  actionLabel: string;
+  actionUrl: string;
+}): Promise<boolean> => {
+  const apiKey = process.env.RESEND_API_KEY?.trim();
+  const from = process.env.AUTH_FROM_EMAIL?.trim();
+  if (!apiKey || !from) return false;
+
+  const response = await fetch('https://api.resend.com/emails', {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({
+      from,
+      to: [input.to],
+      subject: input.subject,
+      html:
+        `<h1>${escapeHtml(input.heading)}</h1><p>${escapeHtml(input.message)}</p>` +
+        `<p><a href="${escapeHtml(input.actionUrl)}">${escapeHtml(input.actionLabel)}</a></p>`,
+    }),
+  });
+  return response.ok;
+};

package/src/app/lib/docs-api/runtime-config.ts

@@ -4,7 +4,6 @@ import type { RuntimeMode } from '@handoff/types/config';
 import {
   DEFAULT_DATABASE_URL_ENV,
   DEFAULT_REGISTRY_DRIVER,
-  DEFAULT_REGISTRY_API_TOKEN_ENV,
   type RegistryDatabaseDriver,
 } from '@handoff/registry/db/driver';
 import { DEFAULT_ASSET_STORAGE_ADAPTER, type AssetStorageSettings } from '@handoff/registry/asset-storage/resolve';
@@ -29,11 +28,6 @@ export interface ServerRegistryRuntimeConfig {
   driver: RegistryDatabaseDriver;
   /** Name of the env var holding the database connection string (value resolved at request time). */
   databaseUrlEnv: string;
-  /**
-   * Name of the env var holding the registry management API bearer token. The token *value* is
-   * resolved from the environment at request time by the management API guard — never persisted.
-   */
-  apiTokenEnv: string;
 }
 
 /** Resolved server-side runtime configuration for the docs read API. */
@@ -55,7 +49,6 @@ const defaults = (): ServerRuntimeConfig => ({
   registry: {
     driver: DEFAULT_REGISTRY_DRIVER,
     databaseUrlEnv: DEFAULT_DATABASE_URL_ENV,
-    apiTokenEnv: DEFAULT_REGISTRY_API_TOKEN_ENV,
   },
   assetStorage: { adapter: DEFAULT_ASSET_STORAGE_ADAPTER },
 });
@@ -108,13 +101,11 @@ const fromEnv = (): ServerRuntimeConfig | null => {
     return null;
   }
   const databaseUrlEnv = process.env.HANDOFF_REGISTRY_DATABASE_URL_ENV?.trim() || DEFAULT_DATABASE_URL_ENV;
-  const apiTokenEnv = process.env.HANDOFF_REGISTRY_API_TOKEN_ENV?.trim() || DEFAULT_REGISTRY_API_TOKEN_ENV;
   return {
     mode: mode === 'registry' ? 'registry' : 'workspace',
     registry: {
       driver: process.env.HANDOFF_REGISTRY_DRIVER?.trim() === 'neon' ? 'neon' : 'pg',
       databaseUrlEnv,
-      apiTokenEnv,
     },
     assetStorage: assetStorageFromEnv(),
   };
@@ -145,10 +136,6 @@ export const getServerRuntimeConfig = (): ServerRuntimeConfig => {
         typeof parsed?.registry?.databaseUrlEnv === 'string' && parsed.registry.databaseUrlEnv.trim()
           ? parsed.registry.databaseUrlEnv.trim()
           : DEFAULT_DATABASE_URL_ENV;
-      const apiTokenEnv =
-        typeof parsed?.registry?.apiTokenEnv === 'string' && parsed.registry.apiTokenEnv.trim()
-          ? parsed.registry.apiTokenEnv.trim()
-          : DEFAULT_REGISTRY_API_TOKEN_ENV;
       const assetStorage: AssetStorageSettings =
         parsed?.assetStorage && typeof parsed.assetStorage === 'object'
           ? parsed.assetStorage
@@ -158,7 +145,6 @@ export const getServerRuntimeConfig = (): ServerRuntimeConfig => {
         registry: {
           driver: parsed?.registry?.driver === 'neon' ? 'neon' : 'pg',
           databaseUrlEnv,
-          apiTokenEnv,
         },
         assetStorage,
       };

package/src/app/lib/registry-api/auth.ts

@@ -1,68 +1,51 @@
 import type { NextApiRequest } from 'next';
-import { getServerRuntimeConfig } from '../docs-api/runtime-config';
+import type { RegistryDatabase } from '@handoff/registry/db/client';
+import {
+  authenticateRegistryAccessToken,
+  registryPrincipalHasScope,
+  type RegistryAccessScope,
+  type RegistryPrincipal,
+} from '@handoff/registry/auth';
 
-/**
- * Bearer-token guard for registry management mutations.
- *
- * This is **proof-of-concept protection**, not production auth: a single static token, resolved
- * from the configured env-var *name* at request time (never persisted in config). GET reads are
- * unauthenticated; only mutations (POST/PUT/DELETE) call this guard.
- *
- * - Token env var unset/empty  → `token_not_configured` (503).
- * - `Authorization: Bearer <token>` missing or not an exact match → `unauthorized` (401).
- */
-/**
- * Result of {@link authorizeMutation}. Flat (not a discriminated union) because the app compiles
- * with `strictNullChecks` off — `ok` decides, with `code`/`message` set on failure.
- */
-export interface MutationAuthResult {
+export interface RegistryAuthResult {
   ok: boolean;
-  code?: 'token_not_configured' | 'unauthorized';
+  code?: 'unauthorized' | 'forbidden';
   message?: string;
+  principal?: RegistryPrincipal;
 }
 
-/** Length-safe constant-time-ish string comparison to avoid trivial timing leaks. */
-const tokensMatch = (provided: string, expected: string): boolean => {
-  if (provided.length !== expected.length) {
-    return false;
-  }
-  let mismatch = 0;
-  for (let i = 0; i < expected.length; i += 1) {
-    mismatch |= provided.charCodeAt(i) ^ expected.charCodeAt(i);
-  }
-  return mismatch === 0;
-};
-
-/** Extract a bearer token from the `Authorization` header, or `''` when absent/malformed. */
 const bearerToken = (req: NextApiRequest): string => {
   const header = req.headers.authorization;
-  if (typeof header !== 'string') {
-    return '';
-  }
+  if (typeof header !== 'string') return '';
   const match = /^Bearer\s+(.+)$/i.exec(header.trim());
   return match ? match[1].trim() : '';
 };
 
-/** Authorize a mutation request against the configured static bearer token. */
-export const authorizeMutation = (req: NextApiRequest): MutationAuthResult => {
-  const { registry } = getServerRuntimeConfig();
-  const expected = process.env[registry.apiTokenEnv]?.trim();
-  if (!expected) {
+/**
+ * Authorize a registry request with a live, revocable user token carrying the required scope: reads
+ * need `registry:read`, mutations need `registry:write`. Every `/api/registry/*` request runs
+ * through this — there are no public endpoints behind the guard stack.
+ */
+export const authorizeRegistryRequest = async (
+  req: NextApiRequest,
+  db: RegistryDatabase,
+  scope: RegistryAccessScope
+): Promise<RegistryAuthResult> => {
+  const principal = await authenticateRegistryAccessToken(db, bearerToken(req));
+  if (!principal) {
     return {
       ok: false,
-      code: 'token_not_configured',
+      code: 'unauthorized',
       message:
-        `Registry management mutations are disabled because the "${registry.apiTokenEnv}" environment ` +
-        `variable is not set. Set it to a bearer token to enable mutations.`,
+        'A valid user-issued access token is required. Run `handoff-app login`, or create a CI token in registry Account settings.',
     };
   }
-  const provided = bearerToken(req);
-  if (!provided || !tokensMatch(provided, expected)) {
+  if (!registryPrincipalHasScope(principal, scope)) {
     return {
       ok: false,
-      code: 'unauthorized',
-      message: 'A valid "Authorization: Bearer <token>" header is required for registry management mutations.',
+      code: 'forbidden',
+      message: `This access token does not include the ${scope} scope.`,
     };
   }
-  return { ok: true };
+  return { ok: true, principal };
 };

package/src/app/lib/registry-api/errors.ts

@@ -12,20 +12,20 @@ import { buildMeta, type RegistryMeta } from './meta';
 export type RegistryErrorCode =
   | 'bad_request'
   | 'unauthorized'
+  | 'forbidden'
   | 'not_found'
   | 'method_not_allowed'
   | 'runtime_mode_conflict'
-  | 'token_not_configured'
   | 'database_unavailable'
   | 'unexpected_error';
 
 const STATUS_BY_CODE: Record<RegistryErrorCode, number> = {
   bad_request: 400,
   unauthorized: 401,
+  forbidden: 403,
   not_found: 404,
   method_not_allowed: 405,
   runtime_mode_conflict: 409,
-  token_not_configured: 503,
   database_unavailable: 503,
   unexpected_error: 500,
 };

package/src/app/lib/registry-api/handler.ts

@@ -1,8 +1,10 @@
 import type { NextApiRequest, NextApiResponse } from 'next';
 import type { RegistryDatabase } from '@handoff/registry/db/client';
+import type { RegistryPrincipal } from '@handoff/registry/auth';
 import { getServerRuntimeConfig } from '../docs-api/runtime-config';
+import { REGISTRY_READ_SCOPE, REGISTRY_WRITE_SCOPE } from '@handoff/registry/auth';
 import { getRegistryConnection, RegistryConnectionError } from '../registry-connection';
-import { authorizeMutation } from './auth';
+import { authorizeRegistryRequest } from './auth';
 import { sendRegistryError } from './errors';
 import { buildMeta, type RegistryMeta } from './meta';
 import { redactSecrets } from '../api/redact';
@@ -12,12 +14,13 @@ import { redactSecrets } from '../api/redact';
  *
  * Enforces, in order: the registry-runtime guard (management APIs exist only when
  * `runtime.mode: registry`, else `409 runtime_mode_conflict`); the per-route method allowlist
- * (`405 method_not_allowed`); the bearer-token guard for mutations (`503 token_not_configured` /
- * `401 unauthorized`); and database resolution (`503 database_unavailable`). The route body then
- * runs against a live connection, with any thrown failure mapped to `unexpected_error`.
+ * (`405 method_not_allowed`); database resolution (`503 database_unavailable`); and scoped,
+ * revocable bearer-token authorization on every request — reads require `registry:read`, mutations
+ * require `registry:write` (`401 unauthorized` / `403 forbidden`). The route body then runs against
+ * a live connection, with any thrown failure mapped to `unexpected_error`.
  */
 
-/** Methods that mutate state and therefore require the bearer token. */
+/** Methods that mutate state and therefore require the `registry:write` scope; all others read. */
 const MUTATION_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
 
 /** Context handed to a registry route body once all guards pass. */
@@ -26,6 +29,8 @@ export interface RegistryRouteContext {
   res: NextApiResponse;
   db: RegistryDatabase;
   method: string;
+  /** Authenticated token owner; every request that reaches a route body is authorized. */
+  principal: RegistryPrincipal;
 }
 
 /**
@@ -66,14 +71,6 @@ export const handleRegistryRoute = async (
     return;
   }
 
-  if (MUTATION_METHODS.has(method)) {
-    const auth = authorizeMutation(req);
-    if (!auth.ok) {
-      sendRegistryError(res, auth.code, auth.message);
-      return;
-    }
-  }
-
   let db: RegistryDatabase;
   try {
     ({ db } = await getRegistryConnection());
@@ -87,8 +84,16 @@ export const handleRegistryRoute = async (
     return;
   }
 
+  const requiredScope = MUTATION_METHODS.has(method) ? REGISTRY_WRITE_SCOPE : REGISTRY_READ_SCOPE;
+  const auth = await authorizeRegistryRequest(req, db, requiredScope);
+  if (!auth.ok) {
+    sendRegistryError(res, auth.code!, auth.message!);
+    return;
+  }
+  const principal = auth.principal!;
+
   try {
-    await body({ req, res, db, method });
+    await body({ req, res, db, method, principal });
   } catch (error) {
     console.error('Registry API request failed.', error);
     sendRegistryError(res, 'unexpected_error', 'Unexpected registry API error.');

package/src/app/lib/registry-api/token-transfer.ts

@@ -161,7 +161,7 @@ const ingestTokenSet = async (db: RegistryDatabase, pkg: TokenSetTransferPackage
   });
 };
 
-/** `GET /api/registry/transfer/tokens` — list set summaries (unauthenticated read behind the guards). */
+/** `GET /api/registry/transfer/tokens` — list set summaries (requires a `registry:read` token). */
 export const handleTokenSummaryRoute = (req: NextApiRequest, res: NextApiResponse): Promise<void> =>
   handleRegistryRoute(req, res, ['GET'], async ({ db }) => {
     const rows = await db

package/src/app/lib/registry-api/transfer.ts

@@ -435,8 +435,8 @@ const upsertBuildMetadata = async (db: RegistryDatabase, kind: TransferEntityKin
 /**
  * Handles `GET /api/registry/transfer/{component|pattern|page}`. Lists summaries for one kind of
  * entity: each id plus its build hashes and status. A connected workspace uses these to skip
- * unchanged entities on a bulk publish and to enumerate published ids for a bulk checkout. The read
- * is unauthenticated; only the registry-runtime and method guards apply.
+ * unchanged entities on a bulk publish and to enumerate published ids for a bulk checkout. Requires
+ * a `registry:read` token (enforced by the guard stack).
  */
 export const handleEntitySummaryRoute = (req: NextApiRequest, res: NextApiResponse, kind: TransferEntityKind): Promise<void> =>
   handleRegistryRoute(req, res, ['GET'], async ({ db }) => {
@@ -465,8 +465,8 @@ export const handleEntitySummaryRoute = (req: NextApiRequest, res: NextApiRespon
  * Handle `GET /api/registry/transfer/{component|pattern}/:id` — checkout read. Returns the
  * normalized record plus its registry-safe source files so a connected workspace can reconstruct
  * the entity locally. Declaration files are workspace-only: registry stores never hold them, but
- * they are filtered defensively so checkout never receives one. The read is unauthenticated,
- * running behind the registry-runtime + method guards only.
+ * they are filtered defensively so checkout never receives one. Requires a `registry:read` token
+ * (enforced by the guard stack).
  */
 export const handleCheckoutRoute = (req: NextApiRequest, res: NextApiResponse, kind: TransferEntityKind): Promise<void> =>
   handleRegistryRoute(req, res, ['GET'], async ({ db }) => {

package/src/app/next.config.mjs

@@ -67,11 +67,21 @@ const nextConfig = {
   reactStrictMode: true,
   pageExtensions: ['js', 'jsx', 'ts', 'tsx'],
   trailingSlash: true,
+  // Extra safety for the invite/reset flow. The token now lives in the URL fragment, so it never
+  // reaches the server or leaks via Referer, but this header hardens the page anyway. Only the
+  // dynamic registry server can send response headers; a static export can't.
+  ...(handoffBuildTarget === 'registry'
+    ? {
+        async headers() {
+          return [{ source: '/reset-password', headers: [{ key: 'Referrer-Policy', value: 'no-referrer' }] }];
+        },
+      }
+    : {}),
   experimental: {
     externalDir: true,
   },
   eslint: {
-    dirs: ['pages', 'utils'],
+    ignoreDuringBuilds: true,
   },
   transpilePackages: ['handoff-app', 'react-syntax-highlighter'],
   typescript: {
@@ -97,7 +107,6 @@ const nextConfig = {
     HANDOFF_RUNTIME_MODE: '%HANDOFF_RUNTIME_MODE%',
     HANDOFF_REGISTRY_DRIVER: '%HANDOFF_REGISTRY_DRIVER%',
     HANDOFF_REGISTRY_DATABASE_URL_ENV: '%HANDOFF_REGISTRY_DATABASE_URL_ENV%',
-    HANDOFF_REGISTRY_API_TOKEN_ENV: '%HANDOFF_REGISTRY_API_TOKEN_ENV%',
     // Asset storage selection (provider + non-secret options + env-var names). Secret values (Blob
     // token, custom credentials) are read from their named env var at request time, never baked.
     HANDOFF_ASSET_STORAGE_ADAPTER: '%HANDOFF_ASSET_STORAGE_ADAPTER%',
@@ -164,7 +173,7 @@ const nextConfig = {
       return content;
     },
   },
-  turbopack: { 
+  turbopack: {
     resolveAlias: {
       '@handoff': path.resolve('%HANDOFF_MODULE_PATH%/src'),
       '@': path.resolve('.'),

package/src/app/pages/_app.tsx

@@ -1,5 +1,7 @@
 import type { AppProps } from 'next/app';
 
+import { RegistrySessionProvider } from '../components/Auth/RegistrySessionProvider';
+import { RegistryInstallGate } from '../components/Auth/RegistryInstallGate';
 import { NavProvider } from '../components/context/NavProvider';
 import '../css/index.css';
 import '../css/theme.css';
@@ -8,10 +10,14 @@ function MyApp({ Component, pageProps }: AppProps) {
   return (
     // NavProvider lives above the page tree so the registry nav (shell + entities) is fetched once
     // and cached across soft navigations, resetting only on hard refresh.
-    <NavProvider initialNav={pageProps.navData} currentSectionId={pageProps.currentSectionId}>
-      {/* @ts-ignore */}
-      <Component {...pageProps} />
-    </NavProvider>
+    <RegistrySessionProvider>
+      <RegistryInstallGate>
+        <NavProvider initialNav={pageProps.navData} currentSectionId={pageProps.currentSectionId}>
+          {/* @ts-ignore */}
+          <Component {...pageProps} />
+        </NavProvider>
+      </RegistryInstallGate>
+    </RegistrySessionProvider>
   );
 }