@mehdad67/apitogo 0.1.27 → 0.1.28

package/dist/cli/cli.js

@@ -3545,6 +3545,13 @@ var init_ZudokuConfig = __esm({
         redirectToAfterSignUp: z8.string().optional(),
         redirectToAfterSignIn: z8.string().optional(),
         redirectToAfterSignOut: z8.string().optional()
+      }),
+      z8.object({
+        type: z8.literal("dev-portal"),
+        apiBaseUrl: z8.string().optional(),
+        redirectToAfterSignUp: z8.string().optional(),
+        redirectToAfterSignIn: z8.string().optional(),
+        redirectToAfterSignOut: z8.string().optional()
       })
     ]);
     MetadataSchema = z8.object({
@@ -4086,6 +4093,9 @@ var getIssuer = async (config2) => {
     case "firebase": {
       return `https://securetoken.google.com/${config2.authentication.projectId}`;
     }
+    case "dev-portal": {
+      return void 0;
+    }
     case void 0: {
       return void 0;
     }
@@ -4111,7 +4121,7 @@ import {
 // package.json
 var package_default = {
   name: "@mehdad67/apitogo",
-  version: "0.1.27",
+  version: "0.1.28",
   type: "module",
   sideEffects: [
     "**/*.css",
@@ -4157,6 +4167,7 @@ var package_default = {
     "./auth/supabase": "./src/lib/authentication/providers/supabase.tsx",
     "./auth/azureb2c": "./src/lib/authentication/providers/azureb2c.tsx",
     "./auth/firebase": "./src/lib/authentication/providers/firebase.tsx",
+    "./auth/dev-portal": "./src/lib/authentication/providers/dev-portal.tsx",
     "./plugins": "./src/lib/core/plugins.ts",
     "./plugins/api-keys": "./src/lib/plugins/api-keys/index.tsx",
     "./plugins/markdown": "./src/lib/plugins/markdown/index.tsx",
@@ -4406,6 +4417,10 @@ var package_default = {
         types: "./dist/declarations/lib/authentication/providers/firebase.d.ts",
         default: "./src/lib/authentication/providers/firebase.tsx"
       },
+      "./auth/dev-portal": {
+        types: "./dist/declarations/lib/authentication/providers/dev-portal.d.ts",
+        default: "./src/lib/authentication/providers/dev-portal.tsx"
+      },
       "./plugins": {
         types: "./dist/declarations/lib/core/plugins.d.ts",
         default: "./src/lib/core/plugins.ts"

package/dist/declarations/config/config.d.ts

@@ -24,3 +24,6 @@ export type FirebaseAuthenticationConfig = Extract<AuthenticationConfig, {
 export type AzureB2CAuthenticationConfig = Extract<AuthenticationConfig, {
     type: "azureb2c";
 }>;
+export type DevPortalAuthenticationConfig = Extract<AuthenticationConfig, {
+    type: "dev-portal";
+}>;

package/dist/declarations/config/validators/ZudokuConfig.d.ts

@@ -366,6 +366,12 @@ declare const AuthenticationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     redirectToAfterSignUp: z.ZodOptional<z.ZodString>;
     redirectToAfterSignIn: z.ZodOptional<z.ZodString>;
     redirectToAfterSignOut: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"dev-portal">;
+    apiBaseUrl: z.ZodOptional<z.ZodString>;
+    redirectToAfterSignUp: z.ZodOptional<z.ZodString>;
+    redirectToAfterSignIn: z.ZodOptional<z.ZodString>;
+    redirectToAfterSignOut: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>], "type">;
 declare const FontConfigSchema: z.ZodUnion<readonly [z.ZodEnum<{
     Inter: "Inter";
@@ -6728,6 +6734,12 @@ export declare const ZudokuConfig: z.ZodObject<{
         redirectToAfterSignUp: z.ZodOptional<z.ZodString>;
         redirectToAfterSignIn: z.ZodOptional<z.ZodString>;
         redirectToAfterSignOut: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"dev-portal">;
+        apiBaseUrl: z.ZodOptional<z.ZodString>;
+        redirectToAfterSignUp: z.ZodOptional<z.ZodString>;
+        redirectToAfterSignIn: z.ZodOptional<z.ZodString>;
+        redirectToAfterSignOut: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>], "type">>;
     search: z.ZodOptional<z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
         type: z.ZodLiteral<"inkeep">;

package/dist/declarations/lib/authentication/components/ProductionUnlockPage.d.ts

@@ -0,0 +1 @@
+export declare const ProductionUnlockPage: () => import("react/jsx-runtime").JSX.Element;

package/dist/declarations/lib/authentication/hook.d.ts

@@ -11,6 +11,8 @@ export declare const useVerifiedEmail: () => {
     requestEmailVerification: (options?: AuthActionOptions) => Promise<void>;
 };
 export declare const useAuth: () => {
+    isBackendAvailable: boolean;
+    authMode: import("./state.js").AuthMode;
     login: (options?: AuthActionOptions) => Promise<void>;
     logout: () => Promise<void>;
     signup: (options?: AuthActionOptions) => Promise<void>;

package/dist/declarations/lib/authentication/providers/dev-portal-constants.d.ts

@@ -0,0 +1,16 @@
+export declare const DEV_PORTAL_PLACEHOLDER_API_URL = "https://dp-example.azurecontainerapps.io";
+export type DevPortalAuthMode = "live" | "preview";
+export type EndUserMeResponse = {
+    userId: string;
+    displayName: string | null;
+    subscriptions: Array<{
+        planSku: string;
+        status: string;
+        entitlementState: string | null;
+        currentPeriodEnd: string | null;
+    }>;
+};
+export type DevPortalAuthStatusResponse = {
+    available: boolean;
+    oidcConfigured: boolean;
+};

package/dist/declarations/lib/authentication/providers/dev-portal-utils.d.ts

@@ -0,0 +1,9 @@
+import type { DevPortalAuthenticationConfig } from "../../../config/config.js";
+import { type EndUserMeResponse } from "./dev-portal-constants.js";
+export declare function resolveDevPortalApiBaseUrl(config: Pick<DevPortalAuthenticationConfig, "apiBaseUrl">): string | undefined;
+export declare function isPlaceholderDevPortalApiUrl(apiBaseUrl: string | undefined): boolean;
+export declare function toAbsoluteReturnUrl(pathOrUrl: string): string;
+export declare function buildDevPortalLoginUrl(apiBaseUrl: string, returnUrl: string): string;
+export declare function buildDevPortalLogoutUrl(apiBaseUrl: string, returnUrl: string): string;
+export declare function probeDevPortalBackend(apiBaseUrl: string, fetchImpl?: typeof fetch): Promise<boolean>;
+export declare function mapEndUserMeToProfile(me: EndUserMeResponse): import("../state.js").UserProfile;

package/dist/declarations/lib/authentication/providers/dev-portal.d.ts

@@ -0,0 +1,36 @@
+import type { DevPortalAuthenticationConfig } from "../../../config/config.js";
+import type { ZudokuContext } from "../../core/ZudokuContext.js";
+import type { AuthActionContext, AuthActionOptions, AuthenticationPlugin, AuthenticationProviderInitializer } from "../authentication.js";
+import { CoreAuthenticationPlugin } from "../AuthenticationPlugin.js";
+import type { DevPortalAuthMode } from "./dev-portal-constants.js";
+export type DevPortalProviderData = {
+    type: "dev-portal";
+    apiBaseUrl: string;
+    authMode: DevPortalAuthMode;
+};
+declare module "../state.js" {
+    interface ProviderDataRegistry {
+        "dev-portal": DevPortalProviderData;
+    }
+}
+export declare class DevPortalAuthenticationProvider extends CoreAuthenticationPlugin implements AuthenticationPlugin {
+    private readonly apiBaseUrl;
+    private readonly redirectToAfterSignIn;
+    private readonly redirectToAfterSignUp;
+    private readonly redirectToAfterSignOut;
+    private authMode;
+    private backendAvailable;
+    constructor({ apiBaseUrl, redirectToAfterSignIn, redirectToAfterSignUp, redirectToAfterSignOut, }: DevPortalAuthenticationConfig);
+    initialize(_context: ZudokuContext): Promise<void>;
+    onPageLoad: () => Promise<void>;
+    private syncBackendAvailability;
+    private setPreviewState;
+    private ensureLiveBackend;
+    refreshUserProfile(): Promise<boolean>;
+    signIn(_: AuthActionContext, { redirectTo }?: AuthActionOptions): Promise<void>;
+    signUp(_: AuthActionContext, { redirectTo }?: AuthActionOptions): Promise<void>;
+    signOut(_: AuthActionContext): Promise<void>;
+    signRequest(request: Request): Promise<Request>;
+}
+declare const devPortalAuth: AuthenticationProviderInitializer<DevPortalAuthenticationConfig>;
+export default devPortalAuth;

package/dist/declarations/lib/authentication/state.d.ts

@@ -1,11 +1,14 @@
 export interface ProviderDataRegistry {
 }
 export type ProviderData = [keyof ProviderDataRegistry] extends [never] ? unknown : ProviderDataRegistry[keyof ProviderDataRegistry];
+export type AuthMode = "live" | "preview";
 export interface AuthState {
     isAuthenticated: boolean;
     isPending: boolean;
     profile: UserProfile | null;
     providerData: ProviderData | null;
+    isBackendAvailable: boolean;
+    authMode: AuthMode;
     setAuthenticationPending: () => void;
     setLoggedOut: () => void;
     setLoggedIn: (args: {

package/dist/flat-config.d.ts

@@ -305,6 +305,12 @@ export interface FlatZudokuConfig {
     redirectToAfterSignUp?: string
     redirectToAfterSignIn?: string
     redirectToAfterSignOut?: string
+  } | {
+    type: "dev-portal"
+    apiBaseUrl?: string
+    redirectToAfterSignUp?: string
+    redirectToAfterSignIn?: string
+    redirectToAfterSignOut?: string
   })
   search?: ({
     type: "inkeep"

package/docs/configuration/authentication.md

@@ -15,12 +15,42 @@ the authentication provider you use.
 
 ## Authentication Providers
 
-APIToGo supports Clerk, Auth0, Supabase, Azure B2C, and any OpenID provider that supports the OpenID
-Connect protocol.
+APIToGo supports Clerk, Auth0, Supabase, Azure B2C, any OpenID provider that supports the OpenID
+Connect protocol, and **dev-portal** (backend-delegated OIDC for APItoGo provisioned developer
+portals).
 
 Not seeing your authentication provider?
 [Let us know](https://github.com/lukoweb/apitogo-doc-tool/issues)
 
+### Dev portal (APItoGo)
+
+For sites provisioned through APItoGo MCP, use backend-delegated authentication. The static site
+redirects sign-in to the provisioned dev-portal API; OIDC client credentials stay on the backend
+only.
+
+```typescript
+{
+  // ...
+  authentication: {
+    type: "dev-portal",
+  },
+  // ...
+}
+```
+
+Set the backend API URL via environment variable (MCP writes this at scaffold/publish):
+
+```bash
+VITE_APITOGO_DEV_PORTAL_API_URL=https://your-dev-portal-api.example.com
+```
+
+**Local preview:** When the backend URL is a placeholder or unreachable, the account area shows a
+message that sign-in unlocks after publish. Docs and API reference remain public.
+
+**Production:** Register one OIDC app with redirect URI `https://{backend}/signin-oidc` (see MCP
+`manualSteps.oidcRedirectUri`). The frontend uses cookie sessions via `credentials: "include"` on
+`/api/v1/auth/me`.
+
 ### Auth0
 
 For Auth0, you will need the `clientId` associated with the domain you are using.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mehdad67/apitogo",
-  "version": "0.1.27",
+  "version": "0.1.28",
   "type": "module",
   "sideEffects": [
     "**/*.css",
@@ -46,6 +46,7 @@
     "./auth/supabase": "./src/lib/authentication/providers/supabase.tsx",
     "./auth/azureb2c": "./src/lib/authentication/providers/azureb2c.tsx",
     "./auth/firebase": "./src/lib/authentication/providers/firebase.tsx",
+    "./auth/dev-portal": "./src/lib/authentication/providers/dev-portal.tsx",
     "./plugins": "./src/lib/core/plugins.ts",
     "./plugins/api-keys": "./src/lib/plugins/api-keys/index.tsx",
     "./plugins/markdown": "./src/lib/plugins/markdown/index.tsx",
@@ -295,6 +296,10 @@
         "types": "./dist/declarations/lib/authentication/providers/firebase.d.ts",
         "default": "./src/lib/authentication/providers/firebase.tsx"
       },
+      "./auth/dev-portal": {
+        "types": "./dist/declarations/lib/authentication/providers/dev-portal.d.ts",
+        "default": "./src/lib/authentication/providers/dev-portal.tsx"
+      },
       "./plugins": {
         "types": "./dist/declarations/lib/core/plugins.d.ts",
         "default": "./src/lib/core/plugins.ts"

package/src/config/config.ts

@@ -68,3 +68,7 @@ export type AzureB2CAuthenticationConfig = Extract<
   AuthenticationConfig,
   { type: "azureb2c" }
 >;
+export type DevPortalAuthenticationConfig = Extract<
+  AuthenticationConfig,
+  { type: "dev-portal" }
+>;

package/src/config/validators/ZudokuConfig.ts

@@ -491,6 +491,13 @@ const AuthenticationSchema = z.discriminatedUnion("type", [
     redirectToAfterSignIn: z.string().optional(),
     redirectToAfterSignOut: z.string().optional(),
   }),
+  z.object({
+    type: z.literal("dev-portal"),
+    apiBaseUrl: z.string().optional(),
+    redirectToAfterSignUp: z.string().optional(),
+    redirectToAfterSignIn: z.string().optional(),
+    redirectToAfterSignOut: z.string().optional(),
+  }),
 ]);
 
 const MetadataSchema = z

package/src/lib/auth/issuer.ts

@@ -21,6 +21,9 @@ export const getIssuer = async (config: ZudokuConfig) => {
     case "firebase": {
       return `https://securetoken.google.com/${config.authentication.projectId}`;
     }
+    case "dev-portal": {
+      return undefined;
+    }
     case undefined: {
       return undefined;
     }

package/src/lib/authentication/components/ProductionUnlockPage.tsx

@@ -0,0 +1,27 @@
+import { Button } from "@mehdad67/apitogo/ui/Button.js";
+import { Link } from "react-router";
+import { Layout } from "../../components/Layout.js";
+
+export const ProductionUnlockPage = () => (
+  <Layout>
+    <div className="mx-auto flex min-h-[50vh] max-w-lg flex-col items-center justify-center gap-4 px-4 text-center">
+      <h1 className="text-2xl font-semibold tracking-tight">
+        Account sign-in unlocks after publish
+      </h1>
+      <p className="text-muted-foreground">
+        Your developer portal account area uses live authentication backed by
+        APItoGo. Preview this site locally for docs and API reference; sign-in,
+        plans, and subscriptions activate once the portal is published to
+        production.
+      </p>
+      <div className="flex flex-wrap items-center justify-center gap-3">
+        <Button asChild variant="default">
+          <Link to="/introduction">Browse documentation</Link>
+        </Button>
+        <Button asChild variant="outline">
+          <Link to="/">Back to home</Link>
+        </Button>
+      </div>
+    </div>
+  </Layout>
+);

package/src/lib/authentication/hook.ts

@@ -77,6 +77,8 @@ export const useAuth = () => {
   return {
     isAuthEnabled,
     ...authState,
+    isBackendAvailable: authState.isBackendAvailable,
+    authMode: authState.authMode,
 
     login: async (options?: AuthActionOptions) => {
       if (!isAuthEnabled) {

package/src/lib/authentication/providers/dev-portal-constants.ts

@@ -0,0 +1,21 @@
+/** Placeholder backend URL written by MCP before publish. */
+export const DEV_PORTAL_PLACEHOLDER_API_URL =
+  "https://dp-example.azurecontainerapps.io";
+
+export type DevPortalAuthMode = "live" | "preview";
+
+export type EndUserMeResponse = {
+  userId: string;
+  displayName: string | null;
+  subscriptions: Array<{
+    planSku: string;
+    status: string;
+    entitlementState: string | null;
+    currentPeriodEnd: string | null;
+  }>;
+};
+
+export type DevPortalAuthStatusResponse = {
+  available: boolean;
+  oidcConfigured: boolean;
+};

package/src/lib/authentication/providers/dev-portal-utils.ts

@@ -0,0 +1,107 @@
+import type { DevPortalAuthenticationConfig } from "../../../config/config.js";
+import {
+  DEV_PORTAL_PLACEHOLDER_API_URL,
+  type DevPortalAuthStatusResponse,
+  type EndUserMeResponse,
+} from "./dev-portal-constants.js";
+
+declare const VITE_APITOGO_DEV_PORTAL_API_URL: string | undefined;
+
+export function resolveDevPortalApiBaseUrl(
+  config: Pick<DevPortalAuthenticationConfig, "apiBaseUrl">,
+): string | undefined {
+  const fromConfig = config.apiBaseUrl?.trim();
+  if (fromConfig) {
+    return fromConfig.replace(/\/+$/, "");
+  }
+
+  const fromEnv =
+    typeof VITE_APITOGO_DEV_PORTAL_API_URL === "string"
+      ? VITE_APITOGO_DEV_PORTAL_API_URL.trim()
+      : "";
+
+  return fromEnv ? fromEnv.replace(/\/+$/, "") : undefined;
+}
+
+export function isPlaceholderDevPortalApiUrl(
+  apiBaseUrl: string | undefined,
+): boolean {
+  if (!apiBaseUrl) {
+    return true;
+  }
+
+  return (
+    apiBaseUrl === DEV_PORTAL_PLACEHOLDER_API_URL ||
+    apiBaseUrl.includes("dp-example.azurecontainerapps.io")
+  );
+}
+
+export function toAbsoluteReturnUrl(pathOrUrl: string): string {
+  if (pathOrUrl.startsWith("http://") || pathOrUrl.startsWith("https://")) {
+    return pathOrUrl;
+  }
+
+  if (typeof window === "undefined") {
+    return pathOrUrl;
+  }
+
+  return new URL(pathOrUrl, window.location.origin).href;
+}
+
+export function buildDevPortalLoginUrl(
+  apiBaseUrl: string,
+  returnUrl: string,
+): string {
+  const url = new URL("/api/v1/auth/login", apiBaseUrl);
+  url.searchParams.set("returnUrl", toAbsoluteReturnUrl(returnUrl));
+  return url.toString();
+}
+
+export function buildDevPortalLogoutUrl(
+  apiBaseUrl: string,
+  returnUrl: string,
+): string {
+  const url = new URL("/api/v1/auth/logout", apiBaseUrl);
+  url.searchParams.set("returnUrl", toAbsoluteReturnUrl(returnUrl));
+  return url.toString();
+}
+
+export async function probeDevPortalBackend(
+  apiBaseUrl: string,
+  fetchImpl: typeof fetch = fetch,
+): Promise<boolean> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 8_000);
+
+  try {
+    const response = await fetchImpl(`${apiBaseUrl}/api/v1/auth/status`, {
+      method: "GET",
+      headers: { Accept: "application/json" },
+      credentials: "include",
+      signal: controller.signal,
+    });
+
+    if (!response.ok) {
+      return false;
+    }
+
+    const body = (await response.json()) as DevPortalAuthStatusResponse;
+    return body.available === true;
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+export function mapEndUserMeToProfile(
+  me: EndUserMeResponse,
+): import("../state.js").UserProfile {
+  return {
+    sub: me.userId,
+    email: undefined,
+    emailVerified: false,
+    name: me.displayName ?? undefined,
+    pictureUrl: undefined,
+  };
+}

package/src/lib/authentication/providers/dev-portal.tsx

@@ -0,0 +1,218 @@
+import type { DevPortalAuthenticationConfig } from "../../../config/config.js";
+import type { ZudokuContext } from "../../core/ZudokuContext.js";
+import type {
+  AuthActionContext,
+  AuthActionOptions,
+  AuthenticationPlugin,
+  AuthenticationProviderInitializer,
+} from "../authentication.js";
+import { CoreAuthenticationPlugin } from "../AuthenticationPlugin.js";
+import { type UserProfile, useAuthState } from "../state.js";
+import type {
+  DevPortalAuthMode,
+  EndUserMeResponse,
+} from "./dev-portal-constants.js";
+import {
+  buildDevPortalLoginUrl,
+  buildDevPortalLogoutUrl,
+  isPlaceholderDevPortalApiUrl,
+  mapEndUserMeToProfile,
+  probeDevPortalBackend,
+  resolveDevPortalApiBaseUrl,
+} from "./dev-portal-utils.js";
+
+export type DevPortalProviderData = {
+  type: "dev-portal";
+  apiBaseUrl: string;
+  authMode: DevPortalAuthMode;
+};
+
+declare module "../state.js" {
+  interface ProviderDataRegistry {
+    "dev-portal": DevPortalProviderData;
+  }
+}
+
+export class DevPortalAuthenticationProvider
+  extends CoreAuthenticationPlugin
+  implements AuthenticationPlugin
+{
+  private readonly apiBaseUrl: string | undefined;
+  private readonly redirectToAfterSignIn: string | undefined;
+  private readonly redirectToAfterSignUp: string | undefined;
+  private readonly redirectToAfterSignOut: string;
+  private authMode: DevPortalAuthMode = "preview";
+  private backendAvailable = false;
+
+  constructor({
+    apiBaseUrl,
+    redirectToAfterSignIn,
+    redirectToAfterSignUp,
+    redirectToAfterSignOut = "/",
+  }: DevPortalAuthenticationConfig) {
+    super();
+    this.apiBaseUrl = resolveDevPortalApiBaseUrl({ apiBaseUrl });
+    this.redirectToAfterSignIn = redirectToAfterSignIn;
+    this.redirectToAfterSignUp = redirectToAfterSignUp;
+    this.redirectToAfterSignOut = redirectToAfterSignOut;
+  }
+
+  async initialize(_context: ZudokuContext): Promise<void> {
+    await this.syncBackendAvailability();
+    if (!this.backendAvailable) {
+      this.setPreviewState();
+      return;
+    }
+
+    await this.refreshUserProfile();
+  }
+
+  onPageLoad = async () => {
+    if (!this.backendAvailable) {
+      this.setPreviewState();
+      return;
+    }
+
+    await this.refreshUserProfile();
+  };
+
+  private async syncBackendAvailability(): Promise<void> {
+    if (!this.apiBaseUrl || isPlaceholderDevPortalApiUrl(this.apiBaseUrl)) {
+      this.backendAvailable = false;
+      this.authMode = "preview";
+      return;
+    }
+
+    this.backendAvailable = await probeDevPortalBackend(this.apiBaseUrl);
+    this.authMode = this.backendAvailable ? "live" : "preview";
+  }
+
+  private setPreviewState(): void {
+    useAuthState.setState({
+      isAuthenticated: false,
+      isPending: false,
+      profile: null,
+      providerData: this.apiBaseUrl
+        ? {
+            type: "dev-portal",
+            apiBaseUrl: this.apiBaseUrl,
+            authMode: "preview",
+          }
+        : null,
+      isBackendAvailable: false,
+      authMode: "preview",
+    });
+  }
+
+  private ensureLiveBackend(): string {
+    if (!this.apiBaseUrl || !this.backendAvailable) {
+      throw new Error("Dev portal authentication is not available in preview.");
+    }
+
+    return this.apiBaseUrl;
+  }
+
+  async refreshUserProfile(): Promise<boolean> {
+    if (!this.apiBaseUrl) {
+      this.setPreviewState();
+      return false;
+    }
+
+    if (isPlaceholderDevPortalApiUrl(this.apiBaseUrl)) {
+      this.setPreviewState();
+      return false;
+    }
+
+    await this.syncBackendAvailability();
+    if (!this.backendAvailable) {
+      this.setPreviewState();
+      return false;
+    }
+
+    try {
+      const response = await fetch(`${this.apiBaseUrl}/api/v1/auth/me`, {
+        method: "GET",
+        headers: { Accept: "application/json" },
+        credentials: "include",
+      });
+
+      if (response.status === 401) {
+        useAuthState.setState({
+          isAuthenticated: false,
+          isPending: false,
+          profile: null,
+          providerData: {
+            type: "dev-portal",
+            apiBaseUrl: this.apiBaseUrl,
+            authMode: "live",
+          },
+          isBackendAvailable: true,
+          authMode: "live",
+        });
+        return false;
+      }
+
+      if (!response.ok) {
+        this.setPreviewState();
+        return false;
+      }
+
+      const me = (await response.json()) as EndUserMeResponse;
+      const profile: UserProfile = mapEndUserMeToProfile(me);
+
+      useAuthState.getState().setLoggedIn({
+        profile,
+        providerData: {
+          type: "dev-portal",
+          apiBaseUrl: this.apiBaseUrl,
+          authMode: "live",
+        },
+      });
+      useAuthState.setState({
+        isBackendAvailable: true,
+        authMode: "live",
+      });
+      return true;
+    } catch {
+      this.setPreviewState();
+      return false;
+    }
+  }
+
+  async signIn(
+    _: AuthActionContext,
+    { redirectTo }: AuthActionOptions = {},
+  ): Promise<void> {
+    const apiBaseUrl = this.ensureLiveBackend();
+    const target =
+      redirectTo ?? this.redirectToAfterSignIn ?? window.location.href;
+    window.location.assign(buildDevPortalLoginUrl(apiBaseUrl, target));
+  }
+
+  async signUp(
+    _: AuthActionContext,
+    { redirectTo }: AuthActionOptions = {},
+  ): Promise<void> {
+    const apiBaseUrl = this.ensureLiveBackend();
+    const target =
+      redirectTo ?? this.redirectToAfterSignUp ?? window.location.href;
+    window.location.assign(buildDevPortalLoginUrl(apiBaseUrl, target));
+  }
+
+  async signOut(_: AuthActionContext): Promise<void> {
+    const apiBaseUrl = this.ensureLiveBackend();
+    window.location.assign(
+      buildDevPortalLogoutUrl(apiBaseUrl, this.redirectToAfterSignOut),
+    );
+  }
+
+  async signRequest(request: Request): Promise<Request> {
+    return request;
+  }
+}
+
+const devPortalAuth: AuthenticationProviderInitializer<
+  DevPortalAuthenticationConfig
+> = (options) => new DevPortalAuthenticationProvider(options);
+
+export default devPortalAuth;

package/src/lib/authentication/state.ts

@@ -21,11 +21,17 @@ export type ProviderData = [keyof ProviderDataRegistry] extends [never]
   ? unknown
   : ProviderDataRegistry[keyof ProviderDataRegistry];
 
+export type AuthMode = "live" | "preview";
+
 export interface AuthState {
   isAuthenticated: boolean;
   isPending: boolean;
   profile: UserProfile | null;
   providerData: ProviderData | null;
+  /** False when dev-portal backend is unavailable (local preview). Defaults true. */
+  isBackendAvailable: boolean;
+  /** Live when backend auth is reachable; preview otherwise. */
+  authMode: AuthMode;
   setAuthenticationPending: () => void;
   setLoggedOut: () => void;
   setLoggedIn: (args: {
@@ -41,12 +47,16 @@ export const authState = create<AuthState>()(
       isPending: true,
       profile: null,
       providerData: null,
+      isBackendAvailable: true,
+      authMode: "live",
       setAuthenticationPending: () =>
         set(() => ({
           isAuthenticated: false,
           isPending: false,
           profile: null,
           providerData: null,
+          isBackendAvailable: true,
+          authMode: "live",
         })),
       setLoggedOut: () =>
         set(() => ({
@@ -54,6 +64,8 @@ export const authState = create<AuthState>()(
           isPending: false,
           profile: null,
           providerData: null,
+          isBackendAvailable: true,
+          authMode: "live",
         })),
       setLoggedIn: ({ profile, providerData }) =>
         set(() => ({

package/src/lib/components/Header.tsx

@@ -73,9 +73,9 @@ const ProfileMenu = () => {
   const context = useZudoku();
   const profileItems = context.getProfileMenuItems();
   const auth = useAuth();
-  const { isAuthEnabled, isAuthenticated, profile } = auth;
+  const { isAuthEnabled, isAuthenticated, profile, isBackendAvailable } = auth;
 
-  if (!isAuthEnabled) return null;
+  if (!isAuthEnabled || !isBackendAvailable) return null;
 
   return (
     <ClientOnly fallback={<Skeleton className="rounded-sm h-5 w-24 mr-4" />}>

package/src/lib/components/MobileTopNavigation.tsx

@@ -130,7 +130,8 @@ export const MobileTopNavigation = () => {
     getProfileMenuItems,
   } = context;
   const headerNavigation = header?.navigation ?? [];
-  const { isAuthenticated, profile, isAuthEnabled } = authState;
+  const { isAuthenticated, profile, isAuthEnabled, isBackendAvailable } =
+    authState;
   const [drawerOpen, setDrawerOpen] = useState(false);
 
   const accountItems = getProfileMenuItems();
@@ -232,7 +233,7 @@ export const MobileTopNavigation = () => {
           </div>
           <div className="border-t shadow-[0_-4px_6px_-1px_rgba(0,0,0,0.05)] px-4 pt-3 flex flex-col gap-2">
             <div className="flex items-center justify-between">
-              {isAuthEnabled && (
+              {isAuthEnabled && isBackendAvailable && (
                 <ClientOnly
                   fallback={<Skeleton className="rounded-sm h-8 w-16" />}
                 >

package/src/lib/core/RouteGuard.tsx

@@ -17,6 +17,7 @@ import {
   useNavigate,
 } from "react-router";
 import { REASON_CODES } from "../../config/validators/reason-codes.js";
+import { ProductionUnlockPage } from "../authentication/components/ProductionUnlockPage.js";
 import { useAuth } from "../authentication/hook.js";
 import { RenderContext } from "../components/context/RenderContext.js";
 import { useZudoku } from "../components/context/ZudokuContext.js";
@@ -174,7 +175,16 @@ export const RouteGuard = () => {
     return null;
   }
 
-  const showDialog = needsToSignIn || isBlocked;
+  if (
+    isProtectedRoute &&
+    needsToSignIn &&
+    auth.isAuthEnabled &&
+    !auth.isBackendAvailable
+  ) {
+    return <ProductionUnlockPage />;
+  }
+
+  const showDialog = auth.isBackendAvailable && (needsToSignIn || isBlocked);
   const redirectTo = isBlocked
     ? blocker.location.pathname + blocker.location.search
     : location.pathname + location.search;