settld 0.2.4 → 0.2.6

package/Dockerfile

@@ -30,8 +30,8 @@ COPY --from=deps /app/node_modules ./node_modules
 COPY --from=deps /app/package.json ./package.json
 COPY --from=deps /app/SETTLD_VERSION ./SETTLD_VERSION
 
-# Runtime-writable locations should be mounted as volumes in k8s; create /data with correct ownership for safety.
-COPY --from=prep /data /data
+# Runtime-writable locations should be mounted as volumes in k8s; copy with nonroot ownership for distroless runtime.
+COPY --chown=65532:65532 --from=prep /data /data
 
 # Copy application code.
 COPY src ./src

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.4",
+  "version": "0.2.6",
   "description": "Settld kernel CLI and local control-plane tooling",
   "private": false,
   "type": "module",
@@ -21,10 +21,12 @@
     "docker-compose.yml",
     "bin",
     "conformance",
+    "packages/api-sdk/src",
     "packages/artifact-verify/src",
     "scripts",
     "docs",
     "src",
+    "services/magic-link",
     "services/finance-sink",
     "services/x402-gateway",
     "services/receiver"
@@ -110,6 +112,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/packages/api-sdk/README.md

@@ -0,0 +1,71 @@
+# settld-api-sdk
+
+Node/TypeScript SDK for Settld API + x402 helpers.
+
+## Webhook Signature Verification
+
+Use `verifySettldWebhookSignature` to verify incoming `x-settld-signature` headers with:
+
+- multi-signature support (`v1=...` list, including rotation windows),
+- constant-time comparison (`crypto.timingSafeEqual`),
+- timestamp tolerance checks (replay protection).
+
+```js
+import express from "express";
+import { verifySettldWebhookSignature } from "settld-api-sdk";
+
+const app = express();
+
+// IMPORTANT: keep the raw body; do not JSON-parse before verification.
+app.post("/webhooks/settld", express.raw({ type: "application/json" }), (req, res) => {
+  const signatureHeader = req.get("x-settld-signature") ?? "";
+  const timestamp = req.get("x-settld-timestamp"); // required for current Settld delivery format
+  const secret = process.env.SETTLD_WEBHOOK_SECRET;
+
+  verifySettldWebhookSignature(req.body, signatureHeader, secret, {
+    timestamp,
+    toleranceSeconds: 300
+  });
+
+  const event = JSON.parse(req.body.toString("utf8"));
+  // handle event...
+  res.status(200).json({ ok: true });
+});
+```
+
+The verifier also supports signature headers that embed timestamp directly:
+
+`x-settld-signature: t=1708380000,v1=<sig-new>,v1=<sig-old>`
+
+## Express Middleware Helper
+
+Use `verifySettldWebhook` to verify signatures in an Express-style middleware.
+
+```js
+import express from "express";
+import { verifySettldWebhook } from "settld-api-sdk";
+
+const app = express();
+const secret = process.env.SETTLD_WEBHOOK_SECRET;
+
+// IMPORTANT: preserve raw body bytes before JSON parsing mutates payload shape.
+app.use(
+  express.json({
+    verify(req, _res, buf) {
+      req.rawBody = buf;
+    }
+  })
+);
+
+app.post(
+  "/webhooks/settld",
+  verifySettldWebhook(secret, { toleranceSeconds: 300 }),
+  (req, res) => {
+    const event = req.body;
+    // handle event...
+    res.status(200).json({ ok: true });
+  }
+);
+```
+
+If `req.rawBody` is missing (or `req.body` is already parsed into a plain object), the middleware returns `400` with a raw-body guidance message.