@jskit-ai/auth-provider-supabase-core 0.1.45 → 0.1.47

package/package.descriptor.mjs

@@ -1,7 +1,7 @@
 export default Object.freeze({
   "packageVersion": 1,
   "packageId": "@jskit-ai/auth-provider-supabase-core",
-  "version": "0.1.45",
+  "version": "0.1.47",
   "kind": "runtime",
   "options": {
     "auth-supabase-url": {
@@ -83,8 +83,8 @@ export default Object.freeze({
   "mutations": {
     "dependencies": {
       "runtime": {
-        "@jskit-ai/auth-core": "0.1.45",
-        "@jskit-ai/kernel": "0.1.46",
+        "@jskit-ai/auth-core": "0.1.47",
+        "@jskit-ai/kernel": "0.1.48",
         "dotenv": "^16.4.5",
         "@supabase/supabase-js": "^2.57.4",
         "jose": "^6.1.0"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/auth-provider-supabase-core",
-  "version": "0.1.45",
+  "version": "0.1.47",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -12,8 +12,8 @@
     "./client": "./src/client/index.js"
   },
   "dependencies": {
-    "@jskit-ai/auth-core": "0.1.45",
-    "@jskit-ai/kernel": "0.1.46",
+    "@jskit-ai/auth-core": "0.1.47",
+    "@jskit-ai/kernel": "0.1.48",
     "jose": "^6.1.0",
     "@supabase/supabase-js": "^2.57.4"
   }

package/src/server/lib/actions/auth.contributor.js

@@ -9,6 +9,7 @@ import {
   authLoginOtpVerifyCommand,
   authLoginOAuthStartCommand,
   authLoginOAuthCompleteCommand,
+  authDevLoginAsCommand,
   authPasswordResetRequestCommand,
   authPasswordRecoveryCompleteCommand,
   authPasswordResetCommand
@@ -23,7 +24,24 @@ function requireRequestContext(context, actionId) {
   throw new Error(`${actionId} requires request context.`);
 }
 
-const authActions = Object.freeze([
+const devLoginAsAction = Object.freeze({
+  id: "auth.dev.loginAs",
+  version: 1,
+  kind: "command",
+  channels: ["api", "internal"],
+  surfacesFrom: "enabled",
+  inputValidator: authDevLoginAsCommand.operation.bodyValidator,
+  idempotency: "none",
+  audit: {
+    actionName: "auth.dev.loginAs"
+  },
+  observability: {},
+  async execute(input, context, deps) {
+    return deps.authService.devLoginAs(requireRequestContext(context, "auth.dev.loginAs"), input);
+  }
+});
+
+const authActionsBeforeDevLogin = Object.freeze([
   {
     id: "auth.register",
     version: 1,
@@ -135,7 +153,10 @@ const authActions = Object.freeze([
     async execute(input, _context, deps) {
       return deps.authService.oauthComplete(input);
     }
-  },
+  }
+]);
+
+const authActionsAfterDevLogin = Object.freeze([
   {
     id: "auth.password.reset.request",
     version: 1,
@@ -241,4 +262,21 @@ const authActions = Object.freeze([
   }
 ]);
 
-export { authActions };
+const baseAuthActions = Object.freeze([
+  ...authActionsBeforeDevLogin,
+  ...authActionsAfterDevLogin
+]);
+
+function buildAuthActions({ includeDevLoginAs = false } = {}) {
+  if (!includeDevLoginAs) {
+    return baseAuthActions;
+  }
+
+  return Object.freeze([
+    ...authActionsBeforeDevLogin,
+    devLoginAsAction,
+    ...authActionsAfterDevLogin
+  ]);
+}
+
+export { baseAuthActions, buildAuthActions, devLoginAsAction };

package/src/server/lib/devAuthBootstrap.js

@@ -0,0 +1,398 @@
+import { AppError } from "@jskit-ai/kernel/server/runtime/errors";
+import { normalizeRecordId } from "@jskit-ai/kernel/shared/support/normalize";
+import { normalizeEmail } from "@jskit-ai/auth-core/server/utils";
+import { loadJose, isExpiredJwtError } from "./authJwt.js";
+
+const DEV_AUTH_TOKEN_PREFIX = "jskit-dev.";
+const DEV_AUTH_ISSUER = "jskit:dev-auth";
+const DEFAULT_DEV_AUTH_ACCESS_TTL_SECONDS = 60 * 60 * 12;
+const DEFAULT_DEV_AUTH_REFRESH_TTL_SECONDS = 60 * 60 * 24 * 30;
+const encoder = new TextEncoder();
+
+function parseBoolean(value, fallback = false) {
+  const raw = String(value || "").trim().toLowerCase();
+  if (!raw) {
+    return fallback;
+  }
+  if (["1", "true", "yes", "on"].includes(raw)) {
+    return true;
+  }
+  if (["0", "false", "no", "off"].includes(raw)) {
+    return false;
+  }
+  return fallback;
+}
+
+function normalizePositiveInteger(value, fallback) {
+  const parsed = Number.parseInt(String(value || "").trim(), 10);
+  if (Number.isInteger(parsed) && parsed > 0) {
+    return parsed;
+  }
+  return fallback;
+}
+
+function normalizeRequestHostname(request) {
+  const hostHeader = String(request?.headers?.host || "").trim();
+  if (!hostHeader) {
+    return "";
+  }
+
+  const firstHost = hostHeader.split(",")[0]?.trim();
+  if (!firstHost) {
+    return "";
+  }
+
+  try {
+    return new URL(`http://${firstHost}`).hostname.trim().toLowerCase();
+  } catch {
+    return firstHost
+      .replace(/^\[/, "")
+      .replace(/\]$/, "")
+      .split(":")[0]
+      .trim()
+      .toLowerCase();
+  }
+}
+
+function resolveDirectRemoteAddress(request) {
+  return String(request?.socket?.remoteAddress || request?.raw?.socket?.remoteAddress || "").trim();
+}
+
+function normalizeLoopbackIp(value) {
+  return String(value || "")
+    .trim()
+    .toLowerCase()
+    .replace(/^\[|\]$/g, "")
+    .replace(/^::ffff:/, "");
+}
+
+function isLoopbackIp(value) {
+  const normalized = normalizeLoopbackIp(value);
+  return normalized === "::1" || normalized === "127.0.0.1" || normalized.startsWith("127.");
+}
+
+function isLoopbackHostname(value) {
+  const normalized = String(value || "")
+    .trim()
+    .toLowerCase()
+    .replace(/^\[|\]$/g, "");
+  return (
+    normalized === "localhost" ||
+    normalized.endsWith(".localhost") ||
+    normalized === "::1" ||
+    normalized === "127.0.0.1"
+  );
+}
+
+function isLocalDevAuthRequest(request) {
+  return (
+    isLoopbackIp(resolveDirectRemoteAddress(request)) &&
+    isLoopbackHostname(normalizeRequestHostname(request))
+  );
+}
+
+function isDevAuthToken(token) {
+  return String(token || "").trim().startsWith(DEV_AUTH_TOKEN_PREFIX);
+}
+
+function stripDevAuthTokenPrefix(token) {
+  return String(token || "").trim().slice(DEV_AUTH_TOKEN_PREFIX.length);
+}
+
+function resolveDevAuthConfig({
+  enabled = false,
+  secret = "",
+  nodeEnv = "development",
+  jwtAudience = "authenticated",
+  accessTtlSeconds = DEFAULT_DEV_AUTH_ACCESS_TTL_SECONDS,
+  refreshTtlSeconds = DEFAULT_DEV_AUTH_REFRESH_TTL_SECONDS
+} = {}) {
+  return Object.freeze({
+    enabled: parseBoolean(enabled, false),
+    secret: String(secret || "").trim(),
+    isProduction: String(nodeEnv || "development").trim().toLowerCase() === "production",
+    jwtAudience: String(jwtAudience || "authenticated").trim() || "authenticated",
+    accessTtlSeconds: normalizePositiveInteger(accessTtlSeconds, DEFAULT_DEV_AUTH_ACCESS_TTL_SECONDS),
+    refreshTtlSeconds: normalizePositiveInteger(refreshTtlSeconds, DEFAULT_DEV_AUTH_REFRESH_TTL_SECONDS)
+  });
+}
+
+function assertDevAuthBootstrapConfig(config, { userProfilesRepository = null } = {}) {
+  if (!config?.enabled) {
+    return;
+  }
+
+  if (config.isProduction) {
+    throw new Error("AUTH_DEV_BYPASS_ENABLED must not be enabled in production.");
+  }
+  if (!config.secret) {
+    throw new Error("AUTH_DEV_BYPASS_SECRET is required when AUTH_DEV_BYPASS_ENABLED=true.");
+  }
+  if (
+    !userProfilesRepository ||
+    typeof userProfilesRepository.findById !== "function" ||
+    typeof userProfilesRepository.findByEmail !== "function"
+  ) {
+    throw new Error(
+      "Dev auth bootstrap requires internal.repository.user-profiles with findById() and findByEmail() when AUTH_DEV_BYPASS_ENABLED=true."
+    );
+  }
+}
+
+function ensureDevAuthBootstrapAvailable(config, request) {
+  if (!config?.enabled || config?.isProduction) {
+    throw new AppError(404, "Not found.");
+  }
+  if (!config.secret) {
+    throw new AppError(500, "AUTH_DEV_BYPASS_SECRET is required when AUTH_DEV_BYPASS_ENABLED=true.");
+  }
+  if (!isLocalDevAuthRequest(request)) {
+    throw new AppError(403, "Dev auth bootstrap is only available from localhost.");
+  }
+}
+
+function buildProfileFromTokenClaims(payload) {
+  const id = normalizeRecordId(payload?.sub, { fallback: null });
+  const email = normalizeEmail(payload?.email || "");
+  if (!id || !email) {
+    return null;
+  }
+
+  const displayName = String(payload?.displayName || "").trim();
+  const username = String(payload?.username || "")
+    .trim()
+    .toLowerCase();
+  const authProvider = String(payload?.authProvider || "dev")
+    .trim()
+    .toLowerCase();
+  const authProviderUserSid = String(payload?.authProviderUserSid || payload?.sub || "").trim();
+
+  return {
+    id,
+    email,
+    username,
+    displayName: displayName || email || `User ${id}`,
+    authProvider,
+    authProviderUserSid,
+    avatarStorageKey: null,
+    avatarVersion: null
+  };
+}
+
+async function resolveProfileFromTokenClaims(payload, { userProfilesRepository = null } = {}) {
+  const userId = normalizeRecordId(payload?.sub, { fallback: null });
+  if (userId && userProfilesRepository && typeof userProfilesRepository.findById === "function") {
+    const latest = await userProfilesRepository.findById(userId);
+    if (latest?.id) {
+      return latest;
+    }
+  }
+
+  const profile = buildProfileFromTokenClaims(payload);
+  if (profile) {
+    return profile;
+  }
+
+  throw new AppError(401, "Dev session is invalid.");
+}
+
+async function signDevAuthToken(kind, profile, config) {
+  const jose = await loadJose();
+  const nowSeconds = Math.floor(Date.now() / 1000);
+  const ttlSeconds = kind === "refresh" ? config.refreshTtlSeconds : config.accessTtlSeconds;
+  const token = await new jose.SignJWT({
+    kind,
+    email: String(profile?.email || "").trim().toLowerCase(),
+    displayName: String(profile?.displayName || "").trim(),
+    username: String(profile?.username || "")
+      .trim()
+      .toLowerCase(),
+    authProvider: String(profile?.authProvider || "dev")
+      .trim()
+      .toLowerCase(),
+    authProviderUserSid: String(profile?.authProviderUserSid || profile?.id || "").trim()
+  })
+    .setProtectedHeader({ alg: "HS256", typ: "JWT" })
+    .setIssuer(DEV_AUTH_ISSUER)
+    .setAudience(config.jwtAudience)
+    .setSubject(String(profile?.id || "").trim())
+    .setIssuedAt(nowSeconds)
+    .setExpirationTime(nowSeconds + ttlSeconds)
+    .sign(encoder.encode(config.secret));
+
+  return `${DEV_AUTH_TOKEN_PREFIX}${token}`;
+}
+
+async function verifyDevAuthToken(token, kind, config) {
+  if (!isDevAuthToken(token) || !config?.secret) {
+    return {
+      status: "invalid",
+      payload: null
+    };
+  }
+
+  const jose = await loadJose();
+  try {
+    const { payload } = await jose.jwtVerify(stripDevAuthTokenPrefix(token), encoder.encode(config.secret), {
+      issuer: DEV_AUTH_ISSUER,
+      audience: config.jwtAudience
+    });
+
+    if (String(payload?.kind || "").trim() !== kind) {
+      return {
+        status: "invalid",
+        payload: null
+      };
+    }
+
+    return {
+      status: "valid",
+      payload
+    };
+  } catch (error) {
+    if (isExpiredJwtError(error)) {
+      return {
+        status: "expired",
+        payload: null
+      };
+    }
+
+    return {
+      status: "invalid",
+      payload: null
+    };
+  }
+}
+
+async function createDevAuthSession(profile, config) {
+  return {
+    access_token: await signDevAuthToken("access", profile, config),
+    refresh_token: await signDevAuthToken("refresh", profile, config),
+    expires_in: config.accessTtlSeconds,
+    token_type: "bearer"
+  };
+}
+
+async function resolveDevAuthProfile(input = {}, { userProfilesRepository = null, validationError } = {}) {
+  if (!userProfilesRepository || typeof userProfilesRepository.findById !== "function") {
+    throw new AppError(500, "Dev auth bootstrap requires internal.repository.user-profiles.findById().");
+  }
+
+  const normalizedUserId = normalizeRecordId(input?.userId, { fallback: null });
+  const normalizedEmail = normalizeEmail(input?.email || "");
+  if (!normalizedUserId && !normalizedEmail) {
+    throw validationError({
+      userId: "Provide a user id or email.",
+      email: "Provide a user id or email."
+    });
+  }
+
+  const fieldErrors = {};
+
+  if (normalizedUserId) {
+    const byId = await userProfilesRepository.findById(normalizedUserId);
+    if (byId?.id) {
+      return byId;
+    }
+    fieldErrors.userId = "User not found.";
+  }
+
+  if (normalizedEmail) {
+    if (typeof userProfilesRepository.findByEmail !== "function") {
+      throw new AppError(500, "Dev auth bootstrap requires internal.repository.user-profiles.findByEmail() for email lookup.");
+    }
+
+    const byEmail = await userProfilesRepository.findByEmail(normalizedEmail);
+    if (byEmail?.id) {
+      return byEmail;
+    }
+    fieldErrors.email = "User not found.";
+  }
+
+  throw validationError(fieldErrors);
+}
+
+async function authenticateDevAuthRequest(
+  { request, accessToken = "", refreshToken = "" },
+  { config, userProfilesRepository = null } = {}
+) {
+  const hasDevAccessToken = isDevAuthToken(accessToken);
+  const hasDevRefreshToken = isDevAuthToken(refreshToken);
+  if (!hasDevAccessToken && !hasDevRefreshToken) {
+    return null;
+  }
+
+  if (!config?.enabled || config?.isProduction || !config?.secret || !isLocalDevAuthRequest(request)) {
+    return {
+      authenticated: false,
+      clearSession: true,
+      session: null,
+      transientFailure: false
+    };
+  }
+
+  if (hasDevAccessToken) {
+    const accessVerification = await verifyDevAuthToken(accessToken, "access", config);
+    if (accessVerification.status === "valid") {
+      const profile = await resolveProfileFromTokenClaims(accessVerification.payload, {
+        userProfilesRepository
+      });
+      return {
+        authenticated: true,
+        profile,
+        clearSession: false,
+        session: null,
+        transientFailure: false
+      };
+    }
+
+    if (accessVerification.status === "invalid" && !hasDevRefreshToken) {
+      return {
+        authenticated: false,
+        clearSession: true,
+        session: null,
+        transientFailure: false
+      };
+    }
+  }
+
+  if (!hasDevRefreshToken) {
+    return {
+      authenticated: false,
+      clearSession: true,
+      session: null,
+      transientFailure: false
+    };
+  }
+
+  const refreshVerification = await verifyDevAuthToken(refreshToken, "refresh", config);
+  if (refreshVerification.status !== "valid") {
+    return {
+      authenticated: false,
+      clearSession: true,
+      session: null,
+      transientFailure: false
+    };
+  }
+
+  const profile = await resolveProfileFromTokenClaims(refreshVerification.payload, {
+    userProfilesRepository
+  });
+  return {
+    authenticated: true,
+    profile,
+    clearSession: false,
+    session: await createDevAuthSession(profile, config),
+    transientFailure: false
+  };
+}
+
+export {
+  assertDevAuthBootstrapConfig,
+  authenticateDevAuthRequest,
+  createDevAuthSession,
+  ensureDevAuthBootstrapAvailable,
+  isDevAuthToken,
+  resolveDevAuthConfig,
+  resolveDevAuthProfile
+};

package/src/server/lib/index.js

@@ -1,2 +1,2 @@
 export { createService, __testables } from "./service.js";
-export { authActions } from "./actions/auth.contributor.js";
+export { baseAuthActions, buildAuthActions, devLoginAsAction } from "./actions/auth.contributor.js";

package/src/server/lib/service.js

@@ -54,6 +54,14 @@ import { createAccountFlows } from "./accountFlows.js";
 import { createOauthFlows } from "./oauthFlows.js";
 import { createPasswordSecurityFlows } from "./passwordSecurityFlows.js";
 import { USER_PROFILE_EMAIL_CONFLICT_CODE } from "./standaloneProfileSyncService.js";
+import {
+  assertDevAuthBootstrapConfig,
+  authenticateDevAuthRequest,
+  createDevAuthSession,
+  ensureDevAuthBootstrapAvailable,
+  resolveDevAuthConfig,
+  resolveDevAuthProfile
+} from "./devAuthBootstrap.js";
 import {
   buildOAuthProviderCatalogResponse,
   resolveOAuthProviderQueryParams,
@@ -103,6 +111,7 @@ function createService(options) {
   const supabaseUrl = String(authProvider.supabaseUrl || "").trim();
   const supabasePublishableKey = String(authProvider.supabasePublishableKey || "").trim();
   const userSettingsRepository = options.userSettingsRepository || null;
+  const userProfilesRepository = options.userProfilesRepository || null;
   const userProfileSyncService = options.userProfileSyncService;
   if (
     !userProfileSyncService ||
@@ -113,6 +122,17 @@ function createService(options) {
   }
   const isProduction = options.nodeEnv === "production";
   const jwtAudience = String(authProvider.jwtAudience || DEFAULT_AUDIENCE).trim();
+  const devAuthConfig = resolveDevAuthConfig({
+    enabled: options.devAuthBypassEnabled,
+    secret: options.devAuthBypassSecret,
+    nodeEnv: options.nodeEnv,
+    jwtAudience,
+    accessTtlSeconds: options.devAuthAccessTtlSeconds,
+    refreshTtlSeconds: options.devAuthRefreshTtlSeconds
+  });
+  assertDevAuthBootstrapConfig(devAuthConfig, {
+    userProfilesRepository
+  });
   const settingsProfileAuthInfo = Object.freeze({
     emailManagedBy: normalizeAuthProviderId(authProvider.emailManagedBy || authProviderId, { fallback: authProviderId }),
     emailChangeFlow: normalizeAuthProviderId(authProvider.emailChangeFlow || authProviderId, { fallback: authProviderId })
@@ -651,12 +671,25 @@ function createService(options) {
   });
 
   async function authenticateRequest(request) {
-    ensureConfigured();
-
     const cookies = safeRequestCookies(request);
     const accessToken = String(cookies[ACCESS_TOKEN_COOKIE] || "");
     const refreshToken = String(cookies[REFRESH_TOKEN_COOKIE] || "");
 
+    const devAuthResult = await authenticateDevAuthRequest(
+      {
+        request,
+        accessToken,
+        refreshToken
+      },
+      {
+        config: devAuthConfig,
+        userProfilesRepository
+      }
+    );
+    if (devAuthResult) {
+      return devAuthResult;
+    }
+
     if (!accessToken && !refreshToken) {
       return {
         authenticated: false,
@@ -666,6 +699,8 @@ function createService(options) {
       };
     }
 
+    ensureConfigured();
+
     if (accessToken) {
       const verification = await verifyAccessToken(accessToken);
 
@@ -796,6 +831,22 @@ function createService(options) {
     return authOAuthCatalogResponse;
   }
 
+  function isDevAuthBootstrapEnabled() {
+    return devAuthConfig.enabled === true;
+  }
+
+  async function devLoginAs(request, input = {}) {
+    ensureDevAuthBootstrapAvailable(devAuthConfig, request);
+    const profile = await resolveDevAuthProfile(input, {
+      userProfilesRepository,
+      validationError
+    });
+    return {
+      profile,
+      session: await createDevAuthSession(profile, devAuthConfig)
+    };
+  }
+
   return {
     register,
     resendRegisterConfirmation,
@@ -816,6 +867,8 @@ function createService(options) {
     getSecurityStatus,
     getSettingsProfileAuthInfo,
     getOAuthProviderCatalog,
+    isDevAuthBootstrapEnabled,
+    devLoginAs,
     authenticateRequest,
     hasAccessTokenCookie,
     hasSessionCookie,

package/src/server/providers/AuthSupabaseServiceProvider.js

@@ -4,7 +4,7 @@ import { normalizeRecordId } from "@jskit-ai/kernel/shared/support/normalize";
 import { createService } from "../lib/service.js";
 import { createStandaloneProfileSyncService } from "../lib/standaloneProfileSyncService.js";
 import { createAuthSessionEventsService } from "../lib/authSessionEventsService.js";
-import { authActions } from "../lib/actions/auth.contributor.js";
+import { buildAuthActions } from "../lib/actions/auth.contributor.js";
 const AUTH_PROFILE_MODE_STANDALONE = "standalone";
 const AUTH_PROFILE_MODE_USERS = "users";
 const SUPPORTED_AUTH_PROFILE_MODES = Object.freeze([AUTH_PROFILE_MODE_STANDALONE, AUTH_PROFILE_MODE_USERS]);
@@ -16,6 +16,20 @@ function splitCsv(value) {
     .filter(Boolean);
 }
 
+function parseBoolean(value, fallback = false) {
+  const raw = String(value || "").trim().toLowerCase();
+  if (!raw) {
+    return fallback;
+  }
+  if (["1", "true", "yes", "on"].includes(raw)) {
+    return true;
+  }
+  if (["0", "false", "no", "off"].includes(raw)) {
+    return false;
+  }
+  return fallback;
+}
+
 function normalizeRecord(value) {
   return value && typeof value === "object" && !Array.isArray(value) ? value : {};
 }
@@ -88,6 +102,18 @@ function resolveAuthProfileMode(env) {
   );
 }
 
+function isDevAuthBypassEnabledForRegistration(env) {
+  if (!isDevAuthBypassRequested(env)) {
+    return false;
+  }
+
+  return String(env?.NODE_ENV || "development").trim().toLowerCase() !== "production";
+}
+
+function isDevAuthBypassRequested(env) {
+  return parseBoolean(env?.AUTH_DEV_BYPASS_ENABLED, false);
+}
+
 function createInMemoryUserSettingsRepository() {
   const settingsByUserId = new Map();
 
@@ -137,10 +163,24 @@ function resolveCommonDependencies(scope) {
   return dependencies;
 }
 
+function resolveRuntimeEnv(scope) {
+  const dependencies = resolveCommonDependencies(scope);
+  const envFromDependencies =
+    dependencies?.env && typeof dependencies.env === "object" ? dependencies.env : {};
+
+  return {
+    ...process.env,
+    ...envFromDependencies
+  };
+}
+
 function resolveOptionalRepositories(scope) {
   const repositories = {};
-  if (scope.has("userSettingsRepository")) {
-    repositories.userSettingsRepository = scope.make("userSettingsRepository");
+  if (scope.has("internal.repository.user-settings")) {
+    repositories.userSettingsRepository = scope.make("internal.repository.user-settings");
+  }
+  if (scope.has("internal.repository.user-profiles")) {
+    repositories.userProfilesRepository = scope.make("internal.repository.user-profiles");
   }
   return repositories;
 }
@@ -163,19 +203,16 @@ class AuthSupabaseServiceProvider {
 
     if (!app.has("authService")) {
       app.singleton("authService", (scope) => {
-        const dependencies = resolveCommonDependencies(scope);
-        const envFromDependencies =
-          dependencies?.env && typeof dependencies.env === "object" ? dependencies.env : {};
-        const env = {
-          ...process.env,
-          ...envFromDependencies
-        };
+        const env = resolveRuntimeEnv(scope);
         const appConfig = scope.has("appConfig") ? scope.make("appConfig") : {};
         const authProvider = resolveAuthProviderConfig(env, appConfig);
         const repositories = resolveOptionalRepositories(scope);
         const userSettingsRepository = repositories.userSettingsRepository || fallbackUserSettingsRepository;
+        const devAuthBypassEnabled = parseBoolean(env.AUTH_DEV_BYPASS_ENABLED, false);
         if (!authProvider.supabaseUrl || !authProvider.supabasePublishableKey) {
-          return null;
+          if (!devAuthBypassEnabled) {
+            return null;
+          }
         }
         const authProfileMode = resolveAuthProfileMode(env);
         let userProfileSyncService = fallbackStandaloneProfileSyncService;
@@ -197,7 +234,12 @@ class AuthSupabaseServiceProvider {
           }),
           nodeEnv: String(env.NODE_ENV || "development").trim() || "development",
           userSettingsRepository,
-          userProfileSyncService
+          userProfileSyncService,
+          userProfilesRepository: repositories.userProfilesRepository || null,
+          devAuthBypassEnabled,
+          devAuthBypassSecret: String(env.AUTH_DEV_BYPASS_SECRET || "").trim(),
+          devAuthAccessTtlSeconds: env.AUTH_DEV_ACCESS_TTL_SECONDS,
+          devAuthRefreshTtlSeconds: env.AUTH_DEV_REFRESH_TTL_SECONDS
         });
       });
     }
@@ -236,7 +278,9 @@ class AuthSupabaseServiceProvider {
     );
 
     app.actions(
-      withActionDefaults(authActions, {
+      withActionDefaults(buildAuthActions({
+        includeDevLoginAs: isDevAuthBypassEnabledForRegistration(resolveRuntimeEnv(app))
+      }), {
         domain: "auth",
         dependencies: {
           authService: "authService",
@@ -245,6 +289,18 @@ class AuthSupabaseServiceProvider {
       })
     );
   }
+
+  boot(app) {
+    if (!app || typeof app.make !== "function") {
+      throw new Error("AuthSupabaseServiceProvider requires application make().");
+    }
+
+    if (!isDevAuthBypassRequested(resolveRuntimeEnv(app))) {
+      return;
+    }
+
+    app.make("authService");
+  }
 }
 
 export { AuthSupabaseServiceProvider };

package/test/devAuthBootstrap.test.js

@@ -0,0 +1,182 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createService } from "../src/server/lib/index.js";
+
+function createProfile(overrides = {}) {
+  return {
+    id: "7",
+    email: "ada@example.com",
+    username: "ada",
+    displayName: "Ada Example",
+    authProvider: "supabase",
+    authProviderUserSid: "supabase-user-7",
+    avatarStorageKey: null,
+    avatarVersion: null,
+    ...overrides
+  };
+}
+
+function createUserProfilesRepository(profile = createProfile()) {
+  return {
+    async findById(userId) {
+      return String(userId || "") === String(profile.id) ? profile : null;
+    },
+    async findByEmail(email) {
+      return String(email || "").trim().toLowerCase() === String(profile.email || "").toLowerCase() ? profile : null;
+    }
+  };
+}
+
+function createUserProfileSyncService() {
+  return {
+    async findByIdentity() {
+      return null;
+    },
+    async syncIdentityProfile(profile) {
+      return createProfile({
+        authProvider: String(profile?.authProvider || "supabase"),
+        authProviderUserSid: String(profile?.authProviderUserSid || "supabase-user-7"),
+        email: String(profile?.email || "ada@example.com").toLowerCase(),
+        displayName: String(profile?.displayName || "Ada Example")
+      });
+    }
+  };
+}
+
+function createLocalRequest(overrides = {}) {
+  const remoteAddress = String(overrides?.socket?.remoteAddress || overrides?.raw?.socket?.remoteAddress || "127.0.0.1");
+  return {
+    ip: "127.0.0.1",
+    hostname: "localhost",
+    headers: {
+      host: "localhost:3000"
+    },
+    cookies: {},
+    socket: {
+      remoteAddress
+    },
+    raw: {
+      socket: {
+        remoteAddress
+      }
+    },
+    ...overrides
+  };
+}
+
+function createServiceFixture(overrides = {}) {
+  return createService({
+    authProvider: {
+      id: "supabase",
+      supabaseUrl: "",
+      supabasePublishableKey: "",
+      jwtAudience: "authenticated"
+    },
+    appPublicUrl: "http://localhost:5173",
+    nodeEnv: "development",
+    devAuthBypassEnabled: true,
+    devAuthBypassSecret: "dev-bootstrap-secret",
+    userProfilesRepository: createUserProfilesRepository(),
+    userProfileSyncService: createUserProfileSyncService(),
+    ...overrides
+  });
+}
+
+test("dev auth bootstrap can issue and authenticate a local session without Supabase", async () => {
+  const authService = createServiceFixture();
+  const loginRequest = createLocalRequest();
+
+  const loginResult = await authService.devLoginAs(loginRequest, {
+    userId: "7"
+  });
+
+  assert.equal(loginResult.profile.id, "7");
+  assert.match(loginResult.session.access_token, /^jskit-dev\./);
+  assert.match(loginResult.session.refresh_token, /^jskit-dev\./);
+
+  const authResult = await authService.authenticateRequest(
+    createLocalRequest({
+      cookies: {
+        sb_access_token: loginResult.session.access_token,
+        sb_refresh_token: loginResult.session.refresh_token
+      }
+    })
+  );
+
+  assert.equal(authResult.authenticated, true);
+  assert.equal(authResult.profile.id, "7");
+  assert.equal(authResult.profile.email, "ada@example.com");
+  assert.equal(authResult.session, null);
+});
+
+test("dev auth bootstrap supports email lookup", async () => {
+  const authService = createServiceFixture();
+
+  const result = await authService.devLoginAs(createLocalRequest(), {
+    email: "ADA@EXAMPLE.COM"
+  });
+
+  assert.equal(result.profile.id, "7");
+  assert.equal(result.profile.email, "ada@example.com");
+});
+
+test("dev auth bootstrap rejects non-local requests and clears leaked dev sessions", async () => {
+  const authService = createServiceFixture();
+  const issued = await authService.devLoginAs(createLocalRequest(), {
+    userId: "7"
+  });
+
+  await assert.rejects(
+    () =>
+      authService.devLoginAs(
+        createLocalRequest({
+          ip: "203.0.113.10",
+          hostname: "example.com",
+          headers: { host: "example.com" }
+        }),
+        { userId: "7" }
+      ),
+    /localhost/
+  );
+
+  const authResult = await authService.authenticateRequest({
+    ip: "203.0.113.10",
+    hostname: "example.com",
+    headers: { host: "example.com" },
+    cookies: {
+      sb_access_token: issued.session.access_token,
+      sb_refresh_token: issued.session.refresh_token
+    }
+  });
+
+  assert.equal(authResult.authenticated, false);
+  assert.equal(authResult.clearSession, true);
+});
+
+test("dev auth bootstrap does not trust forwarded localhost headers", async () => {
+  const authService = createServiceFixture();
+
+  await assert.rejects(
+    () =>
+      authService.devLoginAs(
+        createLocalRequest({
+          ip: "203.0.113.10",
+          socket: {
+            remoteAddress: "203.0.113.10"
+          },
+          raw: {
+            socket: {
+              remoteAddress: "203.0.113.10"
+            }
+          },
+          headers: {
+            host: "localhost:3000",
+            "x-forwarded-for": "127.0.0.1",
+            "x-forwarded-host": "localhost"
+          }
+        }),
+        { userId: "7" }
+      ),
+    /localhost/
+  );
+});

package/test/providerRuntime.test.js

@@ -21,6 +21,14 @@ function createAppConfigFixture() {
   };
 }
 
+function isBootFailureWithCause(error, pattern) {
+  return (
+    error instanceof Error &&
+    /failed during boot\(\)/.test(String(error.message || "")) &&
+    pattern.test(String(error.details?.cause?.message || ""))
+  );
+}
+
 test("auth supabase provider registers authService and contributes auth actions in users mode", async () => {
   const app = createApplication();
   app.instance("appConfig", createAppConfigFixture());
@@ -69,6 +77,7 @@ test("auth supabase provider registers authService and contributes auth actions
   assert.equal(Array.isArray(definitions), true);
   assert.equal(definitions.some((definition) => definition.id === "auth.login.password"), true);
   assert.equal(definitions.some((definition) => definition.id === "auth.register.confirmation.resend"), true);
+  assert.equal(definitions.some((definition) => definition.id === "auth.dev.loginAs"), false);
   const sessionRead = definitions.find((definition) => definition.id === "auth.session.read");
   assert.deepEqual(sessionRead?.surfaces, ["home", "console"]);
 });
@@ -155,6 +164,206 @@ test("auth supabase provider rejects unsupported AUTH_PROFILE_MODE values", asyn
   assert.throws(() => app.make("authService"), /Unsupported AUTH_PROFILE_MODE/);
 });
 
+test("auth supabase provider can boot dev auth without Supabase credentials", async () => {
+  const app = createApplication();
+  app.instance("appConfig", createAppConfigFixture());
+  app.instance("jskit.env", {
+    AUTH_DEV_BYPASS_ENABLED: "true",
+    AUTH_DEV_BYPASS_SECRET: "dev-bootstrap-secret",
+    AUTH_PROFILE_MODE: "users",
+    APP_PUBLIC_URL: "http://localhost:5173",
+    NODE_ENV: "development"
+  });
+  app.instance("jskit.logger", {
+    info() {},
+    warn() {},
+    error() {},
+    debug() {}
+  });
+  app.instance("domainEvents", {
+    async publish() {}
+  });
+  app.instance("users.profile.sync.service", {
+    async findByIdentity() {
+      return null;
+    },
+    async syncIdentityProfile(profile) {
+      return {
+        id: 1,
+        authProvider: String(profile?.authProvider || "supabase"),
+        authProviderUserSid: String(profile?.authProviderUserSid || "user-1"),
+        email: String(profile?.email || "test@example.com"),
+        displayName: String(profile?.displayName || "Test User")
+      };
+    }
+  });
+  app.instance("internal.repository.user-profiles", {
+    async findById() {
+      return null;
+    },
+    async findByEmail() {
+      return null;
+    }
+  });
+
+  await app.start({
+    providers: [ActionRuntimeServiceProvider, AuthSupabaseServiceProvider]
+  });
+
+  const authService = app.make("authService");
+  assert.equal(typeof authService?.devLoginAs, "function");
+  assert.equal(typeof authService?.isDevAuthBootstrapEnabled, "function");
+  assert.equal(authService.isDevAuthBootstrapEnabled(), true);
+
+  const actionExecutor = app.make("actionExecutor");
+  const definitions = actionExecutor.listDefinitions();
+  assert.equal(definitions.some((definition) => definition.id === "auth.dev.loginAs"), true);
+});
+
+test("auth supabase provider rejects dev auth bypass in production", async () => {
+  const app = createApplication();
+  app.instance("appConfig", createAppConfigFixture());
+  app.instance("jskit.env", {
+    AUTH_DEV_BYPASS_ENABLED: "true",
+    AUTH_DEV_BYPASS_SECRET: "dev-bootstrap-secret",
+    AUTH_PROFILE_MODE: "users",
+    APP_PUBLIC_URL: "https://example.com",
+    NODE_ENV: "production"
+  });
+  app.instance("jskit.logger", {
+    info() {},
+    warn() {},
+    error() {},
+    debug() {}
+  });
+  app.instance("domainEvents", {
+    async publish() {}
+  });
+  app.instance("users.profile.sync.service", {
+    async findByIdentity() {
+      return null;
+    },
+    async syncIdentityProfile(profile) {
+      return {
+        id: 1,
+        authProvider: String(profile?.authProvider || "supabase"),
+        authProviderUserSid: String(profile?.authProviderUserSid || "user-1"),
+        email: String(profile?.email || "test@example.com"),
+        displayName: String(profile?.displayName || "Test User")
+      };
+    }
+  });
+  app.instance("internal.repository.user-profiles", {
+    async findById() {
+      return null;
+    },
+    async findByEmail() {
+      return null;
+    }
+  });
+
+  await assert.rejects(
+    () =>
+      app.start({
+        providers: [ActionRuntimeServiceProvider, AuthSupabaseServiceProvider]
+      }),
+    (error) => isBootFailureWithCause(error, /must not be enabled in production/)
+  );
+});
+
+test("auth supabase provider rejects dev auth bypass without a secret during boot", async () => {
+  const app = createApplication();
+  app.instance("appConfig", createAppConfigFixture());
+  app.instance("jskit.env", {
+    AUTH_DEV_BYPASS_ENABLED: "true",
+    AUTH_PROFILE_MODE: "users",
+    APP_PUBLIC_URL: "http://localhost:5173",
+    NODE_ENV: "development"
+  });
+  app.instance("jskit.logger", {
+    info() {},
+    warn() {},
+    error() {},
+    debug() {}
+  });
+  app.instance("domainEvents", {
+    async publish() {}
+  });
+  app.instance("users.profile.sync.service", {
+    async findByIdentity() {
+      return null;
+    },
+    async syncIdentityProfile(profile) {
+      return {
+        id: 1,
+        authProvider: String(profile?.authProvider || "supabase"),
+        authProviderUserSid: String(profile?.authProviderUserSid || "user-1"),
+        email: String(profile?.email || "test@example.com"),
+        displayName: String(profile?.displayName || "Test User")
+      };
+    }
+  });
+  app.instance("internal.repository.user-profiles", {
+    async findById() {
+      return null;
+    },
+    async findByEmail() {
+      return null;
+    }
+  });
+
+  await assert.rejects(
+    () =>
+      app.start({
+        providers: [ActionRuntimeServiceProvider, AuthSupabaseServiceProvider]
+      }),
+    (error) => isBootFailureWithCause(error, /AUTH_DEV_BYPASS_SECRET is required/)
+  );
+});
+
+test("auth supabase provider rejects dev auth bypass without internal.repository.user-profiles during boot", async () => {
+  const app = createApplication();
+  app.instance("appConfig", createAppConfigFixture());
+  app.instance("jskit.env", {
+    AUTH_DEV_BYPASS_ENABLED: "true",
+    AUTH_DEV_BYPASS_SECRET: "dev-bootstrap-secret",
+    AUTH_PROFILE_MODE: "users",
+    APP_PUBLIC_URL: "http://localhost:5173",
+    NODE_ENV: "development"
+  });
+  app.instance("jskit.logger", {
+    info() {},
+    warn() {},
+    error() {},
+    debug() {}
+  });
+  app.instance("domainEvents", {
+    async publish() {}
+  });
+  app.instance("users.profile.sync.service", {
+    async findByIdentity() {
+      return null;
+    },
+    async syncIdentityProfile(profile) {
+      return {
+        id: 1,
+        authProvider: String(profile?.authProvider || "supabase"),
+        authProviderUserSid: String(profile?.authProviderUserSid || "user-1"),
+        email: String(profile?.email || "test@example.com"),
+        displayName: String(profile?.displayName || "Test User")
+      };
+    }
+  });
+
+  await assert.rejects(
+    () =>
+      app.start({
+        providers: [ActionRuntimeServiceProvider, AuthSupabaseServiceProvider]
+      }),
+    (error) => isBootFailureWithCause(error, /requires internal\.repository\.user-profiles with findById\(\) and findByEmail\(\)/)
+  );
+});
+
 test("auth supabase provider reads oauth providers from appConfig.auth.oauth", async () => {
   const app = createApplication();
   app.instance("appConfig", {