settld 0.2.4 → 0.2.5

package/scripts/setup/onboard.mjs

@@ -13,8 +13,10 @@ import { bootstrapWalletProvider } from "../../src/core/wallet-provider-bootstra
 import { extractBootstrapMcpEnv, loadHostConfigHelper, runWizard } from "./wizard.mjs";
 import { SUPPORTED_HOSTS } from "./host-config.mjs";
 import { defaultSessionPath, readSavedSession } from "./session-store.mjs";
-import { runLogin } from "./login.mjs";
+import { detectDeploymentAuthMode, runLogin } from "./login.mjs";
 import { runWalletCli } from "../wallet/cli.mjs";
+import { classifyOnboardingFailure } from "./onboarding-failure-taxonomy.mjs";
+import { ONBOARDING_EVENTS, ONBOARDING_STATES, transitionOnboardingState } from "./onboarding-state-machine.mjs";
 
 const WALLET_MODES = new Set(["managed", "byo", "none"]);
 const WALLET_PROVIDERS = new Set(["circle"]);
@@ -42,6 +44,7 @@ const REPO_ROOT = path.resolve(SCRIPT_DIR, "..", "..");
 const SETTLD_BIN = path.join(REPO_ROOT, "bin", "settld.js");
 const PROFILE_FINGERPRINT_REGEX = /^[0-9a-f]{64}$/;
 const DEFAULT_PUBLIC_BASE_URL = "https://api.settld.work";
+const MAX_INTERACTIVE_API_KEY_MODE_ATTEMPTS = 8;
 const ANSI_RESET = "\u001b[0m";
 const ANSI_BOLD = "\u001b[1m";
 const ANSI_DIM = "\u001b[2m";
@@ -1136,6 +1139,8 @@ async function requestRemoteWalletBootstrap({
   baseUrl,
   tenantId,
   settldApiKey,
+  bootstrapApiKey,
+  sessionCookie,
   walletProvider,
   circleMode,
   circleBaseUrl,
@@ -1157,30 +1162,69 @@ async function requestRemoteWalletBootstrap({
   }
 
   const url = new URL(`/v1/tenants/${encodeURIComponent(String(tenantId ?? ""))}/onboarding/wallet-bootstrap`, normalizedBaseUrl);
-  const res = await fetchImpl(url.toString(), {
-    method: "POST",
-    headers: {
-      "content-type": "application/json",
-      "x-api-key": String(settldApiKey ?? "")
-    },
-    body: JSON.stringify(body)
-  });
+  const candidates = [];
+  const runtimeKey = String(settldApiKey ?? "").trim();
+  const bootstrapKey = String(bootstrapApiKey ?? "").trim();
+  const cookie = String(sessionCookie ?? "").trim();
+  if (runtimeKey) candidates.push({ kind: "runtime_key", apiKey: runtimeKey });
+  if (bootstrapKey && bootstrapKey !== runtimeKey) candidates.push({ kind: "bootstrap_key", apiKey: bootstrapKey });
+  if (cookie) candidates.push({ kind: "session_cookie", cookie });
+  if (!candidates.length) {
+    throw new Error("remote wallet bootstrap requires SETTLD_API_KEY, bootstrap API key, or saved login session");
+  }
 
-  const text = await res.text();
+  let lastError = null;
+  let succeeded = false;
   let json = null;
-  try {
-    json = text ? JSON.parse(text) : null;
-  } catch {
+  for (const candidate of candidates) {
+    const headers = {
+      "content-type": "application/json"
+    };
+    if (candidate.apiKey) headers["x-api-key"] = candidate.apiKey;
+    if (candidate.cookie) headers.cookie = candidate.cookie;
+
+    const res = await fetchImpl(url.toString(), {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body)
+    });
+
+    const text = await res.text();
     json = null;
-  }
-  if (!res.ok) {
+    try {
+      json = text ? JSON.parse(text) : null;
+    } catch {
+      json = null;
+    }
+    if (res.ok) {
+      succeeded = true;
+      break;
+    }
     const message =
       json && typeof json === "object"
         ? json?.message ?? json?.error ?? `HTTP ${res.status}`
         : text || `HTTP ${res.status}`;
-    throw new Error(`remote wallet bootstrap failed (${res.status}): ${String(message)}`);
+    lastError = { status: res.status, message: String(message), kind: candidate.kind };
+    if (res.status !== 403) {
+      throw new Error(`remote wallet bootstrap failed (${res.status}): ${String(message)}`);
+    }
   }
-  const bootstrap = json?.walletBootstrap;
+  if (!succeeded) {
+    const detail = lastError ? ` (${lastError.kind})` : "";
+    if (lastError && lastError.status === 403) {
+      throw new Error(
+        `remote wallet bootstrap failed (403): forbidden${detail}. Try --wallet-mode none (finish trust wiring) or --wallet-bootstrap local with --circle-api-key.`
+      );
+    }
+    if (lastError) {
+      throw new Error(`remote wallet bootstrap failed (${lastError.status}): ${lastError.message}${detail}`);
+    }
+    throw new Error("remote wallet bootstrap failed: unknown error");
+  }
+  if (!json || typeof json !== "object" || Array.isArray(json)) {
+    throw new Error("remote wallet bootstrap response missing payload");
+  }
+  const bootstrap = json.walletBootstrap;
   if (!bootstrap || typeof bootstrap !== "object" || Array.isArray(bootstrap)) {
     throw new Error("remote wallet bootstrap response missing walletBootstrap object");
   }
@@ -1196,6 +1240,7 @@ async function resolveRuntimeConfig({
   stdin = process.stdin,
   stdout = process.stdout,
   detectInstalledHostsImpl = detectInstalledHosts,
+  detectDeploymentAuthModeImpl = detectDeploymentAuthMode,
   fetchImpl = fetch,
   runLoginImpl = runLogin,
   readSavedSessionImpl = readSavedSession
@@ -1234,6 +1279,7 @@ async function resolveRuntimeConfig({
     preflight: Boolean(args.preflight),
     smoke: Boolean(args.smoke),
     dryRun: Boolean(args.dryRun),
+    authMode: "unknown",
     installedHosts
   };
   if (savedSession) {
@@ -1327,21 +1373,48 @@ async function resolveRuntimeConfig({
     );
 
     if (!out.baseUrl) out.baseUrl = DEFAULT_PUBLIC_BASE_URL;
+    if (out.baseUrl) {
+      try {
+        const authDiscovery = await detectDeploymentAuthModeImpl({ baseUrl: out.baseUrl, fetchImpl });
+        out.authMode = String(authDiscovery?.mode ?? "unknown");
+        if (out.authMode !== "unknown") {
+          stdout.write(`Detected auth mode: ${out.authMode}\n`);
+        }
+      } catch {
+        out.authMode = "unknown";
+      }
+    }
+    if (out.authMode === "enterprise_preprovisioned" && !out.tenantId && !savedSession?.tenantId) {
+      out.tenantId = await promptLine(rl, "Tenant ID (required for this deployment mode)", { required: true });
+    }
     if (!out.settldApiKey) {
+      let loginUnavailableForRun = false;
+      let preferredKeyMode = null;
+      let keyModeAttempts = 0;
       while (!out.settldApiKey) {
+        keyModeAttempts += 1;
+        if (keyModeAttempts > MAX_INTERACTIVE_API_KEY_MODE_ATTEMPTS) {
+          const error = new Error(
+            `setup API key flow exceeded ${MAX_INTERACTIVE_API_KEY_MODE_ATTEMPTS} attempts; choose \`Generate during setup\` or \`Paste existing key\``
+          );
+          error.code = "ONBOARDING_KEY_MODE_LOOP_GUARD";
+          throw error;
+        }
         const canUseSavedSession =
           Boolean(out.sessionCookie) &&
           (!savedSession ||
             (normalizeHttpUrl(out.baseUrl) === normalizeHttpUrl(savedSession?.baseUrl) &&
               (!out.tenantId || String(out.tenantId ?? "").trim() === String(savedSession?.tenantId ?? "").trim())));
         const keyOptions = [];
+        const loginAllowedForMode =
+          out.authMode !== "enterprise_preprovisioned" || Boolean(String(out.tenantId ?? "").trim());
         if (canUseSavedSession) {
           keyOptions.push({
             value: "session",
             label: "Use saved login session",
             hint: `Reuse ${out.sessionFile} to mint runtime key`
           });
-        } else {
+        } else if (!loginUnavailableForRun && loginAllowedForMode) {
           keyOptions.push({
             value: "login",
             label: "Login / create tenant (recommended)",
@@ -1352,18 +1425,35 @@ async function resolveRuntimeConfig({
           { value: "bootstrap", label: "Generate during setup", hint: "Use onboarding bootstrap API key" },
           { value: "manual", label: "Paste existing key", hint: "Use an existing tenant API key" }
         );
+        const defaultKeyMode =
+          preferredKeyMode && keyOptions.some((option) => option.value === preferredKeyMode)
+            ? preferredKeyMode
+            : canUseSavedSession
+              ? "session"
+              : loginUnavailableForRun
+                ? "bootstrap"
+                : loginAllowedForMode
+                  ? "login"
+                  : "bootstrap";
         const keyMode = await promptSelect(
           rl,
           stdin,
           stdout,
           "How should setup get your Settld API key?",
           keyOptions,
-          { defaultValue: canUseSavedSession ? "session" : "login", color }
+          { defaultValue: defaultKeyMode, color }
         );
         if (keyMode === "login") {
+          if (!loginAllowedForMode) {
+            throw new Error(
+              "login flow requires --tenant-id in enterprise_preprovisioned mode. Provide tenant ID or choose bootstrap/manual API key mode."
+            );
+          }
           try {
+            const loginArgv = ["--base-url", out.baseUrl, "--session-file", out.sessionFile];
+            if (out.tenantId) loginArgv.push("--tenant-id", out.tenantId);
             await runLoginImpl({
-              argv: ["--base-url", out.baseUrl, "--session-file", out.sessionFile],
+              argv: loginArgv,
               stdin,
               stdout,
               fetchImpl
@@ -1378,13 +1468,21 @@ async function resolveRuntimeConfig({
               savedSession.tenantId = refreshedSession.tenantId;
               savedSession.cookie = refreshedSession.cookie;
             }
+            preferredKeyMode = "session";
           } catch (err) {
-            stdout.write(`Login failed: ${err?.message ?? "unknown error"}\n`);
-            stdout.write("Choose `Generate during setup` if your deployment does not expose public signup/login.\n");
+            const failure = classifyOnboardingFailure(err);
+            stdout.write(`[${failure.code}] ${failure.message}\n`);
+            if (failure.remediation) stdout.write(`Remediation: ${failure.remediation}\n`);
+            if (failure.code === "ONBOARDING_AUTH_PUBLIC_SIGNUP_UNAVAILABLE" || failure.code === "ONBOARDING_AUTH_LOGIN_UNAVAILABLE") {
+              loginUnavailableForRun = true;
+              stdout.write("Login/signup has been disabled for this setup run. Continuing with API key modes.\n");
+            }
+            preferredKeyMode = "bootstrap";
           }
           continue;
         }
         if (keyMode === "bootstrap") {
+          preferredKeyMode = "bootstrap";
           if (!out.bootstrapApiKey) {
             out.bootstrapApiKey = await promptSecretLine(rl, mutableOutput, stdout, "Onboarding bootstrap API key");
           }
@@ -1397,6 +1495,7 @@ async function resolveRuntimeConfig({
           break;
         }
         if (keyMode === "manual") {
+          preferredKeyMode = "manual";
           out.settldApiKey = await promptSecretLine(rl, mutableOutput, stdout, "Settld API key");
           break;
         }
@@ -1530,6 +1629,7 @@ export async function runOnboard({
   requestRemoteWalletBootstrapImpl = requestRemoteWalletBootstrap,
   runPreflightChecksImpl = runPreflightChecks,
   detectInstalledHostsImpl = detectInstalledHosts,
+  detectDeploymentAuthModeImpl = detectDeploymentAuthMode,
   runLoginImpl = runLogin,
   readSavedSessionImpl = readSavedSession,
   runWalletCliImpl = runWalletCli
@@ -1543,6 +1643,11 @@ export async function runOnboard({
   const showSteps = args.format !== "json";
   const totalSteps = args.preflightOnly ? 4 : 6;
   let step = 1;
+  let onboardingState = ONBOARDING_STATES.INIT;
+  const advanceOnboardingState = (event) => {
+    onboardingState = transitionOnboardingState({ state: onboardingState, event });
+    return onboardingState;
+  };
 
   if (showSteps) printStep(stdout, step, totalSteps, "Resolve setup configuration");
   const config = await resolveRuntimeConfig({
@@ -1551,10 +1656,12 @@ export async function runOnboard({
     stdin,
     stdout,
     detectInstalledHostsImpl,
+    detectDeploymentAuthModeImpl,
     fetchImpl,
     runLoginImpl,
     readSavedSessionImpl
   });
+  advanceOnboardingState(ONBOARDING_EVENTS.RESOLVE_CONFIG_OK);
   step += 1;
   const normalizedBaseUrl = normalizeHttpUrl(mustString(config.baseUrl, "SETTLD_BASE_URL / --base-url"));
   if (!normalizedBaseUrl) throw new Error(`invalid Settld base URL: ${config.baseUrl}`);
@@ -1574,6 +1681,7 @@ export async function runOnboard({
     });
     settldApiKey = mustString(runtimeBootstrapEnv?.SETTLD_API_KEY ?? "", "runtime bootstrap SETTLD_API_KEY");
   }
+  advanceOnboardingState(ONBOARDING_EVENTS.RUNTIME_KEY_OK);
   const runtimeBootstrapOptionalEnv = {};
   if (runtimeBootstrapEnv?.SETTLD_PAID_TOOLS_BASE_URL) {
     runtimeBootstrapOptionalEnv.SETTLD_PAID_TOOLS_BASE_URL = String(runtimeBootstrapEnv.SETTLD_PAID_TOOLS_BASE_URL);
@@ -1607,6 +1715,8 @@ export async function runOnboard({
         baseUrl: normalizedBaseUrl,
         tenantId,
         settldApiKey,
+        bootstrapApiKey: config.bootstrapApiKey,
+        sessionCookie: config.sessionCookie,
         walletProvider: config.walletProvider,
         circleMode: config.circleMode,
         circleBaseUrl: config.circleBaseUrl || null,
@@ -1623,6 +1733,7 @@ export async function runOnboard({
       runtimeEnv
     });
   }
+  advanceOnboardingState(ONBOARDING_EVENTS.WALLET_OK);
   step += 1;
 
   let preflight = { ok: false, skipped: true, checks: [] };
@@ -1643,9 +1754,11 @@ export async function runOnboard({
   } else {
     if (showSteps) printStep(stdout, step, totalSteps, "Skip preflight checks");
   }
+  advanceOnboardingState(ONBOARDING_EVENTS.PREFLIGHT_OK);
   step += 1;
 
   if (args.preflightOnly) {
+    advanceOnboardingState(ONBOARDING_EVENTS.COMPLETE);
     if (showSteps) printStep(stdout, step, totalSteps, "Finalize preflight-only output");
     const payload = {
       ok: true,
@@ -1658,14 +1771,19 @@ export async function runOnboard({
         details: wallet && typeof wallet === "object" ? wallet : null
       },
       settld: {
-        baseUrl: normalizedBaseUrl,
-        tenantId,
-        preflight: Boolean(config.preflight),
-        smoke: false,
-        profileApplied: false,
+      baseUrl: normalizedBaseUrl,
+      tenantId,
+      authMode: config.authMode ?? "unknown",
+      preflight: Boolean(config.preflight),
+      smoke: false,
+      profileApplied: false,
         profileId: null
       },
       preflight,
+      onboarding: {
+        schemaVersion: "SettldOnboardingState.v1",
+        state: onboardingState
+      },
       hostInstallDetected: Array.isArray(config.installedHosts) && config.installedHosts.includes(config.host),
       installedHosts: config.installedHosts,
       env: {
@@ -1738,6 +1856,7 @@ export async function runOnboard({
       ...walletEnv
     }
   });
+  advanceOnboardingState(ONBOARDING_EVENTS.HOST_CONFIG_OK);
   step += 1;
 
   const mergedEnv = {
@@ -1765,9 +1884,11 @@ export async function runOnboard({
     stdout,
     runWalletCliImpl
   });
+  advanceOnboardingState(ONBOARDING_EVENTS.GUIDED_OK);
   step += 1;
 
   if (showSteps) printStep(stdout, step, totalSteps, "Finalize output");
+  advanceOnboardingState(ONBOARDING_EVENTS.COMPLETE);
   const payload = {
     ok: true,
     setupMode: config.setupMode,
@@ -1782,12 +1903,17 @@ export async function runOnboard({
     settld: {
       baseUrl: normalizedBaseUrl,
       tenantId,
+      authMode: config.authMode ?? "unknown",
       preflight: Boolean(config.preflight),
       smoke: Boolean(config.smoke),
       profileApplied: !config.skipProfileApply,
       profileId: config.skipProfileApply ? null : (config.profileId || "engineering-spend")
     },
     preflight,
+    onboarding: {
+      schemaVersion: "SettldOnboardingState.v1",
+      state: onboardingState
+    },
     hostInstallDetected: Array.isArray(config.installedHosts) && config.installedHosts.includes(config.host),
     installedHosts: config.installedHosts,
     env: mergedEnv,
@@ -1803,6 +1929,7 @@ export async function runOnboard({
     lines.push("Settld onboard complete.");
     lines.push(`Host: ${config.host}`);
     lines.push(`Settld: ${normalizedBaseUrl} (tenant=${tenantId})`);
+    lines.push(`Auth mode: ${config.authMode ?? "unknown"}`);
     lines.push(`Setup mode: ${config.setupMode}`);
     lines.push(`Preflight: ${config.preflight ? "passed" : "skipped"}`);
     lines.push(`Wallet mode: ${config.walletMode}`);
@@ -1852,7 +1979,11 @@ async function main(argv = process.argv.slice(2)) {
   try {
     await runOnboard({ argv });
   } catch (err) {
-    process.stderr.write(`${err?.message ?? String(err)}\n`);
+    const failure = classifyOnboardingFailure(err);
+    process.stderr.write(`[${failure.code}] ${failure.message}\n`);
+    if (failure.remediation) {
+      process.stderr.write(`Remediation: ${failure.remediation}\n`);
+    }
     process.exit(1);
   }
 }

package/scripts/setup/onboarding-failure-taxonomy.mjs

@@ -0,0 +1,96 @@
+const FAILURE_CLASSES = Object.freeze([
+  {
+    code: "ONBOARDING_AUTH_PUBLIC_SIGNUP_UNAVAILABLE",
+    phase: "auth",
+    patterns: [/Public signup is unavailable/i, /Public signup is disabled/i],
+    remediation:
+      "Use `Generate during setup` with an onboarding bootstrap API key, or rerun with `--tenant-id <existing_tenant>`."
+  },
+  {
+    code: "ONBOARDING_AUTH_LOGIN_UNAVAILABLE",
+    phase: "auth",
+    patterns: [/OTP login is unavailable on this base URL/i, /otp request failed \(403\)/i, /login failed \(403\): forbidden/i],
+    remediation:
+      "This base URL does not expose public OTP login. Use `Generate during setup` with an onboarding bootstrap API key, or use `Paste existing key`."
+  },
+  {
+    code: "ONBOARDING_AUTH_OTP_INVALID",
+    phase: "auth",
+    patterns: [/OTP_(INVALID|EXPIRED|CONSUMED|MISSING)/i, /otp code is required/i, /invalid otp/i],
+    remediation: "Request a fresh OTP and retry `settld login`."
+  },
+  {
+    code: "ONBOARDING_BOOTSTRAP_FORBIDDEN",
+    phase: "bootstrap",
+    patterns: [/runtime bootstrap request failed \(403\)/i],
+    remediation: "Check onboarding bootstrap API key scopes and tenant binding, then rerun setup."
+  },
+  {
+    code: "ONBOARDING_BOOTSTRAP_UNAUTHORIZED",
+    phase: "bootstrap",
+    patterns: [/runtime bootstrap request failed \(401\)/i, /unauthorized/i],
+    remediation: "Verify API key validity and retry with a fresh key/session."
+  },
+  {
+    code: "ONBOARDING_WALLET_BOOTSTRAP_FAILED",
+    phase: "wallet",
+    patterns: [/remote wallet bootstrap failed/i, /wallet bootstrap/i],
+    remediation: "Switch wallet mode to `none` to finish trust wiring, then run `settld wallet status` and retry funding."
+  },
+  {
+    code: "ONBOARDING_BYO_ENV_MISSING",
+    phase: "wallet",
+    patterns: [/BYO wallet mode missing required env keys/i],
+    remediation: "Provide the missing `--wallet-env KEY=VALUE` entries or export required Circle env vars."
+  },
+  {
+    code: "ONBOARDING_HOST_WRITE_FAILED",
+    phase: "host",
+    patterns: [/host config/i, /path not writable/i],
+    remediation: "Use `--dry-run` to inspect target path, then rerun with a writable host config location."
+  },
+  {
+    code: "ONBOARDING_PREFLIGHT_FAILED",
+    phase: "preflight",
+    patterns: [/preflight failed/i],
+    remediation: "Run with `--preflight` and fix the reported failing check before rerunning setup."
+  }
+]);
+
+export function classifyOnboardingFailure(error) {
+  const message = String(error?.message ?? error ?? "").trim();
+  if (!message) {
+    return {
+      code: "ONBOARDING_UNKNOWN_FAILURE",
+      phase: "unknown",
+      message: "unknown onboarding failure",
+      remediation: "Retry setup with `--format json` and inspect the report output."
+    };
+  }
+
+  for (const failureClass of FAILURE_CLASSES) {
+    if (failureClass.patterns.some((pattern) => pattern.test(message))) {
+      return {
+        code: failureClass.code,
+        phase: failureClass.phase,
+        message,
+        remediation: failureClass.remediation
+      };
+    }
+  }
+
+  return {
+    code: "ONBOARDING_UNKNOWN_FAILURE",
+    phase: "unknown",
+    message,
+    remediation: "Retry setup with `--format json` and inspect the report output."
+  };
+}
+
+export function listOnboardingFailureClasses() {
+  return FAILURE_CLASSES.map((item) => ({
+    code: item.code,
+    phase: item.phase,
+    remediation: item.remediation
+  }));
+}

package/scripts/setup/onboarding-state-machine.mjs

@@ -0,0 +1,102 @@
+export const ONBOARDING_STATES = Object.freeze({
+  INIT: "init",
+  CONFIG_RESOLVED: "config_resolved",
+  RUNTIME_KEY_READY: "runtime_key_ready",
+  WALLET_RESOLVED: "wallet_resolved",
+  PREFLIGHT_DONE: "preflight_done",
+  HOST_CONFIGURED: "host_configured",
+  GUIDED_NEXT_DONE: "guided_next_done",
+  COMPLETED: "completed",
+  FAILED: "failed"
+});
+
+export const ONBOARDING_EVENTS = Object.freeze({
+  RESOLVE_CONFIG_OK: "resolve_config_ok",
+  RESOLVE_CONFIG_FAILED: "resolve_config_failed",
+  RUNTIME_KEY_OK: "runtime_key_ok",
+  RUNTIME_KEY_FAILED: "runtime_key_failed",
+  WALLET_OK: "wallet_ok",
+  WALLET_FAILED: "wallet_failed",
+  PREFLIGHT_OK: "preflight_ok",
+  PREFLIGHT_FAILED: "preflight_failed",
+  HOST_CONFIG_OK: "host_config_ok",
+  HOST_CONFIG_FAILED: "host_config_failed",
+  GUIDED_OK: "guided_ok",
+  GUIDED_FAILED: "guided_failed",
+  COMPLETE: "complete",
+  FATAL: "fatal"
+});
+
+const TRANSITIONS = Object.freeze({
+  [ONBOARDING_STATES.INIT]: Object.freeze({
+    [ONBOARDING_EVENTS.RESOLVE_CONFIG_OK]: ONBOARDING_STATES.CONFIG_RESOLVED,
+    [ONBOARDING_EVENTS.RESOLVE_CONFIG_FAILED]: ONBOARDING_STATES.FAILED
+  }),
+  [ONBOARDING_STATES.CONFIG_RESOLVED]: Object.freeze({
+    [ONBOARDING_EVENTS.RUNTIME_KEY_OK]: ONBOARDING_STATES.RUNTIME_KEY_READY,
+    [ONBOARDING_EVENTS.RUNTIME_KEY_FAILED]: ONBOARDING_STATES.FAILED
+  }),
+  [ONBOARDING_STATES.RUNTIME_KEY_READY]: Object.freeze({
+    [ONBOARDING_EVENTS.WALLET_OK]: ONBOARDING_STATES.WALLET_RESOLVED,
+    [ONBOARDING_EVENTS.WALLET_FAILED]: ONBOARDING_STATES.FAILED
+  }),
+  [ONBOARDING_STATES.WALLET_RESOLVED]: Object.freeze({
+    [ONBOARDING_EVENTS.PREFLIGHT_OK]: ONBOARDING_STATES.PREFLIGHT_DONE,
+    [ONBOARDING_EVENTS.PREFLIGHT_FAILED]: ONBOARDING_STATES.FAILED
+  }),
+  [ONBOARDING_STATES.PREFLIGHT_DONE]: Object.freeze({
+    [ONBOARDING_EVENTS.COMPLETE]: ONBOARDING_STATES.COMPLETED,
+    [ONBOARDING_EVENTS.HOST_CONFIG_OK]: ONBOARDING_STATES.HOST_CONFIGURED,
+    [ONBOARDING_EVENTS.HOST_CONFIG_FAILED]: ONBOARDING_STATES.FAILED
+  }),
+  [ONBOARDING_STATES.HOST_CONFIGURED]: Object.freeze({
+    [ONBOARDING_EVENTS.GUIDED_OK]: ONBOARDING_STATES.GUIDED_NEXT_DONE,
+    [ONBOARDING_EVENTS.GUIDED_FAILED]: ONBOARDING_STATES.FAILED
+  }),
+  [ONBOARDING_STATES.GUIDED_NEXT_DONE]: Object.freeze({
+    [ONBOARDING_EVENTS.COMPLETE]: ONBOARDING_STATES.COMPLETED,
+    [ONBOARDING_EVENTS.FATAL]: ONBOARDING_STATES.FAILED
+  }),
+  [ONBOARDING_STATES.COMPLETED]: Object.freeze({}),
+  [ONBOARDING_STATES.FAILED]: Object.freeze({})
+});
+
+function knownStatesList() {
+  return Object.values(ONBOARDING_STATES).join(", ");
+}
+
+function knownEventsList() {
+  return Object.values(ONBOARDING_EVENTS).join(", ");
+}
+
+export function transitionOnboardingState({ state, event }) {
+  const current = String(state ?? "").trim();
+  const nextEvent = String(event ?? "").trim();
+  const stateTransitions = TRANSITIONS[current];
+  if (!stateTransitions) {
+    const err = new Error(`unknown onboarding state: ${current}. expected one of: ${knownStatesList()}`);
+    err.code = "ONBOARDING_UNKNOWN_STATE";
+    throw err;
+  }
+  if (!nextEvent || !Object.prototype.hasOwnProperty.call(stateTransitions, nextEvent)) {
+    const err = new Error(
+      `invalid onboarding transition: state=${current} event=${nextEvent || "<empty>"}. allowed events: ${Object.keys(stateTransitions).join(", ") || "<none>"}`
+    );
+    err.code = "ONBOARDING_INVALID_TRANSITION";
+    throw err;
+  }
+  return stateTransitions[nextEvent];
+}
+
+export function assertOnboardingTransitionSequence(events = []) {
+  if (!Array.isArray(events)) {
+    const err = new Error(`onboarding events must be an array. expected event names: ${knownEventsList()}`);
+    err.code = "ONBOARDING_INVALID_SEQUENCE";
+    throw err;
+  }
+  let state = ONBOARDING_STATES.INIT;
+  for (const event of events) {
+    state = transitionOnboardingState({ state, event });
+  }
+  return state;
+}