spaps 0.7.2 → 0.7.4

package/src/fixture-kernel.js

@@ -0,0 +1,1143 @@
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { DEFAULT_PORT } = require('./config');
+const { buildBaseUrl, getServerRuntime } = require('./local-runtime');
+
+const FIXTURE_SCHEMA_VERSION = 1;
+const FIXTURE_DIRNAME = '.spaps';
+const BROWSER_DIRNAME = 'browser';
+const DEFAULT_BROWSER_BASE_URL = 'http://localhost:3000';
+const DEFAULT_PUBLIC_DIR = 'public';
+const DEFAULT_BRIDGE_SCRIPT_NAME = 'spaps-dev-auth.js';
+const FIXTURE_KEYS = {
+  active_persona: 'spaps.fixture.active_persona',
+  persona: 'spaps.fixture.persona',
+  profile: 'spaps.fixture.profile',
+  roles: 'spaps.fixture.roles',
+  entitlements: 'spaps.fixture.entitlements',
+  application: 'spaps.fixture.application',
+  runtime: 'spaps.fixture.runtime',
+  selector: 'spaps.fixture.selector',
+};
+const COMPAT_STORAGE_KEYS = {
+  sdk_user: 'sweet_potato_user',
+  sdk_access_token: 'sweet_potato_access_token',
+  sdk_refresh_token: 'sweet_potato_refresh_token',
+  legacy_user: 'spaps_user',
+};
+
+const DEFAULT_PERSONAS = [
+  {
+    code: 'user',
+    display_name: 'Local User',
+    selector: {
+      query_param: { _user: 'user' },
+      headers: { 'X-Test-User': 'user' },
+    },
+    profile: {
+      user_id: '00000000-0000-0000-0000-000000000001',
+      email: 'user@localhost',
+      username: 'dev-user',
+      tier: 'free',
+    },
+    permissions: ['view_products'],
+    browser: {
+      local_storage: {},
+    },
+  },
+  {
+    code: 'admin',
+    display_name: 'Local Admin',
+    selector: {
+      query_param: { _user: 'admin' },
+      headers: { 'X-Test-User': 'admin' },
+    },
+    profile: {
+      user_id: '5bdb0db2-5ab1-4e2c-999b-1153cc329477',
+      email: 'buildooor@gmail.com',
+      username: 'admin',
+      tier: 'enterprise',
+    },
+    permissions: [
+      'view_products',
+      'manage_products',
+      'view_users',
+      'manage_users',
+      'view_orders',
+      'manage_orders',
+      'access_admin',
+      'view_analytics',
+      'manage_subscriptions',
+      'manage_system_settings',
+    ],
+    browser: {
+      local_storage: {},
+    },
+  },
+  {
+    code: 'premium',
+    display_name: 'Premium User',
+    selector: {
+      query_param: { _user: 'premium' },
+      headers: { 'X-Test-User': 'premium' },
+    },
+    profile: {
+      user_id: '00000000-0000-0000-0000-000000000002',
+      email: 'premium@localhost',
+      username: 'premium-user',
+      tier: 'premium',
+    },
+    permissions: ['view_products'],
+    browser: {
+      local_storage: {},
+    },
+  },
+];
+
+const DEFAULT_ROLE_GRANTS = {
+  user: ['user'],
+  admin: ['admin', 'super_admin'],
+  premium: ['user'],
+};
+
+const DEFAULT_ENTITLEMENT_GRANTS = {
+  user: [],
+  admin: ['paid_access', 'admin_console'],
+  premium: ['paid_access'],
+};
+
+function createCliError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function resolveRepoRoot(dir = null) {
+  return path.resolve(dir || process.cwd());
+}
+
+function resolveFixturePaths(rootDir) {
+  const fixtureDir = path.join(rootDir, FIXTURE_DIRNAME);
+  const browserDir = path.join(fixtureDir, BROWSER_DIRNAME);
+  const publicDir = path.join(rootDir, DEFAULT_PUBLIC_DIR);
+  return {
+    rootDir,
+    fixtureDir,
+    browserDir,
+    publicDir,
+    app: path.join(fixtureDir, 'app.json'),
+    users: path.join(fixtureDir, 'users.json'),
+    roles: path.join(fixtureDir, 'roles.json'),
+    entitlements: path.join(fixtureDir, 'entitlements.json'),
+    readme: path.join(fixtureDir, 'README.md'),
+    browserGitignore: path.join(browserDir, '.gitignore'),
+    bridgeScript: path.join(publicDir, DEFAULT_BRIDGE_SCRIPT_NAME),
+    lock: path.join(fixtureDir, 'fixtures.lock.json'),
+    starterContract: path.join(rootDir, 'spaps.app.json'),
+  };
+}
+
+function normalizeBaseUrl(baseUrl = null) {
+  const candidate = String(baseUrl || process.env.SPAPS_BROWSER_BASE_URL || DEFAULT_BROWSER_BASE_URL).trim();
+  return candidate.replace(/\/+$/, '');
+}
+
+function resolveStorageOrigin(baseUrl) {
+  const normalizedBaseUrl = normalizeBaseUrl(baseUrl);
+  try {
+    return new URL(normalizedBaseUrl).origin;
+  } catch {
+    return normalizedBaseUrl;
+  }
+}
+
+function readJsonFile(filePath, label) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (error) {
+    throw createCliError('EINVAL', `Could not read ${label} at "${filePath}": ${error.message}`);
+  }
+}
+
+function readExistingStarterContract(paths) {
+  if (!fs.existsSync(paths.starterContract)) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(fs.readFileSync(paths.starterContract, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function buildRuntimeSummary(runtime, port, starterContract = null) {
+  const contractLocal = starterContract?.spaps?.local || {};
+  const contractApp = starterContract?.spaps?.application || {};
+  const apiUrl = runtime?.url || contractLocal.api_url || buildBaseUrl(port);
+  const docsUrl = runtime?.docs || contractLocal.docs_url || `${apiUrl}/docs`;
+
+  return {
+    api_url: apiUrl,
+    docs_url: docsUrl,
+    port,
+    running: Boolean(runtime?.running),
+    local_mode_active:
+      runtime?.running
+        ? (runtime.local_mode?.known ? Boolean(runtime.local_mode.active) : null)
+        : (typeof contractLocal.local_mode_active === 'boolean' ? contractLocal.local_mode_active : null),
+    environment: runtime?.running ? runtime.local_mode?.environment || null : null,
+    application_id: contractApp.id || runtime?.local_mode?.test_application?.id || null,
+    application_slug: contractApp.slug || runtime?.local_mode?.test_application?.slug || null,
+    provisioning_status: contractApp.provisioning_status || null,
+  };
+}
+
+function buildAppConfig({ version, port, baseUrl, runtime, starterContract }) {
+  const server = buildRuntimeSummary(runtime, port, starterContract);
+
+  return {
+    schema_version: FIXTURE_SCHEMA_VERSION,
+    generated_by: `spaps@${version}`,
+    server,
+    browser: {
+      base_url: normalizeBaseUrl(baseUrl),
+      default_persona: 'user',
+      storage_format: 'playwright',
+    },
+    bridge: {
+      enabled: true,
+      public_dir: DEFAULT_PUBLIC_DIR,
+      script_name: DEFAULT_BRIDGE_SCRIPT_NAME,
+      query_param: 'spaps_persona',
+      ui: {
+        enabled: true,
+      },
+    },
+    auth: {
+      mode: server.local_mode_active === true ? 'local_mode' : runtime?.running ? 'application_key' : 'offline',
+      selector: {
+        query_param: '_user',
+        header: 'X-Test-User',
+      },
+      api_key_header: 'X-API-Key',
+    },
+  };
+}
+
+function buildUsersConfig() {
+  return {
+    schema_version: FIXTURE_SCHEMA_VERSION,
+    default_persona: 'user',
+    personas: DEFAULT_PERSONAS,
+  };
+}
+
+function buildRolesConfig() {
+  return {
+    schema_version: FIXTURE_SCHEMA_VERSION,
+    grants: DEFAULT_ROLE_GRANTS,
+  };
+}
+
+function buildEntitlementsConfig() {
+  return {
+    schema_version: FIXTURE_SCHEMA_VERSION,
+    grants: DEFAULT_ENTITLEMENT_GRANTS,
+  };
+}
+
+function buildFixtureReadme() {
+  return `# .spaps
+
+Repo-local SPAPS auth fixtures live here.
+
+What to edit:
+
+- \`app.json\`: local SPAPS server and browser target settings
+- \`users.json\`: personas, profile data, selector hints, and custom browser storage
+- \`roles.json\`: persona-to-role grants
+- \`entitlements.json\`: persona-to-entitlement grants
+
+Generated files:
+
+- \`browser/*.storage-state.json\`: Playwright storageState files
+- \`browser/*.headers.json\`: extraHTTPHeaders companions for local-mode persona routing
+- \`browser/*.context.json\`: merged persona/runtime summary for test harnesses
+- \`public/${DEFAULT_BRIDGE_SCRIPT_NAME}\`: optional browser bridge for frontend-only auth/RBAC clicking around
+
+Common workflow:
+
+1. Run \`npx spaps fixtures init\`
+2. Edit \`.spaps/users.json\`, \`.spaps/roles.json\`, or \`.spaps/entitlements.json\`
+3. Run \`npx spaps fixtures apply\`
+4. Point Playwright or local scripts at the generated browser artifacts
+5. Include \`/${DEFAULT_BRIDGE_SCRIPT_NAME}\` before your app boots if you want frontend-only persona switching
+`;
+}
+
+function writeJson(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+function writeManagedFile(filePath, content, bookkeeping, { overwrite = true } = {}) {
+  const relativePath = path.relative(bookkeeping.rootDir, filePath) || path.basename(filePath);
+  if (fs.existsSync(filePath) && !overwrite) {
+    bookkeeping.files_skipped.push(relativePath);
+    return false;
+  }
+
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+
+  if (fs.existsSync(filePath)) {
+    bookkeeping.files_overwritten.push(relativePath);
+  } else {
+    bookkeeping.files_created.push(relativePath);
+  }
+
+  fs.writeFileSync(filePath, content);
+  return true;
+}
+
+function cleanupGeneratedBrowserArtifacts(paths) {
+  if (!fs.existsSync(paths.browserDir)) {
+    return [];
+  }
+
+  const removed = [];
+  for (const entry of fs.readdirSync(paths.browserDir)) {
+    if (entry === '.gitignore') {
+      continue;
+    }
+    const fullPath = path.join(paths.browserDir, entry);
+    fs.rmSync(fullPath, { recursive: true, force: true });
+    removed.push(path.relative(paths.rootDir, fullPath));
+  }
+
+  if (fs.existsSync(paths.lock)) {
+    fs.rmSync(paths.lock, { force: true });
+    removed.push(path.relative(paths.rootDir, paths.lock));
+  }
+
+  return removed;
+}
+
+async function buildFixtureSeed({ rootDir, port, baseUrl, version }) {
+  const paths = resolveFixturePaths(rootDir);
+  const starterContract = readExistingStarterContract(paths);
+  const runtime = await getServerRuntime({ port });
+
+  return {
+    runtime,
+    appConfig: buildAppConfig({ version, port, baseUrl, runtime, starterContract }),
+    usersConfig: buildUsersConfig(),
+    rolesConfig: buildRolesConfig(),
+    entitlementsConfig: buildEntitlementsConfig(),
+  };
+}
+
+async function initFixtureKernel({
+  dir = null,
+  port = DEFAULT_PORT,
+  baseUrl = null,
+  version = '0.0.0',
+  force = false,
+} = {}) {
+  const rootDir = resolveRepoRoot(dir);
+  const paths = resolveFixturePaths(rootDir);
+  const bookkeeping = {
+    rootDir,
+    files_created: [],
+    files_overwritten: [],
+    files_skipped: [],
+  };
+  const seed = await buildFixtureSeed({ rootDir, port, baseUrl, version });
+
+  writeManagedFile(paths.app, `${JSON.stringify(seed.appConfig, null, 2)}\n`, bookkeeping, { overwrite: force });
+  writeManagedFile(paths.users, `${JSON.stringify(seed.usersConfig, null, 2)}\n`, bookkeeping, { overwrite: force });
+  writeManagedFile(paths.roles, `${JSON.stringify(seed.rolesConfig, null, 2)}\n`, bookkeeping, { overwrite: force });
+  writeManagedFile(paths.entitlements, `${JSON.stringify(seed.entitlementsConfig, null, 2)}\n`, bookkeeping, { overwrite: force });
+  writeManagedFile(paths.readme, buildFixtureReadme(), bookkeeping, { overwrite: force });
+  writeManagedFile(paths.browserGitignore, '*.json\n!.gitignore\n', bookkeeping, { overwrite: force });
+
+  return {
+    success: true,
+    command: 'fixtures',
+    subcommand: force ? 'reset' : 'init',
+    root_dir: rootDir,
+    fixture_dir: paths.fixtureDir,
+    runtime: seed.runtime,
+    files_created: bookkeeping.files_created,
+    files_overwritten: bookkeeping.files_overwritten,
+    files_skipped: bookkeeping.files_skipped,
+    next_steps: [
+      'Edit .spaps/users.json, .spaps/roles.json, or .spaps/entitlements.json as needed',
+      'Run npx spaps fixtures apply',
+    ],
+  };
+}
+
+function loadFixtureKernel(rootDir) {
+  const paths = resolveFixturePaths(rootDir);
+  if (!fs.existsSync(paths.fixtureDir)) {
+    throw createCliError('ENOENT', `No .spaps directory found in "${rootDir}". Run "npx spaps fixtures init" first.`);
+  }
+
+  const app = readJsonFile(paths.app, '.spaps/app.json');
+  const users = readJsonFile(paths.users, '.spaps/users.json');
+  const roles = readJsonFile(paths.roles, '.spaps/roles.json');
+  const entitlements = readJsonFile(paths.entitlements, '.spaps/entitlements.json');
+
+  if (!Array.isArray(users.personas) || users.personas.length === 0) {
+    throw createCliError('EINVAL', '.spaps/users.json must define at least one persona.');
+  }
+
+  return { paths, app, users, roles, entitlements };
+}
+
+function ensurePersona(usersConfig, code) {
+  const persona = usersConfig.personas.find((entry) => entry.code === code);
+  if (!persona) {
+    throw createCliError('EINVAL', `Unknown persona "${code}". Add it to .spaps/users.json or choose one of: ${usersConfig.personas.map((entry) => entry.code).join(', ')}.`);
+  }
+  return persona;
+}
+
+function stringifyStorageValue(value) {
+  if (typeof value === 'string') {
+    return value;
+  }
+  return JSON.stringify(value);
+}
+
+function buildRouteHint(appConfig, persona) {
+  const userCode = persona?.selector?.query_param?._user;
+  if (appConfig.server.local_mode_active === true && userCode) {
+    return `/?_user=${encodeURIComponent(userCode)}`;
+  }
+  return null;
+}
+
+function buildHeaderArtifact(appConfig, persona) {
+  return {
+    format: 'playwright-extra-http-headers',
+    local_mode_active: appConfig.server.local_mode_active === true,
+    headers: persona.selector?.headers || {},
+    route_hint: buildRouteHint(appConfig, persona),
+    note:
+      appConfig.server.local_mode_active === true
+        ? 'Use these headers with Playwright context.extraHTTPHeaders when you want SPAPS local-mode persona routing.'
+        : 'SPAPS local mode is not active. These headers are still emitted so app-specific test harnesses can choose to consume them.',
+  };
+}
+
+function base64UrlEncodeJson(value) {
+  return Buffer.from(JSON.stringify(value)).toString('base64url');
+}
+
+function buildFixtureTokens(appConfig, persona, roles) {
+  const now = Math.floor(Date.now() / 1000);
+  const primaryRole = roles[0] || 'user';
+  const header = base64UrlEncodeJson({ alg: 'none', typ: 'JWT' });
+  const payload = base64UrlEncodeJson({
+    sub: persona.profile?.user_id,
+    user_id: persona.profile?.user_id,
+    email: persona.profile?.email,
+    role: primaryRole,
+    roles,
+    tier: persona.profile?.tier || 'free',
+    app_id: appConfig.server.application_id,
+    aud: appConfig.server.application_slug || 'spaps-fixture',
+    iss: 'spaps-fixture',
+    iat: now,
+    exp: now + (60 * 60 * 24 * 30),
+  });
+
+  return {
+    access_token: `${header}.${payload}.fixture`,
+    refresh_token: `fixture-refresh-${persona.code}`,
+    token_type: 'Bearer',
+    expires_in: 60 * 60 * 24 * 30,
+  };
+}
+
+function buildEntitlementRecords(appConfig, persona, entitlementsConfig) {
+  const entitlementKeys = entitlementsConfig.grants?.[persona.code] || [];
+
+  return entitlementKeys.map((entitlementKey, index) => ({
+    id: `fixture-${persona.code}-${index + 1}`,
+    application_id: appConfig.server.application_id,
+    beneficiary_user_id: persona.profile?.user_id || null,
+    beneficiary_email: persona.profile?.email || null,
+    entitlement_key: entitlementKey,
+    entitlement_type: 'manual',
+    source: 'fixture',
+    resource_type: 'user',
+    resource_id: null,
+    starts_at: '2026-01-01T00:00:00.000Z',
+    ends_at: null,
+    revoked_at: null,
+    metadata: {
+      fixture_persona: persona.code,
+    },
+  }));
+}
+
+function buildCurrentUser(appConfig, persona, rolesConfig, entitlementsConfig) {
+  const roles = rolesConfig.grants?.[persona.code] || [];
+  const entitlements = entitlementsConfig.grants?.[persona.code] || [];
+  const permissions = Array.isArray(persona.permissions) ? persona.permissions : [];
+  const primaryRole = roles[0] || 'user';
+
+  return {
+    id: persona.profile?.user_id || null,
+    email: persona.profile?.email || null,
+    username: persona.profile?.username || null,
+    tier: persona.profile?.tier || 'free',
+    role: primaryRole,
+    roles,
+    permissions,
+    is_admin: roles.includes('admin') || roles.includes('super_admin'),
+    is_super_admin: roles.includes('super_admin'),
+    entitlements,
+    active_entitlements: entitlements.map((entitlementKey) => ({ key: entitlementKey })),
+    application_id: appConfig.server.application_id || null,
+    fixture_persona: persona.code,
+  };
+}
+
+function buildBridgeConfig(appConfig, users, rolesConfig, entitlementsConfig) {
+  const apiOrigin = (() => {
+    try {
+      return new URL(appConfig.server.api_url).origin;
+    } catch {
+      return appConfig.server.api_url;
+    }
+  })();
+
+  return {
+    generated_at: new Date().toISOString(),
+    api_url: appConfig.server.api_url,
+    api_origin: apiOrigin,
+    auth_mode: appConfig.auth.mode,
+    local_mode_active: appConfig.server.local_mode_active === true,
+    default_persona: users.default_persona || appConfig.browser.default_persona || 'user',
+    query_param: appConfig.bridge?.query_param || 'spaps_persona',
+    storage_keys: {
+      ...FIXTURE_KEYS,
+      ...COMPAT_STORAGE_KEYS,
+    },
+    bridge: {
+      script_name: appConfig.bridge?.script_name || DEFAULT_BRIDGE_SCRIPT_NAME,
+      ui_enabled: appConfig.bridge?.ui?.enabled !== false,
+    },
+    application: {
+      api_url: appConfig.server.api_url,
+      application_id: appConfig.server.application_id,
+      application_slug: appConfig.server.application_slug,
+      local_mode_active: appConfig.server.local_mode_active,
+    },
+    personas: users.personas.map((persona) => ({
+      code: persona.code,
+      display_name: persona.display_name,
+      selector: persona.selector || {},
+      route_hint: buildRouteHint(appConfig, persona),
+      user: buildCurrentUser(appConfig, persona, rolesConfig, entitlementsConfig),
+      tokens: buildFixtureTokens(appConfig, persona, rolesConfig.grants?.[persona.code] || []),
+      entitlement_keys: entitlementsConfig.grants?.[persona.code] || [],
+      entitlements: buildEntitlementRecords(appConfig, persona, entitlementsConfig),
+      browser: {
+        local_storage: persona.browser?.local_storage || {},
+      },
+    })),
+  };
+}
+
+function buildDevAuthBridgeScript(config) {
+  const serializedConfig = JSON.stringify(config);
+
+  return `;(function () {
+  if (typeof window === 'undefined' || typeof localStorage === 'undefined') return;
+
+  const CONFIG = ${serializedConfig};
+  const STORAGE_KEYS = CONFIG.storage_keys;
+  const ACTIVE_PERSONA_KEY = STORAGE_KEYS.active_persona;
+  const TOKEN_USER_KEY = STORAGE_KEYS.sdk_user;
+  const TOKEN_ACCESS_KEY = STORAGE_KEYS.sdk_access_token;
+  const TOKEN_REFRESH_KEY = STORAGE_KEYS.sdk_refresh_token;
+  const LEGACY_USER_KEY = STORAGE_KEYS.legacy_user;
+  const PERSONA_LOCAL_STORAGE_KEYS = Array.from(new Set(
+    CONFIG.personas.flatMap((persona) => Object.keys(persona.browser?.local_storage || {}))
+  ));
+  const originalFetch = typeof window.fetch === 'function' ? window.fetch.bind(window) : null;
+
+  function toAbsoluteUrl(input) {
+    if (input instanceof Request) return new URL(input.url, window.location.origin);
+    return new URL(String(input), window.location.origin);
+  }
+
+  function getPersonaByCode(code) {
+    return CONFIG.personas.find((persona) => persona.code === code) || null;
+  }
+
+  function getInitialPersonaCode() {
+    const fromQuery = new URLSearchParams(window.location.search).get(CONFIG.query_param);
+    return fromQuery || localStorage.getItem(ACTIVE_PERSONA_KEY) || CONFIG.default_persona;
+  }
+
+  function getCurrentPersona() {
+    return getPersonaByCode(localStorage.getItem(ACTIVE_PERSONA_KEY)) || getPersonaByCode(getInitialPersonaCode()) || CONFIG.personas[0];
+  }
+
+  function clearPersonaBrowserStorage() {
+    PERSONA_LOCAL_STORAGE_KEYS.forEach((key) => {
+      localStorage.removeItem(key);
+    });
+  }
+
+  function persistPersona(persona) {
+    if (!persona) return;
+    clearPersonaBrowserStorage();
+    localStorage.setItem(ACTIVE_PERSONA_KEY, persona.code);
+    localStorage.setItem(STORAGE_KEYS.persona, persona.code);
+    localStorage.setItem(STORAGE_KEYS.profile, JSON.stringify(persona.user));
+    localStorage.setItem(STORAGE_KEYS.roles, JSON.stringify(persona.user.roles || []));
+    localStorage.setItem(STORAGE_KEYS.entitlements, JSON.stringify(persona.entitlement_keys || []));
+    localStorage.setItem(STORAGE_KEYS.application, JSON.stringify(CONFIG.application));
+    localStorage.setItem(STORAGE_KEYS.runtime, JSON.stringify({
+      auth_mode: CONFIG.auth_mode,
+      local_mode_active: CONFIG.local_mode_active
+    }));
+    localStorage.setItem(STORAGE_KEYS.selector, JSON.stringify(persona.selector || {}));
+    localStorage.setItem(TOKEN_USER_KEY, JSON.stringify(persona.user));
+    localStorage.setItem(TOKEN_ACCESS_KEY, persona.tokens.access_token);
+    localStorage.setItem(TOKEN_REFRESH_KEY, persona.tokens.refresh_token);
+    localStorage.setItem(LEGACY_USER_KEY, JSON.stringify(persona.user));
+
+    Object.entries(persona.browser?.local_storage || {}).forEach(([key, value]) => {
+      localStorage.setItem(key, typeof value === 'string' ? value : JSON.stringify(value));
+    });
+  }
+
+  function clearSession() {
+    [ACTIVE_PERSONA_KEY, STORAGE_KEYS.persona, STORAGE_KEYS.profile, STORAGE_KEYS.roles, STORAGE_KEYS.entitlements, STORAGE_KEYS.application, STORAGE_KEYS.runtime, STORAGE_KEYS.selector, TOKEN_USER_KEY, TOKEN_ACCESS_KEY, TOKEN_REFRESH_KEY, LEGACY_USER_KEY, ...PERSONA_LOCAL_STORAGE_KEYS].forEach((key) => {
+      localStorage.removeItem(key);
+    });
+  }
+
+  function response(body, status) {
+    return Promise.resolve(new Response(JSON.stringify(body), {
+      status: status || 200,
+      headers: { 'Content-Type': 'application/json' }
+    }));
+  }
+
+  function authEnvelope(persona) {
+    return {
+      success: true,
+      data: {
+        access_token: persona.tokens.access_token,
+        refresh_token: persona.tokens.refresh_token,
+        expires_in: persona.tokens.expires_in,
+        token_type: persona.tokens.token_type,
+        user: persona.user
+      }
+    };
+  }
+
+  function userEnvelope(persona) {
+    return {
+      success: true,
+      data: {
+        user: persona.user
+      }
+    };
+  }
+
+  function entitlementsEnvelope(persona, requestedKey) {
+    const matching = requestedKey
+      ? persona.entitlements.filter((entry) => entry.entitlement_key === requestedKey)
+      : persona.entitlements;
+
+    return {
+      success: true,
+      data: {
+        entitlements: matching,
+        count: matching.length
+      }
+    };
+  }
+
+  function entitlementCheckEnvelope(persona, requestedKey) {
+    const matching = requestedKey
+      ? persona.entitlements.filter((entry) => entry.entitlement_key === requestedKey)
+      : persona.entitlements;
+
+    return {
+      success: true,
+      data: {
+        has_entitlement: matching.length > 0,
+        entitlements: matching,
+        entitlement_key: requestedKey || null
+      }
+    };
+  }
+
+  async function parseJsonBody(input, init) {
+    try {
+      const request = input instanceof Request ? input.clone() : new Request(String(input), init);
+      const text = await request.text();
+      return text ? JSON.parse(text) : {};
+    } catch {
+      return {};
+    }
+  }
+
+  function resolvePersonaForEmail(email) {
+    if (!email) return null;
+    return CONFIG.personas.find((persona) => persona.user.email && persona.user.email.toLowerCase() === String(email).toLowerCase()) || null;
+  }
+
+  function shouldIntercept(url) {
+    const path = url.pathname;
+    const supported = path === '/api/auth/login' ||
+      path === '/api/auth/register' ||
+      path === '/api/auth/logout' ||
+      path === '/api/auth/refresh' ||
+      path === '/api/auth/user' ||
+      path === '/api/entitlements' ||
+      path === '/api/entitlements/check';
+
+    if (!supported) return false;
+    return url.origin === window.location.origin || url.origin === CONFIG.api_origin;
+  }
+
+  function installFetchBridge() {
+    if (!originalFetch || window.__spapsDevAuthFetchInstalled) return;
+
+    window.fetch = async function (input, init) {
+      const url = toAbsoluteUrl(input);
+      if (!shouldIntercept(url)) {
+        return originalFetch(input, init);
+      }
+
+      const method = String((init && init.method) || (input instanceof Request && input.method) || 'GET').toUpperCase();
+      const currentPersona = getCurrentPersona();
+
+      if ((url.pathname === '/api/auth/login' || url.pathname === '/api/auth/register') && method === 'POST') {
+        const body = await parseJsonBody(input, init);
+        const persona = resolvePersonaForEmail(body.email) || currentPersona;
+        persistPersona(persona);
+        return response(authEnvelope(persona), 200);
+      }
+
+      if (url.pathname === '/api/auth/refresh' && method === 'POST') {
+        persistPersona(currentPersona);
+        return response(authEnvelope(currentPersona), 200);
+      }
+
+      if (url.pathname === '/api/auth/logout' && method === 'POST') {
+        clearSession();
+        return response({ success: true, message: 'Signed out from dev auth bridge' }, 200);
+      }
+
+      if (url.pathname === '/api/auth/user' && method === 'GET') {
+        persistPersona(currentPersona);
+        return response(userEnvelope(currentPersona), 200);
+      }
+
+      if (url.pathname === '/api/entitlements' && method === 'GET') {
+        const requestedKey = url.searchParams.get('entitlement_key');
+        return response(entitlementsEnvelope(currentPersona, requestedKey), 200);
+      }
+
+      if (url.pathname === '/api/entitlements/check' && method === 'GET') {
+        const requestedKey = url.searchParams.get('key') || url.searchParams.get('entitlement_key');
+        return response(entitlementCheckEnvelope(currentPersona, requestedKey), 200);
+      }
+
+      return originalFetch(input, init);
+    };
+
+    window.__spapsDevAuthFetchInstalled = true;
+  }
+
+  function renderOverlay() {
+    if (CONFIG.bridge.ui_enabled === false || document.getElementById('spaps-dev-auth-overlay')) return;
+    const container = document.createElement('div');
+    container.id = 'spaps-dev-auth-overlay';
+    container.style.cssText = 'position:fixed;right:12px;bottom:12px;z-index:2147483647;background:#111827;color:#f9fafb;padding:10px 12px;border-radius:12px;box-shadow:0 10px 30px rgba(0,0,0,0.25);font:12px/1.4 ui-monospace, SFMono-Regular, Menlo, monospace;display:flex;gap:8px;align-items:center;';
+
+    const label = document.createElement('span');
+    label.textContent = 'SPAPS dev auth';
+    label.style.fontWeight = '600';
+
+    const select = document.createElement('select');
+    select.style.cssText = 'background:#1f2937;color:#f9fafb;border:1px solid #374151;border-radius:8px;padding:4px 8px;';
+    CONFIG.personas.forEach((persona) => {
+      const option = document.createElement('option');
+      option.value = persona.code;
+      option.textContent = persona.code;
+      select.appendChild(option);
+    });
+    select.value = getCurrentPersona().code;
+
+    const button = document.createElement('button');
+    button.type = 'button';
+    button.textContent = 'Switch';
+    button.style.cssText = 'background:#f59e0b;color:#111827;border:0;border-radius:8px;padding:4px 8px;cursor:pointer;font-weight:600;';
+    button.onclick = function () {
+      const nextPersona = getPersonaByCode(select.value);
+      if (!nextPersona) return;
+      persistPersona(nextPersona);
+      window.location.reload();
+    };
+
+    container.appendChild(label);
+    container.appendChild(select);
+    container.appendChild(button);
+    document.body.appendChild(container);
+  }
+
+  const initialPersona = getCurrentPersona();
+  persistPersona(initialPersona);
+  installFetchBridge();
+
+  window.__SPAPS_DEV_AUTH__ = {
+    config: CONFIG,
+    listPersonas: function () {
+      return CONFIG.personas.map((persona) => ({
+        code: persona.code,
+        display_name: persona.display_name,
+        entitlements: persona.entitlement_keys,
+        roles: persona.user.roles || []
+      }));
+    },
+    getCurrentPersona: getCurrentPersona,
+    getCurrentUser: function () {
+      return getCurrentPersona().user;
+    },
+    switchPersona: function (code, options) {
+      const nextPersona = getPersonaByCode(code);
+      if (!nextPersona) return null;
+      persistPersona(nextPersona);
+      if (!options || options.reload !== false) window.location.reload();
+      return nextPersona;
+    },
+    clearSession: clearSession,
+    installFetchBridge: installFetchBridge
+  };
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', renderOverlay, { once: true });
+  } else {
+    renderOverlay();
+  }
+})();\n`;
+}
+
+function buildStorageStateArtifact(appConfig, persona, rolesConfig, entitlementsConfig) {
+  const user = buildCurrentUser(appConfig, persona, rolesConfig, entitlementsConfig);
+  const tokens = buildFixtureTokens(appConfig, persona, rolesConfig.grants?.[persona.code] || []);
+  const localStorage = [
+    {
+      name: FIXTURE_KEYS.active_persona,
+      value: persona.code,
+    },
+    {
+      name: FIXTURE_KEYS.persona,
+      value: persona.code,
+    },
+    {
+      name: FIXTURE_KEYS.profile,
+      value: stringifyStorageValue(persona.profile || {}),
+    },
+    {
+      name: FIXTURE_KEYS.roles,
+      value: stringifyStorageValue(rolesConfig.grants?.[persona.code] || []),
+    },
+    {
+      name: FIXTURE_KEYS.entitlements,
+      value: stringifyStorageValue(entitlementsConfig.grants?.[persona.code] || []),
+    },
+    {
+      name: FIXTURE_KEYS.application,
+      value: stringifyStorageValue({
+        api_url: appConfig.server.api_url,
+        application_id: appConfig.server.application_id,
+        application_slug: appConfig.server.application_slug,
+      }),
+    },
+    {
+      name: FIXTURE_KEYS.runtime,
+      value: stringifyStorageValue({
+        running: appConfig.server.running,
+        local_mode_active: appConfig.server.local_mode_active,
+        auth_mode: appConfig.auth.mode,
+      }),
+    },
+    {
+      name: FIXTURE_KEYS.selector,
+      value: stringifyStorageValue(persona.selector || {}),
+    },
+    {
+      name: COMPAT_STORAGE_KEYS.sdk_user,
+      value: stringifyStorageValue(user),
+    },
+    {
+      name: COMPAT_STORAGE_KEYS.sdk_access_token,
+      value: tokens.access_token,
+    },
+    {
+      name: COMPAT_STORAGE_KEYS.sdk_refresh_token,
+      value: tokens.refresh_token,
+    },
+    {
+      name: COMPAT_STORAGE_KEYS.legacy_user,
+      value: stringifyStorageValue(user),
+    },
+  ];
+
+  for (const [key, value] of Object.entries(persona.browser?.local_storage || {})) {
+    localStorage.push({
+      name: key,
+      value: stringifyStorageValue(value),
+    });
+  }
+
+  return {
+    cookies: [],
+    origins: [
+      {
+        origin: resolveStorageOrigin(appConfig.browser.base_url),
+        localStorage,
+      },
+    ],
+  };
+}
+
+function buildPersonaContext(appConfig, persona, rolesConfig, entitlementsConfig, paths) {
+  const user = buildCurrentUser(appConfig, persona, rolesConfig, entitlementsConfig);
+  const tokens = buildFixtureTokens(appConfig, persona, rolesConfig.grants?.[persona.code] || []);
+  return {
+    persona: persona.code,
+    display_name: persona.display_name,
+    base_url: appConfig.browser.base_url,
+    route_hint: buildRouteHint(appConfig, persona),
+    selector: persona.selector || {},
+    profile: persona.profile || {},
+    roles: rolesConfig.grants?.[persona.code] || [],
+    entitlements: entitlementsConfig.grants?.[persona.code] || [],
+    user,
+    tokens,
+    application: {
+      api_url: appConfig.server.api_url,
+      application_id: appConfig.server.application_id,
+      application_slug: appConfig.server.application_slug,
+      local_mode_active: appConfig.server.local_mode_active,
+    },
+    artifacts: {
+      storage_state_path: path.join(paths.browserDir, `${persona.code}.storage-state.json`),
+      headers_path: path.join(paths.browserDir, `${persona.code}.headers.json`),
+      context_path: path.join(paths.browserDir, `${persona.code}.context.json`),
+    },
+  };
+}
+
+function writePersonaArtifacts({ rootDir, paths, appConfig, users, roles, entitlements, personaCode = null }) {
+  const selectedCodes = personaCode ? [ensurePersona(users, personaCode).code] : users.personas.map((persona) => persona.code);
+  const generated = [];
+
+  for (const code of selectedCodes) {
+    const persona = ensurePersona(users, code);
+    const storageState = buildStorageStateArtifact(appConfig, persona, roles, entitlements);
+    const headers = buildHeaderArtifact(appConfig, persona);
+    const context = buildPersonaContext(appConfig, persona, roles, entitlements, paths);
+
+    writeJson(context.artifacts.storage_state_path, storageState);
+    writeJson(context.artifacts.headers_path, headers);
+    writeJson(context.artifacts.context_path, context);
+
+    generated.push({
+      persona: code,
+      storage_state_path: context.artifacts.storage_state_path,
+      headers_path: context.artifacts.headers_path,
+      context_path: context.artifacts.context_path,
+      route_hint: context.route_hint,
+    });
+  }
+
+  writeJson(paths.lock, {
+    schema_version: FIXTURE_SCHEMA_VERSION,
+    applied_at: new Date().toISOString(),
+    personas: generated.map((entry) => entry.persona),
+    base_url: appConfig.browser.base_url,
+    api_url: appConfig.server.api_url,
+    local_mode_active: appConfig.server.local_mode_active,
+  });
+
+  return generated;
+}
+
+function writeDevAuthBridge({ rootDir, paths, appConfig, users, roles, entitlements }) {
+  const bridgeConfig = buildBridgeConfig(appConfig, users, roles, entitlements);
+  fs.mkdirSync(paths.publicDir, { recursive: true });
+  fs.writeFileSync(paths.bridgeScript, buildDevAuthBridgeScript(bridgeConfig));
+
+  return {
+    script_path: paths.bridgeScript,
+    public_dir: paths.publicDir,
+    script_name: appConfig.bridge?.script_name || DEFAULT_BRIDGE_SCRIPT_NAME,
+    public_url: `/${appConfig.bridge?.script_name || DEFAULT_BRIDGE_SCRIPT_NAME}`,
+  };
+}
+
+async function applyFixtures({
+  dir = null,
+  port = DEFAULT_PORT,
+  baseUrl = null,
+  version = '0.0.0',
+  persona = null,
+} = {}) {
+  const rootDir = resolveRepoRoot(dir);
+  const paths = resolveFixturePaths(rootDir);
+  let bootstrapped = false;
+
+  if (!fs.existsSync(paths.fixtureDir)) {
+    await initFixtureKernel({ dir: rootDir, port, baseUrl, version, force: false });
+    bootstrapped = true;
+  }
+
+  const kernel = loadFixtureKernel(rootDir);
+  const runtime = await getServerRuntime({ port });
+  const starterContract = readExistingStarterContract(paths);
+  const appConfig = buildAppConfig({
+    version,
+    port,
+    baseUrl: baseUrl || kernel.app.browser?.base_url,
+    runtime,
+    starterContract,
+  });
+
+  writeJson(paths.app, appConfig);
+  writeManagedFile(paths.browserGitignore, '*.json\n!.gitignore\n', {
+    rootDir,
+    files_created: [],
+    files_overwritten: [],
+    files_skipped: [],
+  });
+
+  const generated = writePersonaArtifacts({
+    rootDir,
+    paths,
+    appConfig,
+    users: kernel.users,
+    roles: kernel.roles,
+    entitlements: kernel.entitlements,
+    personaCode: persona,
+  });
+  const bridge = writeDevAuthBridge({
+    rootDir,
+    paths,
+    appConfig,
+    users: kernel.users,
+    roles: kernel.roles,
+    entitlements: kernel.entitlements,
+  });
+
+  return {
+    success: true,
+    command: 'fixtures',
+    subcommand: persona ? 'storage-state' : 'apply',
+    root_dir: rootDir,
+    fixture_dir: paths.fixtureDir,
+    bootstrapped,
+    runtime,
+    generated: {
+      personas: generated,
+      bridge,
+    },
+    next_steps: persona
+      ? [
+          `Use ${generated[0].storage_state_path} as Playwright storageState`,
+          `Use ${generated[0].headers_path} for extraHTTPHeaders when needed`,
+          `Include ${bridge.public_url} before your app boots when you want frontend-only persona switching`,
+        ]
+      : [
+          'Wire the generated storage-state and headers files into Playwright or your local harness',
+          `Include ${bridge.public_url} before your app boots to get frontend-only auth/RBAC fixtures`,
+          'Re-run npx spaps fixtures apply after editing .spaps/*.json',
+        ],
+  };
+}
+
+async function exportStorageState(options = {}) {
+  const result = await applyFixtures(options);
+  const personaArtifact = result.generated.personas[0];
+  return {
+    success: true,
+    command: 'fixtures',
+    subcommand: 'storage-state',
+    root_dir: result.root_dir,
+    fixture_dir: result.fixture_dir,
+    persona: personaArtifact.persona,
+    storage_state_path: personaArtifact.storage_state_path,
+    headers_path: personaArtifact.headers_path,
+    context_path: personaArtifact.context_path,
+    route_hint: personaArtifact.route_hint,
+    bridge: result.generated.bridge,
+    runtime: result.runtime,
+    next_steps: result.next_steps,
+  };
+}
+
+async function resetFixtures({
+  dir = null,
+  port = DEFAULT_PORT,
+  baseUrl = null,
+  version = '0.0.0',
+} = {}) {
+  const rootDir = resolveRepoRoot(dir);
+  const paths = resolveFixturePaths(rootDir);
+  const removed = cleanupGeneratedBrowserArtifacts(paths);
+  const initResult = await initFixtureKernel({
+    dir: rootDir,
+    port,
+    baseUrl,
+    version,
+    force: true,
+  });
+  const applyResult = await applyFixtures({
+    dir: rootDir,
+    port,
+    baseUrl,
+    version,
+  });
+
+  return {
+    success: true,
+    command: 'fixtures',
+    subcommand: 'reset',
+    root_dir: rootDir,
+    fixture_dir: paths.fixtureDir,
+    removed,
+    files_created: initResult.files_created,
+    files_overwritten: initResult.files_overwritten,
+    generated: applyResult.generated,
+    runtime: applyResult.runtime,
+    next_steps: applyResult.next_steps,
+  };
+}
+
+module.exports = {
+  DEFAULT_BROWSER_BASE_URL,
+  FIXTURE_DIRNAME,
+  FIXTURE_KEYS,
+  FIXTURE_SCHEMA_VERSION,
+  applyFixtures,
+  exportStorageState,
+  initFixtureKernel,
+  resetFixtures,
+};