settld 0.2.3 → 0.2.5

package/docs/CONFIG.md

@@ -82,6 +82,18 @@ Delivery/worker tuning:
 - `PROXY_AUTH_KEY_TOUCH_MIN_SECONDS` (default: `60`)  
   Throttle how often `last_used_at` is updated for API keys (reduces DB write amplification).
 
+## Public onboarding routing
+
+- `PROXY_ONBOARDING_BASE_URL` (optional but required for public onboarding on `settld-api`)  
+  Absolute `http(s)` URL for the onboarding service (`services/magic-link`). When set, `settld-api` reverse-proxies public onboarding routes:
+  - `/v1/public/auth-mode`
+  - `/v1/public/signup`
+  - `/v1/tenants/:tenantId/buyer/login/otp`
+  - `/v1/tenants/:tenantId/buyer/login`
+  - `/v1/tenants/:tenantId/onboarding/*`
+
+  If missing, these routes fail closed with `503` and code `ONBOARDING_PROXY_NOT_CONFIGURED`.
+
 ## Ingest auth
 
 - `PROXY_INGEST_TOKEN` (optional)  

package/docs/README.md

@@ -32,3 +32,6 @@ Reference docs:
 
 - `docs/QUICKSTART_MCP_HOSTS.md`
 - `docs/QUICKSTART_MCP.md`
+- `planning/trust-os-v1/state-of-the-art-launch-readiness-scorecard.md`
+- `planning/sprints/state-of-the-art-v1-6-week-plan.md`
+- `planning/jira/state-of-the-art-v1-backlog.json`

package/docs/ops/HOSTED_BASELINE_R2.md

@@ -13,14 +13,16 @@ This is the minimum hosted setup for a real product surface.
 
 ## 2) Railway service split
 
-Create two Railway services from this repo per environment:
+Create three Railway services from this repo per environment:
 
 - `settld-api`:
   - start command: `npm run start:prod`
+- `settld-magic-link`:
+  - start command: `npm run start:magic-link`
 - `settld-worker`:
   - start command: `npm run start:maintenance`
 
-Both services must point at the same environment DB and secret set for that environment.
+All services must point at the same environment DB and secret set for that environment.
 
 ## 3) Required runtime controls
 

package/docs/ops/MINIMUM_PRODUCTION_TOPOLOGY.md

@@ -7,12 +7,13 @@ This is the smallest topology that supports real paid agent tool calls with audi
 | Component | Purpose | Start command |
 |---|---|---|
 | `settld-api` | control plane + kernel APIs + receipts + ops endpoints | `npm run start:prod` |
+| `settld-magic-link` | public onboarding/auth/wallet bootstrap service | `npm run start:magic-link` |
 | `settld-maintenance` | reconciliation/cleanup/maintenance ticks | `npm run start:maintenance` |
 | `postgres` | system of record for tenants, gates, receipts, ops state | managed Postgres |
 | `x402-gateway` | payment challenge/authorize/verify wrapper for paid tool calls | `npm run start:x402-gateway` |
 | paid upstream tool API(s) | actual provider tools (`/exa`, `/weather`, etc.) | provider-specific |
 
-Without all five, the end-to-end paid tool path is incomplete.
+Without all six, public onboarding + paid tool path is incomplete.
 
 ## 2) Recommended production shape
 
@@ -35,9 +36,19 @@ Reference baseline: `docs/ops/HOSTED_BASELINE_R2.md`.
 - `PROXY_OPS_TOKENS` (scoped ops tokens)
 - `PROXY_FINANCE_RECONCILE_ENABLED=1`
 - `PROXY_MONEY_RAIL_RECONCILE_ENABLED=1`
+- `PROXY_ONBOARDING_BASE_URL=https://<magic-link-host>`
 
 Primary config source: `docs/CONFIG.md`.
 
+### `settld-magic-link`
+
+- `NODE_ENV=production`
+- `MAGIC_LINK_API_KEY` (admin key)
+- `MAGIC_LINK_PUBLIC_SIGNUP_ENABLED=1` (for self-serve public onboarding)
+- `MAGIC_LINK_BUYER_OTP_DELIVERY_MODE=smtp` + SMTP env
+- `MAGIC_LINK_SETTLD_API_BASE_URL=https://<settld-api-host>`
+- `MAGIC_LINK_SETTLD_OPS_TOKEN=<scoped ops token>`
+
 ### `settld-maintenance`
 
 - Same DB/env set as `settld-api`
@@ -67,22 +78,23 @@ Reference flow: `docs/QUICKSTART_X402_GATEWAY.md`.
 Must host for real customer traffic:
 
 1. `settld-api`
-2. `settld-maintenance`
-3. Postgres
-4. `x402-gateway`
-5. At least one paid upstream provider API
+2. `settld-magic-link`
+3. `settld-maintenance`
+4. Postgres
+5. `x402-gateway`
+6. At least one paid upstream provider API
 
 Optional at first:
 
 1. Receiver service (`npm run start:receiver`)
 2. Finance sink (`npm run start:finance-sink`)
-3. Magic-link UI service
+3. Additional onboarding UI shells
 
 ## 6) Definition of "usable in production"
 
 A deployment is considered usable when all are true:
 
-1. `GET /healthz` is green on API and gateway.
+1. `GET /healthz` is green on API and gateway; `GET /v1/public/auth-mode` is reachable on API host.
 2. Hosted baseline evidence command passes for the environment.
 3. One paid MCP tool call succeeds end-to-end with artifact output.
 4. Receipt verification succeeds and is replay-auditable.

package/docs/ops/PRODUCTION_DEPLOYMENT_CHECKLIST.md

@@ -14,7 +14,7 @@ Use this checklist to launch and verify a real hosted Settld environment.
 2. Confirm release workflow is blocked unless NOO-50 and the kernel/cutover gates are green for the release commit.
 3. Confirm release workflow runs NOO-65 promotion guard and blocks publish lanes if `release-promotion-guard.json` verdict is not pass/override-pass.
 4. Confirm staging and production have separate domains, databases, secrets, and signer keys.
-5. Confirm required services are deployable: `npm run start:prod`, `npm run start:maintenance`, `npm run start:x402-gateway`.
+5. Confirm required services are deployable: `npm run start:prod`, `npm run start:magic-link`, `npm run start:maintenance`, `npm run start:x402-gateway`.
 6. Configure GitHub Environment `production_cutover_gate` with:
    - `PROD_BASE_URL`
    - `PROD_TENANT_ID`
@@ -29,17 +29,22 @@ Use this checklist to launch and verify a real hosted Settld environment.
 3. Set scoped `PROXY_OPS_TOKENS`.
 4. Configure rate limits and quotas from `docs/CONFIG.md`.
 5. Configure gateway secrets: `SETTLD_API_URL`, `SETTLD_API_KEY`, `UPSTREAM_URL`.
+6. Configure onboarding routing:
+   - `PROXY_ONBOARDING_BASE_URL=https://<magic-link-host>` on `settld-api`
+   - `MAGIC_LINK_PUBLIC_SIGNUP_ENABLED=1` and OTP delivery (`smtp`) on `settld-magic-link`
 
 ## Phase 2: Deploy services
 
 1. Deploy `settld-api`.
-2. Deploy `settld-maintenance`.
-3. Deploy `x402-gateway`.
+2. Deploy `settld-magic-link`.
+3. Deploy `settld-maintenance`.
+4. Deploy `x402-gateway`.
 4. Verify service health:
 
 ```bash
 curl -fsS https://api.settld.work/healthz
 curl -fsS https://gateway.settld.work/healthz
+npm run test:ops:public-onboarding-gate -- --base-url https://api.settld.work --tenant-id tenant_default
 ```
 
 ## Phase 3: Baseline ops verification

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "settld",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Settld kernel CLI and local control-plane tooling",
   "private": false,
   "type": "module",
@@ -25,6 +25,7 @@
     "scripts",
     "docs",
     "src",
+    "services/magic-link",
     "services/finance-sink",
     "services/x402-gateway",
     "services/receiver"
@@ -110,6 +111,7 @@
     "test:ops:onboarding-host-success-gate": "node scripts/ci/run-onboarding-host-success-gate.mjs",
     "test:ops:self-serve-benchmark": "node scripts/ci/build-self-serve-benchmark-report.mjs",
     "test:ops:launch-cutover-packet": "node scripts/ci/build-launch-cutover-packet.mjs",
+    "test:ops:public-onboarding-gate": "node scripts/ci/run-public-onboarding-gate.mjs",
     "test:ops:production-cutover-gate": "node scripts/ci/run-production-cutover-gate.mjs",
     "test:ops:release-promotion-guard": "node scripts/ci/run-release-promotion-guard.mjs",
     "test:ci:mcp-host-smoke": "node scripts/ci/run-mcp-host-smoke.mjs",

package/scripts/ci/run-public-onboarding-gate.mjs

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+import fs from "node:fs/promises";
+import path from "node:path";
+
+function parseArgs(argv) {
+  const out = {
+    baseUrl: process.env.SETTLD_BASE_URL ?? "https://api.settld.work",
+    tenantId: process.env.SETTLD_TENANT_ID ?? "tenant_default",
+    email: process.env.SETTLD_ONBOARDING_PROBE_EMAIL ?? "probe@settld.work",
+    out: "artifacts/gates/public-onboarding-gate.json"
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = String(argv[i] ?? "");
+    const next = () => {
+      i += 1;
+      if (i >= argv.length) throw new Error(`missing value for ${arg}`);
+      return String(argv[i] ?? "");
+    };
+    if (arg === "--base-url") out.baseUrl = next();
+    else if (arg.startsWith("--base-url=")) out.baseUrl = arg.slice("--base-url=".length);
+    else if (arg === "--tenant-id") out.tenantId = next();
+    else if (arg.startsWith("--tenant-id=")) out.tenantId = arg.slice("--tenant-id=".length);
+    else if (arg === "--email") out.email = next();
+    else if (arg.startsWith("--email=")) out.email = arg.slice("--email=".length);
+    else if (arg === "--out") out.out = next();
+    else if (arg.startsWith("--out=")) out.out = arg.slice("--out=".length);
+  }
+  out.baseUrl = String(out.baseUrl ?? "").trim().replace(/\/+$/, "");
+  out.tenantId = String(out.tenantId ?? "").trim();
+  out.email = String(out.email ?? "").trim().toLowerCase();
+  out.out = String(out.out ?? "").trim();
+  if (!out.baseUrl) throw new Error("--base-url is required");
+  if (!out.tenantId) throw new Error("--tenant-id is required");
+  if (!out.email) throw new Error("--email is required");
+  if (!out.out) throw new Error("--out is required");
+  return out;
+}
+
+async function requestJson(url, { method = "GET", body = null, headers = {} } = {}) {
+  const res = await fetch(url, {
+    method,
+    headers: {
+      ...(body === null ? {} : { "content-type": "application/json" }),
+      ...headers
+    },
+    body: body === null ? undefined : JSON.stringify(body)
+  });
+  const text = await res.text();
+  let json = null;
+  try {
+    json = text ? JSON.parse(text) : null;
+  } catch {
+    json = null;
+  }
+  return {
+    ok: res.ok,
+    statusCode: res.status,
+    url,
+    text,
+    json
+  };
+}
+
+function summarizeBody(outcome) {
+  if (outcome?.json && typeof outcome.json === "object") {
+    return {
+      code: outcome.json.code ?? null,
+      error: outcome.json.error ?? null,
+      message: outcome.json.message ?? null,
+      authMode: outcome.json.authMode ?? null
+    };
+  }
+  return { raw: String(outcome?.text ?? "").slice(0, 500) };
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const startedAt = new Date().toISOString();
+  const steps = [];
+  const errors = [];
+
+  const authMode = await requestJson(`${args.baseUrl}/v1/public/auth-mode`);
+  steps.push({
+    step: "public_auth_mode",
+    statusCode: authMode.statusCode,
+    body: summarizeBody(authMode)
+  });
+  if (authMode.statusCode !== 200 || typeof authMode.json?.authMode !== "string") {
+    errors.push({
+      code: "PUBLIC_AUTH_MODE_UNAVAILABLE",
+      message: `expected GET /v1/public/auth-mode to return 200 with authMode; got ${authMode.statusCode}`
+    });
+  }
+
+  const otpProbe = await requestJson(
+    `${args.baseUrl}/v1/tenants/${encodeURIComponent(args.tenantId)}/buyer/login/otp`,
+    {
+      method: "POST",
+      body: { email: args.email }
+    }
+  );
+  steps.push({
+    step: "buyer_login_otp_probe",
+    statusCode: otpProbe.statusCode,
+    body: summarizeBody(otpProbe)
+  });
+  if ([403, 404, 405, 503].includes(otpProbe.statusCode)) {
+    errors.push({
+      code: "BUYER_LOGIN_OTP_UNAVAILABLE",
+      message: `expected buyer OTP endpoint to be reachable (non-403/404/405/503); got ${otpProbe.statusCode}`
+    });
+  }
+
+  const report = {
+    schemaVersion: "PublicOnboardingGate.v1",
+    ok: errors.length === 0,
+    startedAt,
+    completedAt: new Date().toISOString(),
+    baseUrl: args.baseUrl,
+    tenantId: args.tenantId,
+    steps,
+    errors
+  };
+
+  await fs.mkdir(path.dirname(args.out), { recursive: true });
+  await fs.writeFile(args.out, `${JSON.stringify(report, null, 2)}\n`, "utf8");
+  process.stdout.write(`wrote public onboarding gate report: ${path.resolve(args.out)}\n`);
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  if (!report.ok) process.exit(1);
+}
+
+main().catch((err) => {
+  process.stderr.write(`${err?.stack ?? err?.message ?? String(err)}\n`);
+  process.exit(1);
+});
+

package/scripts/setup/login.mjs

@@ -8,6 +8,10 @@ import { fileURLToPath } from "node:url";
 import { cookieHeaderFromSetCookie, defaultSessionPath, writeSavedSession } from "./session-store.mjs";
 
 const FORMAT_OPTIONS = new Set(["text", "json"]);
+const AUTH_MODE_PUBLIC_SIGNUP = "public_signup";
+const AUTH_MODE_ENTERPRISE_PREPROVISIONED = "enterprise_preprovisioned";
+const AUTH_MODE_HYBRID = "hybrid";
+const KNOWN_AUTH_MODES = new Set([AUTH_MODE_PUBLIC_SIGNUP, AUTH_MODE_ENTERPRISE_PREPROVISIONED, AUTH_MODE_HYBRID]);
 
 function usage() {
   const text = [
@@ -39,6 +43,7 @@ function readArgValue(argv, index, rawArg) {
 function parseArgs(argv) {
   const out = {
     baseUrl: "https://api.settld.work",
+    baseUrlProvided: false,
     tenantId: "",
     email: "",
     company: "",
@@ -64,6 +69,7 @@ function parseArgs(argv) {
     if (arg === "--base-url" || arg.startsWith("--base-url=")) {
       const parsed = readArgValue(argv, i, arg);
       out.baseUrl = parsed.value;
+      out.baseUrlProvided = true;
       i = parsed.nextIndex;
       continue;
     }
@@ -149,6 +155,66 @@ async function requestJson(url, { method, body, headers = {}, fetchImpl = fetch
   return { res, text, json };
 }
 
+function normalizeAuthMode(value) {
+  const mode = String(value ?? "").trim().toLowerCase();
+  return KNOWN_AUTH_MODES.has(mode) ? mode : "unknown";
+}
+
+export async function detectDeploymentAuthMode({ baseUrl, fetchImpl = fetch } = {}) {
+  const normalizedBaseUrl = mustHttpUrl(baseUrl, "base URL");
+  let response;
+  try {
+    response = await requestJson(`${normalizedBaseUrl}/v1/public/auth-mode`, {
+      method: "GET",
+      fetchImpl
+    });
+  } catch {
+    return {
+      schemaVersion: "SettldAuthModeDiscovery.v1",
+      mode: "unknown",
+      source: "network_error",
+      enterpriseProvisionedTenantsOnly: null
+    };
+  }
+  if (!response.res.ok) {
+    return {
+      schemaVersion: "SettldAuthModeDiscovery.v1",
+      mode: "unknown",
+      source: `http_${response.res.status}`,
+      enterpriseProvisionedTenantsOnly: null
+    };
+  }
+  const mode = normalizeAuthMode(response.json?.authMode);
+  const enterpriseOnly =
+    typeof response.json?.enterpriseProvisionedTenantsOnly === "boolean"
+      ? response.json.enterpriseProvisionedTenantsOnly
+      : mode === AUTH_MODE_ENTERPRISE_PREPROVISIONED
+        ? true
+        : mode === "unknown"
+          ? null
+          : false;
+  return {
+    schemaVersion: "SettldAuthModeDiscovery.v1",
+    mode,
+    source: "endpoint",
+    enterpriseProvisionedTenantsOnly: enterpriseOnly
+  };
+}
+
+function responseCode({ json }) {
+  const direct = typeof json?.code === "string" ? json.code : "";
+  if (direct) return direct;
+  const error = typeof json?.error === "string" ? json.error : "";
+  return error ? error.toUpperCase() : "";
+}
+
+function responseMessage({ json, text }, fallback = "unknown error") {
+  if (typeof json?.message === "string" && json.message.trim()) return json.message.trim();
+  if (typeof json?.error === "string" && json.error.trim()) return json.error.trim();
+  const raw = String(text ?? "").trim();
+  return raw || fallback;
+}
+
 async function promptLine(rl, label, { defaultValue = "", required = true } = {}) {
   const suffix = defaultValue ? ` [${defaultValue}]` : "";
   const value = String(await rl.question(`${label}${suffix}: `) ?? "").trim() || String(defaultValue ?? "").trim();
@@ -190,7 +256,9 @@ export async function runLogin({
   const rl = interactive ? createInterface({ input: stdin, output: stdout }) : null;
   try {
     if (interactive) {
-      state.baseUrl = await promptLine(rl, "Settld base URL", { defaultValue: state.baseUrl || "https://api.settld.work" });
+      if (!args.baseUrlProvided) {
+        state.baseUrl = await promptLine(rl, "Settld base URL", { defaultValue: state.baseUrl || "https://api.settld.work" });
+      }
       state.tenantId = await promptLine(rl, "Tenant ID (optional, leave blank to create new)", {
         defaultValue: state.tenantId,
         required: false
@@ -202,10 +270,38 @@ export async function runLogin({
     }
 
     const baseUrl = mustHttpUrl(state.baseUrl, "base URL");
+    const authMode = await detectDeploymentAuthMode({ baseUrl, fetchImpl });
+    if (interactive && authMode.mode !== "unknown") {
+      stdout.write(`Detected auth mode: ${authMode.mode}\n`);
+    }
+    if (!state.tenantId && authMode.mode === AUTH_MODE_ENTERPRISE_PREPROVISIONED) {
+      throw new Error(
+        "This deployment uses enterprise_preprovisioned mode. Pass --tenant-id <existing_tenant> and login via OTP, or use bootstrap/manual API key flow."
+      );
+    }
     if (!state.email) throw new Error("email is required");
     if (!state.tenantId && !state.company) throw new Error("company is required when tenant ID is omitted");
 
+    const requestTenantOtp = async (tenantId) => {
+      const otpRequest = await requestJson(`${baseUrl}/v1/tenants/${encodeURIComponent(String(tenantId ?? ""))}/buyer/login/otp`, {
+        method: "POST",
+        body: { email: state.email },
+        fetchImpl
+      });
+      if (!otpRequest.res.ok) {
+        const code = responseCode(otpRequest);
+        if (otpRequest.res.status === 403 && code === "FORBIDDEN") {
+          throw new Error(
+            "OTP login is unavailable on this base URL. Use `Generate during setup` with an onboarding bootstrap API key, or use an existing tenant API key."
+          );
+        }
+        const message = responseMessage(otpRequest);
+        throw new Error(`otp request failed (${otpRequest.res.status}): ${message}`);
+      }
+    };
+
     let tenantId = state.tenantId;
+    let otpAlreadyIssued = false;
     if (!tenantId) {
       const signup = await requestJson(`${baseUrl}/v1/public/signup`, {
         method: "POST",
@@ -213,27 +309,24 @@ export async function runLogin({
         fetchImpl
       });
       if (!signup.res.ok) {
-        const code = typeof signup.json?.code === "string" ? signup.json.code : "";
-        const message = typeof signup.json?.message === "string" ? signup.json.message : signup.text;
+        const code = responseCode(signup);
+        const message = responseMessage(signup);
         if (code === "SIGNUP_DISABLED") {
           throw new Error("Public signup is disabled for this environment. Use an existing tenant ID or bootstrap key flow.");
         }
-        throw new Error(`public signup failed (${signup.res.status}): ${message || "unknown error"}`);
+        if (signup.res.status === 403 && code === "FORBIDDEN") {
+          throw new Error(
+            "Public signup is unavailable on this base URL. Retry with --tenant-id <existing_tenant>, or in `settld setup` choose `Generate during setup` and provide an onboarding bootstrap API key."
+          );
+        }
+        throw new Error(`public signup failed (${signup.res.status}): ${message}`);
       }
       tenantId = String(signup.json?.tenantId ?? "").trim();
       if (!tenantId) throw new Error("public signup response missing tenantId");
+      otpAlreadyIssued = Boolean(signup.json?.otpIssued);
       if (interactive) stdout.write(`Created tenant: ${tenantId}\n`);
-    } else {
-      const otpRequest = await requestJson(`${baseUrl}/v1/tenants/${encodeURIComponent(tenantId)}/buyer/login/otp`, {
-        method: "POST",
-        body: { email: state.email },
-        fetchImpl
-      });
-      if (!otpRequest.res.ok) {
-        const message = typeof otpRequest.json?.message === "string" ? otpRequest.json.message : otpRequest.text;
-        throw new Error(`otp request failed (${otpRequest.res.status}): ${message || "unknown error"}`);
-      }
     }
+    if (!otpAlreadyIssued) await requestTenantOtp(tenantId);
 
     if (!state.otp && interactive) {
       state.otp = await promptLine(rl, "OTP code", { required: true });
@@ -246,8 +339,8 @@ export async function runLogin({
       fetchImpl
     });
     if (!login.res.ok) {
-      const message = typeof login.json?.message === "string" ? login.json.message : login.text;
-      throw new Error(`login failed (${login.res.status}): ${message || "unknown error"}`);
+      const message = responseMessage(login);
+      throw new Error(`login failed (${login.res.status}): ${message}`);
     }
     const setCookie = login.res.headers.get("set-cookie") ?? "";
     const cookie = cookieHeaderFromSetCookie(setCookie);
@@ -271,7 +364,8 @@ export async function runLogin({
       tenantId: session.tenantId,
       email: session.email,
       sessionFile: state.sessionFile,
-      expiresAt: session.expiresAt ?? null
+      expiresAt: session.expiresAt ?? null,
+      authMode: authMode.mode
     };
 
     if (state.format === "json") {