merge: admin-org predicate (owner==admin) + home-org billing (debit/gate on X-User-Owner, data scope on X-Org-Id) — admin masquerade bills the admin ledger

THE billing fix (B): split 'who pays' (HOME org, X-User-Owner) from 'whose data'
(EFFECTIVE org, X-Org-Id), which the old code conflated onto one org. A platform
SuperAdmin masquerading into another org now spends from the admin ledger; data
scope stays on the acted-on org.

- clients/principal: Owner(c) (X-User-Owner, bounded+cloned), BillingOrg(c) (home w/
  effective fallback, Validated-gated), Payer(c) (bare-string for the in-handler meters).
- middleware_identity: mint X-User-Owner=home for every validated principal (before the
  admin org-switch) + strip it on ingress (authorityHeaders) so a client can't forge who pays.
- middleware_billing: identityFromCtx keys User+Org (balance check AND debit) on BillingOrg.
- 11 resource-meter live sites (visor/s3/security/platform-run/functions/ml/provisioning/
  bots/tracker/automations): Gate+Meter+MeterUsage bill principal.Payer(c) (home); Org stays
  effective for the namespace. Background/reconcile paths (a.Org/r.Org/b.Org, meterRun) and
  the studio_render 'org' param bill the RESOURCE's own org — FLAGGED (see Red handoff).
- metered_ai + types: ChatRequest/EmbedRequest gain BillingOrg; meteredAI gate+record key on
  billedOrg(BillingOrg,Org); threaded principal.Payer(c) through the code engine (Synthesize/
  Embed) so internal RAG bills home too. Inner AI call keeps req.Org (data scope).

Part A (embedded commerce, clients/commerce mirror of the commerce repo): drop the spoofable
IsSuperAdmin boolean; auth.IAMClaims.IsSuperAdmin() gates homeOrg()=="admin" (HomeOrg from
X-User-Owner ?: Owner); iammiddleware reads X-User-Owner->HomeOrg (Owner stays effective);
EdgeAuth strips+mints X-User-Owner before the ?org override, stops minting X-User-IsSuperAdmin;
all .SuperAdmin() call sites -> .IsSuperAdmin(). Org-scoped IsAdmin untouched.

Tests (green): TestIdentityFromCtx_AdminMasqueradeBillsHomeOrg (owner=admin+effective=victim ->
debit on admin, data on victim), TestBilledOrg, TestMeteredAI_AdminMasqueradeBillsHomeOrg
(end-to-end debit user=admin), vendored TestIAMClaims_IsSuperAdmin masquerade+anti-escalation,
EdgeAuth strips forged X-User-Owner. go build ./...=0, go vet=0.

Rollout: pre-gateway (no X-User-Owner) billing falls back to effective (home==effective for a
normal caller; masquerade fails CLOSED). Deploy gateway (mints X-User-Owner) first.

.dockerignore

@@ -0,0 +1,41 @@
+# VCS
+.git/
+.gitignore
+.gitattributes
+
+# CI / repo metadata not needed inside the build
+.github/
+
+# Docs (image runs the binary; readers visit GitHub)
+*.md
+LICENSE
+SECURITY.md
+
+# Already-built binary at repo root (matches .gitignore)
+/cloud
+
+# Environment files (never bake secrets into images)
+.env
+.env.*
+
+# IDE / editor
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS metadata
+.DS_Store
+Thumbs.db
+
+# Tests stay out of the runtime image
+*_test.go
+
+# Local build outputs
+/dist/
+/build/
+/bin/
+
+# The Dockerfile itself doesn't need to be in the context it builds
+Dockerfile
+.dockerignore

.github/hero.svg

@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1280" height="640" viewBox="0 0 1280 640" role="img" aria-label="cloud">
+<rect width="1280" height="640" fill="#0A0A0A"/>
+<svg x="96" y="215" width="210" height="210" viewBox="0 0 67 67"><path d="M22.21 67V44.6369H0V67H22.21Z" fill="#fff"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z" fill="#fff"/><path d="M22.21 0H0V22.3184H22.21V0Z" fill="#fff"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z" fill="#fff"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z" fill="#fff"/></svg>
+<text x="378" y="276" font-family="Inter,system-ui,-apple-system,sans-serif" font-size="78" font-weight="800" letter-spacing="-2" fill="#ffffff">cloud</text>
+<text x="378" y="322" font-family="Inter,system-ui,sans-serif" font-size="30" fill="#ffffff" opacity=".66">Hanzo Cloud — unified Go binary that imports every Hanzo-native…</text>
+<rect x="378" y="338" width="806" height="3" rx="1.5" fill="#ffffff" opacity=".9"/>
+<text x="378" y="390" font-family="Inter,system-ui,sans-serif" font-size="24" font-weight="600" fill="#ffffff" opacity=".5">github.com/hanzoai</text>
+<text x="1184" y="390" text-anchor="end" font-family="Inter,system-ui,sans-serif" font-size="24" font-weight="600" fill="#ffffff" opacity=".5">hanzo.ai</text>
+</svg>

.github/workflows/containment.yml

@@ -0,0 +1,123 @@
+name: containment
+
+# Guards the Stage-1 byzantine ceremony containment (clients/controlplane,
+# build tag `controlplane`). Its increment-1 crypto is stub/forgeable BY
+# DESIGN (SHA256-of-public-inputs commitments, symmetric-HMAC
+# proof-of-possession, seed-derived threshold shares — see
+# clients/controlplane/doc.go) and MUST NEVER reach a release/serve binary.
+# Three independent checks; any one failing blocks the PR:
+#
+#   1. grep (tag)    — no build/release invocation anywhere in the repo
+#      (Dockerfile, Makefile, shell scripts, any workflow) may pass a `-tags`
+#      value containing `controlplane` to go build/vet/run/install. The
+#      package's own `//go:build controlplane` tag declarations
+#      (clients/controlplane/*) are the thing being guarded, not a violation,
+#      and are excluded by path.
+#   2. grep (spoof)  — no build/release invocation may pass
+#      `-X testing.testBinary=1` (or any -ldflags containing it) to a REAL
+#      `go build`. That linker flag is what `go test` itself uses to make
+#      testing.Testing() report true (cmd/go/internal/load/test.go) — the
+#      runtime guard in containment.go trusts that signal, so this is the one
+#      concrete way to spoof it in a non-test binary. This grep is what turns
+#      "someone could type this" into "CI fails the PR that types it".
+#   3. build         — `go build ./...` (no tag — exactly what the Dockerfile
+#      and Makefile run) must not link clients/controlplane into any cmd/
+#      main, and `go build ./clients/controlplane/...` with no tag must match
+#      zero buildable packages (proves the tag still gates every file in it).
+#
+# Runtime belt-and-suspenders (defense in depth, not a substitute for the
+# above): clients/controlplane/containment.go fail-closed panics if its stub
+# crypto is ever constructed outside a go-test binary (testing.Testing()==
+# false) — see TestContainment_NonHarnessProcessRefuses in
+# containment_test.go. KNOWN RESIDUAL: testing.Testing() is a linker-set
+# string var (testing.testBinary), not cryptographically bound to "actually
+# is a test" — `-ldflags="-X testing.testBinary=1"` spoofs it in a real
+# binary. Check #2 above is the mitigation: it fails the PR that would ship
+# that flag. Closing the residual for real needs a signal `go build` cannot
+# produce at all (increment-2, tracked in doc.go) rather than one merely
+# absent by convention.
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  controlplane-containment:
+    runs-on: [hanzo-build-linux-amd64]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: grep — no build/release path may set -tags controlplane, or spoof testing.Testing()
+        run: |
+          set -euo pipefail
+          hits=0
+
+          # NOTE: exclusions are plain substring matches on the path (not
+          # anchored to a leading "./") so this is robust across grep
+          # implementations that format recursive-search paths differently.
+          # char class includes `!` so a build-constraint negation form
+          # (`-tags '!x,controlplane'`) cannot slip the grep. (Belt only: the
+          # positive-proof step below is the syntax-agnostic guarantee — the
+          # package has zero untagged files, so importing it into serve code
+          # fails the untagged `go build ./...` regardless of any -tags syntax.)
+          if grep -RnE -- '-tags[= ]*["'"'"']?[!A-Za-z0-9_, ]*\bcontrolplane\b' \
+               --exclude-dir=.git --exclude-dir=node_modules --exclude-dir=.claude --exclude-dir=vendor \
+               . 2>/dev/null \
+               | grep -v '\.git/' \
+               | grep -v 'clients/controlplane/' \
+               | grep -v '.github/workflows/containment.yml:'; then
+            echo "::error::found a build/release invocation passing -tags controlplane — clients/controlplane's stub crypto must never enter a release/serve binary (see clients/controlplane/doc.go)"
+            hits=1
+          fi
+
+          if grep -RnE -- 'testing\.testBinary' \
+               --exclude-dir=.git --exclude-dir=node_modules --exclude-dir=.claude --exclude-dir=vendor \
+               . 2>/dev/null \
+               | grep -v '.github/workflows/containment.yml:'; then
+            echo "::error::found a reference to testing.testBinary outside the Go toolchain itself — this is the linker var that spoofs testing.Testing() in a real (non go-test) binary; the containment.go runtime guard trusts that signal, so setting it anywhere in a real build path defeats it (see doc.go)"
+            hits=1
+          fi
+
+          if [ "$hits" -ne 0 ]; then exit 1; fi
+          echo "OK: no build/release path sets -tags controlplane or spoofs testing.Testing()"
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+
+      - name: go env for private modules (matches Dockerfile — zap-proto is direct+authenticated)
+        env:
+          GH_PAT: ${{ secrets.GH_PAT }}
+        run: |
+          git config --global url."https://x-access-token:${GH_PAT}@github.com/".insteadOf "https://github.com/"
+          {
+            echo "GOPRIVATE=github.com/zap-proto/*"
+            echo "GONOSUMDB=github.com/zap-proto/*"
+            echo "GOSUMDB=off"
+            echo "GOPROXY=https://proxy.golang.org,direct"
+          } >> "$GITHUB_ENV"
+
+      - name: positive proof — clients/controlplane is unreachable from the default build
+        run: |
+          set -euo pipefail
+
+          go build ./...
+
+          for m in $(go list ./cmd/...); do
+            if go list -deps "$m" | grep -qx 'github.com/hanzoai/cloud/clients/controlplane'; then
+              echo "::error::$m links clients/controlplane into a real binary — containment breach"
+              exit 1
+            fi
+          done
+
+          out="$(go build ./clients/controlplane/... 2>&1 || true)"
+          if ! printf '%s' "$out" | grep -q 'matched no packages'; then
+            echo "::error::clients/controlplane built successfully WITHOUT -tags controlplane (containment breach): $out"
+            exit 1
+          fi
+
+          echo "OK: containment holds — clients/controlplane has zero buildable files by default and is linked into no cmd/ binary"

.github/workflows/release.yml

@@ -0,0 +1,309 @@
+name: release
+
+# Cuts a release of ghcr.io/hanzoai/cloud. The invariant this workflow exists to
+# enforce:
+#
+#     a git tag v<X.Y.Z> exists  ⇔  an image ghcr.io/hanzoai/cloud:v<X.Y.Z>
+#     was pushed AND booted to "listening" in the smoke test.
+#
+# The tag is a RECEIPT for a proven image, minted only AFTER a successful push —
+# never a trigger for a build that might fail. The prior design triggered builds
+# FROM pushed tags, so a tag could exist with no image behind it (a failed or
+# never-run build) — universe would then try to roll that tag and the pods went
+# ImagePullBackOff (phantom v1.786.42/43). Here the order is inverted:
+#
+#     main push → compute next version → build → SMOKE → push image → tag → notify
+#
+# so a push/smoke/build failure fails the run BEFORE the tag step and leaves no
+# tag; universe is only ever notified of a version whose image is proven present.
+#
+# DO NOT push v* tags by hand anymore. This workflow OWNS them. A hand-cut tag has
+# no image behind it (exactly the phantom this prevents) and won't build (there is
+# no `tags:` trigger). Every merge to main IS the release; skip one with the usual
+# `[skip ci]` in the commit/merge message (a docs-only change need not ship).
+#
+# concurrency: a single serialized lane (cancel-in-progress:false — a
+# mid-flight push must finish, never be killed between "image pushed" and "tag
+# created"). Two main pushes can therefore never compute the same next number:
+# the queued run starts only after the running one tags, re-reads the tags, and
+# lands on the next patch. Monotonic by construction.
+#
+# The next version is max(highest git tag, highest pushed container tag) + 1 (patch
+# bump only — never a major/minor jump). Folding in the container tags means we
+# never reuse a number that already has a pushed image, even if some earlier run
+# pushed an image but died before tagging.
+#
+# ── Infra notes (unchanged, still true) ─────────────────────────────────────────
+# Self-hosted arcd amd64 scale set — NEVER GitHub-hosted runners (this org's
+# GitHub-hosted Actions are billing-frozen). GHCR login uses GH_PAT, not the repo
+# GITHUB_TOKEN: the ghcr.io/hanzoai/cloud package is linked to a DIFFERENT repo
+# (hanzoai/ai, from the cloud→ai module rename), so this repo's GITHUB_TOKEN is
+# denied write to it (permission_denied: write_package). GH_PAT (admin:org +
+# write:packages) writes any hanzoai package regardless of package-repo linkage,
+# and is the BuildKit gh_token the Dockerfile uses to fetch private cross-org Go
+# modules. amd64-only: the cluster is amd64; one platform completes on the live
+# scale set without waiting on the arm64 pool.
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+# Cut tags on the cloud repo (git tag push) → contents: write. packages: write
+# to push the image; id-token for provenance.
+permissions:
+  contents: write
+  packages: write
+  id-token: write
+
+# One serialized release lane. Never cancel in-flight: a run killed between
+# "image pushed" and "tag created" is exactly the drift we are preventing.
+concurrency:
+  group: release-cloud
+  cancel-in-progress: false
+
+jobs:
+  build-amd64:
+    # ARC ephemeral runners match jobs targeting the scale-set NAME as a label.
+    runs-on: [hanzo-build-linux-amd64]
+    outputs:
+      version: ${{ steps.ver.outputs.version }}
+      version_v: ${{ steps.ver.outputs.version_v }}
+    steps:
+      - name: Checkout (full history + all tags — the version floor is read from tags)
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+
+      - name: Compute next version (monotonic patch bump over git + container tags)
+        id: ver
+        env:
+          GH_PAT: ${{ secrets.GH_PAT }}
+        run: |
+          set -euo pipefail
+          git fetch --tags --force --quiet
+
+          # Highest semver git tag (vX.Y.Z), normalised without the leading v.
+          git_max="$(git tag -l 'v[0-9]*.[0-9]*.[0-9]*' \
+            | sed 's/^v//' | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -1 || true)"
+
+          # Best-effort: highest ALREADY-PUSHED container tag, so a number that has
+          # an image (even from a run that died before tagging) is never reused.
+          cont_max=""
+          if command -v gh >/dev/null 2>&1; then
+            cont_max="$(GH_TOKEN="$GH_PAT" gh api --paginate \
+              '/orgs/hanzoai/packages/container/cloud/versions' \
+              --jq '.[].metadata.container.tags[]' 2>/dev/null \
+              | sed 's/^v//' | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -1 || true)"
+          fi
+
+          # Floor = highest of the two; fall back to 1.786.0 only if the repo has
+          # no tags at all (first release ever).
+          max="$(printf '%s\n%s\n%s\n' "1.786.0" "$git_max" "$cont_max" \
+            | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -1)"
+
+          major="${max%%.*}"; rest="${max#*.}"; minor="${rest%%.*}"; patch="${rest##*.}"
+          version="${major}.${minor}.$((patch + 1))"
+
+          # Refuse to proceed if the number we intend to mint already exists as a
+          # git tag (a concurrent run beat us — the serialized lane makes this a
+          # can't-happen, but fail loud rather than clobber).
+          if git rev-parse -q --verify "refs/tags/v${version}" >/dev/null; then
+            echo "::error::computed v${version} already exists as a git tag — aborting to avoid collision"
+            exit 1
+          fi
+
+          echo "version=${version}"     >> "$GITHUB_OUTPUT"
+          echo "version_v=v${version}"  >> "$GITHUB_OUTPUT"
+          echo "major_minor=${major}.${minor}" >> "$GITHUB_OUTPUT"
+          echo "sha_short=$(git rev-parse --short "$GITHUB_SHA")" >> "$GITHUB_OUTPUT"
+          echo "Next release: v${version} (git_max='${git_max:-none}' container_max='${cont_max:-none}')"
+
+          # Console-embed cachebust. The console clone+build layer is keyed on this;
+          # prefer hanzoai/console main HEAD so a CONSOLE-ONLY change re-embeds without
+          # needing a cloud commit (cloud-sha alone froze the embed between cloud pushes).
+          # git ls-remote must CLEAR the extraheader actions/checkout installs (it carries
+          # THIS repo's GITHUB_TOKEN, which 404s the cross-repo console lookup); gh is not
+          # on the runner. If resolution yields nothing, fall back to the cloud sha — still
+          # unique per cloud commit, so the embed is never frozen. Either way THIS build
+          # busts (new value) and re-clones console main fresh.
+          console_head="$(git -c 'http.https://github.com/.extraheader=' ls-remote \
+            "https://x-access-token:${GH_PAT}@github.com/hanzoai/console.git" refs/heads/main 2>/dev/null | cut -f1 || true)"
+          cachebust="${console_head:-$GITHUB_SHA}"
+          echo "cachebust=${cachebust}" >> "$GITHUB_OUTPUT"
+          echo "console cachebust: ${cachebust} (console_head='${console_head:-none}')"
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+        with:
+          driver: docker-container
+          driver-opts: network=host
+
+      - name: Log in to ghcr.io (GH_PAT — writes the cloud package despite its ai-repo linkage)
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: hanzo-dev
+          password: ${{ secrets.GH_PAT }}
+
+      - name: OCI labels
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/hanzoai/cloud
+          tags: type=raw,value=${{ steps.ver.outputs.version_v }}
+
+      # ── Build → SMOKE → push → tag ───────────────────────────────────────────
+      # 1. Build once to a LOCAL tag (load into the daemon, do NOT push). Warms
+      #    the BuildKit cache — the expensive console/npm + Go layers land here.
+      # 2. Boot that exact image and assert it reaches "listening" with no
+      #    startup-crash signature (the gate).
+      # 3. Re-run build with push:true and the real tags: identical context /
+      #    platform / secrets, so every layer is a cache hit from step 1 and the
+      #    step only exports + pushes the already-tested image. Nothing that failed
+      #    the smoke test can reach the registry.
+      # 4. Only after the push succeeds, mint + push the git tag (the receipt).
+      - name: Build (load locally for the smoke test)
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: linux/amd64
+          push: false
+          load: true
+          tags: cloud:smoke
+          labels: ${{ steps.meta.outputs.labels }}
+          # Bust the console clone+build layer every release (the cloud commit sha is
+          # unique per push) so the embed re-fetches console main HEAD fresh — never the
+          # frozen snapshot the persistent BuildKit cache would otherwise serve forever.
+          build-args: |
+            CONSOLE_CACHEBUST=${{ steps.ver.outputs.cachebust }}
+          # gh_token: BuildKit secret the Dockerfile consumes to fetch private
+          # cross-org Go modules (hanzoai/*, luxfi/*) over authenticated git.
+          secrets: |
+            gh_token=${{ secrets.GH_PAT }}
+
+      - name: Smoke test — the binary MUST boot to "listening" with no crash signature
+        run: |
+          set -euo pipefail
+          IMAGE=cloud:smoke
+          CID=""
+          cleanup() { [ -n "$CID" ] && docker rm -f "$CID" >/dev/null 2>&1 || true; }
+          trap cleanup EXIT
+
+          # Minimal, production-representative boot env:
+          #  • a writable ephemeral /data root — the audit store, the embedded
+          #    KMS secrets plane and every per-tenant SQLite open files under
+          #    CLOUD_DATA_DIR; an unwritable dir would fail EVERY image before
+          #    MountAll and the gate would stop discriminating good from bad; and
+          #  • a throwaway 32-byte KMS master key so the KMS plane mounts on its
+          #    normal ready path exactly as prod does (no real secret is used).
+          # The subsystem that crashed the incident (metrics, mount order 40)
+          # mounts AFTER kms (order 10), so the boot must get past kms for the
+          # gate to observe the panic — this env does exactly that.
+          KEY="$(head -c 32 /dev/urandom | base64 | tr -d '\n')"
+          CID="$(docker run -d \
+            --tmpfs /data:rw,size=64m \
+            -e CLOUD_DATA_DIR=/data \
+            -e CLOUD_ENV=smoke \
+            -e CLOUD_KMS_MASTER_KEY_REF="$KEY" \
+            "$IMAGE")"
+
+          # Poll up to 60s for boot to either finish ("listening" is logged once
+          # every subsystem has mounted and both transports are about to bind) or
+          # die (a Mount panic exits the process). A healthy boot is ~1-2s; the
+          # ceiling only guards a cold daemon.
+          listening=0
+          for _ in $(seq 1 60); do
+            logs="$(docker logs "$CID" 2>&1 || true)"
+            if printf '%s' "$logs" | grep -q '"message":"listening"'; then listening=1; break; fi
+            if [ "$(docker inspect -f '{{.State.Running}}' "$CID" 2>/dev/null || echo false)" != "true" ]; then break; fi
+            sleep 1
+          done
+
+          logs="$(docker logs "$CID" 2>&1 || true)"
+          echo "::group::cloud:smoke boot logs"
+          printf '%s\n' "$logs"
+          echo "::endgroup::"
+
+          # (1) No startup-crash signature. Catches the incident's Mount
+          #     type-assert panic AND any generic Go panic — case-insensitive so a
+          #     re-worded variant can't slip through — BEFORE a byte is pushed.
+          if printf '%s' "$logs" | grep -Eiq 'metrics\.Mount|mount metrics|panic|want \*zip\.App'; then
+            echo "SMOKE FAIL: startup-crash signature in boot logs (see above)"
+            exit 1
+          fi
+
+          # (2) Reached "listening" — proof that MountAll returned for every
+          #     enabled subsystem (a failed Mount returns before this line).
+          if [ "$listening" -ne 1 ]; then
+            echo "SMOKE FAIL: binary never reached \"listening\" (a subsystem did not mount)"
+            exit 1
+          fi
+
+          # (3) Still alive — a server that logged "listening" then exited (e.g. a
+          #     listener bind failure) is not a healthy image.
+          if [ "$(docker inspect -f '{{.State.Running}}' "$CID" 2>/dev/null || echo false)" != "true" ]; then
+            echo "SMOKE FAIL: process exited after \"listening\""
+            exit 1
+          fi
+
+          echo "SMOKE PASS: cloud:smoke booted to \"listening\" with no crash signature"
+
+      - name: Push (cache hit from the smoke build — publishes the tested image)
+        id: push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: linux/amd64
+          push: true
+          tags: |
+            ghcr.io/hanzoai/cloud:${{ steps.ver.outputs.version_v }}
+            ghcr.io/hanzoai/cloud:${{ steps.ver.outputs.version }}
+            ghcr.io/hanzoai/cloud:${{ steps.ver.outputs.major_minor }}
+            ghcr.io/hanzoai/cloud:sha-${{ steps.ver.outputs.sha_short }}
+            ghcr.io/hanzoai/cloud:latest
+          labels: ${{ steps.meta.outputs.labels }}
+          # SAME cachebust as the smoke build → every layer is a cache hit from step 1
+          # and the pushed image is byte-identical to the one the smoke test proved.
+          build-args: |
+            CONSOLE_CACHEBUST=${{ steps.ver.outputs.cachebust }}
+          secrets: |
+            gh_token=${{ secrets.GH_PAT }}
+
+      # THE RECEIPT: reached only because build + smoke + push all succeeded. If
+      # any of them failed the job already stopped and no tag was minted.
+      - name: Tag the proven image (git tag = receipt for a pushed, smoke-passed image)
+        env:
+          GH_PAT: ${{ secrets.GH_PAT }}
+        run: |
+          set -euo pipefail
+          V="${{ steps.ver.outputs.version_v }}"
+          git config user.name  "hanzo-dev"
+          git config user.email "dev@hanzo.ai"
+          git tag -a "$V" -m "release $V — image ghcr.io/hanzoai/cloud:$V pushed and smoke-passed (${GITHUB_SHA})"
+          git push "https://x-access-token:${GH_PAT}@github.com/${GITHUB_REPOSITORY}.git" "$V"
+          echo "Tagged $V → ghcr.io/hanzoai/cloud:$V"
+
+  # Notify universe so the GitOps pipeline rolls the new image to prod — same
+  # image-update contract every service uses (gateway, iam, …). Runs ONLY after
+  # build-amd64 succeeds, i.e. only for a version whose image is proven pushed and
+  # tagged. A failed release never reaches here, so universe is never asked to
+  # deploy a phantom tag.
+  notify-universe:
+    needs: build-amd64
+    runs-on: [hanzo-build-linux-amd64]
+    steps:
+      - name: Repository dispatch (image-update)
+        uses: peter-evans/repository-dispatch@v3
+        with:
+          token: ${{ secrets.UNIVERSE_DISPATCH_TOKEN }}
+          repository: hanzoai/universe
+          event-type: image-update
+          client-payload: |
+            {
+              "service": "cloud",
+              "image":   "ghcr.io/hanzoai/cloud:${{ needs.build-amd64.outputs.version_v }}",
+              "sha":     "${{ github.sha }}",
+              "env":     "all"
+            }

.gitignore

@@ -0,0 +1,36 @@
+# Built binaries (Dockerfile output + `go build ./cmd/hanzo`)
+/cloud
+/hanzo
+
+# Local build directories
+/dist/
+/build/
+/bin/
+
+# Go test + coverage artifacts
+*.test
+*.out
+coverage.txt
+coverage.html
+
+# Environment files
+.env
+.env.*
+!.env.example
+
+# IDE / editor
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS metadata
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+.shots/
+
+.claude/

AUTH_BILLING_CONTRACT.md

@@ -0,0 +1,208 @@
+# Unified IAM Auth + Tenant Billing Contract
+
+The ONE way every Hanzo product surface authenticates a user and bills their
+usage. hanzo.chat, hanzo.app, studio.hanzo.ai, and console.hanzo.ai all
+implement THIS contract against `hanzoai/cloud` (api.hanzo.ai). There is no
+per-app billing, no shared API key, and no second way to do any of it.
+
+## The chain, end to end
+
+```
+  Browser (a surface)
+    │  1. OIDC Authorization Code + PKCE, PUBLIC client (no client secret)
+    ▼
+  IAM  (hanzo.id / lux.id / zoolabs.id / pars.id …)
+    │  2. issues user tokens. owner claim = the user's org (the tenant).
+    ▼
+  Surface backend / SPA
+    │  3. holds the user's IAM token server-side (session / httpOnly cookie).
+    │     UI's actively-selected (org, project) = the tenant context.
+    │  4. EVERY call to cloud forwards THAT user's IAM bearer, unchanged:
+    │        Authorization: Bearer <user IAM token>
+    │        X-Project-Id:  <active project>     (optional; org comes from token)
+    ▼
+  cloud (api.hanzo.ai)  — SanitizeIdentity → BillingGate
+    │  5. validates the JWT (JWKS sig + issuer-set + audience + exp).
+    │  6. derives (org, project): org is PINNED from the verified `owner`
+    │     claim (client-supplied X-Org-Id is stripped); project is the
+    │     claim-bound X-Project-Id (else soft-scoped).
+    │  7. meters against the org's shared plan allowance; overflow →
+    │     pay-as-you-go on the org's linked billing account.
+    ▼
+  commerce (billing/pricing) — ONE ledger, keyed on (org, project)
+```
+
+One identity (the user's IAM token), one tenant key (org from the token's
+`owner`, project from the active selection), one ledger. Every surface is a thin
+client of this; none of them holds a shared key or bills anything itself.
+
+## 1. Login — OIDC Authorization Code + PKCE, PUBLIC client
+
+- **Public client, no client secret.** The token endpoint auth method is `none`;
+  security comes from PKCE (`code_challenge_method=S256`) + the signed `state`,
+  not a shared secret baked into a browser-delivered app. A public client cannot
+  leak a secret it does not have.
+- Strategy registration MUST NOT be conditioned on a client secret. (The chat
+  login outage was exactly this: `configureOpenId` was gated on
+  `OPENID_CLIENT_SECRET`, so a secretless public client never registered the
+  `openid` passport strategy → "OpenID strategy not registered".)
+- The `owner` claim is the tenant org. `sub` is the user. A surface reads the org
+  from `owner` (fallback `organization`), never from a client-set field.
+- Reference implementation: `studio/middleware/iam_auth_middleware.py`
+  (`_authorize_redirect` builds the PKCE authorize URL; `handle_callback` adds a
+  `client_secret` to the token exchange ONLY if one is configured — public by
+  default).
+
+## 2. Tenant context — active (org, project)
+
+- A user belongs to one or more orgs; the token's `owner` is the home org, and
+  IAM may carry the full set (`organizations`/`orgs`/`groups`).
+- The UI's actively-selected org + project is the tenant context for the session.
+  Studio carries the active org in the `studio_active_org` cookie and validates
+  it against the token's org set (`middleware/session.py: resolve_org`) — a user
+  can only ever select an org their token authorizes.
+- cloud pins the billing org from the VERIFIED `owner` claim, so even a forged
+  active-org header cannot move spend to another tenant. The active project is
+  forwarded as `X-Project-Id` and is honored as a hard scope only when it is
+  claim-bound; otherwise it degrades to a soft scope (cannot hard-stop, cannot be
+  evaded). See `middleware_billing.go: identityFromCtx`.
+
+## 3. Forwarding to cloud — the user's token, never a shared key
+
+- EVERY request to cloud carries `Authorization: Bearer <the signed-in user's IAM
+  token>`. The token is held server-side (session / httpOnly cookie) and is never
+  exposed to the browser JS.
+- The forwarded token MUST be principal-bound to the authenticated user (`sub`
+  equals the session principal) and unexpired. Fail secure: if no such token is
+  available, DENY (401 / "sign in") — never fall back to an ambient or service
+  credential, which would run as the wrong principal or drain a shared org.
+- NO shared keys. NO per-app keys. NO per-user minted `hk-` keys for chat. The
+  IAM token IS the credential and the billing identity.
+- Reference implementations:
+  - `chat/api/server/routes/agents/cloud.js` +
+    `chat/packages/api/src/endpoints/custom/tenantBearer.ts` — the ONE resolver
+    (`resolveTenantBearer`) both the agents path and the chat-completion path use.
+  - The chat-completion endpoints declare `apiKey: "{{LIBRECHAT_OPENID_TOKEN}}"`;
+    the custom-endpoint initializer substitutes the resolved session bearer at
+    request time (`chat/packages/api/src/endpoints/custom/initialize.ts`).
+
+## 4. Billing — ONE path keyed on (org, project)
+
+cloud is the single meter and gate. `SanitizeIdentity` (mirrored in-binary by
+`auth_identity.go`) validates the token and exposes `c.Org()` / `c.User()` /
+`ValidatedProject(c)`. `BillingGate` (`middleware_billing.go`) then:
+
+- **Billing key = org.** Prepaid balance is per-org: one org credit covers the
+  whole org. `identityFromCtx` sets `User = org` (bare `sub` only when org is
+  absent). Keying per-user would 402 a fully funded org.
+- **Scope axes = (project, service).** `project` is the caller's claim-bound
+  `X-Project-Id`; `service` is SERVER-derived from the route (`/v1/ai/*` → `ai`),
+  never a client field, so a caller cannot spoof another service's cap.
+- **Shared plan, then PAYG.** `AuthorizeVerdict` checks the org's shared plan
+  allowance and per-scope spend caps in one round trip; overflow bills
+  pay-as-you-go against the org's linked billing account. Outcomes map to a frozen
+  HTTP contract:
+  - `200` allowed (with `X-Spend-Warn: <pct>` at a soft cap threshold),
+  - `402 insufficient_balance` — add credits at console.hanzo.ai,
+  - `402 spend_cap_exceeded` — raise the scope cap at console.hanzo.ai/limits,
+  - `503 balance_unavailable` — commerce unreachable, fail-closed.
+- **Single charge.** `/v1/ai/*`, `/v1/agents/*`, and the other self-metering
+  subsystems record their own per-org usage; the edge gate returns price 0 for
+  them so nothing is billed twice (`DefaultPrice` / `selfMeteredPrefixes`).
+
+## 4a. Per-product metering + the product/agent cost axes
+
+Two metering seams share the ONE commerce ledger (`Deps.Metering`):
+
+- **`BillingGate`** (`middleware_billing.go`) — the request EDGE, priced by PATH
+  (`DefaultPrice`). `/v1/ai/*` self-meters token spend upstream (gateway/ai), so it
+  is price-0 here to avoid double-billing.
+
+  **Auto-routing binds to the resolved model.** ai serves a virtual `auto`
+  (alias `zen-router`) model that it resolves to a concrete model id *before*
+  pricing/billing, then meters its own token cost keyed on the SERVED model and
+  reports it via the `X-Routed-Model` response header (echoed in the body
+  `model`). Because the edge prices `/v1/ai/*` by PATH (0), never by the request
+  model, `auto` bills as whatever it resolved to — the ai per-token meter is the
+  single source of the charge. The edge passes `X-Routed-Model` through untouched,
+  so the model reported to the client equals the model billed. Proven end-to-end:
+  `auto_routing_billing_test.go` (`TestAutoRoutingBillsAsResolvedModel`,
+  `TestDefaultPriceAiPathModelAgnostic`).
+- **`ResourceMeter`** (`resource_billing.go`) — IN-HANDLER, priced per-org after the
+  caller's org is resolved. Every non-LLM product uses it: `Gate` (fail-closed
+  pre-auth, `available >= fee`, default fee $1.00 / `DefaultResourceFeeCents`) then
+  `Meter`/`MeterUsage` (debit-on-success, `provider = <product>`). Balance floor is
+  enforced BY DEFAULT — a zero/negative-balance priced call → **402** (proven:
+  `clients/{functions,s3,agents,ml,provisioning}/billing_test.go` `*RefusesUnfundedOrg`).
+
+Metering+gating coverage (each meters its OWN org, debits on success):
+
+| Product | provider label | fee knob | code |
+|---|---|---|---|
+| functions | `functions` | `CLOUD_FUNCTIONS_FEE_CENTS` | `clients/functions/invoke.go` |
+| s3 | `s3` | `S3_*` | `clients/s3/s3.go` |
+| agents | `agent` | `CLOUD_AGENT_FEE_CENTS` | `clients/agents/agents.go` |
+| compute / GPU | `compute` | provision knobs | `clients/ml/ml.go`, `clients/visor/*` |
+| provisioning (sql/kv/vector/docdb) | `provisioning` | `CLOUD_PROVISION_FEE_CENTS[_KIND]` | `clients/provisioning/*` |
+| automations | `automations` | `CLOUD_AUTOMATIONS_FEE_CENTS` | `clients/automations/automations.go` |
+| tracker | `tracker` | fee knob | `clients/tracker/tracker.go` |
+| security | `security.scan` | — | `clients/security/security.go` |
+
+**Product/agent read axes.** The console's per-product Metrics dashboard groups on
+`metadata.product` (and `metadata.agent`). Commerce's `RecordUsage` persists the
+metering SURFACE (`provider`) and billed UNIT (`model`) but has **no `product`
+field** (its `usageRequest` drops `project`/`service`/`product`/`agent`). So the
+customer read handler `clients/billing/usage.go` is the ONE read-side adapter:
+`usage()` fetches the org-scoped ledger and, on 200, injects a canonical
+`metadata.product` onto every row (`productOf`: `agent→agents`,
+`provisioning→<kind>`, token-metered→`inference`, else `provider`) so the
+breakdowns POPULATE from the SAME charged ledger. It also honors, server-side (was
+silently ignored):
+
+- `GET /v1/billing/usage?product=<id>` — filter to one product,
+- `GET /v1/billing/usage?groupBy=product` — per-product rollup
+  `{product,requests,amountCents}`.
+
+A row that already carries `metadata.product`/`agent` wins, so this degrades to a
+no-op when the meter/commerce persist them natively (forward-compatible).
+
+**Remaining checklist** (each is the same seam):
+
+1. **Native `product`/`agent` fields** — add `Product`/`Agent` to
+   `commerce/metering.Usage` + `commerce` `usageRequest`/metadata, have each
+   `ResourceMeter` caller pass its product id, and drop the read-side `productOf`
+   derivation (decomplect: the meter KNOWS its product; record it, don't re-derive).
+   Cross-repo (commerce) — additive/backward-compatible.
+2. **Agent-NAME axis** — needs (1): the agent run debit records `provider=agent` +
+   `model=<llm>` but not the agent name, so `metadata.agent` stays honest-empty
+   until commerce persists an `agent` field the agents meter sets to `a.Name`.
+3. **compute split** — `ml` (predict) and `visor` (GPU) both meter `provider=compute`;
+   read-side can't split `inference` vs `gpus`. Needs (1) so each sets its product id.
+4. **exec / containers** (`clients/exec`, Code Interpreter) — authed by a shared
+   service key (X-API-Key), NO per-org identity, so it can't meter per-org; its
+   compute is billed upstream at the chat/agent layer that invokes it.
+5. **playground** — routes to `/v1/ai/*`, already metered as AI inference.
+
+## 5. Secrets
+
+- Per-tenant, KMS-managed only (`kms.hanzo.ai`, KMSSecret CRDs). No shared
+  service key stands in for a user. The only service tokens that exist are
+  narrow, per-tenant, and never used to impersonate a user for LLM spend.
+- A surface's own OIDC registration is a PUBLIC client — there is no client
+  secret to store.
+
+## Surface conformance (as of this contract)
+
+| Surface | Login (PKCE public) | Forwards user token | Org from `owner` | Billed via cloud (org,project) |
+|---|---|---|---|---|
+| **studio.hanzo.ai** | ✅ reference | ✅ (validates locally) | ✅ | ⚠️ renders run on studio's own GPU workers and self-report to commerce keyed by org via a per-tenant commerce token — org-keyed, but not the forward-bearer-to-gateway path (studio does not call the cloud LLM gateway for its core renders) |
+| **console.hanzo.ai** | ✅ | ✅ same-origin `/v1` through the gateway | ✅ | ✅ (it IS the canonical consumer) |
+| **hanzo.chat** | ✅ (this change) | ✅ (this change: `resolveTenantBearer`) | ✅ | ✅ (this change: forwards bearer to `/v1/ai/*`) |
+| **hanzo.app** | ❌ confidential client (`IAM_CLIENT_SECRET`, userinfo/introspect) | ✅ to its own backend; org from token `owner` | ✅ | ❌ builder AI runs on OpenRouter with an apiKey (`lib/llm/generation-api.ts`), NOT the cloud gateway — off the unified meter |
+
+hanzo.app is the remaining gap: it needs the same treatment chat just got — switch
+its IAM registration to a PKCE public client, and route its builder AI generation
+through api.hanzo.ai forwarding the user's IAM bearer so usage meters against the
+org plan instead of a shared OpenRouter key.
+</content>
+</invoke>

Dockerfile

@@ -1,11 +1,216 @@
-FROM golang:1.26-alpine AS build
-RUN apk add --no-cache ca-certificates tzdata
-RUN addgroup -g 65532 -S nonroot && adduser -u 65532 -S nonroot -G nonroot
-WORKDIR /src
-COPY . .
-RUN CGO_ENABLED=0 go build -ldflags="-s -w" -o /cloud ./cmd/cloud
+# hanzoai/cloud — the ONE unified Hanzo Cloud binary (HIP-0106).
+#
+# This image is a SINGLE artifact that serves BOTH the /v1 API AND the console
+# UI from one process: the console is compiled into the Go binary via
+# //go:embed (see webui.go). The pipeline is:
+#
+#   1. console  stage → build the hanzoai/console static bundle
+#   2. (copied) → into  webui/dist/  of the Go build context
+#   3. build    stage → `go build` bakes webui/dist into the binary (go:embed)
+#
+# so the final `/cloud` binary already carries the UI. No separate console
+# Service, no second origin — the embedded console calls /v1 on its own host.
+#
+# ── console UI stage ─────────────────────────────────────────────────────────
+# Builds the console SPA and emits a STATIC bundle at /out. console is fetched
+# at a pinned ref (CONSOLE_REF) using the same gh_token BuildKit secret the Go
+# build uses for private modules.
+#
+# console exposes `npm run build:embed` (scripts/build-embed.mjs): it prunes the
+# Next server route handlers (BFF proxies — they collapse to the cloud /v1/* the
+# SPA calls same-origin), wraps the client catch-all pages for output:'export',
+# and neutralizes the root layout's request-time headers() read (the per-host
+# <title>, resolved client-side in the embed) so the STATIC export prerenders
+# clean — emitting out/. This stage runs it and copies out/ into /out, which the
+# Go build drops into webui/dist so //go:embed bakes the FULL @hanzo/gui console
+# into the ONE binary. This stage FAILS HARD: the prod image MUST carry the real
+# console — a missing/broken build:embed is a build ERROR, never a silent degrade
+# to the placeholder shell. The one escape hatch is --build-arg ALLOW_PLACEHOLDER=1
+# (pure-Go dev image with no Node console), which is NEVER set for prod.
+FROM public.ecr.aws/docker/library/node:24-alpine@sha256:a0b9bf06e4e6193cf7a0f58816cc935ff8c2a908f81e6f1a95432d679c54fbfd AS console
+ARG CONSOLE_REPO=https://github.com/hanzoai/console.git
+ARG CONSOLE_REF=main
+# CONSOLE_CACHEBUST busts this stage's BuildKit layer cache every build. WHY it must
+# exist: the clone+build layer's cache key is derived from the RUN text + build args.
+# With only a static `git clone --branch main`, the key NEVER changes, so on the
+# persistent ARC dind BuildKit cache every cloud image re-embedded the SAME frozen
+# console snapshot — new console work (the native Tracker, …) silently never shipped,
+# even on a freshly-built+deployed image. release.yml feeds this the cloud commit sha
+# (unique per push) so the clone RUN re-runs each build and re-fetches console
+# ${CONSOLE_REF} (main HEAD) fresh. Correctness over cache reuse: the console stage
+# rebuilds every time, but the embed is never stale.
+ARG CONSOLE_CACHEBUST=none
+RUN apk add --no-cache git
+WORKDIR /console
+# The static export prerenders every page (webpack compile + export prerender);
+# give the heap headroom so a large @hanzo/gui build never OOMs into the stub.
+ENV NEXT_TELEMETRY_DISABLED=1 NODE_OPTIONS=--max-old-space-size=8192
+# Hanzo Analytics: the console's <HanzoAnalytics/> (env-gated) renders the one
+# native analytics.hanzo.ai tag only when a website-id is baked in. Default to the
+# console.hanzo.ai property (7dce54ee, public per-site) so console+team track on
+# the next cloud build. GA4/Pixel stay off (unset). Public id, not a KMS secret.
+ARG NEXT_PUBLIC_ANALYTICS_WEBSITE_ID=7dce54ee-41f6-4751-96bf-fe005067c7c7
+ENV NEXT_PUBLIC_ANALYTICS_WEBSITE_ID=$NEXT_PUBLIC_ANALYTICS_WEBSITE_ID
+RUN --mount=type=secret,id=gh_token \
+    if [ -s /run/secrets/gh_token ]; then \
+      git config --global url."https://x-access-token:$(cat /run/secrets/gh_token)@github.com/".insteadOf "https://github.com/"; \
+    fi && \
+    echo ">> embedding console ${CONSOLE_REF} (cachebust ${CONSOLE_CACHEBUST})" && \
+    git clone --depth 1 --branch "${CONSOLE_REF}" "${CONSOLE_REPO}" . && \
+    echo ">> console @ $(git rev-parse HEAD)" && \
+    npm install --no-audit --no-fund --fetch-retries=5 --fetch-retry-mintimeout=20000 --fetch-timeout=120000
+# FAIL-HARD. build:embed MUST emit a REAL bundle — a non-empty out/index.html AND
+# an out/_next/ chunk dir — and /out then carries it into the Go embed path. If the
+# target is absent, the export fails, or the output is the placeholder shape, this
+# is a build ERROR (exit 1): the prod image can NEVER silently ship the committed
+# fallback shell. Escape hatch: --build-arg ALLOW_PLACEHOLDER=1 leaves /out empty
+# (Go build keeps the committed shell) for a pure-Go dev image — NEVER set in prod.
+ARG ALLOW_PLACEHOLDER=0
+RUN mkdir -p /out; \
+    ok=0; \
+    if npm run 2>/dev/null | grep -q ' build:embed'; then \
+      if npm run build:embed && [ -s out/index.html ] && [ -d out/_next ]; then \
+        cp -r out/. /out/; \
+        echo ">> embedded REAL console static bundle: $(wc -c < out/index.html)-byte index.html, $(du -sh out/_next | cut -f1) _next/"; \
+        ok=1; \
+      else \
+        echo ">> console build:embed produced NO real bundle (missing/empty out/index.html or out/_next)"; \
+      fi; \
+    else \
+      echo ">> console exposes no build:embed target"; \
+    fi; \
+    if [ "$ok" != "1" ]; then \
+      if [ "$ALLOW_PLACEHOLDER" = "1" ]; then \
+        echo ">> ALLOW_PLACEHOLDER=1 — keeping committed fallback shell (DEV image only; NEVER prod)"; \
+      else \
+        echo ">> FATAL: refusing to ship the placeholder console. Fix the console build:embed, or pass --build-arg ALLOW_PLACEHOLDER=1 for a pure-Go dev image."; \
+        exit 1; \
+      fi; \
+    fi
 
-FROM scratch
+# ── Go build stage (CGO=1 + SQLCipher — REAL at-rest encryption) ─────────────
+# The unified binary embeds IAM (clients/iam) whose per-org store is SQLCipher-
+# encrypted (orgIsolation=sqlite), and commerce's per-tenant money DBs likewise.
+# A CGO=0 modernc build SILENTLY SHIPS PLAINTEXT. So this builds CGO=1 against
+# system libsqlcipher — hanzoai/iam's proven recipe: the `libsqlite3` tag + a
+# libsqlcipher symlink + -DSQLITE_HAS_CODEC, with the modernc double-registration
+# guard, TestEncryptionProof, and the cek.go golden-vector KAT baked in — so a
+# build that fails to link REAL SQLCipher, or that would decrypt existing stores
+# differently, produces NO image. alpine3.22 MATCHES the runtime base so the
+# libsqlcipher soname the binary links is the SAME one present at runtime. ECR
+# Public mirror avoids Docker Hub's 429 rate-limit on shared CI runners.
+# ---- agent-skills stage: regenerate the FULL /.well-known/agent-skills catalog
+# from the hanzoai/openapi SOT (skills.py) and carry it into the Go embed path
+# BEFORE `go build`, the SAME way the console bundle is produced. The committed
+# catalog is only the tiny `ai` fallback; prod must embed the full set. FAIL-HARD:
+# if the clone/generation can't produce the master index, the image is not built.
+FROM public.ecr.aws/docker/library/python:3.12-alpine AS skills
+ARG OPENAPI_REPO=https://github.com/hanzoai/openapi.git
+ARG OPENAPI_REF=main
+RUN apk add --no-cache git && pip install --no-cache-dir pyyaml
+WORKDIR /openapi
+RUN --mount=type=secret,id=gh_token \
+    if [ -s /run/secrets/gh_token ]; then \
+      git config --global url."https://x-access-token:$(cat /run/secrets/gh_token)@github.com/".insteadOf "https://github.com/"; \
+    fi && \
+    git clone --depth 1 --branch "${OPENAPI_REF}" "${OPENAPI_REPO}" . && \
+    python3 skills.py --no-services --out /catalog && \
+    test -s /catalog/hanzo/index.json
+
+FROM public.ecr.aws/docker/library/golang:1.26-alpine3.22@sha256:727cfc3c40be55cd1bc9a4a059406b28a059857e3be752aa9d09531e12c20c56 AS build
+# CIPHER-FORMAT FREEZE (cek depends on this). The data-plane stores are
+# SQLCipher pages in a fixed on-disk format (cipher_compatibility 4). An at-open
+# compat pin is infeasible (mattn keys via URI before any pragma), so the format
+# is frozen by pinning sqlcipher-dev to an EXACT version. A repo bump then fails
+# the build LOUDLY (never a silent prod brick); on such a failure, bump the pin
+# AND confirm cek's frozen-fixture test still opens (format unchanged)
+# before shipping. A MAJOR bump (4.x → 5.x) changes the default format and would
+# orphan existing encrypted stores — migrate/rewrap them first.
+RUN apk add --no-cache ca-certificates tzdata git gcc musl-dev sqlcipher-dev=4.6.1-r0 pkgconfig binutils
+RUN addgroup -g 65532 -S nonroot && adduser -u 65532 -S nonroot -G nonroot
+# mattn/go-sqlite3's `libsqlite3` tag hard-codes `-lsqlite3`, but alpine's
+# sqlcipher-dev ships ONLY libsqlcipher (no libsqlite3.so). Symlink so the link
+# resolves -lsqlite3 to libsqlcipher — REAL encryption. Do NOT `apk add sqlite-dev`
+# (a plaintext libsqlite3 would silently disable the codec; the gate below catches it).
+RUN set -eux; \
+    SC="$(find /usr/lib /lib -name 'libsqlcipher.so*' 2>/dev/null | sort | head -1)"; \
+    test -n "$SC"; \
+    ln -sf "$SC" /usr/lib/libsqlite3.so; \
+    ln -sf "$SC" /usr/lib/libsqlite3.so.0
+WORKDIR /src
+# hanzoai/* and luxfi/* are PUBLIC and resolve via the IMMUTABLE public proxy +
+# sumdb — go.sum pins those canonical hashes, so a force-re-pointed tag can never
+# break the build. GOSUMDB stays ON (a money image must not blanket-disable the
+# checksum database); only zap-proto/* is exempt (first-party-direct via GOPRIVATE,
+# authenticated git over gh_token). -mod=readonly means the committed go.sum is the
+# SOLE source of truth: any drift (a needed hash not present) FAILS the build
+# instead of being silently re-recorded. CGO_CFLAGS/LDFLAGS enable the SQLCipher
+# codec + URI keying.
+ENV CGO_CFLAGS="-DSQLITE_HAS_CODEC -DSQLITE_USE_URI=1 -I/usr/include/sqlcipher" \
+    CGO_LDFLAGS="-lsqlcipher" \
+    GOPRIVATE=github.com/zap-proto/* \
+    GONOSUMDB=github.com/zap-proto/* \
+    GOPROXY=https://proxy.golang.org,direct \
+    GOFLAGS=-mod=readonly
+COPY go.mod go.sum ./
+RUN --mount=type=secret,id=gh_token \
+    --mount=type=cache,target=/go/pkg/mod,sharing=locked \
+    if [ -s /run/secrets/gh_token ]; then \
+      git config --global url."https://x-access-token:$(cat /run/secrets/gh_token)@github.com/".insteadOf "https://github.com/"; \
+    fi && \
+    go mod download
+COPY . .
+# Drop the console static bundle into the embed path BEFORE `go build`, so
+# //go:embed all:webui/dist bakes it into the binary (same-origin console).
+COPY --from=console /out/ /src/webui/dist/
+# Overlay the FULL agent-skills catalog before `go build` so //go:embed all:catalog
+# bakes the complete set (all services × brands), not the committed `ai` fallback.
+COPY --from=skills /catalog/ /src/clients/agentskills/catalog/
+# RED gate — modernc double-registration guard: 0 modernc under CGO=1, else the
+# "sqlite" driver is registered twice (mattn + modernc) → panic at init.
+RUN --mount=type=cache,target=/go/pkg/mod,sharing=locked \
+    --mount=type=cache,target=/root/.cache/go-build,sharing=locked \
+    MODERNC="$(CGO_ENABLED=1 go list -tags "libsqlite3 sqlite_fts5" -deps ./cmd/cloud 2>/dev/null | grep -c 'modernc.org/sqlite' || true)"; \
+    [ "$MODERNC" = "0" ] || { echo "SQLITE-GATE FAIL: cmd/cloud links modernc.org/sqlite ($MODERNC pkgs) under CGO=1 — double-registers \"sqlite\" with hanzoai/sqlite(mattn) and panics at init."; exit 1; }
+# RED gate — ENCRYPTION PROOF + the cek.go GOLDEN-VECTOR KAT, under the SAME CGO +
+# libsqlcipher build this image ships. TestEncryptionProof asserts real
+# ciphertext-at-rest (SQLITE_REQUIRE_CODEC=1 makes a plaintext link FAIL → NO
+# image). TestUnwrapGoldenFixture asserts a FROZEN pre-luxfi-swap 61-byte DEK
+# sidecar still decrypts under the shipped luxfi/crypto-AEAD code — existing
+# encrypted stores stay readable, or NO image.
+RUN --mount=type=cache,target=/go/pkg/mod,sharing=locked \
+    --mount=type=cache,target=/root/.cache/go-build,sharing=locked \
+    SQLITE_REQUIRE_CODEC=1 CGO_ENABLED=1 go test -count=1 -tags "libsqlite3 sqlite_fts5" \
+      -run 'TestEncryptionProof|TestUnwrapGoldenFixture|TestWrapUnwrapRoundTripPinsLayout' \
+      github.com/hanzoai/sqlite
+# RED gate — cek FROZEN-FORMAT guard, run INSIDE the image under the pinned Alpine
+# libsqlcipher: opens the committed encrypted fixture and reads its canary row. A
+# sqlcipher-dev pin/base bump that changes the on-disk format fails the IMAGE build
+# HERE (not only Go CI) → a silent prod brick of existing stores becomes a red build.
+RUN --mount=type=cache,target=/go/pkg/mod,sharing=locked \
+    --mount=type=cache,target=/root/.cache/go-build,sharing=locked \
+    SQLITE_REQUIRE_CODEC=1 CGO_ENABLED=1 go test -count=1 -run TestFrozenFixtureOpens \
+      -tags "libsqlite3 sqlite_fts5" ./cek
+RUN --mount=type=cache,target=/go/pkg/mod,sharing=locked \
+    --mount=type=cache,target=/root/.cache/go-build,sharing=locked \
+    CGO_ENABLED=1 go build -tags "libsqlite3 sqlite_fts5" -ldflags="-s -w" -o /cloud ./cmd/cloud
+# Prove the SHIPPED binary binds sqlite3_* to libsqlcipher, not a plaintext libsqlite3.
+RUN readelf -d /cloud | grep -qE 'NEEDED.*(sqlcipher|sqlite3)' || { echo "FATAL: /cloud links no sqlite/sqlcipher .so"; exit 1; }; \
+    ! ldd /cloud 2>/dev/null | grep -E 'libsqlite3' | grep -vq 'libsqlcipher' || { echo "FATAL: /cloud resolves a NON-sqlcipher libsqlite3 (plaintext risk)"; exit 1; }
+
+# ── final image (alpine, NOT scratch — CGO needs libc + libsqlcipher) ─────────
+FROM public.ecr.aws/docker/library/alpine:3.22@sha256:14358309a308569c32bdc37e2e0e9694be33a9d99e68afb0f5ff33cc1f695dce
+ARG REVISION=unknown
+LABEL org.opencontainers.image.revision="${REVISION}" \
+      org.opencontainers.image.source="https://github.com/hanzoai/cloud"
+# Runtime needs libsqlcipher (the codec the binary links). It must NOT also carry
+# a plaintext libsqlite3 — the binary's -lsqlite3 DT_NEEDED would then bind to
+# plaintext sqlite and silently no-op PRAGMA key. sqlcipher-libs ships
+# libsqlcipher.so.0; alias libsqlite3.so.0 to it so sqlite3_* binds there.
+RUN apk add --no-cache ca-certificates tzdata sqlcipher-libs \
+    && SC="$(find /usr/lib /lib -name 'libsqlcipher.so*' 2>/dev/null | sort | head -1)" \
+    && test -n "$SC" \
+    && ln -sf "$SC" /usr/lib/libsqlite3.so.0
 COPY --from=build /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/ca-certificates.crt
 COPY --from=build /usr/share/zoneinfo /usr/share/zoneinfo
 COPY --from=build /etc/passwd /etc/passwd

LICENSE

@@ -0,0 +1,203 @@
+Copyright (c) 2026 Hanzo AI Inc.
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright (c) 2026 Hanzo AI Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

LLM.md

@@ -0,0 +1,60 @@
+# LLM.md — hanzoai/cloud
+
+Guidance for AI agents working in this repo. `hanzoai/cloud` (HIP-0106) is ONE Go
+binary + CLI that mounts every Hanzo subsystem into a single process; the same
+artifact serves `api.hanzo.ai`, `api.lux.cloud`, `api.zoo.cloud`, `api.osage.cloud`
+and every white-label reseller. Brand, enabled subsystems, and org scope are
+deployment configuration.
+
+## Framework doctrine
+
+One way to do everything. Composable, orthogonal, DRY. A new subsystem is a
+package under `clients/<name>` that obeys these seams — nothing more.
+
+- **Subsystem shape.** A subsystem exposes `func Mount(app *zip.App, deps cloud.Deps) error`
+  and self-registers at init with `cloud.Register("<name>", <order>, cloud.Typed(Mount))`
+  (or `RegisterWithShutdown`). `Mount` wires that subsystem's `/v1/<name>/*` routes
+  onto the shared `*zip.App`; `cloud.Deps` carries the process-wide handles
+  (Logger, DataDir, the subsystem `Client` seams). No subsystem reaches into
+  another's internals.
+- **Client seams.** Cross-subsystem calls go through a narrow in-process interface
+  published in `types` and aliased at the provider, e.g. `commerce.Client =
+  types.CommerceClient` (`GetOrgConfig` + `CheckEntitlement`). Consumers depend on
+  the interface, never the implementation; the seam rides zap-proto/zip. Keep each
+  interface minimal — add a method only when a consumer needs it.
+- **Composition root.** `subsystems/subsystems.go` blank-imports every subsystem
+  (its init runs `cloud.Register`), populating `cloud.Registry`. `MountAll`
+  (build.go) sorts the registry by `Order` and calls `Mount` on each ENABLED
+  subsystem (`cfg.Enabled`). That ordered blank-import set IS the wiring — there
+  is no separate `Wire()` function; to add a subsystem you add one import line.
+- **Route precedence is a framework guarantee.** The router is zap-proto/fiber
+  (zip v1.3.0). Most-specific route wins regardless of mount order; a genuine
+  route CONFLICT panics at mount rather than resolving ambiguously. Subsystems may
+  therefore mount in any order and still compose deterministically.
+- **Per-org data.** The ONE way any subsystem opens a per-org SQLite file is
+  `cloud.OrgDB(dataDir, org, project, sub)` — or the cached `cloud.OrgStore[T]`
+  (`NewOrgStore` + `For(org, project)`). Path convention:
+  `{DataDir}/orgs/{org}/{sub}.db`, or `{DataDir}/orgs/{org}/projects/{project}/{sub}.db`
+  when project-scoped. Isolation is PHYSICAL: a distinct `(org[, project])` is a
+  distinct file. `org`/`project` MUST be the VALIDATED principal values
+  (`principal.Org(c)`, `principal.Project(c)`) — never a raw body/header — and are
+  folded through `SanitizeOrg`, the ONE injective org slugger. hanzoai/sqlite is
+  the SOLE driver (blank-imported once, in orgdb.go); subsystems never import a
+  SQLite driver themselves. The caller owns its schema/migration and Close.
+
+## Identity vocabulary is IAM-native
+
+Identity is expressed ONLY in IAM-native nouns: **org, user, project, billing
+account**. The word **"tenant" is banned** in cloud identifiers, strings,
+comments, and filenames. Resolve org/project scope through `clients/principal`
+(`principal.Org(c)`, `principal.Project(c)`) and user identity through `c.User()`
+— all gateway-minted, JWT-validated values (X-Org-Id / X-Project-Id / X-User-Id,
+HIP-0026); never read a raw request header for scope.
+
+- **The one gated exception.** `clients/platform` derives customer-app Kubernetes
+  namespaces, registry image refs, and quota/limit objects from a live `tenant-<org>`
+  string prefix. Renaming that prefix orphans deployed namespaces + built images,
+  so the literal `"tenant-"` string (and its directly-adjacent comment) is retained
+  behind a `// NAMING(gated)` note in `clients/platform/k8s.go`. The surrounding
+  identity vocabulary is org-native regardless; only the on-cluster string waits on
+  an infrastructure migration.

Makefile

@@ -0,0 +1,86 @@
+# hanzoai/cloud — developer ergonomics for the unified Hanzo Cloud binary (HIP-0106).
+# Targets are intentionally minimal; deploy artifacts (compose, helm) live in deploy/ and helm/.
+
+GO              ?= go
+BIN             ?= cloud
+PKG             ?= ./cmd/cloud
+DOCKER_IMAGE    ?= ghcr.io/hanzoai/cloud
+DOCKER_TAG      ?= dev
+LDFLAGS         ?= -s -w
+# Path to a hanzoai/console checkout used to build the embedded console bundle.
+CONSOLE_DIR    ?= ../console
+# Path to a hanzoai/openapi checkout — the SOT the agent-skills catalog is generated from.
+OPENAPI_DIR    ?= ../openapi
+
+# The shipped binary is pure Go (Dockerfile: CGO_ENABLED=0 → scratch). Default all
+# build/test targets to that mode so `make build`/`make test` exercise exactly
+# what prod runs — and, critically, register the ONE "sqlite" driver exactly once:
+# cloud's stores use github.com/hanzoai/sqlite (its !cgo backend IS modernc), and
+# the embedded deps (ai/base/commerce/o11y/orm/tasks) that import modernc directly
+# then resolve to the SAME package → a single registration. A plain CGO_ENABLED=1
+# build instead links the fork's mattn backend ALONGSIDE those modernc importers
+# and panics at init ("sql: Register called twice for driver sqlite"); `make
+# test-cgo` proves the cgo path via the fork's `sqlite_purego` opt-out tag, which
+# forces the fork to modernc too so the whole binary registers "sqlite" once.
+CGO_ENABLED     ?= 0
+
+.PHONY: help webui agentskills build build-standalone hanzo run smoke test test-cgo vet tidy docker docker-push clean
+
+help: ## Show this help.
+	@awk 'BEGIN{FS=":.*##";printf "\nUsage: make <target>\n\nTargets:\n"} /^[a-zA-Z_-]+:.*##/{printf "  \033[36m%-16s\033[0m %s\n", $$1, $$2}' $(MAKEFILE_LIST)
+
+webui: ## Build the real console static bundle into webui/dist (go:embed source). CONSOLE_DIR=<path to console>.
+	@command -v npm >/dev/null 2>&1 || { echo "npm is required to build the console bundle"; exit 1; }
+	@test -f "$(CONSOLE_DIR)/package.json" || { echo "console checkout not found at $(CONSOLE_DIR) — set CONSOLE_DIR=<path>"; exit 1; }
+	@test -d "$(CONSOLE_DIR)/node_modules" || (cd "$(CONSOLE_DIR)" && npm install --no-audit --no-fund)
+	cd "$(CONSOLE_DIR)" && NEXT_TELEMETRY_DISABLED=1 NODE_OPTIONS=--max-old-space-size=8192 npm run build:embed
+	# Overlay the fresh static export onto webui/dist, keeping only the tracked
+	# fallbacks (.gitignore + assets/.gitkeep); the real bundle is build-time-only.
+	find webui/dist -mindepth 1 -maxdepth 1 ! -name .gitignore ! -name assets -exec rm -rf {} +
+	cp -r "$(CONSOLE_DIR)/out/." webui/dist/
+	@echo ">> embedded real console bundle into webui/dist (index.html $$(wc -c < webui/dist/index.html) bytes)"
+
+agentskills: ## Regenerate the FULL agent-skills catalog into clients/agentskills/catalog (go:embed source) from the openapi SOT. OPENAPI_DIR=<path to openapi>.
+	@test -f "$(OPENAPI_DIR)/skills.py" || { echo "openapi checkout not found at $(OPENAPI_DIR) — set OPENAPI_DIR=<path> or clone hanzoai/openapi"; exit 1; }
+	# skills.py rewrites the whole catalog dir; the .gitignore keeps only the tiny
+	# `ai` fallback tracked, so the full set is embedded at build but never committed.
+	python3 "$(OPENAPI_DIR)/skills.py" --no-services --out clients/agentskills/catalog
+	@echo ">> embedded FULL agent-skills catalog ($$(jq -r .skill_count clients/agentskills/catalog/hanzo/index.json) skills/brand)"
+
+build: ## Build the unified cloud binary into ./bin/cloud (embeds whatever webui/dist holds — run `webui` first for the real console).
+	@mkdir -p bin
+	CGO_ENABLED=$(CGO_ENABLED) $(GO) build -ldflags="$(LDFLAGS)" -o bin/$(BIN) $(PKG)
+
+build-standalone: webui build ## Build the REAL 1-binary console: console build:embed → webui/dist → go build.
+
+hanzo: ## Build the hanzo control-plane CLI into ./bin/hanzo (pure Go, same mode as cmd/cloud — registers the ONE "sqlite" driver exactly once; a plain CGO_ENABLED=1 `go build ./cmd/hanzo` links the fork's mattn backend alongside the embedded modernc importers and panics, see header).
+	@mkdir -p bin
+	CGO_ENABLED=$(CGO_ENABLED) $(GO) build -ldflags="$(LDFLAGS)" -o bin/hanzo ./cmd/hanzo
+
+run: build ## Run with iam,base,kms,gateway,o11y enabled (matches README quickstart).
+	./bin/$(BIN) --enable=iam,base,kms,gateway,o11y --brand=hanzo --domain=api.hanzo.ai
+
+smoke: ## Build and run cmd/cloud-smoke (mount-time integration check).
+	$(GO) run ./cmd/cloud-smoke
+
+test: ## Run unit + integration tests (pure-Go, exactly as prod ships).
+	CGO_ENABLED=$(CGO_ENABLED) $(GO) test ./...
+
+test-cgo: ## Prove the cgo build works too — forces the fork's pure-Go backend via -tags sqlite_purego so the embedded modernc importers don't double-register "sqlite".
+	CGO_ENABLED=1 $(GO) test -tags sqlite_purego ./...
+
+vet: ## go vet across the module.
+	CGO_ENABLED=$(CGO_ENABLED) $(GO) vet ./...
+
+tidy: ## go mod tidy + verify go.sum.
+	$(GO) mod tidy
+	$(GO) mod verify
+
+docker: ## Build the Docker image (uses repo Dockerfile, scratch final stage).
+	docker build -t $(DOCKER_IMAGE):$(DOCKER_TAG) .
+
+docker-push: docker ## Push the Docker image to ghcr.io. Requires docker login.
+	docker push $(DOCKER_IMAGE):$(DOCKER_TAG)
+
+clean: ## Remove built artifacts.
+	rm -rf bin

README.md

@@ -1,3 +1,5 @@
+<p align="center"><img src=".github/hero.svg" alt="cloud" width="880"></p>
+
 # cloud
 
 Unified Go control plane and binary for the Hanzo platform (HIP-0106).
@@ -13,7 +15,37 @@ docker run -p 8080:8080 ghcr.io/hanzoai/cloud:latest
 
 ## What this is
 
-`hanzoai/cloud` is one Go binary that mounts every Hanzo subsystem (iam, kms, base, gateway, ai, commerce, vfs, mq, dns, amqp, mcp, o11y, ...) into a single multi-tenant process. Same artifact serves `api.hanzo.ai`, `api.osage.cloud`, `api.lux.cloud`, `api.zoo.cloud`, and every white-label reseller. Brand, enabled subsystems, and tenant scope are deployment configuration.
+`hanzoai/cloud` is one Go binary that mounts every Hanzo subsystem (iam, kms, base, gateway, ai, commerce, vfs, mq, dns, amqp, mcp, o11y, ...) into a single multi-org process. Same artifact serves `api.hanzo.ai`, `api.osage.cloud`, `api.lux.cloud`, `api.zoo.cloud`, and every white-label reseller. Brand, enabled subsystems, and org scope are deployment configuration.
+
+## `hanzo` — cloud control CLI
+
+The same binary is also a gcloud/doctl-class CLI. The first token selects the mode:
+
+- `hanzo <subsystem>` — **server mode**: serve a subsystem (`hanzo iam`, `hanzo cloud`, …).
+- `hanzo <verb>` — **client mode**: control the live estate. A thin client over
+  Hanzo IAM (`hanzo.id`), the platform control plane (`platform.hanzo.ai/v1`),
+  and the cloud `/v1` API — it invents no parallel API.
+
+```bash
+hanzo login                       # IAM password grant against hanzo.id → token in ~/.hanzo (0600)
+hanzo whoami                      # identity from the stored token (--verify hits IAM userinfo)
+hanzo apps list                   # platform apps board: declared/running/latest tag + drift + health
+hanzo apps get <org>/<app>/<env>  # one app row
+hanzo deploy <container> --project <p> --env <e>   # rolling, zero-downtime redeploy
+hanzo clusters list|get|create|select|target       # dedicated DOKS cluster lifecycle
+hanzo build <repo> --sha <sha> --image <img>       # platform-native (arcd/Kaniko) build, no GitHub builders
+hanzo k8s target                  # the org's resolved deploy target (kubeconfig never returned)
+hanzo config set <k> <v>          # ~/.hanzo/config preferences
+```
+
+Global flags: `--org`, `-o/--output table|json`, `--platform-url`, `--iam-issuer`,
+`--platform-token`. Tokens resolve from flag → env → `~/.hanzo` (never hardcoded):
+the IAM user token is the identity; the platform control plane is service-token
+authed (it cannot validate user tokens), so `apps`/`deploy`/`clusters` use
+`--platform-token` / `HANZO_PLATFORM_TOKEN` / `PLATFORM_SERVICE_TOKEN`, and
+`build` uses `HANZO_BUILD_TOKEN` / `PLATFORM_BUILD_CALLBACK_TOKEN`.
+
+Install: `go install github.com/hanzoai/cloud/cmd/hanzo@latest`, or `brew install hanzoai/tap/hanzo`.
 
 ## Specs
 
@@ -29,7 +61,7 @@ Implements:
 ## Architecture
 
 ```
-                 api.{tenant}.{brand}
+                 api.{org}.{brand}
                           |
                    hanzoai/cloud (one Go binary)
                           |
@@ -37,7 +69,7 @@ Implements:
    |    iam   |   base   |   kms    |    ai    | gateway  | ...
    |  Mount() |  Mount() |  Mount() |  Mount() |  Mount() |
    +----------+----------+----------+----------+----------+
-   per-tenant SQLite (HIP-0302)   |   Hanzo IAM JWKS (HIP-0026)
+   per-org SQLite (HIP-0302)   |   Hanzo IAM JWKS (HIP-0026)
    replicate -> S3 (HIP-0107)     |   ZAP inter-subsystem RPC
 ```
 
@@ -56,7 +88,7 @@ Per [HIP-0106](https://github.com/hanzoai/HIPs/blob/main/HIPs/hip-0106-unified-h
 ## Subsystems mounted
 
 - `iam` — identity & access
-- `base` — per-tenant SQLite + extension runtimes (per HIP-0105)
+- `base` — per-org SQLite + extension runtimes (per HIP-0105)
 - `kms` — secrets
 - `commerce` — checkout, billing, pricing, invoicing (light router; NOT in PCI-DSS scope)
 - `ai` — LLM control plane / RAG / model hub / MCP management (was hanzoai/cloud pre-rename)
@@ -88,6 +120,50 @@ deployment configuration.
 [hanzoai/zip](https://github.com/hanzoai/zip) — Sinatra-style Go web framework
 built on Fiber v3. The ONE Go web framework. No `.Fast` escape hatch.
 
+## Console UI — embedded in the ONE binary
+
+The same `hanzoai/cloud` binary serves the [console](https://github.com/hanzoai/console)
+(`@hanzo/gui`) UI at the web root AND the `/v1` API from one process — one
+artifact, one origin, no separate console Service. The UI is compiled in via
+`//go:embed` (see `webui.go`).
+
+Pipeline (in the `Dockerfile`, before `go build`):
+
+```
+console stage  →  build console static bundle  →  /out
+      COPY --from=console /out/ → src/webui/dist/     (overlays the fallback shell)
+build stage    →  go build   →  //go:embed all:webui/dist bakes it into /cloud
+```
+
+Serving (`webui.go`, registered LAST in `Serve` so it never shadows the API):
+
+- `GET /` and any client-side route (`/orgs`, `/models`, …) → the SPA shell
+  (`index.html`) with `Cache-Control: no-cache`; fingerprinted assets under
+  `assets/`/`_next/` are served `immutable` for a year, with brotli/gzip
+  precompressed negotiation when the build emits `.br`/`.gz` siblings.
+- `GET /v1/*` (and `/zap`, `/healthz`, …) → the API. Real subsystem routes are
+  registered before the console catch-all, so they always win; an **unmatched**
+  path under an API prefix returns a real 404 (JSON namespace), never HTML.
+- Same-origin: the embedded console calls `/v1` on its own host, so the session
+  cookie is first-party — no second origin, no CORS.
+
+`webui/dist/index.html` is a committed **fallback shell** (a real same-origin
+`/v1` bootstrap) so `go build` always compiles and the binary always serves a UI
+even without the Node toolchain. The image build overwrites `webui/dist` with the
+real console bundle. See `webui_test.go` for the boot-and-assert tests
+(`/` → shell, deep link → shell 200, `/v1/*` → API, unmatched `/v1` → 404).
+
+Current state: `hanzoai/console` exposes `build:embed` (`scripts/build-embed.mjs`),
+which stashes its Next server route handlers (BFF proxies that collapse to the
+cloud `/v1/*` the SPA calls same-origin), wraps the client catch-all pages for
+`output: 'export'`, neutralizes the root layout's request-time `headers()` read,
+and emits a real static export at `out/` (a ~360 KB `index.html` + `_next/`
+chunks). The image build (and `make webui`) run it and overlay `webui/dist`, so
+`//go:embed` bakes the FULL `@hanzo/gui` console into the ONE binary. The
+Dockerfile console stage FAILS HARD if that bundle is missing or degenerate —
+the placeholder shell can never silently ship to prod (escape hatch:
+`--build-arg ALLOW_PLACEHOLDER=1` for a pure-Go dev image).
+
 ## Status
 
 Scaffold. The Mount(app, deps) integration for each subsystem lands per

audience_admin_guard_test.go

@@ -0,0 +1,50 @@
+// Copyright 2026 The Hanzo Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package cloud
+
+import (
+	"os"
+	"testing"
+)
+
+// TestJWTAudiences_AcceptsAdminGuard is the operator-cockpit keystone. The
+// admin.hanzo.ai forward-auth guard is the confidential client `hanzo-admin-guard`,
+// so IAM mints its access tokens with aud=hanzo-admin-guard (each app's aud is its
+// client_id). The guard forwards that bearer to cloud-api /v1/admin/*; the identity
+// sanitizer only grants SuperAdmin (owner==adminOrg) to a VALIDATED principal, and
+// validation enforces this audience allowlist. If hanzo-admin-guard is not accepted
+// the token resolves anonymous and the SuperAdmin gate reads false -> 403, even
+// though the token's owner IS admin. Pin the client_id into the baked default so the
+// forwarded bearer validates.
+func TestJWTAudiences_AcceptsAdminGuard(t *testing.T) {
+	os.Unsetenv("CLOUD_JWT_AUDIENCES")
+	os.Unsetenv("GATEWAY_ALLOWED_AUDIENCES")
+
+	has := func(list []string, v string) bool {
+		for _, s := range list {
+			if s == v {
+				return true
+			}
+		}
+		return false
+	}
+
+	if !has(defaultJWTAudiences, "hanzo-admin-guard") {
+		t.Fatalf("defaultJWTAudiences must include hanzo-admin-guard (the admin-cockpit guard client_id); got %v", defaultJWTAudiences)
+	}
+	if !has(jwtAudiencesFromEnv(), "hanzo-admin-guard") {
+		t.Fatalf("resolved JWT audiences must include hanzo-admin-guard; got %v", jwtAudiencesFromEnv())
+	}
+}

audience_hanzo_world_test.go

@@ -0,0 +1,47 @@
+// Copyright 2026 The Hanzo Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package cloud
+
+import (
+	"os"
+	"testing"
+)
+
+// TestJWTAudiences_AcceptsHanzoWorld pins the world.hanzo.ai OIDC client. IAM
+// mints world's access tokens with aud=hanzo-world (each app's aud is its
+// client_id). Those bearers hit cloud-api; the identity sanitizer only trusts a
+// principal whose aud is in this allowlist. If hanzo-world is not accepted the
+// token resolves anonymous and the analyst's api.hanzo.ai calls 401. Pin the
+// client_id into the baked default so the forwarded bearer validates.
+func TestJWTAudiences_AcceptsHanzoWorld(t *testing.T) {
+	os.Unsetenv("CLOUD_JWT_AUDIENCES")
+	os.Unsetenv("GATEWAY_ALLOWED_AUDIENCES")
+
+	has := func(list []string, v string) bool {
+		for _, s := range list {
+			if s == v {
+				return true
+			}
+		}
+		return false
+	}
+
+	if !has(defaultJWTAudiences, "hanzo-world") {
+		t.Fatalf("defaultJWTAudiences must include hanzo-world (the world.hanzo.ai client_id); got %v", defaultJWTAudiences)
+	}
+	if !has(jwtAudiencesFromEnv(), "hanzo-world") {
+		t.Fatalf("resolved JWT audiences must include hanzo-world; got %v", jwtAudiencesFromEnv())
+	}
+}

audit/audit_test.go

@@ -0,0 +1,623 @@
+package audit
+
+// Tests for the tamper-evident audit chain. They exercise the REAL SQLite store
+// (an on-disk temp db, not a mock) so the append-only write path, the hash-chain
+// math, the verifier, redaction, and the filtered query are all proven
+// end-to-end. The headline test is tamper-detection: a record edited directly in
+// the database is DETECTED as breaking the chain.
+
+import (
+	"context"
+	"database/sql"
+	"encoding/json"
+	"path/filepath"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+)
+
+// openTemp opens a Recorder backed by a fresh on-disk SQLite file (not :memory:,
+// because tamper tests re-open the same file via a second connection to edit it
+// out-of-band — exactly what an attacker with DB access would do).
+func openTemp(t *testing.T) (*Recorder, string) {
+	t.Helper()
+	path := filepath.Join(t.TempDir(), "audit.db")
+	rec, err := Open(path, nil)
+	if err != nil {
+		t.Fatalf("Open: %v", err)
+	}
+	t.Cleanup(func() { _ = rec.Close() })
+	return rec, path
+}
+
+// sampleRecord is a representative security event (a SuperAdmin org deletion).
+func sampleRecord(action string) Record {
+	return Record{
+		Time:      time.Date(2026, 7, 1, 12, 0, 0, 0, time.UTC),
+		Actor:     Actor{Org: "admin", Sub: "z@hanzo.ai", Email: "z@hanzo.ai"},
+		Action:    action,
+		Resource:  Resource{Type: "org", ID: "acme"},
+		Auth:      AuthContext{Method: "jwt", IsAdmin: true},
+		Outcome:   Outcome{Result: "success", Status: 200},
+		SourceIP:  "203.0.113.7",
+		UserAgent: "console",
+		RequestID: "req-123",
+		Method:    "DELETE",
+		Path:      "/v1/admin/orgs/acme",
+	}
+}
+
+// TestChain_AppendSealsAndLinks proves each appended record gets a monotonic seq,
+// links its PrevHash to the previous record's Hash, and starts from the genesis
+// anchor.
+func TestChain_AppendSealsAndLinks(t *testing.T) {
+	rec, _ := openTemp(t)
+	ctx := context.Background()
+
+	r0, err := rec.Append(ctx, sampleRecord("DELETE /v1/admin/orgs"))
+	if err != nil {
+		t.Fatalf("append 0: %v", err)
+	}
+	if r0.Seq != 0 {
+		t.Fatalf("first seq = %d, want 0", r0.Seq)
+	}
+	if r0.PrevHash != genesisPrevHash {
+		t.Fatalf("genesis prev = %q, want %q", r0.PrevHash, genesisPrevHash)
+	}
+	if r0.Hash == "" || r0.Hash == genesisPrevHash {
+		t.Fatalf("hash not computed: %q", r0.Hash)
+	}
+
+	r1, err := rec.Append(ctx, sampleRecord("POST /v1/admin/roles"))
+	if err != nil {
+		t.Fatalf("append 1: %v", err)
+	}
+	if r1.Seq != 1 {
+		t.Fatalf("second seq = %d, want 1", r1.Seq)
+	}
+	if r1.PrevHash != r0.Hash {
+		t.Fatalf("link broken: r1.prev=%q, r0.hash=%q", r1.PrevHash, r0.Hash)
+	}
+	if r1.Hash == r0.Hash {
+		t.Fatal("distinct records must have distinct hashes")
+	}
+}
+
+// TestVerify_PassesOnUntamperedChain proves a well-formed chain verifies OK.
+func TestVerify_PassesOnUntamperedChain(t *testing.T) {
+	rec, _ := openTemp(t)
+	ctx := context.Background()
+	for i := 0; i < 25; i++ {
+		if _, err := rec.Append(ctx, sampleRecord("POST /v1/admin/sync")); err != nil {
+			t.Fatalf("append %d: %v", i, err)
+		}
+	}
+	integrity, err := rec.Verify(ctx)
+	if err != nil {
+		t.Fatalf("Verify: %v", err)
+	}
+	if !integrity.OK {
+		t.Fatalf("chain not OK: broken at %d (%s)", integrity.BrokenAt, integrity.Reason)
+	}
+	if integrity.Count != 25 {
+		t.Fatalf("count = %d, want 25", integrity.Count)
+	}
+	if integrity.BrokenAt != -1 {
+		t.Fatalf("brokenAt = %d, want -1 on a good chain", integrity.BrokenAt)
+	}
+	// Head must equal the last record's hash.
+	count, head := rec.Head()
+	if count != 25 || head != integrity.HeadHash {
+		t.Fatalf("head mismatch: (%d,%q) vs verify (%d,%q)", count, head, integrity.Count, integrity.HeadHash)
+	}
+}
+
+// TestVerify_DetectsFieldTamper is the headline: an attacker with direct DB
+// access edits a record's content (flips a denied outcome to success, or changes
+// the actor). The stored hash no longer matches the recomputed hash, so Verify
+// reports the exact seq where the chain breaks. THIS is the tamper-evidence
+// property — an audit trail that can be silently forged is worse than none.
+func TestVerify_DetectsFieldTamper(t *testing.T) {
+	rec, path := openTemp(t)
+	ctx := context.Background()
+	for i := 0; i < 10; i++ {
+		if _, err := rec.Append(ctx, sampleRecord("DELETE /v1/admin/orgs")); err != nil {
+			t.Fatalf("append %d: %v", i, err)
+		}
+	}
+	// Sanity: clean chain verifies.
+	if iv, _ := rec.Verify(ctx); !iv.OK {
+		t.Fatalf("precondition: clean chain should verify, broke at %d", iv.BrokenAt)
+	}
+
+	// Tamper OUT OF BAND — a second connection issues an UPDATE the application
+	// never would. This models an attacker who owns the file / a rogue DBA.
+	tamperOutOfBand(t, path, `UPDATE audit_log SET actor_sub='attacker', result='success' WHERE seq=4`)
+
+	iv, err := rec.Verify(ctx)
+	if err != nil {
+		t.Fatalf("Verify after tamper: %v", err)
+	}
+	if iv.OK {
+		t.Fatal("TAMPER NOT DETECTED — a modified record verified as OK; the chain is forgeable")
+	}
+	if iv.BrokenAt != 4 {
+		t.Fatalf("brokenAt = %d, want 4 (the edited record)", iv.BrokenAt)
+	}
+	if !strings.Contains(iv.Reason, "hash mismatch") {
+		t.Fatalf("reason = %q, want a hash-mismatch explanation", iv.Reason)
+	}
+}
+
+// TestVerify_DetectsDeletion proves deleting a record (or a contiguous run) breaks
+// the chain: the record after the hole has a PrevHash that no longer matches the
+// now-preceding record, and the seq sequence gaps. Either way Verify flags it.
+func TestVerify_DetectsDeletion(t *testing.T) {
+	rec, path := openTemp(t)
+	ctx := context.Background()
+	for i := 0; i < 10; i++ {
+		if _, err := rec.Append(ctx, sampleRecord("POST /v1/admin/roles")); err != nil {
+			t.Fatalf("append %d: %v", i, err)
+		}
+	}
+	// Delete a MIDDLE record — the classic "cover your tracks" edit.
+	tamperOutOfBand(t, path, `DELETE FROM audit_log WHERE seq=5`)
+
+	iv, err := rec.Verify(ctx)
+	if err != nil {
+		t.Fatalf("Verify after delete: %v", err)
+	}
+	if iv.OK {
+		t.Fatal("DELETION NOT DETECTED — a removed record left the chain verifying OK")
+	}
+	// The break is observed at seq 6 (the record whose predecessor vanished): its
+	// seq no longer follows the running counter (5 is missing), so the gap check
+	// fires first at 6.
+	if iv.BrokenAt != 6 {
+		t.Fatalf("brokenAt = %d, want 6 (record after the hole)", iv.BrokenAt)
+	}
+}
+
+// TestVerify_DetectsReorder proves swapping two records' positions (an attacker
+// trying to reorder events) breaks the prev-hash linkage.
+func TestVerify_DetectsReorder(t *testing.T) {
+	rec, path := openTemp(t)
+	ctx := context.Background()
+	for i := 0; i < 6; i++ {
+		if _, err := rec.Append(ctx, sampleRecord("POST /v1/kms/secrets")); err != nil {
+			t.Fatalf("append %d: %v", i, err)
+		}
+	}
+	// Swap the hashes of seq 2 and seq 3 (content stays, linkage corrupts). Any
+	// out-of-band shuffle that doesn't recompute the WHOLE suffix is detectable.
+	tamperOutOfBand(t, path, `
+UPDATE audit_log SET hash = (SELECT hash FROM audit_log WHERE seq=3) WHERE seq=2;`)
+
+	iv, _ := rec.Verify(ctx)
+	if iv.OK {
+		t.Fatal("REORDER/HASH-SWAP NOT DETECTED")
+	}
+	if iv.BrokenAt < 0 {
+		t.Fatalf("expected a break, got brokenAt=%d", iv.BrokenAt)
+	}
+}
+
+// TestChain_RestartContinues proves a re-opened store continues the SAME chain
+// (recovers seq + head) rather than forking — so a pod restart cannot silently
+// reset the trail.
+func TestChain_RestartContinues(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "audit.db")
+	ctx := context.Background()
+
+	rec1, err := Open(path, nil)
+	if err != nil {
+		t.Fatalf("open 1: %v", err)
+	}
+	var lastHash string
+	for i := 0; i < 5; i++ {
+		r, err := rec1.Append(ctx, sampleRecord("POST /v1/admin/sync"))
+		if err != nil {
+			t.Fatalf("append %d: %v", i, err)
+		}
+		lastHash = r.Hash
+	}
+	_ = rec1.Close()
+
+	rec2, err := Open(path, nil)
+	if err != nil {
+		t.Fatalf("open 2: %v", err)
+	}
+	defer func() { _ = rec2.Close() }()
+
+	count, head := rec2.Head()
+	if count != 5 {
+		t.Fatalf("recovered count = %d, want 5", count)
+	}
+	if head != lastHash {
+		t.Fatalf("recovered head = %q, want %q", head, lastHash)
+	}
+	// The next append must chain onto the recovered head at seq 5.
+	r5, err := rec2.Append(ctx, sampleRecord("DELETE /v1/admin/orgs"))
+	if err != nil {
+		t.Fatalf("append after restart: %v", err)
+	}
+	if r5.Seq != 5 || r5.PrevHash != lastHash {
+		t.Fatalf("chain did not continue: seq=%d prev=%q (want seq 5 prev %q)", r5.Seq, r5.PrevHash, lastHash)
+	}
+	// And the whole continued chain still verifies.
+	if iv, _ := rec2.Verify(ctx); !iv.OK {
+		t.Fatalf("continued chain broke at %d (%s)", iv.BrokenAt, iv.Reason)
+	}
+}
+
+// TestRedact_StripsSecrets proves the redactor removes credential-bearing fields
+// (by key name, recursively) while keeping non-secret structure — so an explicit
+// emit point's before/after can never carry a password/token/key.
+func TestRedact_StripsSecrets(t *testing.T) {
+	in := json.RawMessage(`{
+      "name": "acme",
+      "password": "hunter2",
+      "apiKey": "sk-live-abc123",
+      "passphrase": "correct horse",
+      "wgPrivKey": "PRIVKEYBYTES",
+      "recoveryPhrase": "twelve words here",
+      "socialSecurityNumber": "078-05-1120",
+      "config": {
+        "clientSecret": "shh",
+        "endpoint": "https://api.example.com",
+        "nested": {"private_key": "-----BEGIN-----", "region": "sfo3"}
+      },
+      "tokens": ["t1", "t2"],
+      "roles": ["admin", "viewer"]
+    }`)
+	out := Redact(in)
+
+	s := string(out)
+	// Secrets gone (incl. the edge-case key names: passphrase, privkey, phrase, ssn).
+	for _, leak := range []string{"hunter2", "sk-live-abc123", "shh", "BEGIN",
+		"correct horse", "PRIVKEYBYTES", "twelve words here", "078-05-1120"} {
+		if strings.Contains(s, leak) {
+			t.Fatalf("secret leaked through redaction: %q still present in %s", leak, s)
+		}
+	}
+	// Non-secret structure preserved.
+	for _, keep := range []string{"acme", "https://api.example.com", "sfo3", "viewer"} {
+		if !strings.Contains(s, keep) {
+			t.Fatalf("redaction dropped a non-secret value %q: %s", keep, s)
+		}
+	}
+	// The redaction marker appears where secrets were.
+	if !strings.Contains(s, redactedMarker) {
+		t.Fatalf("no redaction marker in output: %s", s)
+	}
+	// "tokens" is a secret key → the whole array is redacted (not its elements).
+	var decoded map[string]any
+	if err := json.Unmarshal(out, &decoded); err != nil {
+		t.Fatalf("redacted output is not valid JSON: %v", err)
+	}
+	if decoded["tokens"] != redactedMarker {
+		t.Fatalf("secret-keyed array not redacted whole: %v", decoded["tokens"])
+	}
+}
+
+// TestRedact_FailsClosedOnBadJSON proves unparseable input is never echoed back.
+func TestRedact_FailsClosedOnBadJSON(t *testing.T) {
+	out := Redact(json.RawMessage(`{not valid json, password=hunter2`))
+	if strings.Contains(string(out), "hunter2") {
+		t.Fatalf("bad JSON echoed a secret: %s", out)
+	}
+	if !strings.Contains(string(out), redactedMarker) {
+		t.Fatalf("bad JSON should redact to a marker, got %s", out)
+	}
+}
+
+// TestQuery_Filters proves the filtered read returns the right subset by actor,
+// action, resource, and result, newest-first, with an accurate total.
+func TestQuery_Filters(t *testing.T) {
+	rec, _ := openTemp(t)
+	ctx := context.Background()
+
+	mk := func(org, action, res, result string) Record {
+		r := sampleRecord(action)
+		r.Actor.Org = org
+		r.Resource.Type = res
+		r.Outcome.Result = result
+		return r
+	}
+	// A mixed set.
+	seed := []Record{
+		mk("admin", "DELETE /v1/admin/orgs", "org", "success"),
+		mk("acme", "POST /v1/base/records", "records", "success"),
+		mk("admin", "POST /v1/admin/roles", "roles", "deny"),
+		mk("admin", "DELETE /v1/admin/orgs", "org", "success"),
+		mk("acme", "POST /v1/kms/secrets", "secrets", "error"),
+	}
+	for i, r := range seed {
+		if _, err := rec.Append(ctx, r); err != nil {
+			t.Fatalf("seed %d: %v", i, err)
+		}
+	}
+
+	// Filter by org=admin → 3 rows.
+	rows, total, err := rec.Query(ctx, Filter{Org: "admin"})
+	if err != nil {
+		t.Fatalf("query org: %v", err)
+	}
+	if total != 3 || len(rows) != 3 {
+		t.Fatalf("org=admin: got %d rows, total %d, want 3/3", len(rows), total)
+	}
+	// Newest first: the last-appended admin row (seq 3) comes before seq 2, 0.
+	if rows[0].Seq < rows[len(rows)-1].Seq {
+		t.Fatalf("not newest-first: %d..%d", rows[0].Seq, rows[len(rows)-1].Seq)
+	}
+
+	// Filter by result=deny → 1 row (the 403-style role change).
+	denies, dtotal, err := rec.Query(ctx, Filter{Result: "deny"})
+	if err != nil {
+		t.Fatalf("query deny: %v", err)
+	}
+	if dtotal != 1 || len(denies) != 1 || denies[0].Action != "POST /v1/admin/roles" {
+		t.Fatalf("result=deny: got %d (%+v), want 1 role-change", dtotal, denies)
+	}
+
+	// Filter by resource=secrets → 1 row.
+	secs, stotal, err := rec.Query(ctx, Filter{Resource: "secrets"})
+	if err != nil {
+		t.Fatalf("query resource: %v", err)
+	}
+	if stotal != 1 || len(secs) != 1 {
+		t.Fatalf("resource=secrets: got %d, want 1", stotal)
+	}
+}
+
+// TestQuery_SQLInjectionInFilterIsInert proves a malicious filter value is a
+// parameter, never SQL: it simply matches nothing and cannot drop the table.
+func TestQuery_SQLInjectionInFilterIsInert(t *testing.T) {
+	rec, _ := openTemp(t)
+	ctx := context.Background()
+	for i := 0; i < 3; i++ {
+		if _, err := rec.Append(ctx, sampleRecord("POST /v1/admin/sync")); err != nil {
+			t.Fatalf("seed %d: %v", i, err)
+		}
+	}
+	inject := Filter{Org: "admin'; DROP TABLE audit_log;--"}
+	rows, total, err := rec.Query(ctx, inject)
+	if err != nil {
+		t.Fatalf("query should not error on injection attempt: %v", err)
+	}
+	if total != 0 || len(rows) != 0 {
+		t.Fatalf("injection value matched %d rows, want 0", total)
+	}
+	// The table survived — a normal query still returns the seeded rows.
+	if _, all, err := rec.Query(ctx, Filter{}); err != nil || all != 3 {
+		t.Fatalf("table damaged by injection attempt: all=%d err=%v", all, err)
+	}
+}
+
+// TestChain_ConcurrentAppendsStayGapless proves the serialized writer keeps the
+// chain a true, gapless total order under CONCURRENT appends: many goroutines
+// append at once, and the resulting chain must have every seq 0..N-1 exactly once
+// AND verify. A race in the head/seq handoff would surface as a duplicate seq (a
+// PRIMARY KEY error), a gap, or a broken link — all of which this catches.
+func TestChain_ConcurrentAppendsStayGapless(t *testing.T) {
+	rec, _ := openTemp(t)
+	ctx := context.Background()
+
+	const goroutines, per = 16, 20
+	total := goroutines * per
+	errCh := make(chan error, total)
+	var wg sync.WaitGroup
+	for g := 0; g < goroutines; g++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			for i := 0; i < per; i++ {
+				if _, err := rec.Append(ctx, sampleRecord("POST /v1/admin/sync")); err != nil {
+					errCh <- err
+				}
+			}
+		}()
+	}
+	wg.Wait()
+	close(errCh)
+	for err := range errCh {
+		t.Fatalf("concurrent append failed (race in seq/head handoff?): %v", err)
+	}
+
+	// The chain must verify and contain exactly `total` gapless records.
+	iv, err := rec.Verify(ctx)
+	if err != nil {
+		t.Fatalf("verify: %v", err)
+	}
+	if !iv.OK {
+		t.Fatalf("concurrent chain broke at %d (%s)", iv.BrokenAt, iv.Reason)
+	}
+	if iv.Count != uint64(total) {
+		t.Fatalf("recorded %d records, want %d (a lost/duplicated append)", iv.Count, total)
+	}
+}
+
+// checkpointMirror is a Mirror that also captures checkpoints (implements
+// CheckpointSink) so the test can assert the head digest reaches an independent
+// sink.
+type checkpointMirror struct {
+	mu  sync.Mutex
+	cps []Checkpoint
+}
+
+func (m *checkpointMirror) Append(context.Context, Record) error { return nil }
+func (m *checkpointMirror) Checkpoint(_ context.Context, cp Checkpoint) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	m.cps = append(m.cps, cp)
+	return nil
+}
+func (m *checkpointMirror) last() (Checkpoint, bool) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if len(m.cps) == 0 {
+		return Checkpoint{}, false
+	}
+	return m.cps[len(m.cps)-1], true
+}
+
+// TestCheckpoint_EmitsHeadDigest proves the AU-9 anchor: the periodic checkpoint
+// emits the current (count, head) to the log function AND, when the mirror is a
+// CheckpointSink, to the independent digest store — and a final checkpoint fires
+// on Close. This is what an external monitor compares to detect tail-truncation.
+func TestCheckpoint_EmitsHeadDigest(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "audit.db")
+	mirror := &checkpointMirror{}
+	rec, err := Open(path, mirror)
+	if err != nil {
+		t.Fatalf("open: %v", err)
+	}
+	ctx := context.Background()
+
+	var logged []Checkpoint
+	var lmu sync.Mutex
+	// every=0 → no ticker; we drive checkpoints via Close (final) + a manual tick.
+	rec.StartCheckpoints(0, func(cp Checkpoint) {
+		lmu.Lock()
+		logged = append(logged, cp)
+		lmu.Unlock()
+	})
+
+	for i := 0; i < 7; i++ {
+		if _, err := rec.Append(ctx, sampleRecord("POST /v1/admin/sync")); err != nil {
+			t.Fatalf("append %d: %v", i, err)
+		}
+	}
+	// Close emits the FINAL checkpoint (count=7, head=chain head).
+	if err := rec.Close(); err != nil {
+		t.Fatalf("close: %v", err)
+	}
+
+	lmu.Lock()
+	n := len(logged)
+	var lastLogged Checkpoint
+	if n > 0 {
+		lastLogged = logged[n-1]
+	}
+	lmu.Unlock()
+	if n == 0 {
+		t.Fatal("no checkpoint logged (Close should emit a final head digest)")
+	}
+	if lastLogged.Count != 7 {
+		t.Errorf("final checkpoint count = %d, want 7", lastLogged.Count)
+	}
+	if lastLogged.Head == "" || lastLogged.Head == genesisPrevHash {
+		t.Errorf("final checkpoint head not set: %q", lastLogged.Head)
+	}
+	// The independent sink also received the final digest.
+	if cp, ok := mirror.last(); !ok || cp.Count != 7 {
+		t.Errorf("checkpoint sink final = %+v (ok=%v), want count 7", cp, ok)
+	}
+}
+
+// TestCheckpoint_DoubleStartIsSafe proves a second StartCheckpoints call is
+// ignored (no re-arm, no field/WaitGroup race) — the Red-review robustness fix.
+// Run under -race to catch a regression.
+func TestCheckpoint_DoubleStartIsSafe(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "audit.db")
+	rec, err := Open(path, nil)
+	if err != nil {
+		t.Fatalf("open: %v", err)
+	}
+	rec.StartCheckpoints(time.Hour, func(Checkpoint) {})
+	rec.StartCheckpoints(time.Hour, func(Checkpoint) {}) // second call must be a no-op.
+	// Append + close must not race or hang.
+	if _, err := rec.Append(context.Background(), sampleRecord("POST /v1/admin/sync")); err != nil {
+		t.Fatalf("append: %v", err)
+	}
+	if err := rec.Close(); err != nil {
+		t.Fatalf("close: %v", err)
+	}
+}
+
+// TestCheckpoint_CloseSyncsToSink proves the FINAL checkpoint on Close reaches the
+// independent sink SYNCHRONOUSLY (the Red-review durability fix) — the sink has
+// the final count before Close returns, not on a detached goroutine that might
+// not run before process exit.
+func TestCheckpoint_CloseSyncsToSink(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "audit.db")
+	mirror := &checkpointMirror{}
+	rec, err := Open(path, mirror)
+	if err != nil {
+		t.Fatalf("open: %v", err)
+	}
+	rec.StartCheckpoints(0, func(Checkpoint) {}) // no ticker; only the on-close checkpoint.
+	for i := 0; i < 4; i++ {
+		if _, err := rec.Append(context.Background(), sampleRecord("POST /v1/admin/sync")); err != nil {
+			t.Fatalf("append %d: %v", i, err)
+		}
+	}
+	if err := rec.Close(); err != nil {
+		t.Fatalf("close: %v", err)
+	}
+	// Immediately after Close returns (no sleep), the sink MUST already have the
+	// final digest — proving the Close-path write was synchronous.
+	cp, ok := mirror.last()
+	if !ok || cp.Count != 4 {
+		t.Fatalf("sink final checkpoint = %+v (ok=%v), want count 4 synchronously on Close", cp, ok)
+	}
+}
+
+// TestCheckpoint_CountMonotonicDetectsTruncation demonstrates the DETECTION an
+// external monitor performs: consecutive checkpoints have non-decreasing Count;
+// after a tail truncation the head reported by Head() drops below a prior
+// checkpoint — the signal the o11y alert fires on.
+func TestCheckpoint_CountMonotonicDetectsTruncation(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "audit.db")
+	rec, err := Open(path, nil)
+	if err != nil {
+		t.Fatalf("open: %v", err)
+	}
+	ctx := context.Background()
+	for i := 0; i < 10; i++ {
+		if _, err := rec.Append(ctx, sampleRecord("POST /v1/admin/sync")); err != nil {
+			t.Fatalf("append %d: %v", i, err)
+		}
+	}
+	before, _ := rec.Head() // the monitor's last pinned checkpoint count.
+	if before != 10 {
+		t.Fatalf("pre-truncation count = %d, want 10", before)
+	}
+	_ = rec.Close()
+
+	// Attacker truncates the tail (deletes the last 4 records) out of band.
+	tamperOutOfBand(t, path, `DELETE FROM audit_log WHERE seq >= 6`)
+
+	rec2, err := Open(path, nil)
+	if err != nil {
+		t.Fatalf("reopen: %v", err)
+	}
+	defer func() { _ = rec2.Close() }()
+	after, _ := rec2.Head()
+	// The internal chain still verifies (a truncated prefix is self-consistent)…
+	if iv, _ := rec2.Verify(ctx); !iv.OK {
+		t.Fatalf("truncated prefix should self-verify, broke at %d", iv.BrokenAt)
+	}
+	// …but the count REGRESSED vs the pinned checkpoint — the truncation signal.
+	if after >= before {
+		t.Fatalf("count did not regress after truncation: before=%d after=%d", before, after)
+	}
+	t.Logf("truncation detected by count regression: %d → %d (chain-internal verify is OK; external anchor catches it)", before, after)
+}
+
+// tamperOutOfBand opens the SAME sqlite file on a SEPARATE connection and runs a
+// mutating statement the audit application itself never issues — modeling an
+// attacker with direct database/file access. The Recorder's own connection is
+// unaffected; Verify then re-reads and must catch the damage.
+func tamperOutOfBand(t *testing.T, path, stmt string) {
+	t.Helper()
+	db, err := sql.Open("sqlite", path)
+	if err != nil {
+		t.Fatalf("tamper open: %v", err)
+	}
+	defer func() { _ = db.Close() }()
+	if _, err := db.Exec(stmt); err != nil {
+		t.Fatalf("tamper exec %q: %v", stmt, err)
+	}
+}

audit/query.go

@@ -0,0 +1,235 @@
+package audit
+
+// The read paths: filtered Query (for /v1/admin/audit) and Verify (the
+// tamper-evidence walk for /v1/admin/audit/verify). Both are read-only — they
+// issue SELECT only, never mutate — so exposing them can never weaken the
+// append-only property.
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"strings"
+	"time"
+)
+
+// Filter narrows a Query. Zero-value fields are ignored (no constraint), so an
+// empty Filter returns the most-recent Limit records. Time bounds are inclusive
+// and compared against the RFC3339Nano ts column lexicographically (RFC3339 is
+// order-preserving as text, so a string range is a correct time range).
+type Filter struct {
+	Org        string    // actor_org exact match (tenant scope)
+	Sub        string    // actor_sub exact match (a specific user)
+	Action     string    // action exact match
+	Resource   string    // res_type exact match
+	ResourceID string    // res_id exact match (a specific resource instance)
+	Result     string    // outcome result: success|deny|error
+	Since      time.Time // ts >= Since (UTC)
+	Until      time.Time // ts <= Until (UTC)
+	Limit      int       // max rows (default 100, cap 1000)
+	Offset     int       // pagination offset
+}
+
+// Query returns records matching f, newest first, and the total count matching
+// the same predicate (ignoring Limit/Offset) for pagination. All predicates are
+// parameterized — never string-interpolated — so a filter value can never inject
+// SQL. Column names in the WHERE come from a fixed allowlist below, not caller
+// input.
+func (r *Recorder) Query(ctx context.Context, f Filter) (rows []Record, total int, err error) {
+	where, args := f.build()
+	limit := f.Limit
+	if limit <= 0 {
+		limit = 100
+	}
+	if limit > 1000 {
+		limit = 1000
+	}
+	offset := f.Offset
+	if offset < 0 {
+		offset = 0
+	}
+
+	countQ := `SELECT COUNT(*) FROM audit_log` + where
+	if err = r.db.QueryRowContext(ctx, countQ, args...).Scan(&total); err != nil {
+		return nil, 0, fmt.Errorf("audit: count: %w", err)
+	}
+
+	listQ := `SELECT ` + selectCols + ` FROM audit_log` + where +
+		` ORDER BY seq DESC LIMIT ? OFFSET ?`
+	listArgs := append(append([]any{}, args...), limit, offset)
+	rs, err := r.db.QueryContext(ctx, listQ, listArgs...)
+	if err != nil {
+		return nil, 0, fmt.Errorf("audit: query: %w", err)
+	}
+	defer func() { _ = rs.Close() }()
+	for rs.Next() {
+		rec, scanErr := scanRecord(rs)
+		if scanErr != nil {
+			return nil, 0, fmt.Errorf("audit: scan: %w", scanErr)
+		}
+		rows = append(rows, rec)
+	}
+	return rows, total, rs.Err()
+}
+
+// build assembles the parameterized WHERE clause from the non-zero filter
+// fields. Each fragment uses a fixed column name and a ? placeholder, so no
+// caller value ever reaches the SQL text.
+func (f Filter) build() (string, []any) {
+	var conds []string
+	var args []any
+	add := func(frag string, val any) {
+		conds = append(conds, frag)
+		args = append(args, val)
+	}
+	if f.Org != "" {
+		add("actor_org = ?", f.Org)
+	}
+	if f.Sub != "" {
+		add("actor_sub = ?", f.Sub)
+	}
+	if f.Action != "" {
+		add("action = ?", f.Action)
+	}
+	if f.Resource != "" {
+		add("res_type = ?", f.Resource)
+	}
+	if f.ResourceID != "" {
+		add("res_id = ?", f.ResourceID)
+	}
+	if f.Result != "" {
+		add("result = ?", f.Result)
+	}
+	if !f.Since.IsZero() {
+		add("ts >= ?", f.Since.UTC().Format(time.RFC3339Nano))
+	}
+	if !f.Until.IsZero() {
+		add("ts <= ?", f.Until.UTC().Format(time.RFC3339Nano))
+	}
+	if len(conds) == 0 {
+		return "", nil
+	}
+	return " WHERE " + strings.Join(conds, " AND "), args
+}
+
+const selectCols = `seq, ts, actor_org, actor_sub, actor_email, action, res_type, res_id,
+  auth_method, is_admin, result, status, reason, source_ip, user_agent,
+  request_id, method, path, before, after, prev_hash, hash`
+
+// scanRecord reconstructs a Record from a row of selectCols.
+func scanRecord(sc interface{ Scan(...any) error }) (Record, error) {
+	var (
+		rec           Record
+		ts            string
+		isAdmin       int
+		before, after string
+	)
+	if err := sc.Scan(
+		&rec.Seq, &ts, &rec.Actor.Org, &rec.Actor.Sub, &rec.Actor.Email,
+		&rec.Action, &rec.Resource.Type, &rec.Resource.ID,
+		&rec.Auth.Method, &isAdmin, &rec.Outcome.Result, &rec.Outcome.Status, &rec.Outcome.Reason,
+		&rec.SourceIP, &rec.UserAgent, &rec.RequestID, &rec.Method, &rec.Path,
+		&before, &after, &rec.PrevHash, &rec.Hash,
+	); err != nil {
+		return Record{}, err
+	}
+	if t, err := time.Parse(time.RFC3339Nano, ts); err == nil {
+		rec.Time = t
+	}
+	rec.Auth.IsAdmin = isAdmin != 0
+	if before != "" {
+		rec.Before = json.RawMessage(before)
+	}
+	if after != "" {
+		rec.After = json.RawMessage(after)
+	}
+	return rec, nil
+}
+
+// Integrity is the result of a Verify walk — the AU-9 evidence that the trail has
+// not been tampered with.
+type Integrity struct {
+	// OK is true iff every record's stored hash equals the recomputed hash AND the
+	// chain links are continuous (each PrevHash == the prior record's Hash, seqs
+	// gapless from 0).
+	OK bool `json:"ok"`
+	// Count is the number of records walked.
+	Count uint64 `json:"count"`
+	// HeadHash is the hash of the last record (or the genesis anchor for an empty
+	// chain). Pin this externally over time to detect tail-truncation.
+	HeadHash string `json:"headHash"`
+	// BrokenAt is the seq of the FIRST record that failed verification, or -1 when
+	// OK. Reason describes the break (recomputed-hash mismatch, prev-hash
+	// discontinuity, or a seq gap).
+	BrokenAt int64  `json:"brokenAt"`
+	Reason   string `json:"reason,omitempty"`
+}
+
+// Verify walks the entire chain in seq order, recomputing each record's hash from
+// its content + the running prev-hash and checking continuity. It is the
+// tamper-detector: any modification (a changed field re-hashes differently), any
+// deletion or reordering (a seq gap or a broken prev-hash link), or a forged row
+// (its recomputed hash won't match unless the attacker also recomputed the entire
+// suffix — which they cannot do without re-inserting every subsequent record) is
+// reported with the exact seq where the chain first breaks.
+//
+// Complexity is O(n) over the records; for very large trails this streams row by
+// row (no full materialization). At cloud's audit volume this is fine; if a trail
+// grows past what an on-demand full walk should touch, verify a seq WINDOW
+// (Verify is easily extended with a bound) or rely on the externally-pinned head.
+func (r *Recorder) Verify(ctx context.Context) (Integrity, error) {
+	rs, err := r.db.QueryContext(ctx,
+		`SELECT `+selectCols+` FROM audit_log ORDER BY seq ASC`)
+	if err != nil {
+		return Integrity{}, fmt.Errorf("audit: verify query: %w", err)
+	}
+	defer func() { _ = rs.Close() }()
+
+	prevHash := genesisPrevHash
+	var expectSeq uint64
+	var count uint64
+	headHash := genesisPrevHash
+
+	for rs.Next() {
+		rec, scanErr := scanRecord(rs)
+		if scanErr != nil {
+			return Integrity{}, fmt.Errorf("audit: verify scan: %w", scanErr)
+		}
+		// Gapless, 0-based ordering.
+		if rec.Seq != expectSeq {
+			return Integrity{
+				OK: false, Count: count, HeadHash: headHash,
+				BrokenAt: int64(rec.Seq),
+				Reason:   fmt.Sprintf("seq gap: expected %d, got %d", expectSeq, rec.Seq),
+			}, nil
+		}
+		// Link continuity: this record must chain to the previous record's hash.
+		if rec.PrevHash != prevHash {
+			return Integrity{
+				OK: false, Count: count, HeadHash: headHash,
+				BrokenAt: int64(rec.Seq),
+				Reason:   "prev_hash discontinuity (a record was deleted, reordered, or altered)",
+			}, nil
+		}
+		// Content integrity: recompute the hash from the record's own fields.
+		want, hErr := computeHash(rec, rec.PrevHash)
+		if hErr != nil {
+			return Integrity{}, fmt.Errorf("audit: verify hash: %w", hErr)
+		}
+		if want != rec.Hash {
+			return Integrity{
+				OK: false, Count: count, HeadHash: headHash,
+				BrokenAt: int64(rec.Seq),
+				Reason:   "hash mismatch (record content was modified after it was written)",
+			}, nil
+		}
+		prevHash = rec.Hash
+		headHash = rec.Hash
+		expectSeq = rec.Seq + 1
+		count++
+	}
+	if err := rs.Err(); err != nil {
+		return Integrity{}, fmt.Errorf("audit: verify rows: %w", err)
+	}
+	return Integrity{OK: true, Count: count, HeadHash: headHash, BrokenAt: -1}, nil
+}

audit/record.go

@@ -0,0 +1,176 @@
+// Package audit is the unified cloud binary's compliance-grade audit trail —
+// tamper-evident, append-only, and complete over the security-relevant request
+// surface (FedRAMP AU-* / SOC 2 CC-* controls).
+//
+// THE CONTROL, IN ONE SENTENCE. Every security-relevant action against this
+// binary is captured as a structured Record, hash-chained to its predecessor so
+// any later deletion or modification is detectable, and written INLINE (never
+// dropped) to an append-only store the application can only INSERT into.
+//
+// THREE PIECES, EACH IN ITS LANE (orthogonal, per the Zen of Hanzo):
+//   - record.go  — the event model + the hash-chain math (what a record IS and
+//     how it links to the one before it). Pure, no I/O.
+//   - store.go   — the append-only sink (SQLite primary, INSERT-only; a
+//     best-effort OLAP mirror) and the serialized Recorder that
+//     owns the chain head. All persistence.
+//   - redact.go  — the secret-stripping allowlist/denylist for any structured
+//     before/after an explicit emit point supplies. No secret ever
+//     reaches a record.
+//
+// The HTTP middleware (Middleware, in the cloud package) and the query/verify
+// endpoints (in clients/admin) are thin callers of this package. This package
+// holds the security logic; it has zero knowledge of routes.
+package audit
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"time"
+)
+
+// Actor identifies WHO performed the action. It is populated ONLY from a
+// validated principal (the sanitized X-User-* headers SanitizeIdentity mints
+// from a verified IAM JWT), never from a raw client header — so an actor can
+// never be forged by the request that is being audited. A service principal
+// (M2M / no user sub) records Org with an empty Sub.
+type Actor struct {
+	// Org is the tenant (IAM `owner`). Empty for an unauthenticated request.
+	Org string `json:"org"`
+	// Sub is the user id (IAM `sub`/`preferred_username`). Empty for a service
+	// principal or an anonymous request.
+	Sub string `json:"sub"`
+	// Email is the validated user email, when present.
+	Email string `json:"email,omitempty"`
+}
+
+// Resource identifies WHAT was acted upon: a type (e.g. "org", "role",
+// "secret", "provider-config", "credit") and its id. For a plain HTTP mutation
+// with no finer resource semantics, Type is the route family and ID is empty —
+// the Action verb + path already pin the object.
+type Resource struct {
+	Type string `json:"type"`
+	ID   string `json:"id,omitempty"`
+}
+
+// AuthContext records HOW the actor authenticated and what authority they held
+// at decision time — the AC-* evidence (was this a SuperAdmin? by what
+// credential?). Method is "jwt" | "api-key" | "none". IsAdmin is the VALIDATED
+// SuperAdmin bit (owner == AdminOrg), never a raw X-User-IsAdmin.
+type AuthContext struct {
+	Method  string `json:"method"`
+	IsAdmin bool   `json:"isAdmin"`
+}
+
+// Outcome is the result of the action: whether it was allowed and what
+// happened. Result is "success" | "deny" | "error". Status is the HTTP status.
+// Reason is a short, non-sensitive explanation for a deny/error (e.g.
+// "SuperAdmin required", "insufficient_balance") — never a secret, never a
+// raw upstream error body.
+type Outcome struct {
+	Result string `json:"result"`
+	Status int    `json:"status"`
+	Reason string `json:"reason,omitempty"`
+}
+
+// Record is one audit event. The JSON tags ARE the on-disk and on-wire contract.
+//
+// Field order in the struct is deliberate but IRRELEVANT to the hash: the chain
+// hashes the CANONICAL (sorted-key) JSON of the record with Hash/PrevHash zeroed
+// (see canonicalBytes), so re-ordering fields or adding an omitempty field can
+// never change an existing record's hash.
+type Record struct {
+	// Seq is the strictly-increasing chain position (0-based). It is assigned by
+	// the Recorder under its lock, so it is a true total order with no gaps.
+	Seq uint64 `json:"seq"`
+
+	// Time is the UTC event timestamp (RFC3339Nano).
+	Time time.Time `json:"time"`
+
+	// Actor / Action / Resource / Auth / Outcome — the AU-3 "content of audit
+	// records" core: who, what, on what, how-authenticated, with what result.
+	Actor    Actor       `json:"actor"`
+	Action   string      `json:"action"`
+	Resource Resource    `json:"resource"`
+	Auth     AuthContext `json:"auth"`
+	Outcome  Outcome     `json:"outcome"`
+
+	// SourceIP + UserAgent — the AU-3 "source of the event" fields.
+	SourceIP  string `json:"sourceIp,omitempty"`
+	UserAgent string `json:"userAgent,omitempty"`
+
+	// RequestID correlates the record to the request-line log and any downstream
+	// trace (the X-Request-Id the pipeline mints).
+	RequestID string `json:"requestId,omitempty"`
+
+	// Method + Path are the HTTP verb and route for a request-sourced event.
+	Method string `json:"method,omitempty"`
+	Path   string `json:"path,omitempty"`
+
+	// Before / After capture a mutation's prior and resulting state for the
+	// AU-required "before/after" on config-affecting changes. They are populated
+	// ONLY by explicit emit points and ONLY after Redact has stripped secrets —
+	// the HTTP middleware never sets them (it never reads bodies), so a secret in
+	// a request body can never leak here. Raw JSON so any shape round-trips.
+	Before json.RawMessage `json:"before,omitempty"`
+	After  json.RawMessage `json:"after,omitempty"`
+
+	// PrevHash is the hash of record Seq-1 (hex). For the genesis record (Seq 0)
+	// it is genesisPrevHash. Hash is this record's hash. Neither participates in
+	// its own hash computation (both are zeroed in canonicalBytes).
+	PrevHash string `json:"prevHash"`
+	Hash     string `json:"hash"`
+}
+
+// genesisPrevHash is the PrevHash of the first record in a fresh chain: 32 zero
+// bytes, hex-encoded. A non-empty, fixed anchor so the genesis record's hash is
+// still a function of a known constant (not the empty string, which would be
+// indistinguishable from "field omitted").
+const genesisPrevHash = "0000000000000000000000000000000000000000000000000000000000000000"
+
+// canonicalBytes returns the deterministic byte string a record hashes over: the
+// record with Hash AND PrevHash zeroed, marshaled by encoding/json (which sorts
+// struct fields in declaration order and, critically, is stable for a given
+// struct — the SAME bytes on every machine and every run). Zeroing PrevHash here
+// means the hash covers only the record's OWN content; the link to the previous
+// record is added explicitly in computeHash by appending prevHash. This keeps
+// the two concerns separable and the math obvious.
+//
+// We marshal a copy with the two hash fields cleared rather than a parallel
+// struct so there is exactly ONE definition of a record's fields (DRY): add a
+// field to Record and it is covered by the hash automatically.
+func canonicalBytes(r Record) ([]byte, error) {
+	r.Hash = ""
+	r.PrevHash = ""
+	return json.Marshal(r)
+}
+
+// computeHash returns the hex SHA-256 of (canonical(record) || prevHash-bytes).
+// The prevHash is folded in as its RAW hex string bytes — the exact value stored
+// in the record's PrevHash field — so the verifier reproduces it byte-for-byte
+// from stored data alone. Any change to the record's content OR to which record
+// precedes it changes this output, which is the whole tamper-evidence property.
+func computeHash(r Record, prevHash string) (string, error) {
+	body, err := canonicalBytes(r)
+	if err != nil {
+		return "", err
+	}
+	h := sha256.New()
+	h.Write(body)
+	h.Write([]byte(prevHash))
+	return hex.EncodeToString(h.Sum(nil)), nil
+}
+
+// seal finalizes a record into position seq linked to prevHash: it stamps Seq
+// and PrevHash, computes Hash, and returns the sealed record ready to append.
+// The Recorder calls this under its lock so seq/prevHash reflect the true head.
+func seal(r Record, seq uint64, prevHash string) (Record, error) {
+	r.Seq = seq
+	r.PrevHash = prevHash
+	hash, err := computeHash(r, prevHash)
+	if err != nil {
+		return Record{}, err
+	}
+	r.Hash = hash
+	return r, nil
+}

audit/redact.go

@@ -0,0 +1,140 @@
+package audit
+
+// Secret redaction for the before/after captured on a mutation.
+//
+// THE RULE. An audit record must NEVER contain a credential — no password,
+// token, API key, private key, card number, or session secret. Two layers
+// enforce this:
+//
+//  1. The HTTP middleware captures METADATA ONLY (actor/action/resource/outcome).
+//     It NEVER reads a request or response body, so a secret in a POST body can
+//     never reach a record through the automatic path. This is the primary
+//     guarantee: the code that can't see a secret can't leak one.
+//
+//  2. An EXPLICIT emit point that supplies structured before/after (e.g. a config
+//     change diff) runs it through Redact first. Redact walks the JSON and
+//     replaces the VALUE of any key whose name matches the secret denylist with a
+//     fixed marker, recursively. It is deny-by-key-name — the same allowlist
+//     PATTERN cloud already uses for user-secret redaction — chosen because a
+//     mutation diff has arbitrary shape and key-name matching is the robust,
+//     well-understood control (vs. trying to detect "secret-looking" values).
+//
+// Redact is conservative: on any structural surprise it returns the redaction
+// marker rather than the input, so a parser edge case fails CLOSED (no raw
+// passthrough).
+
+import (
+	"encoding/json"
+	"strings"
+)
+
+// redactedMarker replaces every redacted value. A constant so tests and the
+// query UI recognize it unambiguously.
+const redactedMarker = "[REDACTED]"
+
+// secretKeyParts are substrings that, when contained (case-insensitively) in a
+// JSON object key, mark that key's value as secret. Kept as a small, auditable
+// denylist of the credential-bearing field names that actually occur across the
+// Hanzo surface (IAM, KMS, commerce, provider config). Matching is substring so
+// "clientSecret", "api_key", "PRIVATE_KEY", "accessToken" all match.
+var secretKeyParts = []string{
+	"password",
+	"passwd",
+	"secret",
+	"token",
+	"apikey",
+	"api_key",
+	"api-key",
+	"authorization",
+	"auth_token",
+	"private_key",
+	"privatekey",
+	"privkey", // privkey, wgPrivKey
+	"passphrase",
+	"client_secret",
+	"credential",
+	"session",
+	"cookie",
+	"card", // card_number, cardNumber
+	"cvv",
+	"cvc",
+	"pin",
+	"ssn",
+	"social_security", // socialSecurityNumber (lower-cased match covers camelCase)
+	"socialsecurity",
+	"otp",
+	"mnemonic",
+	"phrase", // seed_phrase, seedPhrase, recoveryPhrase
+	"access_key",
+	"secret_key",
+	"refresh_token",
+	"id_token",
+	"bearer",
+	"signing_key",
+	"encryption_key",
+}
+
+// isSecretKey reports whether a JSON key names a credential-bearing field.
+func isSecretKey(key string) bool {
+	k := strings.ToLower(key)
+	for _, part := range secretKeyParts {
+		if strings.Contains(k, part) {
+			return true
+		}
+	}
+	return false
+}
+
+// Redact returns a copy of the JSON value with every secret-keyed value replaced
+// by the redaction marker, recursively through objects and arrays. Non-JSON or
+// empty input yields nil (nothing to record). On a JSON parse error the input is
+// dropped (returns the marker as a JSON string) rather than passed through —
+// fail closed.
+//
+// Use it at any explicit emit point that supplies before/after:
+//
+//	audit.Emit(ctx, rec.WithChange(audit.Redact(before), audit.Redact(after)))
+func Redact(raw json.RawMessage) json.RawMessage {
+	if len(raw) == 0 {
+		return nil
+	}
+	var v any
+	if err := json.Unmarshal(raw, &v); err != nil {
+		// Unparseable — never echo it back verbatim; record a marker instead.
+		b, _ := json.Marshal(redactedMarker)
+		return b
+	}
+	cleaned := redactValue("", v)
+	out, err := json.Marshal(cleaned)
+	if err != nil {
+		b, _ := json.Marshal(redactedMarker)
+		return b
+	}
+	return out
+}
+
+// redactValue walks a decoded JSON value. key is the object key under which v
+// sits (empty at the root and for array elements); when key is a secret key, the
+// ENTIRE value v is replaced (whether it is a scalar, object, or array — a secret
+// nested object is redacted whole). Otherwise objects/arrays are recursed.
+func redactValue(key string, v any) any {
+	if key != "" && isSecretKey(key) {
+		return redactedMarker
+	}
+	switch t := v.(type) {
+	case map[string]any:
+		out := make(map[string]any, len(t))
+		for k, val := range t {
+			out[k] = redactValue(k, val)
+		}
+		return out
+	case []any:
+		out := make([]any, len(t))
+		for i, val := range t {
+			out[i] = redactValue("", val) // array elements inherit no key
+		}
+		return out
+	default:
+		return v
+	}
+}

audit/shareability_probe_test.go

@@ -0,0 +1,107 @@
+package audit
+
+// Shareability probe (HA carve evidence, NOT a shipped feature).
+//
+// Proves the audit SQLite store is SHAREABLE by a read-only second opener while
+// the single writer is live-appending — the exact reader/writer split the HA
+// carve needs. A reader opened with ?mode=ro:
+//   - never takes the write lock, so it cannot contend with or corrupt the
+//     writer's serialized appends (no chain-head fork: the reader never appends),
+//   - sees the writer's committed records via the shared WAL (concurrent reads),
+//   - and on "promotion" a fresh RW open recovers the head from disk == the
+//     writer's last synchronously-persisted record (no gap, no fork).
+//
+// This is the audit-store analog of clients/kms TestReaderReadOnlyRoundTrip
+// (which proves the same for the KMS ZapDB store). Run:
+//   CGO_ENABLED=0 GOWORK=off GOFLAGS=-mod=mod go test ./audit/ -run Shareability -v
+
+import (
+	"context"
+	"database/sql"
+	"sync"
+	"testing"
+	"time"
+
+	_ "github.com/hanzoai/sqlite"
+)
+
+func TestShareability_ReaderSharesLiveWriterStore(t *testing.T) {
+	dir := t.TempDir()
+	path := dir + "/audit.db"
+
+	// Writer: the real serialized Recorder (WAL, MaxOpenConns(1)).
+	w, err := Open(path, nil)
+	if err != nil {
+		t.Fatalf("writer Open: %v", err)
+	}
+	defer w.Close()
+
+	const total = 200
+	var wg sync.WaitGroup
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		for i := 0; i < total; i++ {
+			if _, err := w.Append(context.Background(), Record{Action: "POST /v1/probe"}); err != nil {
+				t.Errorf("append %d: %v", i, err)
+				return
+			}
+			time.Sleep(200 * time.Microsecond)
+		}
+	}()
+
+	// Reader: a SECOND, independent connection opened READ-ONLY against the SAME
+	// files while the writer appends. This is what a reader-role pod does.
+	ro, err := sql.Open("sqlite", "file:"+path+"?mode=ro")
+	if err != nil {
+		t.Fatalf("reader Open(ro): %v", err)
+	}
+	defer ro.Close()
+
+	// Poll the reader's view of the head while the writer runs. It must (a) never
+	// error, (b) be monotonic, and (c) eventually observe the writer's records —
+	// concurrent cross-connection RO reads over a live WAL writer.
+	var lastSeen int64 = -1
+	deadline := time.Now().Add(5 * time.Second)
+	for time.Now().Before(deadline) {
+		var maxSeq sql.NullInt64
+		if err := ro.QueryRow(`SELECT MAX(seq) FROM audit_log`).Scan(&maxSeq); err != nil {
+			t.Fatalf("reader concurrent read failed (store NOT shareable): %v", err)
+		}
+		if maxSeq.Valid {
+			if maxSeq.Int64 < lastSeen {
+				t.Fatalf("reader head regressed %d -> %d (not monotonic)", lastSeen, maxSeq.Int64)
+			}
+			lastSeen = maxSeq.Int64
+		}
+		if lastSeen >= total-1 {
+			break
+		}
+		time.Sleep(2 * time.Millisecond)
+	}
+	wg.Wait()
+
+	if lastSeen < total-1 {
+		t.Fatalf("reader never caught up: saw head %d, writer wrote %d", lastSeen, total-1)
+	}
+
+	// Writer chain is intact and complete AFTER concurrent reader activity.
+	gotCount, _ := w.Head()
+	if gotCount != total {
+		t.Fatalf("writer head count = %d, want %d", gotCount, total)
+	}
+
+	// "Promotion": a fresh RW opener (the reader taking over) recovers the head
+	// from disk == the writer's last synchronously-persisted record. No fork.
+	promoted, err := Open(path, nil)
+	if err != nil {
+		t.Fatalf("promotion RW re-open: %v", err)
+	}
+	defer promoted.Close()
+	pc, _ := promoted.Head()
+	if pc != total {
+		t.Fatalf("promoted writer recovered head %d, want %d (chain gap/fork)", pc, total)
+	}
+	t.Logf("SHAREABLE: reader observed %d records concurrently; writer chain=%d; promotion recovered head=%d",
+		lastSeen+1, gotCount, pc)
+}

audit/store.go

@@ -0,0 +1,381 @@
+package audit
+
+// The append-only sink + the serialized Recorder that owns the hash-chain head.
+//
+// WHY SQLITE IS THE PRIMARY, DURABLE STORE (not datastore). The chain is only
+// tamper-EVIDENT if records are appended in a strict, gapless total order and
+// each record's PrevHash is the immediately-preceding record's Hash. That demands
+// a single serializing writer with a synchronous, read-your-write head. cloud's
+// canonical store is embedded SQLite (one store per the storagelock lockdown;
+// pricing/provisioning already persist to {DataDir}/*.db). A local SQLite table
+// the application can only INSERT into gives us: (a) a real total order under one
+// connection, (b) synchronous durability so NO record is ever lost on the request
+// path (unlike a fire-and-forget mirror), and (c) an append-only surface — the
+// app issues no UPDATE/DELETE, and the hash-chain detects any out-of-band edit to
+// the file. That is the compliance-grade primary control.
+//
+// THE CLICKHOUSE MIRROR IS A PROJECTION, NOT THE SOURCE OF TRUTH. The datastore
+// (datastore MergeTree — insert-only, mutation-rejected at parse time) is the
+// fleet-wide OLAP mirror for long-retention, cross-deployment query. It is
+// best-effort and asynchronous: a mirror outage must never block or fail an
+// audited request, and the local chain remains the authority the verifier walks.
+// Losing a mirror row is a query-completeness issue, not an integrity one.
+//
+// FAIL MODE. Append is INLINE and its error is RETURNED to the middleware, which
+// fails the request CLOSED (a security-relevant action that cannot be recorded is
+// not permitted to silently succeed). This is the AU-5 "response to audit logging
+// process failure": deny rather than act-unlogged.
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"fmt"
+	"sync"
+	"time"
+
+	// github.com/hanzoai/sqlite is the ONE Hanzo SQLite driver: it registers
+	// the "sqlite" database/sql name under both build tags (cgo →
+	// mattn+SQLCipher, encrypted at rest; !cgo → pure-Go modernc). Importing
+	// modernc directly instead would double-register "sqlite" under CGO and
+	// panic at init. Blank import registers the driver.
+	"github.com/hanzoai/cloud/cek"
+	_ "github.com/hanzoai/sqlite"
+)
+
+// Mirror is the optional OLAP projection sink (the datastore/datastore). It is
+// deliberately a tiny interface, not a concrete client, so the Recorder has no
+// compile-time dependency on datastore and tests can supply a fake. Append is
+// called best-effort, asynchronously, off the request path.
+type Mirror interface {
+	// Append writes one sealed record to the projection. A returned error is
+	// logged and dropped by the Recorder — the mirror never gates a request.
+	Append(ctx context.Context, r Record) error
+}
+
+// Checkpoint is a periodic, tamper-EVIDENCE digest of the chain head: the record
+// count and the head hash at a moment in time. It is the AU-9 anchor for
+// TAIL-TRUNCATION detection — an internal chain walk cannot notice that the last
+// K records were deleted (the surviving prefix still verifies), but a durable,
+// INDEPENDENT series of head checkpoints can: Count is monotonic, so any decrease
+// between two consecutive checkpoints is deletion, and an attacker cannot forge a
+// higher count without appending records whose hashes the chain walk would reject.
+type Checkpoint struct {
+	Time  time.Time `json:"time"`
+	Count uint64    `json:"count"`
+	Head  string    `json:"head"`
+}
+
+// CheckpointSink is an optional capability a Mirror may implement to persist the
+// head digest series to an INDEPENDENT store (so truncating the local SQLite
+// cannot also rewrite the anchor history). A Mirror that does not implement it
+// still gets its records; checkpoints then flow only to the structured log.
+type CheckpointSink interface {
+	Checkpoint(ctx context.Context, cp Checkpoint) error
+}
+
+// Recorder is the single serialized writer that owns the audit chain head and
+// the append-only store. Every Record flows through Append, which under one lock
+// assigns the next Seq, links PrevHash to the current head, seals (hashes), and
+// synchronously persists to SQLite before returning. Concurrency is serialized
+// by mu AND by the single-connection SQLite pool, so the on-disk order equals
+// the chain order with no gaps.
+type Recorder struct {
+	db     *sql.DB
+	mirror Mirror // nil when no OLAP mirror is configured.
+
+	mu       sync.Mutex // guards nextSeq/headHash and serializes appends.
+	nextSeq  uint64     // Seq to assign to the next record.
+	headHash string     // Hash of the last-appended record (PrevHash for the next).
+
+	// Checkpoint emission (AU-9 tail-truncation anchor). logCheckpoint, when set,
+	// receives each head digest so it lands in the append-only observability log;
+	// stopCh/wg manage the periodic emitter goroutine's lifecycle; started guards
+	// against a second StartCheckpoints call (the field write + WaitGroup use are
+	// not safe to race). All three are set once, before any concurrent Append.
+	logCheckpoint func(cp Checkpoint)
+	stopCh        chan struct{}
+	wg            sync.WaitGroup
+	started       bool
+}
+
+// CheckpointFunc receives a head digest for the structured (o11y) log. It is a
+// plain func so the pure audit package stays free of any concrete logger type;
+// the cloud wiring adapts luxlog to it.
+type CheckpointFunc func(cp Checkpoint)
+
+// Open opens (creating if needed) the append-only audit DB at path and recovers
+// the chain head from it, so a restart continues the SAME chain rather than
+// forking a new one. path may be ":memory:" for tests. mirror may be nil.
+//
+// the hanzoai/sqlite "sqlite" driver; MaxOpenConns(1) serializes every statement against
+// the file lock — the same single-writer discipline pricing/provisioning use,
+// here doubling as the chain's serialization guarantee.
+func Open(path string, mirror Mirror) (*Recorder, error) {
+	db, err := cek.Open(path)
+	if err != nil {
+		return nil, fmt.Errorf("audit: open sqlite %q: %w", path, err)
+	}
+	db.SetMaxOpenConns(1)
+	for _, pragma := range []string{
+		"PRAGMA busy_timeout=5000",
+		"PRAGMA journal_mode=WAL",
+		"PRAGMA synchronous=NORMAL",
+	} {
+		if _, err := db.Exec(pragma); err != nil {
+			_ = db.Close()
+			return nil, fmt.Errorf("audit: pragma %q: %w", pragma, err)
+		}
+	}
+	r := &Recorder{db: db, mirror: mirror}
+	if err := r.migrate(); err != nil {
+		_ = db.Close()
+		return nil, err
+	}
+	if err := r.recoverHead(); err != nil {
+		_ = db.Close()
+		return nil, err
+	}
+	return r, nil
+}
+
+// migrate creates the append-only audit table. It is INSERT-only by application
+// discipline: this package issues no UPDATE or DELETE against it, and seq is the
+// PRIMARY KEY so a replayed/duplicated seq is rejected by the engine. The hash
+// columns make any out-of-band row edit detectable by Verify regardless of the
+// storage layer's own guarantees.
+func (r *Recorder) migrate() error {
+	const ddl = `
+CREATE TABLE IF NOT EXISTS audit_log (
+  seq        INTEGER PRIMARY KEY,       -- chain position; gapless, assigned under lock
+  ts         TEXT    NOT NULL,          -- RFC3339Nano UTC event time
+  actor_org  TEXT    NOT NULL DEFAULT '',
+  actor_sub  TEXT    NOT NULL DEFAULT '',
+  actor_email TEXT   NOT NULL DEFAULT '',
+  action     TEXT    NOT NULL,
+  res_type   TEXT    NOT NULL DEFAULT '',
+  res_id     TEXT    NOT NULL DEFAULT '',
+  auth_method TEXT   NOT NULL DEFAULT '',
+  is_admin   INTEGER NOT NULL DEFAULT 0,
+  result     TEXT    NOT NULL,          -- success|deny|error
+  status     INTEGER NOT NULL DEFAULT 0,
+  reason     TEXT    NOT NULL DEFAULT '',
+  source_ip  TEXT    NOT NULL DEFAULT '',
+  user_agent TEXT    NOT NULL DEFAULT '',
+  request_id TEXT    NOT NULL DEFAULT '',
+  method     TEXT    NOT NULL DEFAULT '',
+  path       TEXT    NOT NULL DEFAULT '',
+  before     TEXT    NOT NULL DEFAULT '',  -- redacted JSON (explicit emit only)
+  after      TEXT    NOT NULL DEFAULT '',  -- redacted JSON (explicit emit only)
+  prev_hash  TEXT    NOT NULL,
+  hash       TEXT    NOT NULL
+);
+-- Query indexes for the /v1/admin/audit filters (actor/action/resource/time).
+CREATE INDEX IF NOT EXISTS ix_audit_org_seq    ON audit_log(actor_org, seq);
+CREATE INDEX IF NOT EXISTS ix_audit_action_seq ON audit_log(action, seq);
+CREATE INDEX IF NOT EXISTS ix_audit_result_seq ON audit_log(result, seq);
+CREATE INDEX IF NOT EXISTS ix_audit_ts         ON audit_log(ts);
+`
+	if _, err := r.db.Exec(ddl); err != nil {
+		return fmt.Errorf("audit: migrate: %w", err)
+	}
+	return nil
+}
+
+// recoverHead loads the highest-seq record so a restarted process continues the
+// existing chain (nextSeq = maxSeq+1, headHash = its hash). An empty table starts
+// the genesis chain (nextSeq 0, headHash = genesisPrevHash).
+func (r *Recorder) recoverHead() error {
+	var (
+		maxSeq sql.NullInt64
+		hash   sql.NullString
+	)
+	row := r.db.QueryRow(`SELECT seq, hash FROM audit_log WHERE seq = (SELECT MAX(seq) FROM audit_log)`)
+	if err := row.Scan(&maxSeq, &hash); err != nil {
+		if errors.Is(err, sql.ErrNoRows) {
+			r.nextSeq = 0
+			r.headHash = genesisPrevHash
+			return nil
+		}
+		return fmt.Errorf("audit: recover head: %w", err)
+	}
+	if !maxSeq.Valid { // empty table (MAX over zero rows is NULL)
+		r.nextSeq = 0
+		r.headHash = genesisPrevHash
+		return nil
+	}
+	r.nextSeq = uint64(maxSeq.Int64) + 1
+	r.headHash = hash.String
+	return nil
+}
+
+// Append seals r into the next chain position and persists it. It fills Seq,
+// PrevHash, and Hash (the caller sets everything else), advances the in-memory
+// head only AFTER the durable INSERT succeeds, and mirrors best-effort. A
+// persistence error is returned so the caller can fail the request CLOSED — the
+// head is NOT advanced on failure, so the chain never gaps.
+//
+// The whole critical section (assign seq → seal → INSERT → advance head) holds
+// mu, so two concurrent requests can never claim the same seq or race the head.
+func (r *Recorder) Append(ctx context.Context, rec Record) (Record, error) {
+	if rec.Time.IsZero() {
+		rec.Time = time.Now().UTC()
+	} else {
+		rec.Time = rec.Time.UTC()
+	}
+
+	r.mu.Lock()
+	defer r.mu.Unlock()
+
+	sealed, err := seal(rec, r.nextSeq, r.headHash)
+	if err != nil {
+		return Record{}, fmt.Errorf("audit: seal: %w", err)
+	}
+	if err := r.insert(ctx, sealed); err != nil {
+		// Head not advanced; the next append reuses this seq. Fail closed upstream.
+		return Record{}, fmt.Errorf("audit: persist: %w", err)
+	}
+	// Durable — advance the chain head.
+	r.nextSeq = sealed.Seq + 1
+	r.headHash = sealed.Hash
+
+	// Best-effort OLAP mirror, detached so a slow/failed mirror never blocks the
+	// request or corrupts the reply. The local chain is already durable and is the
+	// authority; a lost mirror row is a query-completeness gap, not an integrity
+	// one. Copy by value: the record is immutable and safe to hand to a goroutine.
+	if r.mirror != nil {
+		m, out := r.mirror, sealed
+		go func() { _ = m.Append(context.Background(), out) }()
+	}
+	return sealed, nil
+}
+
+// insert writes one sealed record. INSERT-only — the sole write statement in this
+// package. A duplicate seq (PRIMARY KEY) fails here, which is the desired
+// invariant: the chain never overwrites a position.
+func (r *Recorder) insert(ctx context.Context, rec Record) error {
+	_, err := r.db.ExecContext(ctx, `
+INSERT INTO audit_log (
+  seq, ts, actor_org, actor_sub, actor_email, action, res_type, res_id,
+  auth_method, is_admin, result, status, reason, source_ip, user_agent,
+  request_id, method, path, before, after, prev_hash, hash
+) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`,
+		rec.Seq, rec.Time.Format(time.RFC3339Nano),
+		rec.Actor.Org, rec.Actor.Sub, rec.Actor.Email,
+		rec.Action, rec.Resource.Type, rec.Resource.ID,
+		rec.Auth.Method, boolToInt(rec.Auth.IsAdmin),
+		rec.Outcome.Result, rec.Outcome.Status, rec.Outcome.Reason,
+		rec.SourceIP, rec.UserAgent, rec.RequestID, rec.Method, rec.Path,
+		string(rec.Before), string(rec.After), rec.PrevHash, rec.Hash,
+	)
+	return err
+}
+
+// checkpointCloseTimeout bounds the final (synchronous) checkpoint write to the
+// independent sink at shutdown, so Close cannot hang on an unreachable datastore.
+const checkpointCloseTimeout = 5 * time.Second
+
+// Close stops the periodic checkpoint emitter, emits a FINAL checkpoint
+// SYNCHRONOUSLY (so the head at shutdown reaches both the o11y log and the
+// independent digest store before the process exits — the AU-9 anchor must be
+// current exactly when an attacker might trigger shutdown then truncate), and
+// closes the underlying database.
+func (r *Recorder) Close() error {
+	if r == nil || r.db == nil {
+		return nil
+	}
+	if r.stopCh != nil {
+		close(r.stopCh)
+		r.wg.Wait()
+		r.stopCh = nil
+	}
+	// Anchor the final head before the DB closes — independent of whether the
+	// periodic ticker was running (every<=0 still gets a shutdown checkpoint).
+	// Synchronous to the sink (bounded), so the independent store's last count is
+	// as fresh as the local chain at the moment of shutdown.
+	r.emitCheckpoint(true)
+	return r.db.Close()
+}
+
+// StartCheckpoints begins periodic head-digest emission every `every` (no ticker
+// if every<=0; the on-Close checkpoint still fires). logFn, when non-nil,
+// receives each digest for the append-only observability log (o11y), and a mirror
+// implementing CheckpointSink also gets it persisted to an INDEPENDENT store —
+// together the AU-9 anchor an external monitor compares to detect tail-truncation
+// (count regression). MUST be called at most once, before any concurrent Append
+// (a second call is ignored); the emitter stops on Close.
+func (r *Recorder) StartCheckpoints(every time.Duration, logFn CheckpointFunc) {
+	// Guard the check-and-set under mu so a (mis)use that calls this concurrently
+	// is race-free, not just the single-call production path.
+	r.mu.Lock()
+	if r.started {
+		r.mu.Unlock()
+		return // already started — do not re-arm (avoids a field/WaitGroup race).
+	}
+	r.started = true
+	r.logCheckpoint = logFn
+	r.mu.Unlock()
+	if every <= 0 {
+		return
+	}
+	r.stopCh = make(chan struct{})
+	stop := r.stopCh
+	r.wg.Add(1)
+	go func() {
+		defer r.wg.Done()
+		t := time.NewTicker(every)
+		defer t.Stop()
+		for {
+			select {
+			case <-stop:
+				return
+			case <-t.C:
+				r.emitCheckpoint(false)
+			}
+		}
+	}()
+}
+
+// emitCheckpoint snapshots the head and emits it to the log and (if the mirror is
+// a CheckpointSink) the independent digest store. sync controls the sink write:
+// on the periodic path (sync=false) it is detached so a slow sink never delays
+// the ticker; on the Close path (sync=true) it BLOCKS on a bounded context so the
+// final anchor is durable before shutdown. The log emission is always synchronous
+// (it is the primary anchor and o11y ingests it append-only).
+func (r *Recorder) emitCheckpoint(sync bool) {
+	count, head := r.Head()
+	cp := Checkpoint{Time: time.Now().UTC(), Count: count, Head: head}
+	if r.logCheckpoint != nil {
+		r.logCheckpoint(cp)
+	}
+	cs, ok := r.mirror.(CheckpointSink)
+	if !ok || cs == nil {
+		return
+	}
+	if sync {
+		ctx, cancel := context.WithTimeout(context.Background(), checkpointCloseTimeout)
+		defer cancel()
+		_ = cs.Checkpoint(ctx, cp)
+		return
+	}
+	go func() { _ = cs.Checkpoint(context.Background(), cp) }()
+}
+
+// Head returns the current chain head (count of records, and the head hash). A
+// count of 0 means the genesis (empty) chain, headHash == genesisPrevHash. An
+// external monitor can pin (count, headHash) over time to detect tail-truncation
+// — which an internal chain walk alone cannot catch (a truncated prefix still
+// verifies). This is the anchor point for AU-9 protection against deletion of the
+// most-recent records.
+func (r *Recorder) Head() (count uint64, headHash string) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	return r.nextSeq, r.headHash
+}
+
+func boolToInt(b bool) int {
+	if b {
+		return 1
+	}
+	return 0
+}

audit/wire.go

@@ -0,0 +1,60 @@
+package audit
+
+import "time"
+
+// Wire is the JSON shape of one audit record on the operator/console contract. It
+// is cloud's OWN record projection — richer than the IAM record it supersedes: it
+// carries the outcome, the validated auth context, and the hash-chain linkage
+// (Hash/PrevHash) so a console can show tamper-evidence per row. The JSON tags ARE
+// the contract; both the admin god-view (/v1/admin/audit) and the org-scoped trail
+// (/v1/audit) serialize this ONE shape so a single console adapter reads either.
+type Wire struct {
+	Seq        uint64 `json:"seq"`
+	Time       string `json:"time"`
+	Org        string `json:"org"`
+	Sub        string `json:"sub"`
+	Email      string `json:"email,omitempty"`
+	Action     string `json:"action"`
+	Resource   string `json:"resource"`
+	ResourceID string `json:"resourceId,omitempty"`
+	Method     string `json:"method,omitempty"`
+	Path       string `json:"path,omitempty"`
+	Result     string `json:"result"`
+	Status     int    `json:"status"`
+	Reason     string `json:"reason,omitempty"`
+	SourceIP   string `json:"sourceIp,omitempty"`
+	UserAgent  string `json:"userAgent,omitempty"`
+	RequestID  string `json:"requestId,omitempty"`
+	IsAdmin    bool   `json:"isAdmin"`
+	Auth       string `json:"authMethod,omitempty"`
+	Hash       string `json:"hash"`
+	PrevHash   string `json:"prevHash"`
+}
+
+// ToWire projects a stored Record onto the console wire shape. Time is emitted as
+// RFC3339Nano (UTC) — the same nanosecond-precise, order-preserving format the ts
+// column stores — so a client can sort/range on it verbatim.
+func (r Record) ToWire() Wire {
+	return Wire{
+		Seq:        r.Seq,
+		Time:       r.Time.UTC().Format(time.RFC3339Nano),
+		Org:        r.Actor.Org,
+		Sub:        r.Actor.Sub,
+		Email:      r.Actor.Email,
+		Action:     r.Action,
+		Resource:   r.Resource.Type,
+		ResourceID: r.Resource.ID,
+		Method:     r.Method,
+		Path:       r.Path,
+		Result:     r.Outcome.Result,
+		Status:     r.Outcome.Status,
+		Reason:     r.Outcome.Reason,
+		SourceIP:   r.SourceIP,
+		UserAgent:  r.UserAgent,
+		RequestID:  r.RequestID,
+		IsAdmin:    r.Auth.IsAdmin,
+		Auth:       r.Auth.Method,
+		Hash:       r.Hash,
+		PrevHash:   r.PrevHash,
+	}
+}

audit/wire_test.go

@@ -0,0 +1,73 @@
+package audit
+
+import (
+	"context"
+	"testing"
+	"time"
+)
+
+func TestToWire_MapsEveryField(t *testing.T) {
+	r := Record{
+		Seq:      7,
+		Time:     time.Date(2026, 7, 4, 12, 30, 0, 0, time.UTC),
+		Actor:    Actor{Org: "maxpower", Sub: "dave", Email: "dave@maxpower.ai"},
+		Action:   "machine.create",
+		Resource: Resource{Type: "machine", ID: "m-1"},
+		Auth:     AuthContext{Method: "jwt", IsAdmin: true},
+		Outcome:  Outcome{Result: "success", Status: 201, Reason: "ok"},
+		SourceIP: "1.2.3.4", UserAgent: "test-agent", RequestID: "req-1",
+		Method: "POST", Path: "/v1/machines",
+		PrevHash: "aa", Hash: "bb",
+	}
+	w := r.ToWire()
+	if w.Seq != 7 || w.Time != "2026-07-04T12:30:00Z" {
+		t.Fatalf("seq/time: %+v", w)
+	}
+	if w.Org != "maxpower" || w.Sub != "dave" || w.Email != "dave@maxpower.ai" {
+		t.Fatalf("actor: %+v", w)
+	}
+	if w.Action != "machine.create" || w.Resource != "machine" || w.ResourceID != "m-1" {
+		t.Fatalf("action/resource: %+v", w)
+	}
+	if w.Auth != "jwt" || !w.IsAdmin {
+		t.Fatalf("auth: %+v", w)
+	}
+	if w.Result != "success" || w.Status != 201 || w.Reason != "ok" {
+		t.Fatalf("outcome: %+v", w)
+	}
+	if w.Method != "POST" || w.Path != "/v1/machines" || w.SourceIP != "1.2.3.4" {
+		t.Fatalf("request: %+v", w)
+	}
+	if w.Hash != "bb" || w.PrevHash != "aa" {
+		t.Fatalf("chain: %+v", w)
+	}
+}
+
+func TestQuery_ResourceIDFilter(t *testing.T) {
+	rec, err := Open(":memory:", nil)
+	if err != nil {
+		t.Fatalf("Open: %v", err)
+	}
+	defer func() { _ = rec.Close() }()
+	ctx := context.Background()
+	for _, id := range []string{"m-1", "m-1", "m-2"} {
+		if _, err := rec.Append(ctx, Record{
+			Actor: Actor{Org: "o"}, Action: "machine.op",
+			Resource: Resource{Type: "machine", ID: id}, Outcome: Outcome{Result: "success"},
+		}); err != nil {
+			t.Fatalf("append: %v", err)
+		}
+	}
+	rows, total, err := rec.Query(ctx, Filter{ResourceID: "m-1"})
+	if err != nil {
+		t.Fatalf("Query: %v", err)
+	}
+	if total != 2 || len(rows) != 2 {
+		t.Fatalf("resourceId filter: want 2 rows on m-1, got %d rows total %d", len(rows), total)
+	}
+	for _, r := range rows {
+		if r.Resource.ID != "m-1" {
+			t.Fatalf("filter leaked %q", r.Resource.ID)
+		}
+	}
+}

audit_middleware.go

@@ -0,0 +1,677 @@
+package cloud
+
+// The audit middleware — the ONE place every security-relevant request is
+// recorded to the tamper-evident trail (decomplected: one function, every route).
+//
+// PLACEMENT (why it sits exactly where serve.go puts it). The pipeline is
+// Recover → RequestID → Logger → SanitizeIdentity → AuditTrail → BillingGate →
+// subsystems. AuditTrail runs:
+//   - AFTER SanitizeIdentity, so the actor/isAdmin it records come from a
+//     VALIDATED IAM principal (the sanitized X-User-* headers), never a raw
+//     client header. The request being audited cannot forge its own actor.
+//   - BEFORE BillingGate and every subsystem, so it WRAPS the whole handler
+//     chain and observes the FINAL outcome — including a 402/503 billing denial
+//     and a 403 admin-guard denial (both security-relevant) — via the response
+//     status after Continue(), exactly like the Logger middleware reads it.
+//
+// WHAT IT CAPTURES: metadata only — actor, action (method+route family),
+// resource, source ip, user agent, request id, auth context, and the outcome
+// (result/status/reason). It NEVER reads the request or response BODY, so a
+// secret in a POST body can never reach a record through this path. before/after
+// diffs are the job of explicit emit points (audit.Recorder.Append with a
+// redacted diff), not this middleware.
+//
+// WHAT IT RECORDS (the coverage predicate, auditable in one place — see
+// isSecurityRelevant): every mutating request (POST/PUT/PATCH/DELETE), every
+// /v1/admin/* request (read or write — admin reads are AC-relevant), and every
+// auth-failure outcome (401/403) on ANY method (a denied GET is an access-control
+// event). Safe, unauthenticated reads (a 200 GET on a public route) are NOT
+// audited — that is request-log noise, not a security event, and auditing it
+// would bury the signal and balloon the trail.
+//
+// FAIL MODE (AU-5): if the trail write fails on a request we decided to audit,
+// the CLIENT gets a fail-closed 503 rather than a success it can rely on — the
+// AU-5 "response to an audit logging process failure" is to interrupt, not to
+// operate silently unlogged. A write to local SQLite is sub-millisecond, so this
+// is a real integrity stance, not a latency tax. When no Recorder is configured
+// the middleware is a no-op passthrough (an unconfigured deployment is never
+// blocked), exactly like BillingGate.
+//
+// PRECISE SEMANTIC (do not over-read the 503). This is POST-RESPONSE audit: the
+// handler has already run when the record is written, so a 503 here means "this
+// event could not be RECORDED", NOT "the action did not execute". PREVENTION is
+// the access-control layer's job and runs BEFORE the action — SanitizeIdentity
+// (identity can't be forged) + the per-route admin guard both execute inside
+// c.Next() ahead of any side effect. The audit trail's job is DETECTION and
+// ACCOUNTABILITY (tamper-evident record of what happened), which it does. On a
+// persistent audit-store outage every mutation returns 503 (loud, logged), so
+// the system degrades to read-only rather than mutating unaudited — the intended
+// compliance posture.
+//
+// PANIC BOUND. If a handler PANICS, the outermost middleware.Recover catches it
+// and renders 500 with a full stack trace (loud, never silent); the panic unwinds
+// PAST this middleware's post-c.Next() code, so a panicking request is not written
+// to the trail. This is an accepted bound, not an evasion: an attacker cannot turn
+// a panic into a SUCCESSFUL-but-unaudited mutation (a panic yields 500, not a
+// completed action), and every panic is already captured by Recover's logging.
+// Normal outcomes — including billing 402/503 and admin 403 denials, which return
+// through c.Next() rather than panicking — are always audited.
+
+import (
+	"errors"
+	"net/url"
+	"strings"
+
+	"github.com/hanzoai/cloud/audit"
+	"github.com/hanzoai/cloud/clients/principal"
+	"github.com/zap-proto/zip"
+)
+
+// AuditTrail returns the audit middleware bound to rec. A nil rec makes it a
+// no-op passthrough so callers always Use() it unconditionally.
+func AuditTrail(rec *audit.Recorder) zip.Handler {
+	if rec == nil {
+		return func(c *zip.Ctx) error { return c.Next() }
+	}
+	return func(c *zip.Ctx) error {
+		// Capture the pre-decision inputs BEFORE running the chain: the request
+		// context is recycled by Fiber after the handler returns, so identity and
+		// request fields must be read now (mirrors BillingGate capturing usage by
+		// value pre-Record).
+		method := c.Method()
+		path := c.Path()
+
+		err := c.Next()
+
+		// Resolve the EFFECTIVE status. A handler may set it on the response
+		// directly (c.Status(...).JSON(...)) OR return a *zip.HTTPError that the
+		// framework's error handler renders AFTER this middleware unwinds — in the
+		// latter case the response still reads 200 here, so the returned error is
+		// the authoritative source of a 401/403. Prefer the error's status when it
+		// carries one; this is what makes admin-guard denials (which return
+		// ErrForbidden) get audited as 403.
+		status := effectiveStatus(c.Fiber().Response().StatusCode(), err)
+		if !isSecurityRelevant(method, path, status) {
+			return err // not an audited event; pass the handler result through.
+		}
+
+		record := audit.Record{
+			Actor:    actorFromCtx(c),
+			Action:   method + " " + routeFamily(path),
+			Resource: resourceFromPath(path),
+			Auth:     authFromCtx(c),
+			Outcome:  outcomeOf(status, err),
+			SourceIP: ClientIP(c),
+			// User-Agent is client-controlled free text; a misconfigured/malicious
+			// client could embed a bearer token in it. Scrub credential-shaped runs
+			// (and cap length) so the UA can never carry a secret into the record.
+			UserAgent: scrubFreeText(c.Header("User-Agent")),
+			RequestID: c.RequestID(),
+			Method:    method,
+			// Path is scrubbed of any credential-shaped segment: Hanzo routes use
+			// identifiers (:name/:slug/:id), not secrets, but a token that ever
+			// rides in the path (an hk-/sk-/pk-/fw_/hz_ key) must never be recorded
+			// verbatim. resourceFromPath applies the same scrub to the resource id.
+			Path: scrubCredentialSegments(path),
+		}
+
+		if _, aerr := rec.Append(c.Context(), record); aerr != nil {
+			// AU-5: could not record a security-relevant event — fail the request
+			// closed. Do NOT leak the audit error to the client; log it loud.
+			c.Log().Error("audit append failed — failing request closed",
+				"path", path, "method", method, "err", aerr)
+			return c.JSON(503, map[string]any{
+				"error": map[string]string{
+					"code":    "audit_unavailable",
+					"message": "Request could not be securely recorded",
+				},
+			})
+		}
+		return err
+	}
+}
+
+// isSecurityRelevant is the coverage predicate — the ONE place that decides which
+// requests enter the audit trail (AC/AU scope). Kept tiny and total so the
+// coverage matrix is reviewable at a glance. Order matters and is deliberate:
+// the security-relevant conditions are checked FIRST and are unconditional, so
+// the health-probe exemption can NEVER be used to evade audit of a mutation or a
+// denial (a POST/DELETE, or any 401/403, is always audited whatever the path).
+//   - any auth-failure outcome (401/403) on any method (a denied access attempt),
+//   - any /v1/admin/* request (admin reads are access-control-relevant),
+//   - any mutating request (POST/PUT/PATCH/DELETE).
+//
+// Only then, a genuine liveness probe (a GET to an exact health route) is
+// exempted — it is neither a mutation, a denial, nor an admin call, so it is pure
+// request-log noise. The exemption matches EXACT probe paths, never an arbitrary
+// path that merely ends in "/health" (which a wildcard/attacker-named segment
+// like POST /v1/admin/orgs/x/health could otherwise abuse to slip past audit).
+func isSecurityRelevant(method, path string, status int) bool {
+	// Unconditional security signals — never suppressed by any path shape. A
+	// denial, an admin call, or a mutation is ALWAYS audited, whatever the path
+	// (so a wildcard/attacker-named "/health" tail cannot evade it).
+	if status == 401 || status == 403 {
+		return true
+	}
+	if strings.HasPrefix(path, "/v1/admin/") {
+		return true
+	}
+	if isMutation(method) {
+		return true
+	}
+	// Everything left is a safe read (non-mutating, non-admin, non-denied). None
+	// are audited — they are request-log noise, not security events. (Liveness
+	// probes fall here too; there is no separate case because the answer is the
+	// same: not recorded.)
+	return false
+}
+
+// isMutation reports whether a method changes state.
+func isMutation(method string) bool {
+	switch method {
+	case "POST", "PUT", "PATCH", "DELETE":
+		return true
+	default:
+		return false
+	}
+}
+
+// actorFromCtx builds the Actor from the sanitized identity headers, gating
+// ANTI-FORGERY of the recorded actor on a VALIDATED principal.
+//
+// The authoritative "this request carried a validated principal" signal is a
+// non-empty X-User-Id (c.User()): SanitizeIdentity sets X-User-Id ONLY from a
+// JWT it verified, and strips any client-supplied copy on ingress. A request
+// with no principal — anonymous, OR one bearing an INVALID/garbage bearer that
+// failed validation — has an empty c.User().
+//
+// In that unvalidated case the org header is NOT trustworthy: SanitizeIdentity's
+// Phase-1 residual restores a client-supplied X-Org-Id for the data path, so an
+// anonymous attacker could send X-Org-Id: victim-org and, if we recorded it,
+// forge a FALSE ATTRIBUTION (an event stamped with a victim's org). So when there
+// is no validated sub, the actor is left EMPTY — the record stands as an honest
+// anonymous event identified by SourceIP, never mis-attributed to a claimed org.
+//
+// With a validated sub, org/sub/email all reflect the verified principal and are
+// recorded authoritatively.
+func actorFromCtx(c *zip.Ctx) audit.Actor {
+	if !principal.Validated(c) {
+		// No validated principal — do not trust the client-asserted org.
+		return audit.Actor{}
+	}
+	return audit.Actor{
+		Org:   strings.TrimSpace(c.Org()),
+		Sub:   strings.TrimSpace(c.User()),
+		Email: strings.TrimSpace(c.UserEmail()),
+	}
+}
+
+// authFromCtx records HOW the caller authenticated and the VALIDATED admin bit.
+// IsAdmin comes from c.IsAdmin() (the sanitized X-User-IsAdmin, true only for a
+// verified SuperAdmin), never a raw header. Method is inferred from the
+// presence/shape of a credential: an Authorization/X-Authorization bearer or a
+// session cookie ⇒ "jwt" (or "api-key" for an opaque hk-/sk- token); none ⇒
+// "none".
+func authFromCtx(c *zip.Ctx) audit.AuthContext {
+	return audit.AuthContext{
+		Method:  authMethodOf(c),
+		IsAdmin: c.IsAdmin(),
+	}
+}
+
+// authMethodOf classifies the credential kind WITHOUT capturing it — it inspects
+// only the token PREFIX (never stores the value). Order mirrors the sanitizer's
+// extraction (bearer, then cookie).
+func authMethodOf(c *zip.Ctx) string {
+	auth := c.Header("Authorization")
+	if auth == "" {
+		auth = c.Header("X-Authorization")
+	}
+	if tok := bearerFromAuth(auth); tok != "" {
+		if isAPIKey(tok) {
+			return "api-key"
+		}
+		return "jwt"
+	}
+	if basicFromAuth(auth) != "" {
+		return "basic"
+	}
+	for _, name := range cookieTokenNames {
+		if c.Fiber().Cookies(name) != "" {
+			return "jwt"
+		}
+	}
+	return "none"
+}
+
+// effectiveStatus reconciles the response status with a returned error. If the
+// handler returned a *zip.HTTPError (e.g. ErrForbidden), its Status is
+// authoritative — the framework renders it after this middleware unwinds, so the
+// live response status does not yet reflect it. A non-HTTPError returned error
+// with a still-2xx response means the framework will render a 500. Otherwise the
+// response status stands.
+func effectiveStatus(respStatus int, err error) int {
+	if err != nil {
+		var he *zip.HTTPError
+		if errors.As(err, &he) && he.Status != 0 {
+			return he.Status
+		}
+		// A non-HTTPError propagating up renders as 500, unless the handler already
+		// set an explicit error status on the response.
+		if respStatus < 400 {
+			return 500
+		}
+	}
+	return respStatus
+}
+
+// outcomeOf maps the final HTTP status + handler error to an audit Outcome.
+// 2xx/3xx ⇒ success; 401/403 ⇒ deny; everything else (4xx/5xx) ⇒ error. The
+// reason is a short, non-sensitive label derived from the status class — never a
+// raw upstream error body (which could echo sensitive detail).
+func outcomeOf(status int, err error) audit.Outcome {
+	switch {
+	case status == 401:
+		return audit.Outcome{Result: "deny", Status: status, Reason: "unauthenticated"}
+	case status == 403:
+		return audit.Outcome{Result: "deny", Status: status, Reason: "forbidden"}
+	case status >= 500:
+		return audit.Outcome{Result: "error", Status: status, Reason: "server_error"}
+	case status >= 400:
+		return audit.Outcome{Result: "error", Status: status, Reason: "client_error"}
+	default:
+		return audit.Outcome{Result: "success", Status: status}
+	}
+}
+
+// routeFamily reduces a concrete path to its stable route family for the action
+// verb, dropping trailing high-cardinality id segments so "DELETE /v1/admin/
+// orgs/acme" and "DELETE /v1/admin/orgs/globex" share the action "DELETE
+// /v1/admin/orgs". The full concrete path is preserved separately in Record.Path.
+func routeFamily(path string) string {
+	segs := strings.Split(strings.Trim(path, "/"), "/")
+	// Keep the leading "v1/<subsystem>/<noun>" and stop before an id-looking tail.
+	out := make([]string, 0, len(segs))
+	for _, s := range segs {
+		if looksLikeID(s) {
+			break
+		}
+		out = append(out, s)
+	}
+	if len(out) == 0 {
+		return "/" + strings.Join(segs, "/")
+	}
+	return "/" + strings.Join(out, "/")
+}
+
+// resourceFromPath derives the {type,id} resource from a /v1/<subsystem>/<type>/
+// [<id>] path. Type is the noun after the subsystem; ID is the following segment
+// when it looks like an identifier. Best-effort — the Action verb + Path are the
+// authoritative locator; this is a convenience for filtering by resource type.
+func resourceFromPath(path string) audit.Resource {
+	segs := strings.Split(strings.Trim(path, "/"), "/")
+	// segs: [v1, <subsystem>, <type>, <id?>, ...]
+	if len(segs) < 3 {
+		return audit.Resource{}
+	}
+	res := audit.Resource{Type: segs[2]}
+	if len(segs) >= 4 && looksLikeID(segs[3]) {
+		res.ID = scrubToken(segs[3])
+	}
+	return res
+}
+
+// scrubToken replaces a path segment that is a credential-shaped token with a
+// fixed marker, so a secret that ever appears in a URL is never recorded
+// verbatim. It catches, in increasing generality:
+//   - a known API-key prefix (hk-/sk-/pk-/fw_/hz_ — what isAPIKey recognizes),
+//     ALSO after percent-decoding, so hk%2DKEY can't slip the prefix check,
+//   - a JWT (three base64url parts split by '.', starting eyJ),
+//   - a long, high-entropy base64url/hex run (>=24) — a raw API key / access
+//     token / hex secret that carries no telltale prefix.
+//
+// A normal identifier passes through unchanged: a UUID (5 hyphen-split groups,
+// each short), a slug, a numeric id, a dotted model name — none is a long
+// unbroken high-entropy blob. See TestScrubToken_NoFalsePositives.
+//
+// RED-review hardening (finding: scrub bypass): the entropy test now (a) accepts
+// the FULL base64url alphabet incl. '-' and '_' (RFC 4648 §5), (b) does NOT
+// require a digit (an all-alpha opaque key is still a secret), (c) percent-
+// decodes first so %2D/%5F can't hide structure, and (d) drops the threshold to
+// 24 (short enough for a 128-bit base64 or a 24-hex key, long enough that no
+// human-readable slug reaches it).
+func scrubToken(seg string) string {
+	dec := percentDecode(seg)
+	if isAPIKey(seg) || isAPIKey(dec) ||
+		looksLikeJWT(seg) || looksLikeJWT(dec) ||
+		looksLikeHighEntropyToken(seg) || looksLikeHighEntropyToken(dec) {
+		return "[REDACTED-TOKEN]"
+	}
+	return seg
+}
+
+// percentDecode best-effort URL-decodes s so a percent-encoded credential
+// (hk%2DKEY, sk%5Flive%5F…) is normalized before the credential tests run. On a
+// malformed escape it returns s unchanged (the raw form is then tested as-is).
+func percentDecode(s string) string {
+	// Decode repeatedly (bounded) so a NESTED encoding (%252D -> %2D -> -) is
+	// fully normalized before the credential tests run. Stop when a pass makes no
+	// change, on a malformed escape, or after a small cap (defeats a decode bomb).
+	for i := 0; i < 3 && strings.Contains(s, "%"); i++ {
+		dec, err := url.PathUnescape(s)
+		if err != nil || dec == s {
+			break
+		}
+		s = dec
+	}
+	return s
+}
+
+// looksLikeJWT reports whether s is a JSON Web Token OR a JWT header segment. A
+// full JWT is three base64url parts split by '.', header starting "eyJ". But when
+// free text (a UA) is tokenized on '.', a dotted JWT splits into parts; a real
+// header part is >=24 chars (caught by the high-entropy run), yet to be safe we
+// ALSO flag any lone segment starting with the canonical base64url header prefix
+// "eyJ" (which decodes to '{"') regardless of length — a JWT header can never be
+// a legitimate resource id, so redacting it has no false-positive cost.
+func looksLikeJWT(s string) bool {
+	if !strings.HasPrefix(s, "eyJ") {
+		return false
+	}
+	// A full token (two dots) or a bare header segment — either way, redact.
+	return true
+}
+
+// highEntropyMinLen is the length at/above which an UNBROKEN run of base64/hex
+// chars is treated as an opaque secret. 24 covers a 128-bit base64 token, a
+// 24-nibble hex key, and short API keys, while every human-readable path
+// segment/slug/model-name stays under it once split on its separators — no
+// single run of a name like "text-embedding-3-large" reaches 24.
+const highEntropyMinLen = 24
+
+// looksLikeHighEntropyToken reports whether s CONTAINS an unbroken run of
+// >= highEntropyMinLen base64/hex chars — the shape of a raw API key / access
+// token / hex secret — UNLESS s is a structured human identifier.
+//
+// The run alphabet is [A-Za-z0-9_+/-] — the base64 alphabets (url-safe §5 '-”_'
+// and standard §4 '+”/') and hex. '-' is INCLUDED so a url-safe-base64 token
+// that embeds '-' is still caught by its run (excluding '-' left an ~11% bypass
+// for 32-byte url-safe tokens whose '-' happened to break every 24-run — measured).
+//
+// TWO-STAGE DETECTION:
+//
+//  1. UNCONDITIONAL run scan — a >= highEntropyMinLen UNBROKEN run over
+//     [A-Za-z0-9_+/-] flags the value REGARDLESS of the structured-id exemption.
+//     This catches every raw secret WITHOUT internal separators (hex, base64) —
+//     the realistic "a client bug put a raw key in the URL" case — at 100%. A
+//     structured identifier never has a 24-char unbroken run, so this stage never
+//     over-scrubs one.
+//
+//  2. STRUCTURED-ID EXEMPTION for the rest (values with separators that DON'T have
+//     a 24-run): exempt a clearly hyphen-joined human id, judged by LEXICAL
+//     content — every group WORD-LIKE (single-case word or decimal number), which
+//     a mixed-case base64 chunk or a long hex-with-letters chunk is NOT (those are
+//     redacted). Shape alone is attacker-satisfiable (RED found a 3x12-chunked
+//     secret slipped a shape-only check); the lexical test rejects the common
+//     secret encodings.
+//
+// ACCEPTED RESIDUAL BOUND (documented, per RED review): the ONLY residual is a
+// secret deliberately chunked into >=3 SINGLE-CASE-ALPHABETIC groups of <=12 chars
+// with no hex-letter runs >= hexChunkMinLen (a lowercase- or uppercase-only base32
+// alphabet, e.g. abcdefghijkl-mnopqrstuvwx-…). Such a value is lexically
+// indistinguishable from a hyphenated model id (deepseek-r1-distill-qwen-32b
+// carries the SAME 24-char entropy budget), so it passes stage 2. This is NOT
+// closable by any length/case/count rule without a word dictionary
+// (over-engineering for a defense-in-depth URL/UA backstop). Mixed-case base64
+// chunks AND small-hex chunks (md5/sha display grouping) ARE now caught
+// (isWordLikeGroup). The residual does not widen exposure for any REAL credential:
+// Hanzo keys are hk-/sk-/pk-/fw_/hz_-prefixed (isAPIKey, caught at any
+// length/shape), JWTs are eyJ-prefixed (looksLikeJWT), and request/response BODIES
+// are never read. It is an adversary DELIBERATELY base32-chunking their OWN secret
+// into a URL path to seed an admin-only audit row — contrived, low-value. The
+// realistic accidental leak (an unbroken raw key) is caught by stage 1.
+//
+// A canonical UUID is exempt (its longest run is 12; the check documents intent).
+func looksLikeHighEntropyToken(s string) bool {
+	if len(s) < highEntropyMinLen {
+		return false
+	}
+	// Stage 1 — unconditional: a long unbroken run is always a secret.
+	if hasHighEntropyRun(s) {
+		return true
+	}
+	// Stage 2 — separated values: redact unless it's a lexical structured id.
+	if isUUID(s) || isStructuredID(s) {
+		return false
+	}
+	// A >=24-length value with separators, not a UUID, not a structured id — e.g.
+	// "sk.live.LONGSECRET…" dotted, or a chunk pattern that is not word-like.
+	return true
+}
+
+// hasHighEntropyRun reports whether s contains an unbroken run of
+// >= highEntropyMinLen high-entropy chars where the run alphabet EXCLUDES '-'
+// (and '.'): a real separator breaks the run. This is stage 1 — it fires only on
+// a genuinely UNBROKEN opaque blob (a raw hex/base64 key with no separators), so
+// it never catches a hyphenated identifier (which stage 2 then classifies). A
+// url-safe-base64 secret that embeds '-' still trips because the run on ONE side
+// of the hyphen is >= 24 (verified: "AbCdEf-GhIjKl_MnOpQrStUvWxYz012345" -> 27).
+func hasHighEntropyRun(s string) bool {
+	run := 0
+	for _, r := range s {
+		if isUnbrokenTokenChar(r) {
+			run++
+			if run >= highEntropyMinLen {
+				return true
+			}
+		} else {
+			run = 0
+		}
+	}
+	return false
+}
+
+// isUnbrokenTokenChar is the stage-1 run alphabet: base64/hex MINUS '-' (and the
+// implicit exclusion of '.', space, etc.). '_' '+' '/' are kept — they appear
+// inside opaque tokens and are not identifier separators.
+func isUnbrokenTokenChar(r rune) bool {
+	return (r >= 'A' && r <= 'Z') || (r >= 'a' && r <= 'z') ||
+		(r >= '0' && r <= '9') || r == '_' || r == '+' || r == '/'
+}
+
+// idPartMaxLen bounds a hyphen-group length in the structured-id exemption. 12
+// covers the longest word in real model ids ("embedding", "20241022", "preview")
+// while a raw secret's random hyphen groups routinely exceed it.
+const idPartMaxLen = 12
+
+// isStructuredID reports whether s is a hyphen-joined human identifier (a model
+// name, slug): >= 3 hyphen groups where EVERY group is non-empty, <= idPartMaxLen
+// chars, and WORD-LIKE. The word-like test is the anti-bypass core — a raw secret
+// chunk cannot satisfy it — so the exemption is not attacker-satisfiable by shape.
+func isStructuredID(s string) bool {
+	groups := strings.Split(s, "-")
+	if len(groups) < 3 {
+		return false
+	}
+	for _, g := range groups {
+		if g == "" || len(g) > idPartMaxLen || !isWordLikeGroup(g) {
+			return false
+		}
+	}
+	return true
+}
+
+// isWordLikeGroup reports whether a hyphen group looks like a model-id token (a
+// dictionary word or a decimal number) rather than a random secret chunk. Two
+// lexical signals reject a secret chunk:
+//   - MIXED CASE (both upper and lower letters) — base64 tokens are dense
+//     mixed-case; real model tokens are single-case ("sonnet", "Instruct", "3").
+//   - an all-hex-with-letters run (>= hexChunkMinLen chars, all [0-9a-fA-F], and
+//     not all-digits) — a hex secret chunk ("dead", "beef", "cafebabe"); a version
+//     date ("20241022", all digits) is NOT hex-with-letters, so it stays
+//     word-like. The threshold is 4: RED re-review verified that NO real model-id
+//     group is all-hex-with-letters of length >= 4, so 4 (vs the prior 8) closes
+//     the small-hex-chunk leak (md5/sha shown in "xxxx-xxxx" display grouping)
+//     with zero model-id over-scrub.
+func isWordLikeGroup(g string) bool {
+	var hasUpper, hasLower, allHex, allDigit bool = false, false, true, true
+	for _, r := range g {
+		switch {
+		case r >= 'A' && r <= 'Z':
+			hasUpper = true
+		case r >= 'a' && r <= 'z':
+			hasLower = true
+		}
+		if r < '0' || r > '9' {
+			allDigit = false
+		}
+		isHex := (r >= '0' && r <= '9') || (r >= 'a' && r <= 'f') || (r >= 'A' && r <= 'F')
+		if !isHex {
+			allHex = false
+		}
+	}
+	if hasUpper && hasLower {
+		return false // dense mixed-case → base64 secret chunk, not a word.
+	}
+	if allHex && !allDigit && len(g) >= hexChunkMinLen {
+		return false // hex-with-letters → hex secret chunk (not a version date).
+	}
+	return true
+}
+
+// hexChunkMinLen is the length at/above which an all-hex-with-letters group is
+// treated as a secret chunk rather than a word. 4 is the tightest bound that does
+// not over-scrub any real model-id group (RED-verified across 19 model ids) while
+// catching hex secrets displayed in short groups (md5 "xxxx-xxxx", uuid-ish).
+const hexChunkMinLen = 4
+
+// isUUID reports whether s is a canonical 8-4-4-4-12 hex UUID (case-insensitive).
+// Used to exempt uuids from the high-entropy secret test — a uuid is a legitimate
+// resource id, not a credential.
+func isUUID(s string) bool {
+	if len(s) != 36 {
+		return false
+	}
+	for i, r := range s {
+		switch i {
+		case 8, 13, 18, 23:
+			if r != '-' {
+				return false
+			}
+		default:
+			if !((r >= '0' && r <= '9') || (r >= 'a' && r <= 'f') || (r >= 'A' && r <= 'F')) {
+				return false
+			}
+		}
+	}
+	return true
+}
+
+// maxUserAgentLen caps the recorded User-Agent so an oversized UA can neither
+// bloat the trail nor smuggle a long payload. 512 chars covers every real UA.
+const maxUserAgentLen = 512
+
+// scrubFreeText scrubs credential-shaped words out of client-controlled free
+// text (the User-Agent) and caps its length. It tokenizes on a broad delimiter
+// superset — whitespace and the punctuation that commonly glues a token into a
+// UA/header value (= ; , : / ( ) [ ] { } " ' < > | and backslash) — scrubs each
+// token, and rebuilds the string preserving the exact delimiters between tokens.
+//
+// RED-review hardening (finding: UA tokenizer split on too few delimiters, and
+// strings.ReplaceAll was substring-fragile): this walks the string in one pass
+// (token-run, delimiter-run, …) and replaces each credential token IN PLACE, so a
+// secret delimited by ':' '/' '(' etc. is caught and a token that is a substring
+// of another is never mis-replaced. A normal UA ("Mozilla/5.0 (Macintosh …)") is
+// unchanged because none of its words is credential-shaped.
+func scrubFreeText(s string) string {
+	if s == "" {
+		return ""
+	}
+	if len(s) > maxUserAgentLen {
+		s = s[:maxUserAgentLen]
+	}
+	var b strings.Builder
+	b.Grow(len(s))
+	start := -1 // start index of the current token run, or -1 in a delimiter run.
+	flush := func(end int) {
+		if start >= 0 {
+			b.WriteString(scrubToken(s[start:end]))
+			start = -1
+		}
+	}
+	for i, r := range s {
+		if isFreeTextDelimiter(r) {
+			flush(i)
+			b.WriteRune(r)
+		} else if start < 0 {
+			start = i
+		}
+	}
+	flush(len(s))
+	return b.String()
+}
+
+// isFreeTextDelimiter reports whether r separates tokens in free text (a UA /
+// header value). Deliberately broad so a credential can't hide behind an unusual
+// separator.
+//
+// RED re-review (UA bypass persists): '.' '@' '#' '~' are INCLUDED — a prefixed
+// key glued by one of them (client@sk-live-KEY, app.sk-live-KEY, build#hk-KEY)
+// otherwise stayed one token whose PREFIX was no longer sk-/hk-, so isAPIKey
+// missed it. Splitting on them exposes the bare key to scrubToken. Real UA dots
+// are numeric version separators (<24, safe) and are split harmlessly. A JWT
+// (eyJ.h.p.s) is handled up-front by scrubToken via looksLikeJWT before any
+// tokenizer runs on a URL path segment; in free text a dotted JWT will split,
+// but each ~40-char base64 part is itself a >=24 high-entropy run, so every part
+// is still redacted.
+func isFreeTextDelimiter(r rune) bool {
+	switch r {
+	case ' ', '\t', '\n', '\r', '=', ';', ',', ':', '/', '\\',
+		'(', ')', '[', ']', '{', '}', '"', '\'', '<', '>', '|', '&', '?',
+		'.', '@', '#', '~':
+		return true
+	}
+	return false
+}
+
+// scrubCredentialSegments applies scrubToken to every segment of a path, so the
+// recorded Path can never carry a credential even if a future route embeds one.
+// Route nouns/ids pass through unchanged (they are not isAPIKey-shaped).
+func scrubCredentialSegments(path string) string {
+	if !strings.ContainsAny(path, "/") {
+		return scrubToken(path)
+	}
+	segs := strings.Split(path, "/")
+	changed := false
+	for i, s := range segs {
+		if scrubbed := scrubToken(s); scrubbed != s {
+			segs[i] = scrubbed
+			changed = true
+		}
+	}
+	if !changed {
+		return path
+	}
+	return strings.Join(segs, "/")
+}
+
+// looksLikeID heuristically flags a path segment as a high-cardinality id (a
+// uuid, a long hex/opaque token, or a numeric id) vs a fixed route noun. Used to
+// collapse route families; false positives only make the action slightly more
+// specific, never leak anything.
+func looksLikeID(s string) bool {
+	if s == "" {
+		return false
+	}
+	if len(s) >= 16 { // long opaque/uuid-ish segment
+		return true
+	}
+	allDigits := true
+	for _, r := range s {
+		if r < '0' || r > '9' {
+			allDigits = false
+			break
+		}
+	}
+	return allDigits && len(s) > 0
+}

audit_middleware_test.go

@@ -0,0 +1,579 @@
+package cloud
+
+// Integration tests for the audit middleware. They drive REAL requests through
+// the zip/fiber stack (app.Fiber().Test) with the audit middleware in front of a
+// handler, backed by a REAL on-disk audit store, then read the store back to
+// assert what was (and was not) recorded. No mocks — the whole capture path runs.
+//
+// The middleware trusts SanitizeIdentity to have already validated identity, so
+// these tests set the sanitized X-User-* headers directly (as SanitizeIdentity
+// would after verifying a JWT) — that is the contract boundary under test here.
+// The forgery/bypass properties of SanitizeIdentity itself are proven in
+// middleware_identity_test.go; here we prove the middleware records the VALIDATED
+// identity and the correct outcome for every security-relevant request.
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/hanzoai/cloud/audit"
+	"github.com/zap-proto/zip"
+)
+
+// newAuditApp wires a zip app with the audit middleware in front of a small set
+// of routes covering the coverage matrix: a mutating POST, a safe GET, an
+// admin-gated route that 403s, and a route that echoes a (secret-bearing) body
+// so we can prove the body never reaches a record.
+func newAuditApp(t *testing.T) (*zip.App, *audit.Recorder) {
+	t.Helper()
+	path := filepath.Join(t.TempDir(), "audit.db")
+	rec, err := audit.Open(path, nil)
+	if err != nil {
+		t.Fatalf("audit.Open: %v", err)
+	}
+	t.Cleanup(func() { _ = rec.Close() })
+
+	app := zip.New(zip.Config{})
+	app.Use(AuditTrail(rec))
+
+	// Mutating route — must be audited.
+	app.Post("/v1/kms/secrets", func(c *zip.Ctx) error {
+		return c.JSON(http.StatusCreated, map[string]string{"id": "sec_1"})
+	})
+	// Safe read — must NOT be audited (not a mutation, not admin, not a denial).
+	app.Get("/v1/pricing/models", func(c *zip.Ctx) error {
+		return c.JSON(http.StatusOK, map[string]string{"ok": "true"})
+	})
+	// Admin route that denies (as the real admin guard would) — the 403 is a
+	// security event and MUST be audited even though it is a GET.
+	app.Get("/v1/admin/orgs", func(c *zip.Ctx) error {
+		if !c.IsAdmin() {
+			return zip.ErrForbidden("SuperAdmin required")
+		}
+		return c.JSON(http.StatusOK, map[string]string{"ok": "true"})
+	})
+	// A mutation whose request body carries secrets — used to prove the body is
+	// never captured. The handler ignores the body; the point is what the
+	// middleware records (metadata only).
+	app.Post("/v1/iam/users", func(c *zip.Ctx) error {
+		return c.JSON(http.StatusOK, map[string]string{"ok": "true"})
+	})
+	return app, rec
+}
+
+// asAdmin sets the sanitized identity headers a VALIDATED SuperAdmin would
+// carry after SanitizeIdentity (X-User-IsAdmin=true, org=admin).
+func asAdmin(req *http.Request) {
+	req.Header.Set("X-User-Id", "z@hanzo.ai")
+	req.Header.Set("X-User-Email", "z@hanzo.ai")
+	req.Header.Set("X-Org-Id", "admin")
+	req.Header.Set("X-User-IsAdmin", "true")
+	req.Header.Set("Authorization", "Bearer eyJ.validated.jwt") // shape only; classifies as jwt
+}
+
+// asUser sets sanitized headers for a normal (non-admin) validated principal.
+func asUser(req *http.Request) {
+	req.Header.Set("X-User-Id", "alice")
+	req.Header.Set("X-Org-Id", "acme")
+	req.Header.Set("Authorization", "Bearer eyJ.validated.jwt")
+}
+
+func mustTest(t *testing.T, app *zip.App, req *http.Request) *http.Response {
+	t.Helper()
+	resp, err := app.Fiber().Test(req)
+	if err != nil {
+		t.Fatalf("Test %s %s: %v", req.Method, req.URL.Path, err)
+	}
+	return resp
+}
+
+// TestAudit_RecordsMutation proves a mutating request is captured with the
+// correct validated actor, action, resource, outcome, and auth context — and the
+// record is hash-chained (has a hash) and verifies.
+func TestAudit_RecordsMutation(t *testing.T) {
+	app, rec := newAuditApp(t)
+
+	req := httptest.NewRequest(http.MethodPost, "/v1/kms/secrets", nil)
+	asUser(req)
+	req.Header.Set("X-Forwarded-For", "203.0.113.9, 10.0.0.1")
+	req.Header.Set("User-Agent", "test-agent/1.0")
+	resp := mustTest(t, app, req)
+	if resp.StatusCode != http.StatusCreated {
+		t.Fatalf("status = %d, want 201", resp.StatusCode)
+	}
+
+	rows, total, err := rec.Query(t.Context(), audit.Filter{})
+	if err != nil {
+		t.Fatalf("Query: %v", err)
+	}
+	if total != 1 || len(rows) != 1 {
+		t.Fatalf("recorded %d events, want exactly 1", total)
+	}
+	r := rows[0]
+	if r.Actor.Org != "acme" || r.Actor.Sub != "alice" {
+		t.Errorf("actor = %+v, want org=acme sub=alice (the VALIDATED identity)", r.Actor)
+	}
+	if r.Method != "POST" || r.Path != "/v1/kms/secrets" {
+		t.Errorf("method/path = %s %s, want POST /v1/kms/secrets", r.Method, r.Path)
+	}
+	if r.Resource.Type != "secrets" {
+		t.Errorf("resource type = %q, want secrets", r.Resource.Type)
+	}
+	if r.Outcome.Result != "success" || r.Outcome.Status != 201 {
+		t.Errorf("outcome = %+v, want success/201", r.Outcome)
+	}
+	if r.Auth.Method != "jwt" {
+		t.Errorf("auth method = %q, want jwt", r.Auth.Method)
+	}
+	if r.SourceIP != "203.0.113.9" {
+		t.Errorf("source ip = %q, want the left-most XFF entry", r.SourceIP)
+	}
+	if r.UserAgent != "test-agent/1.0" {
+		t.Errorf("user agent = %q, want test-agent/1.0", r.UserAgent)
+	}
+	if r.Hash == "" {
+		t.Error("record has no hash — not chained")
+	}
+	if iv, _ := rec.Verify(t.Context()); !iv.OK {
+		t.Errorf("chain broke after one record at %d (%s)", iv.BrokenAt, iv.Reason)
+	}
+}
+
+// TestAudit_RecordsDenial proves a 403 (access-control denial) is audited even on
+// a GET, with outcome result="deny", and records the actor who was denied.
+func TestAudit_RecordsDenial(t *testing.T) {
+	app, rec := newAuditApp(t)
+
+	// A NON-admin hits the admin route → 403.
+	req := httptest.NewRequest(http.MethodGet, "/v1/admin/orgs", nil)
+	asUser(req) // not admin
+	resp := mustTest(t, app, req)
+	if resp.StatusCode != http.StatusForbidden {
+		t.Fatalf("status = %d, want 403", resp.StatusCode)
+	}
+
+	rows, total, err := rec.Query(t.Context(), audit.Filter{Result: "deny"})
+	if err != nil {
+		t.Fatalf("Query: %v", err)
+	}
+	if total != 1 {
+		t.Fatalf("recorded %d denials, want 1", total)
+	}
+	r := rows[0]
+	if r.Outcome.Result != "deny" || r.Outcome.Status != 403 {
+		t.Errorf("outcome = %+v, want deny/403", r.Outcome)
+	}
+	if r.Actor.Sub != "alice" {
+		t.Errorf("denied actor sub = %q, want alice", r.Actor.Sub)
+	}
+	if r.Auth.IsAdmin {
+		t.Error("denied non-admin recorded as admin")
+	}
+}
+
+// TestAudit_SkipsSafeReads proves an ordinary successful GET on a non-admin route
+// is NOT audited — the trail captures security events, not read-log noise.
+func TestAudit_SkipsSafeReads(t *testing.T) {
+	app, rec := newAuditApp(t)
+
+	req := httptest.NewRequest(http.MethodGet, "/v1/pricing/models", nil)
+	asUser(req)
+	resp := mustTest(t, app, req)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("status = %d, want 200", resp.StatusCode)
+	}
+	_, total, err := rec.Query(t.Context(), audit.Filter{})
+	if err != nil {
+		t.Fatalf("Query: %v", err)
+	}
+	if total != 0 {
+		t.Fatalf("a safe GET was audited (%d rows) — trail should skip non-security reads", total)
+	}
+}
+
+// TestAudit_AdminReadIsAudited proves a SUCCESSFUL admin read is audited (admin
+// access itself is an AC-relevant event), distinguishing it from a normal read.
+func TestAudit_AdminReadIsAudited(t *testing.T) {
+	app, rec := newAuditApp(t)
+
+	req := httptest.NewRequest(http.MethodGet, "/v1/admin/orgs", nil)
+	asAdmin(req)
+	resp := mustTest(t, app, req)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("status = %d, want 200", resp.StatusCode)
+	}
+	rows, total, err := rec.Query(t.Context(), audit.Filter{})
+	if err != nil {
+		t.Fatalf("Query: %v", err)
+	}
+	if total != 1 {
+		t.Fatalf("admin read recorded %d, want 1", total)
+	}
+	if !rows[0].Auth.IsAdmin || rows[0].Outcome.Result != "success" {
+		t.Errorf("admin read record = auth.isAdmin=%v outcome=%+v, want admin+success", rows[0].Auth.IsAdmin, rows[0].Outcome)
+	}
+}
+
+// TestAudit_NeverCapturesRequestBody is the secret-safety proof: a mutation whose
+// body is FULL of credentials is audited, but the stored record contains NONE of
+// the body — the middleware captures metadata only, so a secret in a body can
+// never leak into the trail. This is the "reuse RedactUserSecrets" guarantee at
+// its strongest: the code that could leak a secret never reads it.
+func TestAudit_NeverCapturesRequestBody(t *testing.T) {
+	app, rec := newAuditApp(t)
+
+	secretBody := `{"username":"bob","password":"hunter2","apiKey":"sk-live-DEADBEEF","token":"ghp_SECRET"}`
+	req := httptest.NewRequest(http.MethodPost, "/v1/iam/users", strings.NewReader(secretBody))
+	req.Header.Set("Content-Type", "application/json")
+	asAdmin(req)
+	// Also stuff a secret into a header value that is NOT an identity header — it
+	// must not be captured either (we only record User-Agent + XFF, never arbitrary
+	// headers, and never Authorization's value).
+	req.Header.Set("Authorization", "Bearer eyJsuper.secret.token.value")
+	resp := mustTest(t, app, req)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("status = %d, want 200", resp.StatusCode)
+	}
+
+	rows, total, err := rec.Query(t.Context(), audit.Filter{})
+	if err != nil {
+		t.Fatalf("Query: %v", err)
+	}
+	if total != 1 {
+		t.Fatalf("recorded %d, want 1", total)
+	}
+	// Serialize the WHOLE record and scan for any secret substring.
+	blob, _ := json.Marshal(rows[0])
+	for _, secret := range []string{"hunter2", "sk-live-DEADBEEF", "ghp_SECRET", "super.secret.token.value"} {
+		if strings.Contains(string(blob), secret) {
+			t.Fatalf("SECRET LEAKED into audit record: %q found in %s", secret, blob)
+		}
+	}
+	// But the metadata IS there: the auth method is classified without the token.
+	if rows[0].Auth.Method != "jwt" {
+		t.Errorf("auth method = %q, want jwt (classified from prefix, token not stored)", rows[0].Auth.Method)
+	}
+	if rows[0].Before != nil || rows[0].After != nil {
+		t.Errorf("middleware set before/after (%s / %s) — it must never read bodies", rows[0].Before, rows[0].After)
+	}
+}
+
+// TestAudit_ScrubsCredentialInPath proves a credential-shaped token that rides in
+// the URL PATH (e.g. a KMS route where a caller wrongly puts an sk-/hk- key in the
+// path) is never recorded verbatim in either Path or resource.ID — defense in
+// depth beyond "bodies are never read". A normal identifier is untouched.
+func TestAudit_ScrubsCredentialInPath(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "audit.db")
+	rec, err := audit.Open(path, nil)
+	if err != nil {
+		t.Fatalf("open: %v", err)
+	}
+	t.Cleanup(func() { _ = rec.Close() })
+	app := zip.New(zip.Config{})
+	app.Use(AuditTrail(rec))
+	app.Delete("/v1/kms/secrets/*", func(c *zip.Ctx) error {
+		return c.JSON(http.StatusOK, map[string]string{"ok": "true"})
+	})
+
+	// Three credential shapes smuggled into the path across three requests: a
+	// prefixed key, a raw high-entropy hex secret (NO telltale prefix), and a JWT.
+	paths := []struct{ path, secret string }{
+		{"/v1/kms/secrets/sk-live-SUPERSECRETKEY1234567890", "SUPERSECRETKEY"},
+		{"/v1/kms/secrets/deadbeefcafe0123456789abcdef0123456789abcdef0123", "deadbeefcafe0123"},
+		{"/v1/kms/secrets/eyJhbGciOiJIUzI1NiJ9.cGF5bG9hZA.c2ln", "eyJhbGciOiJIUzI1NiJ9"},
+	}
+	for _, tc := range paths {
+		req := httptest.NewRequest(http.MethodDelete, tc.path, nil)
+		asAdmin(req)
+		if resp := mustTest(t, app, req); resp.StatusCode != http.StatusOK {
+			t.Fatalf("%s: status = %d, want 200", tc.path, resp.StatusCode)
+		}
+	}
+
+	rows, total, err := rec.Query(t.Context(), audit.Filter{})
+	if err != nil {
+		t.Fatalf("Query: %v", err)
+	}
+	if total != len(paths) {
+		t.Fatalf("recorded %d, want %d", total, len(paths))
+	}
+	blob, _ := json.Marshal(rows)
+	for _, tc := range paths {
+		if strings.Contains(string(blob), tc.secret) {
+			t.Fatalf("credential in path leaked into record: %q present in %s", tc.secret, blob)
+		}
+	}
+	for _, r := range rows {
+		if !strings.Contains(r.Path, "[REDACTED-TOKEN]") {
+			t.Errorf("path token not scrubbed: %q", r.Path)
+		}
+	}
+}
+
+// TestAudit_ScrubsSecretInUserAgent proves a bearer/API-key embedded in the
+// client-controlled User-Agent is scrubbed, and a normal UA is untouched.
+func TestAudit_ScrubsSecretInUserAgent(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "audit.db")
+	rec, err := audit.Open(path, nil)
+	if err != nil {
+		t.Fatalf("open: %v", err)
+	}
+	t.Cleanup(func() { _ = rec.Close() })
+	app := zip.New(zip.Config{})
+	app.Use(AuditTrail(rec))
+	app.Post("/v1/kms/secrets", func(c *zip.Ctx) error { return c.JSON(http.StatusOK, map[string]string{"ok": "1"}) })
+
+	req := httptest.NewRequest(http.MethodPost, "/v1/kms/secrets", nil)
+	asAdmin(req)
+	req.Header.Set("User-Agent", "myclient/1.0 Bearer eyJhbGciOiJI.pay.sig key=sk-live-LEAKME99999")
+	mustTest(t, app, req)
+
+	rows, _, _ := rec.Query(t.Context(), audit.Filter{})
+	if len(rows) != 1 {
+		t.Fatalf("got %d rows, want 1", len(rows))
+	}
+	for _, secret := range []string{"eyJhbGciOiJI", "sk-live-LEAKME99999"} {
+		if strings.Contains(rows[0].UserAgent, secret) {
+			t.Errorf("UA secret leaked: %q in %q", secret, rows[0].UserAgent)
+		}
+	}
+	// The non-secret UA prefix survives (audit usefulness preserved).
+	if !strings.Contains(rows[0].UserAgent, "myclient/1.0") {
+		t.Errorf("UA over-scrubbed, lost the client name: %q", rows[0].UserAgent)
+	}
+}
+
+// TestScrubToken_NoFalsePositives proves legitimate identifiers are NEVER
+// scrubbed — the guard fires only on genuinely secret-shaped segments, so the
+// audit trail keeps its query precision for normal resource ids.
+func TestScrubToken_NoFalsePositives(t *testing.T) {
+	for _, id := range []string{
+		"acme-corp", "gpt-4o-mini", "my_project_123", "user@example.com",
+		"550e8400-e29b-41d4-a716-446655440000", // uuid (hyphens)
+		"claude-opus-4-20250514", "text-embedding-3-large",
+		"my-cool-project-name", "feature-branch-xyz",
+		"deployment-2024-01-15", "report.pdf", "data.json",
+		// Red re-review round 2 — hyphenated model ids MUST pass (AU-3: an auditor
+		// must still see WHICH model a config change touched).
+		"claude-3-5-sonnet-20241022", "claude-3-5-haiku-20241022",
+		"claude-sonnet-4-20250514", "claude-3-7-sonnet-20250219",
+		"claude-3-5-sonnet-latest", "deepseek-r1-distill-qwen-32b",
+		"claude-3-opus-20240229", "stable-diffusion-xl-base",
+		"mixtral-8x7b-instruct", "llama-3-1-8b-instruct", "whisper-large-v3-turbo",
+		"v1", "models", "sync", "12345", "a", "",
+	} {
+		if got := scrubToken(id); got != id {
+			t.Errorf("false scrub: legit id %q → %q", id, got)
+		}
+	}
+	// And genuine secrets ARE scrubbed.
+	for _, sec := range []string{
+		"sk-live-abcdef", "hk-1234567890abcdef", "eyJhbG.payload.signature",
+		"deadbeefcafe0123456789abcdef0123456789abcdef0123", // 48-char raw hex
+	} {
+		if scrubToken(sec) == sec {
+			t.Errorf("missed secret: %q not scrubbed", sec)
+		}
+	}
+}
+
+// TestScrubToken_RedReviewBypassClasses is the regression for the 4 scrub-bypass
+// classes Red found: base64url with -/_, all-alpha opaque >=len, percent-encoded
+// prefixes, and delimiter-glued UA tokens. Each MUST now be redacted.
+func TestScrubToken_RedReviewBypassClasses(t *testing.T) {
+	for _, sec := range []string{
+		"AbCdEf-GhIjKl_MnOpQrStUvWxYz012345",       // base64url with - and _
+		"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMN", // all-alpha opaque, no digit
+		"hk%2DROTATEKEY0001SECRETKEY",              // percent-encoded hk-
+		"sk%5Flive%5FBYPASS0001SECRETKEY",          // percent-encoded sk_
+		// Red re-review round 2 — dotted-exemption + encoding + standard-base64:
+		"deadbeefcafe0123456789abcdef0123456789abcdef.x", // ".x" tail forces dotted exemption
+		"AbCdEfGhIjKlMnOpQrStUvWxYz012345.json",          // secret with a filename-ish suffix
+		"hk%252DROTATEKEY0001SECRETKEY",                  // double percent-encoded hk-
+		"AbCdEfGhIjKlMnOpQrStUvWx0123456789",             // 34-char opaque run (standard/url b64)
+		// Red re-review round 3 — interior-hyphen raw secret (NOT a structured id:
+		// only 1 hyphen, long parts) must still redact despite '-' in the run.
+		"aaaaaaaaaaaaaaaaaaaaaaaa-bbbbbbbbbbbbbbbbbbbbbbbb",
+		// Red final re-review — a secret CHUNKED to satisfy the structured-id shape
+		// (>=3 groups <=12 chars) must STILL redact: the lexical (word-like) test
+		// rejects mixed-case base64 chunks and hex chunks (>= hexChunkMinLen=4).
+		"AbCdEfGhIjKl-MnOpQrStUvWx-YzAbCdEfGhIj", // mixed-case base64 chunks
+		"A1b2C3d4-E5f6G7h8-I9j0K1l2",             // 128-bit mixed-case chunks
+		"deadbeef-cafebabe-01234567-89abcdef",    // all-hex chunks (8-char groups)
+		"abcdef01-23456789-abcdef01",             // hex chunks
+		// Red final polish — SMALL hex chunks (md5/sha "xxxx-xxxx" display) now
+		// caught by the len>=4 hex rule.
+		"abcd-ef01-2345-6789-abcd-ef01", // 4-char hex groups
+		"dead-beef-cafe-babe-0123-4567", // 4-char hex groups
+	} {
+		if got := scrubToken(sec); got != "[REDACTED-TOKEN]" {
+			t.Errorf("Red bypass STILL OPEN: %q → %q (want redacted)", sec, got)
+		}
+	}
+	// UA with a secret glued by :/()[]= — must be scrubbed, client name kept.
+	ua := scrubFreeText("myapp/1.0 (token:sk-live-BYPASS0001) [key=hk-1234567890abcdef]")
+	for _, leak := range []string{"sk-live-BYPASS0001", "hk-1234567890abcdef"} {
+		if strings.Contains(ua, leak) {
+			t.Errorf("UA bypass: %q leaked in %q", leak, ua)
+		}
+	}
+	if !strings.Contains(ua, "myapp/1.0") {
+		t.Errorf("UA over-scrubbed, lost client name: %q", ua)
+	}
+	// Red re-review round 2 — a key glued by . @ # ~ must NOT survive.
+	for _, glued := range []string{
+		"client@sk-live-SECRETKEY00001", "app.sk-live-SECRETKEY00001",
+		"build#hk-SECRETKEY000000001", "v1~sk-live-SECRETKEY00001",
+	} {
+		if got := scrubFreeText(glued); strings.Contains(got, "SECRETKEY") {
+			t.Errorf("UA glue-char bypass: %q → %q (secret survives)", glued, got)
+		}
+	}
+	// Normal UAs must be byte-identical (no false scrub).
+	for _, ua := range []string{
+		"console", "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
+		"curl/8.1.2", "Go-http-client/2.0",
+	} {
+		if got := scrubFreeText(ua); got != ua {
+			t.Errorf("UA false positive: %q → %q", ua, got)
+		}
+	}
+}
+
+// TestAudit_HealthSuffixCannotEvadeAudit proves a mutating request whose path
+// ENDS in /health (an attacker-named wildcard segment) is STILL audited — the
+// liveness exemption is exact and never suppresses a mutation or a denial. This
+// closes an audit-evasion hole where POST /v1/admin/orgs/x/health would slip past.
+func TestAudit_HealthSuffixCannotEvadeAudit(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "audit.db")
+	rec, err := audit.Open(path, nil)
+	if err != nil {
+		t.Fatalf("open: %v", err)
+	}
+	t.Cleanup(func() { _ = rec.Close() })
+	app := zip.New(zip.Config{})
+	app.Use(AuditTrail(rec))
+	app.Post("/v1/admin/orgs/*", func(c *zip.Ctx) error { return c.JSON(http.StatusOK, map[string]string{"ok": "1"}) })
+	app.Get("/v1/kms/health", func(c *zip.Ctx) error { return c.JSON(http.StatusOK, map[string]string{"status": "ok"}) })
+
+	// (a) A mutating POST ending in /health MUST be audited.
+	req := httptest.NewRequest(http.MethodPost, "/v1/admin/orgs/evil/health", nil)
+	asAdmin(req)
+	mustTest(t, app, req)
+	_, total, _ := rec.Query(t.Context(), audit.Filter{})
+	if total != 1 {
+		t.Fatalf("EVASION: mutating POST ending /health audited %d times, want 1", total)
+	}
+
+	// (b) A genuine liveness GET /v1/kms/health MUST still be skipped.
+	req2 := httptest.NewRequest(http.MethodGet, "/v1/kms/health", nil)
+	mustTest(t, app, req2)
+	_, total2, _ := rec.Query(t.Context(), audit.Filter{})
+	if total2 != 1 {
+		t.Fatalf("liveness probe was audited (total went %d→%d) — should be exempt", total, total2)
+	}
+}
+
+// TestAudit_AnonRequestNotAttributedToForgedOrg proves an UNAUTHENTICATED
+// attacker cannot forge a false attribution: sending X-Org-Id/X-User-Id/
+// X-User-IsAdmin with no validated principal records an ANONYMOUS actor (empty
+// org+sub, not admin), never the claimed victim org. Runs the REAL SanitizeIdentity
+// (nil validator ⇒ strips authority, restores client X-Org-Id for the data path)
+// ahead of AuditTrail, exactly as serve.go wires them.
+func TestAudit_AnonRequestNotAttributedToForgedOrg(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "audit.db")
+	rec, err := audit.Open(path, nil)
+	if err != nil {
+		t.Fatalf("open: %v", err)
+	}
+	t.Cleanup(func() { _ = rec.Close() })
+	app := zip.New(zip.Config{})
+	app.Use(SanitizeIdentity(nil, "admin")) // trust boundary
+	app.Use(AuditTrail(rec))
+	app.Post("/v1/kms/secrets", func(c *zip.Ctx) error { return c.JSON(http.StatusOK, map[string]string{"ok": "1"}) })
+
+	req := httptest.NewRequest(http.MethodPost, "/v1/kms/secrets", nil)
+	// Anonymous attacker forging every identity header.
+	req.Header.Set("X-Org-Id", "victim-org")
+	req.Header.Set("X-User-Id", "victim-user")
+	req.Header.Set("X-User-IsAdmin", "true")
+	mustTest(t, app, req)
+
+	rows, _, _ := rec.Query(t.Context(), audit.Filter{})
+	if len(rows) != 1 {
+		t.Fatalf("got %d rows, want 1", len(rows))
+	}
+	r := rows[0]
+	if r.Auth.IsAdmin {
+		t.Error("forged X-User-IsAdmin survived into the record")
+	}
+	if r.Actor.Sub != "" {
+		t.Errorf("forged X-User-Id recorded as actor.Sub = %q", r.Actor.Sub)
+	}
+	if r.Actor.Org == "victim-org" {
+		t.Errorf("FALSE ATTRIBUTION: anonymous request stamped with claimed org %q", r.Actor.Org)
+	}
+	if r.Auth.Method != "none" {
+		t.Errorf("auth method = %q, want none (no valid credential)", r.Auth.Method)
+	}
+	// The event is still recorded (a mutation), honestly anonymous.
+	if r.Outcome.Result != "success" {
+		t.Errorf("outcome = %+v, want the anonymous mutation recorded", r.Outcome)
+	}
+}
+
+// TestAudit_NoopWhenUnconfigured proves a nil Recorder makes the middleware a
+// pass-through (an unconfigured deployment is never blocked), exactly like
+// BillingGate's nil-client behavior.
+func TestAudit_NoopWhenUnconfigured(t *testing.T) {
+	app := zip.New(zip.Config{})
+	app.Use(AuditTrail(nil))
+	var ran bool
+	app.Post("/v1/kms/secrets", func(c *zip.Ctx) error {
+		ran = true
+		return c.JSON(http.StatusOK, map[string]string{"ok": "true"})
+	})
+	req := httptest.NewRequest(http.MethodPost, "/v1/kms/secrets", nil)
+	resp := mustTest(t, app, req)
+	if resp.StatusCode != http.StatusOK || !ran {
+		t.Fatalf("nil-recorder gate must pass through: status=%d ran=%v", resp.StatusCode, ran)
+	}
+}
+
+// TestAudit_FailsClosedOnWriteError proves that when the audit store cannot
+// record a security-relevant event, the request is failed CLOSED (503) rather
+// than allowed to succeed unlogged (AU-5). We force the failure by closing the
+// store's DB before the request, so Append errors.
+func TestAudit_FailsClosedOnWriteError(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "audit.db")
+	rec, err := audit.Open(path, nil)
+	if err != nil {
+		t.Fatalf("open: %v", err)
+	}
+	// Close the underlying store so every subsequent Append fails.
+	_ = rec.Close()
+
+	app := zip.New(zip.Config{})
+	app.Use(AuditTrail(rec))
+	var ran bool
+	app.Post("/v1/kms/secrets", func(c *zip.Ctx) error {
+		ran = true
+		return c.JSON(http.StatusCreated, map[string]string{"id": "x"})
+	})
+
+	req := httptest.NewRequest(http.MethodPost, "/v1/kms/secrets", nil)
+	asAdmin(req)
+	resp := mustTest(t, app, req)
+	// The handler may have run (audit wraps AFTER the chain), but the response the
+	// CLIENT sees must be the fail-closed 503, not the handler's 201 — a
+	// security-relevant action that could not be recorded is not acknowledged as
+	// success.
+	if resp.StatusCode != http.StatusServiceUnavailable {
+		t.Fatalf("status = %d, want 503 (fail-closed when audit write fails)", resp.StatusCode)
+	}
+	_ = ran
+}

audit_mirror.go

@@ -0,0 +1,199 @@
+package cloud
+
+// The datastore OLAP mirror — a best-effort projection of the audit
+// trail for fleet-wide, long-retention, cross-deployment query. It implements
+// audit.Mirror.
+//
+// The datastore is the natural OLAP audit sink: the table is a MergeTree, which
+// is INSERT-ONLY by engine — datastore rejects UPDATE/DELETE against it at parse
+// time ("MergeTree does not support mutations"), so the mirror is append-only at
+// the storage layer, matching the local chain's discipline. We create the table
+// idempotently on first connect (CREATE TABLE IF NOT EXISTS) and insert via the
+// canonical datastore-go PrepareBatch → Append → Send idiom (the same the
+// provisioning subsystem uses; the driver is already in cloud's module graph, so
+// this adds no dependency).
+//
+// This mirror is NEVER the integrity authority — the local SQLite hash-chain is.
+// Its rows carry the same seq + hash so an operator CAN cross-check the OLAP copy
+// against the chain, but a mirror gap is a query-completeness issue, not a
+// tamper-evidence one. Every mirror error is logged and dropped by the Recorder;
+// the request path never sees it.
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"strings"
+	"time"
+
+	datastore "github.com/hanzo-ds/go"
+	"github.com/hanzoai/cloud/audit"
+	luxlog "github.com/luxfi/log"
+)
+
+// datastoreMirror writes audit records to a datastore MergeTree table.
+type datastoreMirror struct {
+	conn  datastore.Conn
+	table string
+	log   luxlog.Logger
+}
+
+// newAuditMirror builds the OLAP mirror from operator config, or returns nil when
+// no datastore is configured (mirroring is optional — the local chain is the
+// authority). It connects lazily-validated (a Ping) and ensures the table exists.
+//
+// Config (all from env / KMS-injected secrets, never hard-coded):
+//
+//	CLOUD_AUDIT_CLICKHOUSE_ADDR   host:9000 of the datastore native port
+//	CLOUD_AUDIT_CLICKHOUSE_DB     database (default "hanzo")
+//	CLOUD_AUDIT_CLICKHOUSE_TABLE  table (default "audit_log")
+//	CLOUD_AUDIT_CLICKHOUSE_USER   user
+//	CLOUD_AUDIT_CLICKHOUSE_PASSWORD  password (KMS-backed secret)
+func newAuditMirror(log luxlog.Logger) (audit.Mirror, error) {
+	addr := strings.TrimSpace(os.Getenv("CLOUD_AUDIT_CLICKHOUSE_ADDR"))
+	if addr == "" {
+		return nil, nil // no datastore configured — local chain only.
+	}
+	db := getenv("CLOUD_AUDIT_CLICKHOUSE_DB", "hanzo")
+	table := getenv("CLOUD_AUDIT_CLICKHOUSE_TABLE", "audit_log")
+
+	conn, err := datastore.Open(&datastore.Options{
+		Addr: []string{addr},
+		Auth: datastore.Auth{
+			Database: db,
+			Username: os.Getenv("CLOUD_AUDIT_CLICKHOUSE_USER"),
+			Password: os.Getenv("CLOUD_AUDIT_CLICKHOUSE_PASSWORD"),
+		},
+		DialTimeout: 5 * time.Second,
+	})
+	if err != nil {
+		return nil, fmt.Errorf("audit mirror: open: %w", err)
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+	if err := conn.Ping(ctx); err != nil {
+		_ = conn.Close()
+		return nil, fmt.Errorf("audit mirror: ping %s: %w", addr, err)
+	}
+
+	qualified := db + "." + table
+	m := &datastoreMirror{conn: conn, table: qualified, log: log}
+	if err := m.ensureTable(ctx); err != nil {
+		_ = conn.Close()
+		return nil, err
+	}
+	if log != nil {
+		log.Info("audit OLAP mirror connected", "addr", addr, "table", qualified)
+	}
+	return m, nil
+}
+
+// ensureTable creates the append-only audit table if it does not exist. MergeTree
+// = insert-only (mutations rejected at parse time). Partitioned by month and
+// ordered for the (org, time) query pattern; seq + hash are carried so the OLAP
+// copy is cross-checkable against the local chain.
+func (m *datastoreMirror) ensureTable(ctx context.Context) error {
+	ddl := fmt.Sprintf(`
+CREATE TABLE IF NOT EXISTS %s (
+  seq        UInt64,
+  ts         DateTime64(3, 'UTC'),
+  actor_org  LowCardinality(String),
+  actor_sub  String,
+  actor_email String,
+  action     LowCardinality(String),
+  res_type   LowCardinality(String),
+  res_id     String,
+  auth_method LowCardinality(String),
+  is_admin   UInt8,
+  result     LowCardinality(String),
+  status     UInt16,
+  reason     String,
+  source_ip  String,
+  user_agent String,
+  request_id String,
+  method     LowCardinality(String),
+  path       String,
+  prev_hash  String,
+  hash       String
+) ENGINE = MergeTree
+PARTITION BY toYYYYMM(ts)
+ORDER BY (actor_org, ts, seq)`, m.table)
+	if err := m.conn.Exec(ctx, ddl); err != nil {
+		return fmt.Errorf("audit mirror: ensure table: %w", err)
+	}
+	return nil
+}
+
+// Append writes one record to the OLAP mirror via the canonical batch idiom. The
+// before/after diffs are DELIBERATELY not mirrored — the OLAP copy is for
+// query/analytics over the event stream, and keeping the (already-redacted but
+// still payload-bearing) diffs out of the fleet warehouse minimizes the blast
+// radius of a warehouse compromise. The full record (with diffs) lives only in
+// the local, access-controlled chain.
+func (m *datastoreMirror) Append(ctx context.Context, r audit.Record) error {
+	batch, err := m.conn.PrepareBatch(ctx, "INSERT INTO "+m.table+` (
+  seq, ts, actor_org, actor_sub, actor_email, action, res_type, res_id,
+  auth_method, is_admin, result, status, reason, source_ip, user_agent,
+  request_id, method, path, prev_hash, hash)`)
+	if err != nil {
+		return fmt.Errorf("audit mirror: prepare: %w", err)
+	}
+	if err := batch.Append(
+		r.Seq, r.Time.UTC(), r.Actor.Org, r.Actor.Sub, r.Actor.Email,
+		r.Action, r.Resource.Type, r.Resource.ID,
+		r.Auth.Method, boolToUint8(r.Auth.IsAdmin),
+		r.Outcome.Result, uint16(r.Outcome.Status), r.Outcome.Reason,
+		r.SourceIP, r.UserAgent, r.RequestID, r.Method, r.Path,
+		r.PrevHash, r.Hash,
+	); err != nil {
+		_ = batch.Abort()
+		return fmt.Errorf("audit mirror: append: %w", err)
+	}
+	return batch.Send()
+}
+
+// Checkpoint persists a head-digest checkpoint to an INDEPENDENT digest table in
+// the datastore — the AU-9 tail-truncation anchor. Because this lives in a store
+// SEPARATE from the local SQLite chain, truncating the chain cannot also rewrite
+// the checkpoint history: an external monitor querying this table sees the count
+// series and alerts on any regression. Best-effort; a failure is dropped by the
+// Recorder (the structured log carries the same digest). Implements
+// audit.CheckpointSink.
+func (m *datastoreMirror) Checkpoint(ctx context.Context, cp audit.Checkpoint) error {
+	if err := m.ensureCheckpointTable(ctx); err != nil {
+		return err
+	}
+	batch, err := m.conn.PrepareBatch(ctx, "INSERT INTO "+m.table+"_checkpoints (ts, count, head)")
+	if err != nil {
+		return fmt.Errorf("audit mirror: checkpoint prepare: %w", err)
+	}
+	if err := batch.Append(cp.Time.UTC(), cp.Count, cp.Head); err != nil {
+		_ = batch.Abort()
+		return fmt.Errorf("audit mirror: checkpoint append: %w", err)
+	}
+	return batch.Send()
+}
+
+// ensureCheckpointTable creates the append-only checkpoint digest table. A plain
+// MergeTree ordered by time — the monitor reads the latest rows and checks that
+// count never decreases.
+func (m *datastoreMirror) ensureCheckpointTable(ctx context.Context) error {
+	ddl := fmt.Sprintf(`
+CREATE TABLE IF NOT EXISTS %s_checkpoints (
+  ts    DateTime64(3, 'UTC'),
+  count UInt64,
+  head  String
+) ENGINE = MergeTree
+ORDER BY ts`, m.table)
+	if err := m.conn.Exec(ctx, ddl); err != nil {
+		return fmt.Errorf("audit mirror: ensure checkpoint table: %w", err)
+	}
+	return nil
+}
+
+func boolToUint8(b bool) uint8 {
+	if b {
+		return 1
+	}
+	return 0
+}

audit_serve.go

@@ -0,0 +1,95 @@
+package cloud
+
+// Audit trail construction — the wiring Serve calls to stand up the Recorder.
+//
+// The audit store is a COMPLIANCE CONTROL, so its persistence is treated like the
+// pricing catalog overlay's: a non-persistent (in-memory) audit trail would
+// silently lose the record of every prior action on each restart — a fail-OPEN
+// degradation of an integrity control. So an empty DataDir is a hard boot error
+// in a normal run (prod always sets CLOUD_DATA_DIR; provisioning + pricing already
+// require it, so the unified binary always has one). The trail can be turned OFF
+// deliberately (CLOUD_AUDIT_DISABLED=true) for a minimal single-service dev run —
+// an explicit opt-out, never a silent one.
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"time"
+
+	"github.com/hanzoai/cloud/audit"
+	luxlog "github.com/luxfi/log"
+)
+
+// buildAuditRecorder constructs the audit Recorder from cfg: the append-only
+// SQLite chain at {DataDir}/audit.db plus a best-effort datastore OLAP mirror
+// when a datastore is configured. Returns (nil, nil) only when the trail is
+// explicitly disabled — the caller then wires a no-op middleware.
+func buildAuditRecorder(cfg *Config, logger luxlog.Logger) (*audit.Recorder, error) {
+	if getenvBool("CLOUD_AUDIT_DISABLED") {
+		if logger != nil {
+			logger.Warn("audit trail DISABLED by CLOUD_AUDIT_DISABLED — no tamper-evident record will be kept")
+		}
+		return nil, nil
+	}
+	if cfg.DataDir == "" {
+		return nil, fmt.Errorf("empty DataDir — the audit trail is a compliance control and requires a persistent data dir (set CLOUD_DATA_DIR); refusing to boot with a non-persistent trail that would lose all prior records on restart (or set CLOUD_AUDIT_DISABLED=true to opt out explicitly)")
+	}
+	if err := os.MkdirAll(cfg.DataDir, 0o755); err != nil {
+		return nil, fmt.Errorf("data dir: %w", err)
+	}
+
+	// OLAP mirror is optional and best-effort. A mirror that cannot be reached at
+	// boot must NOT stop the binary — the local chain is the authority — so a
+	// mirror construction error is logged and the trail runs local-only.
+	var mirror audit.Mirror
+	if m, err := newAuditMirror(logger); err != nil {
+		if logger != nil {
+			logger.Warn("audit OLAP mirror unavailable — running local-only (chain integrity unaffected)", "err", err)
+		}
+	} else {
+		mirror = m
+	}
+
+	dbPath := filepath.Join(cfg.DataDir, "audit.db")
+	rec, err := audit.Open(dbPath, mirror)
+	if err != nil {
+		return nil, fmt.Errorf("open audit store: %w", err)
+	}
+
+	// AU-9 tail-truncation anchor: emit a periodic head-digest checkpoint to the
+	// append-only observability log (and, when a mirror supports it, an
+	// independent digest store). An external o11y monitor compares consecutive
+	// checkpoints and alerts on a count regression — the only way to detect that
+	// the most-recent records were deleted (an internal chain walk cannot). The
+	// interval is CLOUD_AUDIT_CHECKPOINT_INTERVAL (default 5m; 0 disables).
+	interval := auditCheckpointInterval()
+	if logger != nil {
+		rec.StartCheckpoints(interval, func(cp audit.Checkpoint) {
+			logger.Info("audit_head_checkpoint",
+				"count", cp.Count, "head", cp.Head, "ts", cp.Time.Format(time.RFC3339Nano))
+		})
+	} else {
+		rec.StartCheckpoints(interval, nil)
+	}
+
+	if logger != nil {
+		count, head := rec.Head()
+		logger.Info("audit trail ready (tamper-evident, append-only)",
+			"store", dbPath, "records", count, "head", head,
+			"mirror", mirror != nil, "checkpoint_interval", interval.String())
+	}
+	return rec, nil
+}
+
+// auditCheckpointInterval resolves the head-digest checkpoint cadence.
+// CLOUD_AUDIT_CHECKPOINT_INTERVAL is a Go duration (e.g. "5m", "1h"); default 5m;
+// "0" disables periodic checkpoints (the on-close checkpoint still fires).
+func auditCheckpointInterval() time.Duration {
+	if v := getenv("CLOUD_AUDIT_CHECKPOINT_INTERVAL", ""); v != "" {
+		if d, err := time.ParseDuration(v); err == nil {
+			return d
+		}
+	}
+	return 5 * time.Minute
+}

auth_identity.go

@@ -0,0 +1,440 @@
+package cloud
+
+// In-binary IAM JWT validation — the trust anchor for SanitizeIdentity.
+//
+// This MIRRORS github.com/hanzoai/gateway/v2/iamauth, the canonical edge
+// validator, but cloud deliberately does NOT import that package: iamauth lives
+// in the heavyweight gateway module (KrakenD/gin/traefik) AND gateway/v2 already
+// imports github.com/hanzoai/cloud, so importing it back would braid a module
+// cycle and pull the gateway's whole dependency tree into cloud for ~150 lines
+// of validation. The gateway remains the PRIMARY edge authority — in production
+// it fronts cloud-api (universe routes.yaml). This validator is the in-binary
+// defense-in-depth layer for the in-cluster / direct path, kept tiny and
+// auditable on go-jose alone (already in cloud's module graph).
+//
+// What it enforces, exactly like iamauth.ValidateToken: signature against the
+// IAM JWKS, issuer (strict), audience (allowlist, OR semantics), and expiry —
+// always. A token missing the issuer is rejected.
+
+import (
+	"context"
+	"crypto/rsa"
+	"encoding/base64"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"strings"
+	"sync"
+	"time"
+
+	gojose "github.com/go-jose/go-jose/v4"
+	"github.com/go-jose/go-jose/v4/jwt"
+
+	"github.com/hanzoai/cloud/clients/principal"
+)
+
+// idClaims is the subset of Hanzo IAM JWT claims the identity sanitizer needs.
+// Shape mirrors iamauth.Claims so a token resolves identically at both layers.
+type idClaims struct {
+	jwt.Claims
+
+	Owner             string `json:"owner"`              // org slug (the org)
+	Project           string `json:"project"`            // org SUB-SCOPE within owner (empty ⟹ default project)
+	Name              string `json:"name"`               // display name (id fallback)
+	PreferredUsername string `json:"preferred_username"` // id fallback
+	Email             string `json:"email"`
+	IsAdmin           bool   `json:"isAdmin"`
+}
+
+// mintedProject returns the project id to stamp into X-Project-Id, or "" when the
+// header must be OMITTED. The project rides in the validated JWT `project` claim,
+// scoped to the caller's org exactly like `owner` — trusted, not forgeable. The
+// default project (absent claim, or the literal principal.DefaultProject) mints
+// nothing, so X-Project-Id is present iff a non-default project is in scope. This
+// mirrors the edge (iamauth.Claims.MintedProject) byte-for-byte, so the in-binary
+// path binds the same header the gateway would.
+func (c *idClaims) mintedProject() string {
+	if principal.IsDefaultProject(c.Project) {
+		return ""
+	}
+	return strings.TrimSpace(c.Project)
+}
+
+// userID resolves the canonical user id: sub, then preferred_username, then
+// name. IAM may leave sub empty. This is the STABLE identifier (a UUID when IAM
+// sets sub) stamped as X-User-Id and consumed as the attribution key everywhere.
+func (c *idClaims) userID() string {
+	if c.Subject != "" {
+		return c.Subject
+	}
+	if c.PreferredUsername != "" {
+		return c.PreferredUsername
+	}
+	return c.Name
+}
+
+// username resolves the IAM USERNAME — the `name` half of the `<owner>/<name>`
+// key IAM's privileged ops (mint-user-keys, get-user) parse. Prefers the `name`
+// claim (IAM's canonical username, e.g. "z"), then preferred_username. It NEVER
+// returns the subject: sub is a UUID, and `<owner>/<uuid>` fails IAM's
+// GetOwnerAndNameFromId user lookup ("password or code is incorrect"). This is
+// the distinct-from-userID() value stamped as X-User-Name so the direct-Bearer
+// path builds owner/name correctly — the gateway historically minted
+// X-User-Id==name, which userID() (sub-first) breaks on the in-binary path.
+func (c *idClaims) username() string {
+	if c.Name != "" {
+		return c.Name
+	}
+	return c.PreferredUsername
+}
+
+// jwtSigAlgs is the accepted signature-algorithm allowlist passed to
+// jwt.ParseSigned (go-jose v4 requires it explicitly). RSA + ECDSA + PSS, the
+// set IAM may sign with — never "none".
+var jwtSigAlgs = []gojose.SignatureAlgorithm{
+	gojose.RS256, gojose.RS384, gojose.RS512,
+	gojose.ES256, gojose.ES384, gojose.ES512,
+	gojose.PS256, gojose.PS384, gojose.PS512,
+}
+
+// identityValidator validates an IAM JWT against a cached JWKS. Issuer (any of a
+// trusted SET) + audience + expiry are always enforced.
+//
+// The issuer is a SET so ONE cloud binary validates every white-label brand's
+// tokens (hanzo iss=hanzo.id AND lux iss=lux.id, ...). Signature verification is
+// unaffected: the in-cluster IAM serves EVERY brand's signing cert in one JWKS
+// (cert-hanzo/cert-lux/cert-zoo/...), keyed by the token kid, so a single
+// jwksURL verifies all brands. Only the issuer-string comparison had to widen.
+type identityValidator struct {
+	issuers   []string
+	audiences []string
+	cache     *jwksCache
+}
+
+// newIdentityValidator builds a validator whose trusted-issuer set is the primary
+// issuer UNIONED with every white-label brand issuer (BrandIssuers) plus any
+// WHITELABEL_ISSUERS override. ttl<=0 uses the 15m JWKS default. The union is
+// fail-secure: it only ADDS the known-good brand issuers, never an arbitrary one.
+func newIdentityValidator(issuer, jwksURL string, audiences []string, ttl time.Duration) *identityValidator {
+	return &identityValidator{
+		issuers:   trustedIssuers(issuer),
+		audiences: audiences,
+		cache:     newJWKSCache(jwksURL, ttl),
+	}
+}
+
+// kmsMachineAudSuffix is the fixed suffix of a per-org PaaS-KMS sync machine
+// identity's audience. Each org's KMS sync authenticates as a dedicated,
+// NON-shared IAM application named "<org>-platform-kms" (Organization=<org>,
+// client_credentials grant), so IAM stamps the token's aud == the app's own
+// clientId == "<org>-platform-kms" (a non-shared app's audience is its clientId,
+// object/token_jwt.go tokenAudience) and owner == <org>
+// (object/token_oauth.go GetClientCredentialsToken sets owner = app.Organization).
+//
+// That audience is, by construction, absent from CLOUD_JWT_AUDIENCES — it is
+// per-org, not a fixed app — which is EXACTLY why the sync stayed pending: the
+// machine token failed the audience check below, SanitizeIdentity treated it as
+// anonymous, and the /v1/kms org-scope guard 403'd it before the store. The fix is
+// to accept this one audience, but ONLY when it equals the token's OWN owner claim
+// plus this suffix, so it certifies "the KMS sync identity for its own org" and
+// grants nothing wider. Org-scoping is still enforced downstream by owner at the guard
+// (owner == :org); this only lets a legitimately-minted, owner-scoped machine token
+// clear validation. A per-org application means a per-org clientSecret — never
+// a shared platform-wide reader, which would be a cross-org hole.
+const kmsMachineAudSuffix = "-platform-kms"
+
+// kmsMachineAudience returns the audience an org org's PaaS-KMS sync identity
+// carries: "<owner>-platform-kms". An empty owner yields empty — no machine
+// audience is ever granted to an org-less token (fail closed).
+func kmsMachineAudience(owner string) string {
+	if owner == "" {
+		return ""
+	}
+	return owner + kmsMachineAudSuffix
+}
+
+// isKMSMachinePrincipal reports whether a validated token is a per-org KMS-sync
+// machine identity: its audience set contains the owner-bound machine audience
+// (<owner>-platform-kms). Such a principal is a client_credentials machine identity
+// scoped to exactly one org. SanitizeIdentity uses this to DENY it SuperAdmin
+// authority even if it somehow carries isAdmin=true and owner==adminOrg, so V6's
+// audience widening can never be leveraged (via an admin-org machine token) into a
+// cross-org read. Its org-scoped data access is unaffected — this gates ONLY the
+// admin grant, keeping the machine path decoupled from admin inside cloud (rather
+// than resting on the external invariant "IAM never stamps isAdmin=true on a
+// machine-aud token", which cloud cannot see or enforce).
+func isKMSMachinePrincipal(claims *idClaims) bool {
+	mach := kmsMachineAudience(claims.Owner)
+	if mach == "" {
+		return false
+	}
+	for _, a := range claims.Audience {
+		if a == mach {
+			return true
+		}
+	}
+	return false
+}
+
+// validate parses raw, verifies its signature against the JWKS, and enforces
+// issuer/audience/expiry. Returns the claims on success, an error otherwise.
+func (v *identityValidator) validate(raw string) (*idClaims, error) {
+	tok, err := jwt.ParseSigned(raw, jwtSigAlgs)
+	if err != nil {
+		return nil, fmt.Errorf("parse: %w", err)
+	}
+	keys, err := v.cache.get()
+	if err != nil {
+		return nil, fmt.Errorf("jwks: %w", err)
+	}
+
+	var claims idClaims
+	if err := verifyAgainstKeys(tok, keys, &claims); err != nil {
+		return nil, err
+	}
+
+	// Reject a missing issuer: an empty issuer must never pass the set check.
+	if claims.Issuer == "" {
+		return nil, fmt.Errorf("missing issuer")
+	}
+	// Reject a missing expiry: ValidateWithLeeway only enforces exp when present
+	// (it checks `if c.Expiry != nil`), so a token with NO exp would never expire.
+	// An IAM access token always carries exp; require it.
+	if claims.Expiry == nil {
+		return nil, fmt.Errorf("missing expiry")
+	}
+	// Issuer must be one of the trusted brand issuers. go-jose's jwt.Expected
+	// checks a SINGLE issuer, so the issuer is validated here against the set and
+	// left out of Expected (audience + expiry stay with Expected).
+	if !issuerAllowed(claims.Issuer, v.issuers) {
+		return nil, fmt.Errorf("untrusted issuer %q", claims.Issuer)
+	}
+	// Audience: the static allowlist (CLOUD_JWT_AUDIENCES / brand app client_ids)
+	// PLUS the per-org PaaS-KMS sync machine audience bound to THIS token's own
+	// owner (<owner>-platform-kms). The machine audience is added only when the
+	// allowlist is active (non-empty — always so in production) and only for the
+	// token's own org, so accepting it never widens org-scoping: the /v1/kms guard still
+	// gates on owner == :org. Without this, a real client_credentials machine token
+	// (aud == its per-org clientId, never in the allowlist) fails here and the
+	// sync silently stays pending — the activation blocker.
+	expected := jwt.Expected{}
+	if len(v.audiences) > 0 {
+		auds := v.audiences
+		if mach := kmsMachineAudience(claims.Owner); mach != "" {
+			auds = append(append(make([]string, 0, len(v.audiences)+1), v.audiences...), mach)
+		}
+		expected.AnyAudience = jwt.Audience(auds)
+	}
+	if err := claims.Claims.ValidateWithLeeway(expected, 2*time.Minute); err != nil {
+		return nil, fmt.Errorf("claims: %w", err)
+	}
+	return &claims, nil
+}
+
+// verifyAgainstKeys tries the kid-matched key first, then any RSA signing key —
+// mirrors iamauth's selection so a token verifies the same way at both layers.
+func verifyAgainstKeys(tok *jwt.JSONWebToken, keys *gojose.JSONWebKeySet, claims *idClaims) error {
+	var lastErr error
+	for _, h := range tok.Headers {
+		if h.KeyID == "" {
+			continue
+		}
+		for _, k := range keys.Key(h.KeyID) {
+			if err := tok.Claims(k.Key, claims); err == nil {
+				return nil
+			} else {
+				lastErr = err
+			}
+		}
+	}
+	for _, k := range keys.Keys {
+		if k.Use != "sig" && k.Use != "" {
+			continue
+		}
+		if _, ok := k.Key.(*rsa.PublicKey); !ok {
+			continue
+		}
+		if err := tok.Claims(k.Key, claims); err == nil {
+			return nil
+		} else {
+			lastErr = err
+		}
+	}
+	if lastErr != nil {
+		return fmt.Errorf("no matching key: %w", lastErr)
+	}
+	return fmt.Errorf("no matching key in JWKS")
+}
+
+// ----------------------------------------------------------------------------
+// JWKS cache (TTL refresh, stale-on-error) — mirrors iamauth.JWKSCache.
+// ----------------------------------------------------------------------------
+
+type jwksCache struct {
+	mu        sync.RWMutex
+	keys      *gojose.JSONWebKeySet
+	fetchedAt time.Time
+	ttl       time.Duration
+	url       string
+	client    *http.Client
+}
+
+func newJWKSCache(url string, ttl time.Duration) *jwksCache {
+	if ttl <= 0 {
+		ttl = 15 * time.Minute
+	}
+	return &jwksCache{url: url, ttl: ttl, client: &http.Client{Timeout: 10 * time.Second}}
+}
+
+// get returns the cached key set, refreshing past TTL. On a fetch error with a
+// previously-cached set, the stale set is returned rather than failing — a
+// transient JWKS blip must not flap validation (and so admin auth) closed.
+func (c *jwksCache) get() (*gojose.JSONWebKeySet, error) {
+	c.mu.RLock()
+	if c.keys != nil && time.Since(c.fetchedAt) < c.ttl {
+		k := c.keys
+		c.mu.RUnlock()
+		return k, nil
+	}
+	c.mu.RUnlock()
+
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	if c.keys != nil && time.Since(c.fetchedAt) < c.ttl {
+		return c.keys, nil
+	}
+	keys, err := c.fetch()
+	if err != nil {
+		if c.keys != nil {
+			return c.keys, nil
+		}
+		return nil, err
+	}
+	c.keys = keys
+	c.fetchedAt = time.Now()
+	return keys, nil
+}
+
+func (c *jwksCache) fetch() (*gojose.JSONWebKeySet, error) {
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, c.url, nil)
+	if err != nil {
+		return nil, fmt.Errorf("request: %w", err)
+	}
+	resp, err := c.client.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("fetch: %w", err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("status %d", resp.StatusCode)
+	}
+	body, err := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
+	if err != nil {
+		return nil, fmt.Errorf("read: %w", err)
+	}
+	var set gojose.JSONWebKeySet
+	if err := json.Unmarshal(body, &set); err != nil {
+		return nil, fmt.Errorf("parse: %w", err)
+	}
+	return &set, nil
+}
+
+// ----------------------------------------------------------------------------
+// Token extraction — mirrors iamauth's Bearer / Basic / API-key helpers.
+// ----------------------------------------------------------------------------
+
+// isAPIKey reports whether tok is an opaque, backend-validated key (hk-/sk-/…)
+// rather than a JWT, so the sanitizer skips JWT parsing for it.
+func isAPIKey(tok string) bool {
+	return strings.HasPrefix(tok, "hk-") ||
+		strings.HasPrefix(tok, "sk-") ||
+		strings.HasPrefix(tok, "pk-") ||
+		strings.HasPrefix(tok, "fw_") ||
+		strings.HasPrefix(tok, "hz_")
+}
+
+// bearerFromAuth extracts the token from a "Bearer <token>" header value.
+func bearerFromAuth(auth string) string {
+	if auth == "" {
+		return ""
+	}
+	parts := strings.SplitN(auth, " ", 2)
+	if len(parts) != 2 || !strings.EqualFold(parts[0], "Bearer") {
+		return ""
+	}
+	return strings.TrimSpace(parts[1])
+}
+
+// basicFromAuth extracts the token from an HTTP Basic header value: the password
+// field (the go/.netrc proxy idiom), falling back to the username when empty.
+func basicFromAuth(auth string) string {
+	if auth == "" {
+		return ""
+	}
+	parts := strings.SplitN(auth, " ", 2)
+	if len(parts) != 2 || !strings.EqualFold(parts[0], "Basic") {
+		return ""
+	}
+	raw, err := base64.StdEncoding.DecodeString(strings.TrimSpace(parts[1]))
+	if err != nil {
+		return ""
+	}
+	user, pass, ok := strings.Cut(string(raw), ":")
+	if !ok {
+		return ""
+	}
+	if pass != "" {
+		return pass
+	}
+	return user
+}
+
+// trustedIssuers returns the full trusted-issuer set for the in-binary validator:
+// the PRIMARY issuer (the deployment's own brand, cfg.IAMIssuer) UNIONED with every
+// white-label brand issuer (BrandIssuers) and any WHITELABEL_ISSUERS override
+// (comma-separated). Fail-secure: it only ADDS known-good issuers; a nil/empty
+// result is impossible when a primary is set, so the issuer check is always
+// enforced. Duplicates are removed; order is primary-first.
+func trustedIssuers(primary string) []string {
+	out := make([]string, 0, 6)
+	add := func(v string) {
+		v = strings.TrimSpace(v)
+		if v == "" {
+			return
+		}
+		for _, e := range out {
+			if e == v {
+				return
+			}
+		}
+		out = append(out, v)
+	}
+	add(primary)
+	for _, iss := range BrandIssuers() {
+		add(iss)
+	}
+	for _, iss := range splitTrim(os.Getenv("WHITELABEL_ISSUERS")) {
+		add(iss)
+	}
+	return out
+}
+
+// issuerAllowed reports whether iss is one of the trusted issuers. An empty set
+// (no primary, no brands — never the case in production) skips the check, matching
+// the prior "empty issuer disables the check" behavior; a non-empty set is
+// fail-secure (a token whose iss is not in the set is rejected).
+func issuerAllowed(iss string, trusted []string) bool {
+	if len(trusted) == 0 {
+		return true
+	}
+	for _, t := range trusted {
+		if iss == t {
+			return true
+		}
+	}
+	return false
+}

auth_identity_kms_test.go

@@ -0,0 +1,87 @@
+package cloud
+
+// V6 (the activation blocker) — the identity validator must accept a per-org
+// PaaS-KMS sync machine token: a client_credentials JWT whose aud is the org's
+// own IAM application clientId "<owner>-platform-kms" (a per-org value, NEVER in
+// CLOUD_JWT_AUDIENCES) — but ONLY when that audience is bound to the token's OWN
+// owner claim. Before the fix the machine token failed the audience check,
+// SanitizeIdentity resolved anonymous, and the /v1/kms guard 403'd it, so the sync
+// silently stayed pending. These are white-box unit tests of validate() itself;
+// the end-to-end proof through SanitizeIdentity + the real guard lives in
+// clients/kms (v6_aud_e2e_test.go). Reuses the jwksServer/signWith/tokenClaims
+// helpers from middleware_identity_test.go (same package).
+
+import (
+	"crypto/rand"
+	"crypto/rsa"
+	"testing"
+	"time"
+)
+
+func TestIdentityValidator_KMSMachineAudience(t *testing.T) {
+	key, err := rsa.GenerateKey(rand.Reader, 2048)
+	if err != nil {
+		t.Fatalf("genkey: %v", err)
+	}
+	jwks := jwksServer(t, &key.PublicKey)
+	// The static allowlist deliberately contains NO *-platform-kms audience, so any
+	// acceptance below can come ONLY from the owner-bound machine-aud rule, not the
+	// allowlist — this is what makes it a fix and not a config workaround.
+	v := newIdentityValidator(testIssuer, jwks.URL, []string{"hanzo-console"}, 0)
+	future := time.Now().Add(time.Hour)
+
+	t.Run("machine token for its own org is accepted", func(t *testing.T) {
+		c, err := v.validate(signWith(t, key, tokenClaims("maxpower-platform-kms", "maxpower", "", false, future)))
+		if err != nil {
+			t.Fatalf("machine token rejected: %v", err)
+		}
+		if c.Owner != "maxpower" {
+			t.Fatalf("owner=%q, want maxpower", c.Owner)
+		}
+	})
+
+	t.Run("machine aud for a DIFFERENT org is rejected (owner-bound)", func(t *testing.T) {
+		// owner=maxpower but aud=acme-platform-kms: the accepted machine aud is bound
+		// to the token's OWN owner (maxpower-platform-kms), so this must fail — it is
+		// not a blanket "*-platform-kms" wildcard.
+		if _, err := v.validate(signWith(t, key, tokenClaims("acme-platform-kms", "maxpower", "", false, future))); err == nil {
+			t.Fatal("cross-org machine audience must be rejected (owner-bound)")
+		}
+	})
+
+	t.Run("arbitrary audience still rejected (fix is scoped, not a disable)", func(t *testing.T) {
+		if _, err := v.validate(signWith(t, key, tokenClaims("some-random-app", "maxpower", "", false, future))); err == nil {
+			t.Fatal("an arbitrary audience must still be rejected")
+		}
+	})
+
+	t.Run("machine aud with empty owner is rejected (fail closed)", func(t *testing.T) {
+		// aud="-platform-kms" with owner="": kmsMachineAudience("")=="" so no machine
+		// audience is granted and the bare suffix is not in the allowlist.
+		if _, err := v.validate(signWith(t, key, tokenClaims("-platform-kms", "", "", false, future))); err == nil {
+			t.Fatal("machine aud with empty owner must be rejected")
+		}
+	})
+
+	t.Run("normal static-allowlist token still accepted (regression)", func(t *testing.T) {
+		if _, err := v.validate(signWith(t, key, tokenClaims("hanzo-console", "maxpower", "", false, future))); err != nil {
+			t.Fatalf("static-allowlist token rejected: %v", err)
+		}
+	})
+
+	t.Run("machine token expiry still enforced", func(t *testing.T) {
+		if _, err := v.validate(signWith(t, key, tokenClaims("maxpower-platform-kms", "maxpower", "", false, time.Now().Add(-time.Hour)))); err == nil {
+			t.Fatal("expired machine token must be rejected")
+		}
+	})
+}
+
+// kmsMachineAudience is a pure helper; lock its contract directly.
+func TestKMSMachineAudience(t *testing.T) {
+	if got := kmsMachineAudience("maxpower"); got != "maxpower-platform-kms" {
+		t.Fatalf("kmsMachineAudience(maxpower)=%q, want maxpower-platform-kms", got)
+	}
+	if got := kmsMachineAudience(""); got != "" {
+		t.Fatalf("kmsMachineAudience(\"\")=%q, want \"\" (no machine aud for an org-less token)", got)
+	}
+}

auth_identity_whitelabel_test.go

@@ -0,0 +1,150 @@
+package cloud
+
+import (
+	"os"
+	"testing"
+)
+
+// TestTrustedIssuers_WhiteLabel proves the in-binary validator's trusted-issuer
+// set is the primary issuer UNIONED with every white-label brand issuer plus the
+// WHITELABEL_ISSUERS override, deduped, primary-first.
+func TestTrustedIssuers_WhiteLabel(t *testing.T) {
+	os.Unsetenv("WHITELABEL_ISSUERS")
+	got := trustedIssuers("https://hanzo.id")
+	want := map[string]bool{
+		"https://hanzo.id":     true,
+		"https://lux.id":       true,
+		"https://zoo.id":       true, // per cloud brand.go registry
+		"https://pars.id":      true,
+		"https://id.bootno.de": true, // bootnode brand also in the registry
+	}
+	set := map[string]bool{}
+	for _, g := range got {
+		set[g] = true
+	}
+	for w := range want {
+		if !set[w] {
+			t.Errorf("trusted set %v missing %q", got, w)
+		}
+	}
+	if got[0] != "https://hanzo.id" {
+		t.Errorf("primary issuer must be first, got %q", got[0])
+	}
+
+	// Override adds a brand without a rebuild.
+	t.Setenv("WHITELABEL_ISSUERS", "https://custom.id, https://another.id")
+	got2 := trustedIssuers("https://hanzo.id")
+	if !issuerAllowed("https://custom.id", got2) || !issuerAllowed("https://another.id", got2) {
+		t.Errorf("WHITELABEL_ISSUERS override must add issuers, got %v", got2)
+	}
+}
+
+// TestIssuerAllowed proves the set membership check: brand issuers pass, an
+// outsider is rejected, and an empty set (never in prod) skips the check.
+func TestIssuerAllowed(t *testing.T) {
+	set := []string{"https://hanzo.id", "https://lux.id"}
+	if !issuerAllowed("https://lux.id", set) {
+		t.Error("lux.id must be allowed")
+	}
+	if issuerAllowed("https://attacker.id", set) {
+		t.Error("attacker.id must be rejected")
+	}
+	if !issuerAllowed("anything", nil) {
+		t.Error("empty set must skip the check (matches prior empty-issuer behavior)")
+	}
+}
+
+// TestBrandIssuers proves the issuer list is derived from the brands registry and
+// covers every configured brand (one source of truth).
+func TestBrandIssuers(t *testing.T) {
+	got := BrandIssuers()
+	for _, want := range []string{"https://hanzo.id", "https://lux.id", "https://zoo.id", "https://pars.id", "https://id.bootno.de"} {
+		found := false
+		for _, g := range got {
+			if g == want {
+				found = true
+				break
+			}
+		}
+		if !found {
+			t.Errorf("BrandIssuers()=%v missing %q", got, want)
+		}
+	}
+}
+
+// TestNewIdentityValidator_MultiIssuer proves the constructed validator carries the
+// full brand set, so a lux token would pass the issuer gate on the hanzo binary.
+func TestNewIdentityValidator_MultiIssuer(t *testing.T) {
+	os.Unsetenv("WHITELABEL_ISSUERS")
+	v := newIdentityValidator("https://hanzo.id", "http://iam.hanzo.svc/v1/iam/.well-known/jwks", []string{"hanzo-cloud", "lux-cloud"}, 0)
+	if !issuerAllowed("https://lux.id", v.issuers) {
+		t.Fatalf("validator must trust the lux issuer, set=%v", v.issuers)
+	}
+	if !issuerAllowed("https://hanzo.id", v.issuers) {
+		t.Fatalf("validator must still trust hanzo (no regression), set=%v", v.issuers)
+	}
+	if issuerAllowed("https://evil.id", v.issuers) {
+		t.Fatalf("validator must reject an untrusted issuer, set=%v", v.issuers)
+	}
+}
+
+// TestBrandAudiences proves every brand's cloud audience (<brand>-cloud) is derived
+// from the brands registry — one source of truth, mirroring BrandIssuers.
+func TestBrandAudiences(t *testing.T) {
+	got := BrandAudiences()
+	for _, want := range []string{"hanzo-cloud", "lux-cloud", "zoo-cloud", "pars-cloud", "bootnode-cloud"} {
+		found := false
+		for _, g := range got {
+			if g == want {
+				found = true
+				break
+			}
+		}
+		if !found {
+			t.Errorf("BrandAudiences()=%v missing %q", got, want)
+		}
+	}
+}
+
+// TestJWTAudiencesFromEnv_BrandUnion proves the resolved audience allowlist ALWAYS
+// includes every brand's <brand>-cloud aud (so a lux token validates), whether the
+// list comes from the baked default or a hanzo-only env override — and that an
+// env-supplied entry is not duplicated.
+func TestJWTAudiencesFromEnv_BrandUnion(t *testing.T) {
+	has := func(list []string, v string) bool {
+		for _, s := range list {
+			if s == v {
+				return true
+			}
+		}
+		return false
+	}
+
+	// Baked default path (no env).
+	os.Unsetenv("CLOUD_JWT_AUDIENCES")
+	os.Unsetenv("GATEWAY_ALLOWED_AUDIENCES")
+	def := jwtAudiencesFromEnv()
+	for _, want := range []string{"hanzo-cloud", "lux-cloud", "zoo-cloud", "pars-cloud"} {
+		if !has(def, want) {
+			t.Errorf("baked audiences %v missing brand aud %q", def, want)
+		}
+	}
+
+	// A legacy hanzo-only env override must STILL accept lux-cloud (brand union),
+	// with no duplicate of the env-supplied hanzo-cloud.
+	os.Setenv("GATEWAY_ALLOWED_AUDIENCES", "hanzo-app,hanzo-console,hanzo-cloud")
+	defer os.Unsetenv("GATEWAY_ALLOWED_AUDIENCES")
+	got := jwtAudiencesFromEnv()
+	if !has(got, "lux-cloud") {
+		t.Fatalf("hanzo-only env override must still accept lux-cloud, got %v", got)
+	}
+	n := 0
+	for _, s := range got {
+		if s == "hanzo-cloud" {
+			n++
+		}
+	}
+	if n != 1 {
+		t.Fatalf("hanzo-cloud must appear exactly once (no duplicate), got %d in %v", n, got)
+	}
+}

auto_routing_billing_test.go

@@ -0,0 +1,102 @@
+// Copyright 2023-2025 Hanzo AI Inc. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package cloud
+
+// Auto-routing billing binding at the cloud edge.
+//
+// The ai subsystem serves a virtual `auto`/`zen-router` model: it resolves the
+// request to a concrete model id BEFORE pricing/billing, meters its own LLM
+// token cost to commerce keyed on the SERVED model, and reports that id via the
+// `X-Routed-Model` response header (and the response body `model` field).
+//
+// The cloud edge must therefore do two things for an `auto` request, both
+// verified here end-to-end through the real BillingGate + DefaultPrice:
+//  1. NOT re-price it by the (virtual) request model — /v1/ai/* is self-metered,
+//     so the edge gate delegates all LLM billing to the ai subsystem. That
+//     subsystem bills the resolved model, so `auto` bills as what served it.
+//  2. Pass the `X-Routed-Model` header through untouched, so the model the
+//     client sees reported is exactly the model that was billed.
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/zap-proto/zip"
+)
+
+// TestAutoRoutingBillsAsResolvedModel drives an `auto` chat request through the
+// real edge gate (BillingGate + DefaultPrice) in front of a handler that
+// simulates the ai subsystem after it resolved auto→zen4-coder.
+func TestAutoRoutingBillsAsResolvedModel(t *testing.T) {
+	fc := &fakeCommerce{balanceBody: `{"available":5000}`}
+	srv := fc.server(t)
+	m := mustClient(t, srv.URL, false /* fail-closed */)
+
+	app := zip.New(zip.Config{})
+	// The genuine edge gate with the genuine price function.
+	app.Use(BillingGate(m, DefaultPrice))
+	// Stand-in for the mounted ai subsystem: auto already resolved to zen4-coder,
+	// which it reports on the header + body (and meters itself — not modeled here).
+	app.Post("/v1/ai/chat/completions", func(c *zip.Ctx) error {
+		c.SetHeader("X-Routed-Model", "zen4-coder")
+		return c.JSON(http.StatusOK, map[string]string{"model": "zen4-coder"})
+	})
+
+	req := httptest.NewRequest(http.MethodPost, "/v1/ai/chat/completions",
+		strings.NewReader(`{"model":"auto","messages":[{"role":"user","content":"refactor this"}]}`))
+	req.Header.Set("X-Org-Id", "hanzo")
+	req.Header.Set("X-User-Id", "alice")
+	req.Header.Set("Content-Type", "application/json")
+
+	resp, err := app.Fiber().Test(req)
+	if err != nil {
+		t.Fatalf("Test request: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("status = %d, want 200", resp.StatusCode)
+	}
+
+	// (1) The edge did NOT bill: /v1/ai/* is self-metered (DefaultPrice 0), so the
+	// gate short-circuits before Authorize/Record. Billing is delegated to the ai
+	// subsystem, which meters the RESOLVED model — never the virtual `auto`.
+	// (Give any erroneous async Record a moment to land before asserting zero.)
+	if fc.usages() != 0 {
+		t.Fatalf("edge recorded %d usage(s) for /v1/ai/*, want 0 (self-metered by ai)", fc.usages())
+	}
+	if waitFor(func() bool { return fc.usages() > 0 }, 50*time.Millisecond) {
+		t.Fatalf("edge double-billed an ai request (usages=%d): auto must be billed by the ai meter, not the edge", fc.usages())
+	}
+
+	// (2) Header pass-through: the resolved model the ai meter billed reaches the
+	// client, so what's reported == what's billed.
+	if got := resp.Header.Get("X-Routed-Model"); got != "zen4-coder" {
+		t.Errorf("X-Routed-Model = %q, want zen4-coder (must pass through the edge)", got)
+	}
+}
+
+// TestDefaultPriceAiPathModelAgnostic documents the binding at the pricing layer:
+// the edge price for the ai chat path is 0 regardless of the request model, so
+// `auto` and a concrete model are treated identically — the ai subsystem's own
+// per-token meter (keyed on the resolved model) is the single source of the
+// charge. Path-based, never request-model-based, pricing is what makes `auto`
+// bill as the model that served it.
+func TestDefaultPriceAiPathModelAgnostic(t *testing.T) {
+	if got := priceForPath(t, "/v1/ai/chat/completions"); got != 0 {
+		t.Errorf("DefaultPrice(/v1/ai/chat/completions) = %d, want 0 — ai self-meters the resolved model", got)
+	}
+}

brand.go

@@ -0,0 +1,140 @@
+package cloud
+
+import "strings"
+
+// Brand white-label registry (HIP-0111).
+//
+// The cloud binary is one artifact serving every brand's API host
+// (api.hanzo.ai, api.lux.cloud, api.zoo.cloud, api.cloud.pars.network, ...).
+// Brand is a per-deployment value (CLOUD_BRAND / --brand). This registry maps a
+// brand to its PUBLIC IAM facts — the canonical OIDC issuer the deployment must
+// validate JWTs against. These are public (issuer host + brand domain), so they
+// live in code, not in KMS.
+//
+// One source of truth: nothing else in the binary hardcodes a per-brand issuer.
+// Config.IAMIssuer is derived from here when the operator does not pin one, so a
+// lux deployment validates against lux.id, a zoo deployment against zoo.id, etc.,
+// instead of silently defaulting every brand to iam.hanzo.ai.
+
+// BrandInfo is the PUBLIC per-brand identity used for token validation + URL
+// scoping. No secrets.
+type BrandInfo struct {
+	// ID is the canonical brand key.
+	ID string
+	// IAMIssuer is the OIDC issuer (JWKS source) for this brand — the value the
+	// JWT `iss` claim must equal and whose /v1/iam/.well-known/jwks signs tokens.
+	IAMIssuer string
+	// Domain is the brand's primary marketing/site domain (for response scoping
+	// and base-URL derivation, e.g. api.<Domain>).
+	Domain string
+	// AltDomains are additional registrable domains that ALSO belong to this
+	// brand, used ONLY for hostname→brand white-label detection (BrandForHostOK).
+	// A brand's real serving surfaces span more than its marketing domain — the
+	// cloud console runs on <brand>.cloud hosts (console.lux.cloud,
+	// console.zoo.cloud), and a request Host there must brand as Lux/Zoo, never
+	// fall through to Hanzo. Base-URL/issuer scoping still uses the primary Domain.
+	AltDomains []string
+}
+
+// brands is the brand→IAM registry. Keys are the canonical brand IDs accepted
+// by CLOUD_BRAND. Per HIP-0111 §Brands: hanzo→hanzo.id, lux→lux.id,
+// zoo→zoo.id, pars→pars.id, bootnode→id.bootno.de.
+//
+// IAMIssuer MUST equal the `iss` IAM actually stamps AND host the signing JWKS.
+// For hanzo the live .well-known/openid-configuration on BOTH hanzo.id and
+// iam.hanzo.ai reports issuer=https://hanzo.id + jwks_uri=
+// https://hanzo.id/v1/iam/.well-known/jwks (iam.hanzo.ai is a routing alias, not
+// the issuer), and the cloud CLI already defaults to hanzo.id. Pinning
+// iam.hanzo.ai here would fail the issuer check on every real token, anonymizing
+// every principal — SuperAdmin would 403 platform-wide (fail-secure, but
+// broken). lux/zoo/pars already correctly point at their own .id issuers.
+var brands = map[string]BrandInfo{
+	"hanzo":    {ID: "hanzo", IAMIssuer: "https://hanzo.id", Domain: "hanzo.ai", AltDomains: []string{"hanzo.cloud", "hanzo.app"}},
+	"lux":      {ID: "lux", IAMIssuer: "https://lux.id", Domain: "lux.network", AltDomains: []string{"lux.cloud"}},
+	"zoo":      {ID: "zoo", IAMIssuer: "https://zoo.id", Domain: "zoo.ngo", AltDomains: []string{"zoo.network", "zoo.cloud"}},
+	"pars":     {ID: "pars", IAMIssuer: "https://pars.id", Domain: "pars.network", AltDomains: []string{"pars.ai"}},
+	"bootnode": {ID: "bootnode", IAMIssuer: "https://id.bootno.de", Domain: "bootno.de"},
+}
+
+// DefaultBrand is the fallback brand when CLOUD_BRAND is unknown.
+const DefaultBrand = "hanzo"
+
+// BrandFor returns the BrandInfo for id, falling back to the Hanzo brand for an
+// unknown id. Lookup is case-insensitive.
+func BrandFor(id string) BrandInfo {
+	if b, ok := brands[strings.ToLower(strings.TrimSpace(id))]; ok {
+		return b
+	}
+	return brands[DefaultBrand]
+}
+
+// IssuerForBrand returns the canonical OIDC issuer for a brand id.
+func IssuerForBrand(id string) string {
+	return BrandFor(id).IAMIssuer
+}
+
+// BrandForHostOK resolves a request Host to a brand id from the same `brands`
+// registry, mirroring the hostname→brand semantics of platform.ts's
+// getWhiteLabelBrand: a Host at or under a brand's Domain (api.lux.network,
+// lux.network) is that brand. The port is stripped and the compare is
+// case-insensitive; the longest matching Domain wins so a nested brand domain is
+// never shadowed by a shorter one. ok is false when NO brand domain matches, so
+// the caller can choose its own fallback (the deployment brand) rather than
+// silently emitting Hanzo branding on, say, a Zoo pod hit with an odd Host.
+func BrandForHostOK(host string) (string, bool) {
+	host = strings.ToLower(strings.TrimSpace(host))
+	if i := strings.IndexByte(host, ':'); i >= 0 {
+		host = host[:i]
+	}
+	best, bestLen := "", -1
+	for id, b := range brands {
+		for _, d := range append([]string{b.Domain}, b.AltDomains...) {
+			d = strings.ToLower(d)
+			if d == "" {
+				continue
+			}
+			if (host == d || strings.HasSuffix(host, "."+d)) && len(d) > bestLen {
+				best, bestLen = id, len(d)
+			}
+		}
+	}
+	return best, best != ""
+}
+
+// BrandForHost is BrandForHostOK with the Hanzo default for an unmatched Host.
+func BrandForHost(host string) string {
+	if b, ok := BrandForHostOK(host); ok {
+		return b
+	}
+	return DefaultBrand
+}
+
+// BrandIssuers returns the OIDC issuer of every configured white-label brand. The
+// in-binary identity validator (auth_identity.go) trusts a token whose `iss` is
+// any of these, so ONE cloud binary validates hanzo AND lux/zoo/pars tokens. One
+// source of truth: derived from the same `brands` registry above.
+func BrandIssuers() []string {
+	out := make([]string, 0, len(brands))
+	for _, b := range brands {
+		if b.IAMIssuer != "" {
+			out = append(out, b.IAMIssuer)
+		}
+	}
+	return out
+}
+
+// BrandAudiences returns the OAuth `aud` (== IAM client_id == app name) of every
+// white-label brand's cloud login app: `<brand>-cloud` (hanzo-cloud, lux-cloud,
+// zoo-cloud, pars-cloud, bootnode-cloud). A brand's session token carries
+// aud=<brand>-cloud (HIP-0111: client_id == app == aud), so the audience allowlist
+// must include each to accept a lux/zoo/pars token on the ONE binary. Derived from
+// the same `brands` registry as BrandIssuers — one source of truth, no hand-listing.
+func BrandAudiences() []string {
+	out := make([]string, 0, len(brands))
+	for id := range brands {
+		if id != "" {
+			out = append(out, id+"-cloud")
+		}
+	}
+	return out
+}

brand_test.go

@@ -0,0 +1,85 @@
+package cloud
+
+import (
+	"os"
+	"testing"
+)
+
+func TestBrandFor(t *testing.T) {
+	// hanzo → hanzo.id (NOT iam.hanzo.ai): brand.go was pinned to the real OIDC
+	// issuer in fddaeb14 ("pin hanzo IAM issuer to hanzo.id") — iam.hanzo.ai is a
+	// routing alias, and the live .well-known reports iss=https://hanzo.id, so a
+	// token would fail the issuer check against iam.hanzo.ai. This stale
+	// assertion predated that pin; aligned here (drive-by, brand.go unchanged).
+	cases := map[string]string{
+		"hanzo":    "https://hanzo.id",
+		"lux":      "https://lux.id",
+		"zoo":      "https://zoo.id",
+		"pars":     "https://pars.id",
+		"bootnode": "https://id.bootno.de",
+		"LUX":      "https://lux.id",   // case-insensitive
+		"  zoo  ":  "https://zoo.id",   // trimmed
+		"unknown":  "https://hanzo.id", // falls back to hanzo
+		"":         "https://hanzo.id", // empty → hanzo default
+	}
+	for brand, want := range cases {
+		if got := IssuerForBrand(brand); got != want {
+			t.Errorf("IssuerForBrand(%q) = %q, want %q", brand, got, want)
+		}
+	}
+}
+
+func TestBrandForHost(t *testing.T) {
+	match := map[string]string{
+		"api.hanzo.ai":        "hanzo",
+		"hanzo.ai":            "hanzo",
+		"api.lux.network":     "lux",
+		"lux.network":         "lux",
+		"API.LUX.NETWORK":     "lux", // case-insensitive
+		"api.lux.network:443": "lux", // port stripped
+		"api.zoo.ngo":         "zoo",
+		"chat.zoo.ngo":        "zoo",
+		"api.pars.network":    "pars",
+		// AltDomains: the real cloud console surfaces run on <brand>.cloud /
+		// <brand>.network — a Host there must brand as Lux/Zoo, never Hanzo.
+		"console.lux.cloud":   "lux",
+		"console.zoo.cloud":   "zoo",
+		"foo.zoo.network":     "zoo",
+		"console.hanzo.cloud": "hanzo",
+		"app.hanzo.app":       "hanzo",
+	}
+	for host, want := range match {
+		if got, ok := BrandForHostOK(host); !ok || got != want {
+			t.Errorf("BrandForHostOK(%q) = %q,%v; want %q,true", host, got, ok, want)
+		}
+		if got := BrandForHost(host); got != want {
+			t.Errorf("BrandForHost(%q) = %q; want %q", host, got, want)
+		}
+	}
+	// No brand domain matches → not ok, and BrandForHost defaults to hanzo. The
+	// caller (agentskills) uses the not-ok signal to fall back to the DEPLOYMENT
+	// brand instead of blindly emitting Hanzo on a non-hanzo pod.
+	for _, host := range []string{"example.com", "localhost", "", "10.0.0.1"} {
+		if _, ok := BrandForHostOK(host); ok {
+			t.Errorf("BrandForHostOK(%q) matched a brand, want no match", host)
+		}
+		if got := BrandForHost(host); got != DefaultBrand {
+			t.Errorf("BrandForHost(%q) = %q, want %q", host, got, DefaultBrand)
+		}
+	}
+}
+
+// TestLoadConfig_IssuerDerivedFromBrand asserts that when CLOUD_IAM_ISSUER is
+// unset, the issuer is derived from CLOUD_BRAND — so a non-hanzo brand does not
+// silently validate against iam.hanzo.ai.
+func TestLoadConfig_IssuerDerivedFromBrand(t *testing.T) {
+	t.Setenv("CLOUD_BRAND", "lux")
+	os.Unsetenv("CLOUD_IAM_ISSUER")
+	cfg := LoadConfig()
+	if cfg.IAMIssuer != "https://lux.id" {
+		t.Fatalf("derived issuer = %q, want https://lux.id", cfg.IAMIssuer)
+	}
+	if cfg.Brand != "lux" {
+		t.Fatalf("brand = %q, want lux", cfg.Brand)
+	}
+}

build.go

@@ -1,11 +1,20 @@
 package cloud
 
 import (
+	"context"
 	"fmt"
+	"os"
+	"strings"
 
+	aiobject "github.com/hanzoai/ai/object"
+	"github.com/hanzoai/cloud/clients/commerce/metering"
+	"github.com/hanzoai/cloud/clients/commerceinproc"
 	luxlog "github.com/luxfi/log"
+	"github.com/zap-proto/zip"
 
 	"github.com/hanzoai/cloud/clients"
+	"github.com/hanzoai/cloud/clients/gatewaypolicy"
+	"github.com/hanzoai/cloud/clients/s3admin"
 )
 
 // BuildDeps constructs the Deps used by every subsystem's Mount(app, deps).
@@ -33,7 +42,7 @@ import (
 // JSON does not appear in any of these paths. Inter-subsystem calls
 // are ZAP-typed Go values either via direct method dispatch (mode 1)
 // or via ZAP RPC over the wire (mode 2). JSON happens only at the
-// gateway/ingress edge, through the hanzoai/zip jsonenc helper.
+// gateway/ingress edge, through the zip jsonenc helper.
 //
 // Payments and Vault are special: they are NEVER in-process per
 // HIP-0106 solo-vault CDE. Their clients always resolve via
@@ -41,57 +50,213 @@ import (
 // when no endpoint is configured.
 func BuildDeps(cfg *Config) Deps {
 	logger := luxlog.New("cloud")
-	logger.Info("building deps",
+	logger.Info(
+		"building deps",
 		"brand", cfg.Brand,
 		"domain", cfg.Domain,
+		"iam_issuer", cfg.IAMIssuer,
 		"data_dir", cfg.DataDir,
 		"enabled", cfg.Enable,
 	)
 
 	deps := Deps{
-		Logger:  logger,
-		Brand:   cfg.Brand,
-		Domain:  cfg.Domain,
-		DataDir: cfg.DataDir,
+		Logger:         logger,
+		Brand:          cfg.Brand,
+		Env:            cfg.Env,
+		Domain:         cfg.Domain,
+		IAMIssuer:      cfg.IAMIssuer,
+		DataDir:        cfg.DataDir,
+		AIDefaultModel: cfg.AIDefaultModel,
 	}
 
 	// For each subsystem: enabled → leave nil (Mount fills it); not
 	// enabled + endpoint → RPC client; not enabled + no endpoint →
-	// disabled stub.
-	deps.IAM = pickIAMClient(cfg, logger)
+	// disabled stub. The plain co-resident-or-RPC-or-disabled clients share
+	// ONE resolver (pick); KMS/AI/VFS keep bespoke pickers because their
+	// construction genuinely differs (embedded store / gateway preference /
+	// S3-admin backend). O11y's disabled stub is a no-op (telemetry going
+	// nowhere is normal), not fail-closed.
+	deps.IAM = pick(cfg, logger, "iam", "IAM", cfg.IAMZAPAddr, clients.IAMRPCAt, clients.DisabledIAM)
 	deps.KMS = pickKMSClient(cfg, logger)
-	deps.Base = pickBaseClient(cfg, logger)
+	deps.Base = pick(cfg, logger, "base", "Base", cfg.BaseZAPAddr, clients.BaseRPCAt, clients.DisabledBase)
 	deps.Commerce = pickCommerceClient(cfg, logger)
-	deps.AI = pickAIClient(cfg, logger)
-	deps.O11y = pickO11yClient(cfg, logger)
+	// Metering client BEFORE the AI client: deps.AI is wrapped in the metering
+	// decorator (the ONE inference gate+meter — no exempt path, no bypass, no
+	// side-channel key), which needs deps.Metering. nil-safe — an unconfigured
+	// commerce URL yields a !Enabled() client, so the wrap is a transparent
+	// pass-through and a dev deployment is never blocked.
+	deps.Metering = buildMeteringClient(cfg, logger)
+	deps.AI = meteredAIClient(pickAIClient(cfg, logger), deps)
+	wireAIPrepaidGate(cfg, logger)
+	deps.O11y = pick(cfg, logger, "o11y", "O11y", cfg.O11yZAPAddr, clients.O11yRPCAt, clients.DisabledO11y)
 	deps.VFS = pickVFSClient(cfg, logger)
-	deps.MQ = pickMQClient(cfg, logger)
+	deps.MQ = pick(cfg, logger, "mq", "MQ", cfg.MQZAPAddr, clients.MQRPCAt, clients.DisabledMQ)
 
 	// Payments and Vault never co-resident. Disabled stub when no
 	// endpoint, otherwise RPC.
 	deps.Payments = pickPaymentsClient(cfg, logger)
 	deps.Vault = pickVaultClient(cfg, logger)
 
+	// Runtime-mutable edge-policy store (/v1/gateway config plane), layered over
+	// the static env/flag defaults so an un-provisioned deployment behaves exactly
+	// as the static config until an operator PUTs an override. New always returns a
+	// working *Store (static-only if the SQLite file can't open), so the edge
+	// middleware is never left without a policy source — a store-open error is
+	// logged, not fatal.
+	gp, err := gatewaypolicy.New(cfg.DataDir, cfg.AdminOrg, staticEdgePolicy(cfg))
+	if err != nil {
+		logger.Warn("gateway policy store degraded to static-only", "err", err)
+	}
+	deps.GatewayPolicy = gp
+
 	return deps
 }
 
-// pickIAMClient returns the canonical IAMClient for this process.
-// nil = enabled here, Mount will fill it. RPC = remote endpoint
-// configured. Disabled = not enabled, no endpoint.
-func pickIAMClient(cfg *Config, log luxlog.Logger) IAMClient {
-	if cfg.Enabled("iam") {
-		return nil
+// staticEdgePolicy projects the static env/flag edge config into the boot-default
+// policy the gatewaypolicy.Store layers runtime overrides on top of. A disabled
+// per-IP limiter (CLOUD_EDGE_RATELIMIT=false) maps to PerIPRPM 0 (a live no-op).
+func staticEdgePolicy(cfg *Config) gatewaypolicy.Policy {
+	p := gatewaypolicy.Policy{
+		CORSOrigins: cfg.CORSOrigins,
+		WindowSec:   cfg.EdgeRateWindowSec,
 	}
-	if cfg.IAMZAPAddr != "" {
-		log.Info("deps.IAM → ZAP RPC", "addr", cfg.IAMZAPAddr)
-		return clients.IAMRPCAt(cfg.IAMZAPAddr)
+	if cfg.EdgeRateEnabled {
+		p.PerIPRPM = cfg.EdgeRatePerIP
 	}
-	return clients.DisabledIAM()
+	return p
 }
 
+// buildMeteringClient constructs the commerce metering client for BillingGate —
+// the request-edge debit on every paid AI call.
+//
+// CO-RESIDENT (task #111): when commerce is folded in-process (Enabled("commerce")),
+// the gate DEBITS the in-process commerce handler over commerceinproc's self-routing
+// transport — a direct Go call, no socket to commerce.hanzo.svc:8001. The base is
+// pinned NON-EMPTY (real CLOUD_COMMERCE_HTTP_URL, else the in-process placeholder) so
+// the gate stays ENABLED even after the standalone + its env are retired — a metering
+// gate that silently no-ops is a free-money hole, so it must never drop to
+// "not configured" while commerce is co-resident. The transport resolves the handler
+// lazily (published by commerce.Mount before any request), so building the client
+// here (pre-MountAll) is fine.
+//
+// SPLIT-DEPLOY (unchanged): without co-residency an empty CommerceHTTPURL yields a
+// not-Enabled() client (allow + no-op) and a set one speaks plain HTTP to the
+// standalone, exactly as before. The token is KMS-sourced; never logged.
+func buildMeteringClient(cfg *Config, log luxlog.Logger) *metering.Client {
+	base := cfg.CommerceHTTPURL
+	var httpClient metering.HTTPDoer
+	inProcess := cfg.Enabled("commerce")
+	if inProcess {
+		if base == "" {
+			base = commerceinproc.PlaceholderBase
+		}
+		httpClient = commerceinproc.Client(0) // in-process dispatch; no network timeout
+	}
+	m, err := metering.New(metering.Config{
+		BaseURL:    base,
+		Token:      cfg.CommerceServiceToken,
+		Org:        cfg.Brand, // X-Org-Id default for S2S; per-request org overrides.
+		FailOpen:   cfg.BillingFailOpen,
+		HTTPClient: httpClient, // nil off the co-resident path → metering builds its own
+	})
+	if err != nil {
+		// Only an unparseable URL reaches here. Fall back to a not-configured
+		// client (no-op gate) rather than failing boot over billing wiring.
+		log.Error("billing: invalid commerce URL, gate disabled", "err", err)
+		m, _ = metering.New(metering.Config{})
+	}
+	if m.Enabled() {
+		log.Info("billing gate enabled", "commerce", boolStr(inProcess, "in-process", "http:"+base), "fail_open", cfg.BillingFailOpen)
+	} else {
+		log.Info("billing gate disabled (no commerce URL)")
+	}
+	return m
+}
+
+func boolStr(b bool, t, f string) string {
+	if b {
+		return t
+	}
+	return f
+}
+
+// wireAIPrepaidGate routes the embedded ai router's PREPAID balance gate + usage
+// debit to the co-resident commerce handler: the SAME self-routing transport the
+// metering client uses (service-token, in-process, no socket) — so the ai gate
+// reads and debits the ONE commerce ledger the rest of the platform bills, WITHOUT
+// hitting the public customer billing proxy (which 401s a service token). The ai
+// module reads commerceEndpoint/commerceToken from env (conf.GetConfigString); when
+// commerce is co-resident, self-configure them to the in-process placeholder so no
+// CR env is required for the ai gate to work. There is NO exempt path in the ai gate
+// (hanzoai/ai >= v1.805.7): every principal is gated on a positive prepaid balance,
+// fail-closed. MUST run before ai.Mount — InitBalanceGate builds its client once at
+// mount — which BuildDeps guarantees (deps are built before MountAll).
+func wireAIPrepaidGate(cfg *Config, log luxlog.Logger) {
+	if !cfg.Enabled("commerce") {
+		// Split-deploy: the ai module speaks real HTTP to its own commerceEndpoint
+		// (the standalone commerce), unchanged — no in-process transport.
+		return
+	}
+	aiobject.CommerceTransport = commerceinproc.Transport()
+	if os.Getenv("commerceEndpoint") == "" {
+		_ = os.Setenv("commerceEndpoint", commerceinproc.PlaceholderBase)
+	}
+	if os.Getenv("commerceToken") == "" && cfg.CommerceServiceToken != "" {
+		_ = os.Setenv("commerceToken", cfg.CommerceServiceToken)
+	}
+	log.Info("ai prepaid gate wired to in-process commerce (no exempt, fail-closed)",
+		"commerceEndpoint", os.Getenv("commerceEndpoint"))
+}
+
+// pick resolves one inter-subsystem client under the HIP-0106 wiring rule shared
+// by every co-resident-capable dependency: enabled in THIS process → zero value
+// (nil) so the subsystem's own Mount installs the in-process client; not enabled
+// but a ZAP endpoint is configured → an RPC client at that endpoint; neither →
+// the fail-closed/no-op disabled stub. name is the enable-list id; label is the
+// deps.<X> log tag; rpc/disabled are the client's typed constructors. This is the
+// ONE implementation of that rule — KMS/AI/VFS opt out with bespoke pickers only
+// because their construction genuinely differs.
+func pick[T any](cfg *Config, log luxlog.Logger, name, label, zapAddr string, rpc func(string) T, disabled func() T) T {
+	if cfg.Enabled(name) {
+		var zero T // enabled here → Mount fills deps.<label>
+		return zero
+	}
+	if zapAddr != "" {
+		log.Info("deps."+label+" → ZAP RPC", "addr", zapAddr)
+		return rpc(zapAddr)
+	}
+	return disabled()
+}
+
+// pickKMSClient resolves deps.KMS. When the kms subsystem is co-resident
+// (Enabled("kms")) it returns the IN-PROCESS Client backed by the embedded
+// luxfi/kms SecretStore under CLOUD_DATA_DIR — no external RPC. A store-open
+// failure is NOT fatal to the whole binary: it falls back to the disabled stub
+// (fail-closed) and logs, so a bad data dir degrades KMS rather than crashing
+// every subsystem. Absent co-residency the legacy ZAP-RPC + disabled fallbacks
+// apply (out-of-process KMS, or not wired).
+//
+// The subsystem id is "kms" (clients/kms registers it with cloud.HealthOwner so
+// the generic liveness route never shadows its real /v1/kms/health, and registers
+// the client factory this gate calls); this gate keys on the same id so "enabled"
+// is one concept.
 func pickKMSClient(cfg *Config, log luxlog.Logger) KMSClient {
 	if cfg.Enabled("kms") {
-		return nil
+		// The embedded-client constructor is registered by clients/kms in init()
+		// (RegisterKMSClientFactory). cloud never imports clients/kms, so the KMS
+		// library and its /v1/kms subsystem live in one package with no cloud⇄kms
+		// import cycle. Absent the registration (clients/kms not linked into this
+		// binary) KMS fails closed rather than pretending to host secrets.
+		if kmsClientFactory == nil {
+			log.Error("deps.KMS: kms enabled but no client factory registered (clients/kms not linked); failing closed")
+			return clients.DisabledKMS()
+		}
+		c, err := kmsClientFactory(cfg, log)
+		if err != nil {
+			log.Error("deps.KMS: embedded KMS unavailable, failing closed", "err", err)
+			return clients.DisabledKMS()
+		}
+		return c
 	}
 	if cfg.KMSZAPAddr != "" {
 		log.Info("deps.KMS → ZAP RPC", "addr", cfg.KMSZAPAddr)
@@ -100,20 +265,83 @@ func pickKMSClient(cfg *Config, log luxlog.Logger) KMSClient {
 	return clients.DisabledKMS()
 }
 
-func pickBaseClient(cfg *Config, log luxlog.Logger) BaseClient {
-	if cfg.Enabled("base") {
-		return nil
-	}
-	if cfg.BaseZAPAddr != "" {
-		log.Info("deps.Base → ZAP RPC", "addr", cfg.BaseZAPAddr)
-		return clients.BaseRPCAt(cfg.BaseZAPAddr)
-	}
-	return clients.DisabledBase()
+// kmsClientFactory constructs the embedded in-process KMS client from cloud
+// Config. clients/kms registers it in init(); pickKMSClient calls it so cloud
+// depends on the KMSClient interface + this hook, never the concrete kms package
+// — the same inversion the subsystem Registry already uses (cloud mounts every
+// subsystem it never imports). Exactly one registration.
+var kmsClientFactory func(cfg *Config, log luxlog.Logger) (KMSClient, error)
+
+// RegisterKMSClientFactory installs the embedded-KMS constructor. clients/kms
+// calls this from its init(); it is the ONE inversion point that lets the KMS
+// library and its /v1/kms subsystem share one package with no cloud⇄kms cycle.
+func RegisterKMSClientFactory(f func(cfg *Config, log luxlog.Logger) (KMSClient, error)) {
+	kmsClientFactory = f
 }
 
+// ---- git-push-to-deploy ----
+
+// GitPushEvent describes a push that just landed on the embedded git server: the
+// org, the repo, the branch that moved, and its new tip commit. CloneURL is the
+// canonical clone URL of that repo (https://<host>/v1/git/<org>/<repo>.git) — the
+// exact value an Application's RepoURL carries — so the builder can resolve which
+// app (if any) tracks this branch and needs a rebuild.
+type GitPushEvent struct {
+	Org      string
+	Project  string
+	Repo     string
+	Branch   string
+	Commit   string
+	CloneURL string
+}
+
+// pushBuilder is the registered git-push-to-deploy trigger. clients/platform
+// installs it in Mount; clients/git calls OnGitPush after a push lands. The
+// inversion keeps git⇄platform decoupled — git never imports platform — exactly
+// like kmsClientFactory and the subsystem Registry. Exactly one registration.
+var pushBuilder func(ctx context.Context, ev GitPushEvent) error
+
+// RegisterPushBuilder installs the git-push-to-deploy trigger. clients/platform
+// calls this from its Mount when co-resident; it is the ONE inversion point that
+// lets the embedded git server launch a platform build with no git⇄platform cycle.
+func RegisterPushBuilder(f func(ctx context.Context, ev GitPushEvent) error) {
+	pushBuilder = f
+}
+
+// OnGitPush fires the registered push-to-deploy trigger for a landed push. It is a
+// no-op when no builder is registered (git server running without the platform
+// subsystem co-resident). Best-effort by contract: the caller must never fail the
+// push the client already committed just because a build could not be triggered.
+func OnGitPush(ctx context.Context, ev GitPushEvent) error {
+	if pushBuilder == nil {
+		return nil
+	}
+	return pushBuilder(ctx, ev)
+}
+
+// pickCommerceClient resolves deps.Commerce — the typed inter-subsystem client the
+// entitlements/licensing tier calls (GetOrgConfig, CheckEntitlement). When the
+// commerce subsystem is co-resident (Enabled("commerce")) it returns the IN-PROCESS
+// client via the factory clients/commerce registers in init() — a direct Go call
+// that reads the embedded commerce datastore + the @hanzo/plans vocabulary, no
+// network hop (the HIP-0106 co-resident default). cloud never imports clients/commerce,
+// so the commerce library, its /v1/commerce subsystem, and this client share ONE
+// package with no cloud⇄commerce cycle — the same inversion KMS uses. Absent the
+// registration (clients/commerce not linked) it fails closed rather than pretending.
+//
+// NETWORK PATH PRESERVED: absent co-residency the ZAP-RPC + disabled fallbacks apply
+// (out-of-process commerce, or not wired), so the remote proxy seam
+// (CLOUD_COMMERCE_ZAP_ADDR) is unchanged — this fold does NOT force the in-process
+// cutover; the live default still selects the network client when commerce is not
+// enabled in this process.
 func pickCommerceClient(cfg *Config, log luxlog.Logger) CommerceClient {
 	if cfg.Enabled("commerce") {
-		return nil
+		if commerceClientFactory == nil {
+			log.Error("deps.Commerce: commerce enabled but no client factory registered (clients/commerce not linked); failing closed")
+			return clients.DisabledCommerce()
+		}
+		log.Info("deps.Commerce → in-process (embedded commerce)", "brand", cfg.Brand)
+		return commerceClientFactory(cfg, log)
 	}
 	if cfg.CommerceZAPAddr != "" {
 		log.Info("deps.Commerce → ZAP RPC", "addr", cfg.CommerceZAPAddr)
@@ -122,52 +350,116 @@ func pickCommerceClient(cfg *Config, log luxlog.Logger) CommerceClient {
 	return clients.DisabledCommerce()
 }
 
+// commerceClientFactory constructs the embedded in-process Commerce client from
+// cloud Config. clients/commerce registers it in init(); pickCommerceClient calls it
+// so cloud depends on the CommerceClient interface + this hook, never the concrete
+// commerce package — the same inversion KMS + the subsystem Registry use. Exactly
+// one registration.
+var commerceClientFactory func(cfg *Config, log luxlog.Logger) CommerceClient
+
+// RegisterCommerceClientFactory installs the embedded-Commerce client constructor.
+// clients/commerce calls this from its init(); it is the ONE inversion point that
+// lets the commerce library and its /v1/commerce subsystem share one package with no
+// cloud⇄commerce cycle.
+func RegisterCommerceClientFactory(f func(cfg *Config, log luxlog.Logger) CommerceClient) {
+	commerceClientFactory = f
+}
+
+// pickAIClient resolves deps.AI — the client the agents subsystem runs chat
+// completions through. Unlike the co-resident subsystems, there is NO in-process
+// "ai" mount that fills a nil deps.AI: inference is an external gateway, so this
+// must return a concrete client, never nil. (A nil deps.AI was the live bug —
+// the default all-enabled config returned nil here and nothing ever filled it,
+// so every /v1/agents/:name/run 503'd "inference is not configured".)
+//
+// Preference order:
+//  1. Static-key HTTP gateway when a base URL AND a static key are configured —
+//     an operator override / pre-provisioned key. The key is a KMS-injected
+//     secret; only the base URL and default model are ever logged.
+//  2. M2M HTTP gateway when a base URL AND the binary's IAM identity are present
+//     (the durable Hanzo default): the client mints+refreshes a client-
+//     credentials token from IAM_CLIENT_ID/SECRET — no static key to rotate. The
+//     secret is never logged.
+//  3. ZAP RPC when an addr is configured (split-deploy of a future ai subsystem).
+//  4. Fail-closed stub otherwise — a run records an honest error, never fakes one.
 func pickAIClient(cfg *Config, log luxlog.Logger) AIClient {
-	if cfg.Enabled("ai") {
-		return nil
+	if cfg.AIBaseURL != "" && cfg.AIAPIKey != "" {
+		log.Info("deps.AI → HTTP gateway (static key)", "base_url", cfg.AIBaseURL, "default_model", cfg.AIDefaultModel)
+		return clients.AIHTTPAt(cfg.AIBaseURL, cfg.AIAPIKey, cfg.AIDefaultModel)
+	}
+	if cfg.AIBaseURL != "" && cfg.AIAuthClientID != "" && cfg.AIAuthClientSecret != "" {
+		tokenURL := aiM2MTokenURL(cfg)
+		if tokenURL != "" {
+			log.Info("deps.AI → HTTP gateway (IAM M2M)", "base_url", cfg.AIBaseURL,
+				"token_url", tokenURL, "client_id", cfg.AIAuthClientID, "default_model", cfg.AIDefaultModel)
+			return clients.AIHTTPM2M(cfg.AIBaseURL, tokenURL, cfg.AIAuthClientID, cfg.AIAuthClientSecret, cfg.AIDefaultModel)
+		}
 	}
 	if cfg.AIZAPAddr != "" {
 		log.Info("deps.AI → ZAP RPC", "addr", cfg.AIZAPAddr)
 		return clients.AIRPCAt(cfg.AIZAPAddr)
 	}
+	log.Info("deps.AI → disabled (no CLOUD_AI_API_KEY, no IAM M2M identity, no gateway configured)")
 	return clients.DisabledAI()
 }
 
-func pickO11yClient(cfg *Config, log luxlog.Logger) O11yClient {
-	if cfg.Enabled("o11y") {
-		return nil
+// aiM2MTokenURL resolves IAM's client_credentials endpoint the agent runner mints
+// its M2M inference token at. It MUST be reachable FROM INSIDE THE CLUSTER: the
+// runner runs in-cluster and the public issuer host (https://hanzo.id) is fronted
+// by Cloudflare, which 403s a server-side (non-browser) loopback POST with edge
+// error 1006 — so minting against the PUBLIC issuer URL fails and every
+// POST /v1/agents/:ref/run 502s (root-caused 2026-07-04: in-cluster POST to
+// https://hanzo.id/v1/iam/oauth/token → 403/1006, while http://iam.hanzo.svc/... → 200).
+// This mirrors the KMS login-broker resolution (clients/kms) exactly — one
+// split-horizon policy, no drift. Prefer, in order: an explicit override
+// (CLOUD_AI_IAM_TOKEN_URL), the in-cluster IAM service base (IAM_URL — already
+// wired to http://iam.hanzo.svc for JWKS), then the public issuer as a last resort
+// (single-process / no split-horizon deploys). Returns "" only when no identity is
+// resolvable, which keeps the M2M branch off (caller falls through to the stub).
+func aiM2MTokenURL(cfg *Config) string {
+	if override := strings.TrimSpace(os.Getenv("CLOUD_AI_IAM_TOKEN_URL")); override != "" {
+		return override
 	}
-	if cfg.O11yZAPAddr != "" {
-		log.Info("deps.O11y → ZAP RPC", "addr", cfg.O11yZAPAddr)
-		return clients.O11yRPCAt(cfg.O11yZAPAddr)
+	if base := strings.TrimRight(strings.TrimSpace(os.Getenv("IAM_URL")), "/"); base != "" {
+		return base + "/v1/iam/oauth/token"
 	}
-	// O11y disabled-stub is no-op (not fail-closed) — telemetry
-	// going nowhere is a normal mode.
-	return clients.DisabledO11y()
+	if iss := strings.TrimRight(strings.TrimSpace(cfg.IAMIssuer), "/"); iss != "" {
+		return iss + "/v1/iam/oauth/token"
+	}
+	return ""
 }
 
 func pickVFSClient(cfg *Config, log luxlog.Logger) VFSClient {
-	if cfg.Enabled("vfs") {
-		return nil
-	}
+	// deps.VFS must NEVER be nil (R-7): files.go and any other VFS consumer call
+	// s.vfs.Put/Get/Delete unconditionally, so a nil here is a per-request 500
+	// (dishonest degradation) instead of a fail-closed 502. Unlike the
+	// nil-then-Mount-fills convention other subsystems use, nothing fills deps.VFS
+	// after MountAll (Mount receives deps by value), so we ALWAYS hand back a
+	// concrete client.
 	if cfg.VFSZAPAddr != "" {
 		log.Info("deps.VFS → ZAP RPC", "addr", cfg.VFSZAPAddr)
 		return clients.VFSRPCAt(cfg.VFSZAPAddr)
 	}
+	// Real blob backend (.97): the shared SeaweedFS S3 gateway — the canonical,
+	// key-based object store, reached with the SAME S3_ADMIN_* admin identity
+	// clients/s3 uses (s3admin, one construction). Present only when those creds
+	// are injected; a construction failure degrades to fail-closed rather than a
+	// nil deref. Team blobs (avatars/attachments) round-trip through this to the
+	// team-blobs bucket, org-scoped by the caller-built key prefix.
+	if admin := s3admin.New(); admin.Configured() {
+		v, err := clients.NewS3VFS(admin)
+		if err != nil {
+			log.Error("deps.VFS → S3 construction failed; falling back to fail-closed", "err", err)
+			return clients.DisabledVFS()
+		}
+		log.Info("deps.VFS → SeaweedFS S3", "bucket", clients.TeamBlobBucket)
+		return v
+	}
+	// No VFS endpoint and no S3 admin creds → fail-closed stub (R-7): Put/Get/Delete
+	// return a non-nil error → files answer 502, never a nil-deref 500.
 	return clients.DisabledVFS()
 }
 
-func pickMQClient(cfg *Config, log luxlog.Logger) MQClient {
-	if cfg.Enabled("mq") {
-		return nil
-	}
-	if cfg.MQZAPAddr != "" {
-		log.Info("deps.MQ → ZAP RPC", "addr", cfg.MQZAPAddr)
-		return clients.MQRPCAt(cfg.MQZAPAddr)
-	}
-	return clients.DisabledMQ()
-}
-
 func pickPaymentsClient(cfg *Config, log luxlog.Logger) PaymentsClient {
 	if cfg.PaymentsZAPAddr != "" {
 		log.Info("deps.Payments → ZAP RPC", "addr", cfg.PaymentsZAPAddr)
@@ -184,45 +476,67 @@ func pickVaultClient(cfg *Config, log luxlog.Logger) VaultClient {
 	return clients.DisabledVault()
 }
 
-// MountFunc is the canonical signature every subsystem exposes per
-// HIP-0106. Each Hanzo Go service ships a top-level `Mount` symbol
-// matching this signature; cmd/cloud/main.go imports the package and
-// calls it.
-type MountFunc func(app any, deps Deps) error // app is *zip.App; using any here to avoid an import cycle in pkg/cloud
+// MountFunc is a subsystem's mount contract. app is `any`, not *zip.App, and that
+// is load-bearing: some external modules expose Mount as func(any, Deps) error
+// (e.g. hanzoai/licensing), which subsystems.Wire references DIRECTLY — a
+// func(any,…) value is not assignable to a func(*zip.App,…) parameter, so
+// narrowing the type would break them at compile time. The concrete value is
+// always a *zip.App; strongly-typed Mounts (func(*zip.App, Deps) error, what every
+// in-repo subsystem exports) are adapted by Typed, which recovers it in ONE place.
+type MountFunc func(app any, deps Deps) error
 
-// MountSpec describes one subsystem registered for mounting. The Order
-// is used when ordering matters for inter-subsystem deps (e.g. iam
-// before authz before commerce).
-type MountSpec struct {
-	Name  string
-	Order int
-	Mount MountFunc
-}
-
-// Registry is the in-process subsystem registry. Subsystems register via
-// init() functions in their respective packages OR cmd/cloud/main.go can
-// explicitly enumerate them. Either pattern works.
-var Registry []MountSpec
-
-// Register adds a subsystem to the in-process registry.
-func Register(name string, order int, mount MountFunc) {
-	Registry = append(Registry, MountSpec{Name: name, Order: order, Mount: mount})
-}
-
-// MountAll iterates the registry in order and calls Mount() on each
-// enabled subsystem.
-func MountAll(app any, cfg *Config, deps Deps) error {
-	// Sort registry by order — bubble sort, registry is tiny.
-	for i := 0; i < len(Registry); i++ {
-		for j := i + 1; j < len(Registry); j++ {
-			if Registry[j].Order < Registry[i].Order {
-				Registry[i], Registry[j] = Registry[j], Registry[i]
-			}
+// Typed adapts a strongly-typed subsystem Mount — func(*zip.App, Deps) error,
+// the signature every in-repo subsystem already exports — into the registry's
+// MountFunc. It performs the *zip.App recovery in ONE place, fail-closed with a
+// clear error, so no subsystem repeats the `a, ok := app.(*zip.App)` boilerplate.
+// The concrete value MountAll passes is always a *zip.App, so the assertion is
+// total in practice; it stays as a defensive, self-documenting guard.
+func Typed(mount func(*zip.App, Deps) error) MountFunc {
+	return func(app any, deps Deps) error {
+		a, ok := app.(*zip.App)
+		if !ok {
+			return fmt.Errorf("cloud.Mount: app is %T, want *zip.App", app)
 		}
+		return mount(a, deps)
 	}
+}
 
+// ShutdownFunc releases a subsystem's process-lifetime resources (background
+// goroutines, open DB handles) on graceful shutdown. It must be idempotent and
+// bounded — Serve calls it within the shutdown deadline. ctx carries that
+// deadline so a slow teardown is cut off rather than hanging SIGTERM.
+type ShutdownFunc func(ctx context.Context) error
+
+// MountSpec describes one subsystem to mount. There is NO Order field: the slice
+// position in subsystems.Wire() IS the mount order — the composition root lists
+// subsystems in the exact sequence they mount (and, reversed, tear down), so order
+// is data read top-to-bottom in one file, not ints scattered across the tree.
+type MountSpec struct {
+	Name     string
+	Mount    MountFunc
+	Shutdown ShutdownFunc // optional; nil means the subsystem has nothing to tear down.
+
+	// OwnsHealth marks a subsystem that serves its OWN GET /v1/<name>/health
+	// (a real, fail-closed probe). Serve's generic liveness loop skips these so
+	// its always-ok route never shadows the subsystem's real probe.
+	OwnsHealth bool
+}
+
+// MountAll mounts every ENABLED subsystem in specs, in slice order — the order is
+// the composition root's (subsystems.Wire()); MountAll does NOT sort. app is the
+// concrete *zip.App from Serve; the MountFunc accepts it as `any` and in-repo
+// subsystems recover it via Typed.
+//
+// Teardown is wired HERE, at mount time: right after a subsystem mounts, its
+// ShutdownFunc (if any) is registered via app.OnShutdown. zip drains those hooks
+// LIFO — AFTER the listeners stop accepting and in-flight requests drain — so
+// registration-at-mount yields reverse-mount teardown (a dependency mounted before
+// its dependents is torn down after them) with no subsystem torn down while a
+// request still uses it. Only ENABLED specs mount, so only they register a hook;
+// teardown needs no separate enablement gate.
+func MountAll(app *zip.App, specs []MountSpec, cfg *Config, deps Deps) error {
 	logger := deps.Logger
-	for _, spec := range Registry {
+	for _, spec := range specs {
 		if !cfg.Enabled(spec.Name) {
 			logger.Debug("subsystem disabled", "name", spec.Name)
 			continue
@@ -230,6 +544,12 @@ func MountAll(app any, cfg *Config, deps Deps) error {
 		if err := spec.Mount(app, deps); err != nil {
 			return fmt.Errorf("mount %s: %w", spec.Name, err)
 		}
+		// Register teardown as a zip shutdown hook. zip runs hooks LIFO after the
+		// drain (zip.App.Shutdown), so this reproduces the reverse-mount order the
+		// hand-rolled reverse-loop gave — without the teardown-before-drain race.
+		if spec.Shutdown != nil {
+			app.OnShutdown(spec.Shutdown)
+		}
 		logger.Info("mounted subsystem", "name", spec.Name)
 	}
 	return nil

build_aitoken_internal_test.go

@@ -0,0 +1,62 @@
+package cloud
+
+import "testing"
+
+// TestAIM2MTokenURL pins the split-horizon resolution order for the agent-runner
+// M2M token endpoint (the GAP that 502'd every POST /v1/agents/:ref/run: the
+// public issuer host is Cloudflare-fronted and 403s an in-cluster loopback with
+// edge error 1006). The runner must mint its token from an IN-CLUSTER URL. Order:
+// explicit override → in-cluster IAM_URL → public IAMIssuer fallback.
+func TestAIM2MTokenURL(t *testing.T) {
+	const tokenPath = "/v1/iam/oauth/token"
+
+	cases := []struct {
+		name      string
+		override  string // CLOUD_AI_IAM_TOKEN_URL
+		iamURL    string // IAM_URL
+		iamIssuer string // cfg.IAMIssuer
+		want      string
+	}{
+		{
+			name:     "explicit override wins over everything",
+			override: "http://iam.internal:1234/custom/token",
+			iamURL:   "http://iam.hanzo.svc",
+			// even a public issuer present must not be chosen
+			iamIssuer: "https://hanzo.id",
+			want:      "http://iam.internal:1234/custom/token",
+		},
+		{
+			name:      "in-cluster IAM_URL preferred over public issuer",
+			iamURL:    "http://iam.hanzo.svc",
+			iamIssuer: "https://hanzo.id",
+			want:      "http://iam.hanzo.svc" + tokenPath,
+		},
+		{
+			name:      "trailing slash on IAM_URL is trimmed",
+			iamURL:    "http://iam.hanzo.svc/",
+			iamIssuer: "https://hanzo.id",
+			want:      "http://iam.hanzo.svc" + tokenPath,
+		},
+		{
+			name:      "falls back to public issuer only when no in-cluster URL",
+			iamIssuer: "https://hanzo.id",
+			want:      "https://hanzo.id" + tokenPath,
+		},
+		{
+			name: "empty when no identity is resolvable (keeps M2M branch off)",
+			want: "",
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			// t.Setenv restores prior values + prevents parallel interference.
+			t.Setenv("CLOUD_AI_IAM_TOKEN_URL", tc.override)
+			t.Setenv("IAM_URL", tc.iamURL)
+			cfg := &Config{IAMIssuer: tc.iamIssuer}
+			if got := aiM2MTokenURL(cfg); got != tc.want {
+				t.Fatalf("aiM2MTokenURL() = %q, want %q", got, tc.want)
+			}
+		})
+	}
+}

build_onshutdown_test.go

@@ -0,0 +1,203 @@
+package cloud_test
+
+import (
+	"context"
+	"net"
+	"net/http"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/hanzoai/cloud"
+	luxlog "github.com/luxfi/log"
+	"github.com/zap-proto/zip"
+)
+
+// noopMount mounts nothing: the fake specs below carry the behavior under test in
+// their Shutdown, not their Mount.
+func noopMount(any, cloud.Deps) error { return nil }
+
+// freeAddr reserves an ephemeral loopback port and hands back its address; the
+// listener is closed so the app under test can bind it.
+func freeAddr(t *testing.T) string {
+	t.Helper()
+	ln, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatalf("reserve port: %v", err)
+	}
+	addr := ln.Addr().String()
+	_ = ln.Close()
+	return addr
+}
+
+// waitListening blocks until addr accepts a TCP connection (the app's Listen
+// goroutine has bound it) or a short deadline elapses.
+func waitListening(t *testing.T, addr string) {
+	t.Helper()
+	deadline := time.Now().Add(3 * time.Second)
+	for time.Now().Before(deadline) {
+		if c, err := net.DialTimeout("tcp", addr, 100*time.Millisecond); err == nil {
+			_ = c.Close()
+			return
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+	t.Fatalf("server never listened on %s", addr)
+}
+
+// TestMountAll_ShutdownHooksLIFOAfterDrain proves the OnShutdown teardown wiring:
+// MountAll registers each ENABLED subsystem's ShutdownFunc as a zip shutdown hook,
+// so on app.Shutdown they run (1) AFTER in-flight requests drain and (2) LIFO =
+// reverse-mount order (a dependency mounted before its dependents is torn down
+// after them). That is exactly the contract the deleted hand-rolled reverse-loop
+// provided by hand — now owned by zip, minus the teardown-before-drain race.
+func TestMountAll_ShutdownHooksLIFOAfterDrain(t *testing.T) {
+	app := zip.New(zip.Config{Logger: luxlog.NewNoOpLogger(), DisableStartupMessage: true})
+
+	// One monotonic tick stamps the ONLY two kinds of event we order against each
+	// other: the in-flight request finishing its drain, and each teardown hook.
+	var tick atomic.Int64
+	var mu sync.Mutex
+	teardown := map[string]int64{}
+	record := func(name string) cloud.ShutdownFunc {
+		return func(context.Context) error {
+			mu.Lock()
+			teardown[name] = tick.Add(1)
+			mu.Unlock()
+			return nil
+		}
+	}
+
+	// Mount order a, b, c ⇒ LIFO teardown must be c, b, a.
+	specs := []cloud.MountSpec{
+		{Name: "a", Mount: noopMount, Shutdown: record("a")},
+		{Name: "b", Mount: noopMount, Shutdown: record("b")},
+		{Name: "c", Mount: noopMount, Shutdown: record("c")},
+	}
+	cfg := &cloud.Config{Enable: []string{"a", "b", "c"}}
+	deps := cloud.Deps{Logger: luxlog.NewNoOpLogger()}
+
+	// A request that parks inside its handler until released, so the shutdown drain
+	// has something real to wait on. Its drain tick is stamped the instant the
+	// handler returns — i.e. the moment this request finishes draining.
+	entered := make(chan struct{})
+	release := make(chan struct{})
+	var drainTick int64
+	app.Get("/hold", func(c *zip.Ctx) error {
+		close(entered)
+		<-release
+		atomic.StoreInt64(&drainTick, tick.Add(1))
+		return c.JSON(http.StatusOK, map[string]bool{"ok": true})
+	})
+
+	if err := cloud.MountAll(app, specs, cfg, deps); err != nil {
+		t.Fatalf("MountAll: %v", err)
+	}
+
+	// Serve on a real loopback listener: an in-flight request over the HTTP
+	// transport is what zip's shutdown actually drains (closeServers → drain) in
+	// production — the path a listener-less test cannot exercise.
+	addr := freeAddr(t)
+	serveDone := make(chan error, 1)
+	go func() { serveDone <- app.Listen("http://" + addr) }()
+	waitListening(t, addr)
+
+	// Fire the request; it parks mid-handler with the connection held open.
+	reqDone := make(chan struct{})
+	go func() {
+		defer close(reqDone)
+		req, _ := http.NewRequest(http.MethodGet, "http://"+addr+"/hold", nil)
+		req.Close = true // no keep-alive: server drops the conn once the handler returns
+		client := &http.Client{Timeout: 30 * time.Second}
+		if resp, err := client.Do(req); err == nil {
+			_ = resp.Body.Close()
+		}
+	}()
+	<-entered // the request is now in-flight, parked mid-handler
+
+	// Shut down WHILE the request is in-flight. zip stops the listeners accepting,
+	// drains (blocking on our parked handler), THEN runs the hooks LIFO.
+	shutDone := make(chan error, 1)
+	go func() {
+		ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+		defer cancel()
+		shutDone <- app.ShutdownWithContext(ctx)
+	}()
+
+	// Barrier: with a request still in-flight, Shutdown MUST NOT complete — it is
+	// blocked in the drain. If it returns here, teardown ran without waiting for the
+	// drain (the exact race the OnShutdown move fixes).
+	select {
+	case <-shutDone:
+		t.Fatal("Shutdown completed while a request was still in-flight — teardown did not wait for the drain")
+	case <-time.After(150 * time.Millisecond):
+	}
+
+	// Let the handler finish so the drain can complete; hooks fire only after.
+	close(release)
+
+	if err := <-shutDone; err != nil {
+		t.Fatalf("ShutdownWithContext: %v", err)
+	}
+	<-reqDone
+	<-serveDone // Listen returns once the transport listener is closed
+
+	// (1) AFTER THE DRAIN: the in-flight request finished (drainTick) strictly
+	// before ANY teardown hook ran — no hook raced a request still using it.
+	dt := atomic.LoadInt64(&drainTick)
+	if dt == 0 {
+		t.Fatal("in-flight request never drained")
+	}
+	for name, tk := range teardown {
+		if tk < dt {
+			t.Fatalf("hook %q ran at tick %d, before the drain finished at tick %d — teardown raced the still-draining request", name, tk, dt)
+		}
+	}
+
+	// (2) LIFO = reverse mount order: c (mounted last) tears down first, a last.
+	if len(teardown) != 3 {
+		t.Fatalf("want 3 hooks run, got %d (%v)", len(teardown), teardown)
+	}
+	if !(teardown["c"] < teardown["b"] && teardown["b"] < teardown["a"]) {
+		t.Fatalf("teardown not LIFO: a=%d b=%d c=%d (want c<b<a)", teardown["a"], teardown["b"], teardown["c"])
+	}
+}
+
+// TestMountAll_ShutdownRegistration_EnablementAndNil proves MountAll registers a
+// teardown hook ONLY for an ENABLED spec that HAS a ShutdownFunc: a disabled spec
+// never mounts (so never registers a hook), and an enabled spec whose Shutdown is
+// nil is skipped without panicking. This keeps the enablement axis and the nil
+// guard from silently regressing now that teardown moved onto app.OnShutdown.
+func TestMountAll_ShutdownRegistration_EnablementAndNil(t *testing.T) {
+	app := zip.New(zip.Config{Logger: luxlog.NewNoOpLogger(), DisableStartupMessage: true})
+
+	var mu sync.Mutex
+	var ran []string
+	record := func(name string) cloud.ShutdownFunc {
+		return func(context.Context) error {
+			mu.Lock()
+			ran = append(ran, name)
+			mu.Unlock()
+			return nil
+		}
+	}
+
+	specs := []cloud.MountSpec{
+		{Name: "enabled", Mount: noopMount, Shutdown: record("enabled")},
+		{Name: "disabled", Mount: noopMount, Shutdown: record("disabled")},
+		{Name: "nilsd", Mount: noopMount}, // enabled, but no Shutdown
+	}
+	cfg := &cloud.Config{Enable: []string{"enabled", "nilsd"}} // "disabled" omitted
+
+	if err := cloud.MountAll(app, specs, cfg, cloud.Deps{Logger: luxlog.NewNoOpLogger()}); err != nil {
+		t.Fatalf("MountAll: %v", err)
+	}
+	if err := app.Shutdown(); err != nil {
+		t.Fatalf("Shutdown: %v", err)
+	}
+
+	if len(ran) != 1 || ran[0] != "enabled" {
+		t.Fatalf("teardown hooks ran = %v, want [enabled] (disabled never mounts; nil Shutdown skipped)", ran)
+	}
+}

build_registration_test.go

@@ -0,0 +1,49 @@
+package cloud_test
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/hanzoai/cloud"
+	"github.com/zap-proto/zip"
+)
+
+// TestTyped_RecoversZipApp verifies cloud.Typed adapts a strongly-typed
+// func(*zip.App, Deps) into the registry MountFunc: it hands the concrete
+// *zip.App straight through to the wrapped mount.
+func TestTyped_RecoversZipApp(t *testing.T) {
+	app := zip.New(zip.Config{})
+	var got *zip.App
+	mf := cloud.Typed(func(a *zip.App, _ cloud.Deps) error {
+		got = a
+		return nil
+	})
+	if err := mf(app, cloud.Deps{}); err != nil {
+		t.Fatalf("Typed mount returned error: %v", err)
+	}
+	if got != app {
+		t.Fatalf("Typed did not pass the concrete *zip.App through (got %p, want %p)", got, app)
+	}
+}
+
+// TestTyped_WrongTypeFailsClosed verifies cloud.Typed fails closed with a clear
+// error — never a panic — when the registry passes a value that is not a
+// *zip.App. This is the single, central replacement for the per-subsystem
+// assertion boilerplate.
+func TestTyped_WrongTypeFailsClosed(t *testing.T) {
+	called := false
+	mf := cloud.Typed(func(*zip.App, cloud.Deps) error {
+		called = true
+		return nil
+	})
+	err := mf("not-a-zip-app", cloud.Deps{})
+	if err == nil {
+		t.Fatal("Typed must return an error on a non-*zip.App value")
+	}
+	if called {
+		t.Fatal("Typed must NOT invoke the wrapped mount on a type mismatch")
+	}
+	if !strings.Contains(err.Error(), "*zip.App") {
+		t.Errorf("error should name the wanted type *zip.App, got: %v", err)
+	}
+}

build_test.go

@@ -6,25 +6,57 @@ import (
 
 	"github.com/hanzoai/cloud"
 	"github.com/hanzoai/cloud/clients"
+
+	// Blank import registers the kms subsystem's client factory (init) into cloud,
+	// so BuildDeps can build the in-process deps.KMS below. cloud itself never
+	// imports clients/kms (no cloud⇄kms cycle); this external test can.
+	_ "github.com/hanzoai/cloud/clients/kms"
 )
 
-// TestBuildDeps_EnabledLeavesNil verifies that BuildDeps leaves an
-// enabled subsystem's Client field nil — the subsystem Mount() is
-// responsible for filling it in.
+// TestBuildDeps_EnabledLeavesNil verifies that BuildDeps leaves an enabled
+// Mount-fills-it subsystem's Client field nil — the subsystem Mount() installs
+// it. KMS is the exception (see TestBuildDeps_KMSEnabledIsInProcess): it is
+// constructed eagerly in BuildDeps because its store must exist before any
+// dependent subsystem mounts.
 func TestBuildDeps_EnabledLeavesNil(t *testing.T) {
 	cfg := &cloud.Config{
 		Brand:   "hanzo",
 		Domain:  "api.hanzo.ai",
-		DataDir: "/tmp",
-		Enable:  []string{"iam", "kms", "base", "commerce", "ai", "o11y", "vfs", "mq"},
+		DataDir: t.TempDir(),
+		Enable:  []string{"iam", "base", "commerce", "ai", "o11y", "vfs", "mq"},
 	}
 	deps := cloud.BuildDeps(cfg)
 
 	if deps.IAM != nil {
 		t.Errorf("deps.IAM: enabled subsystem must leave Client nil, got %T", deps.IAM)
 	}
-	if deps.KMS != nil {
-		t.Errorf("deps.KMS: enabled subsystem must leave Client nil, got %T", deps.KMS)
+}
+
+// TestBuildDeps_KMSEnabledIsInProcess verifies the HIP-0106 "embed KMS in cloud"
+// contract: when the kms subsystem is enabled, deps.KMS is a live
+// in-process client (never nil, never a disabled stub) so other subsystems get a
+// working KMS via direct Go dispatch with no RPC. Absent a master key it still
+// resolves (health-only, fail-closed) — the point is that deps.KMS is populated.
+func TestBuildDeps_KMSEnabledIsInProcess(t *testing.T) {
+	cfg := &cloud.Config{
+		Brand:   "hanzo",
+		Domain:  "api.hanzo.ai",
+		DataDir: t.TempDir(),
+		Enable:  []string{"kms"},
+	}
+	deps := cloud.BuildDeps(cfg)
+
+	if deps.KMS == nil {
+		t.Fatal("deps.KMS: enabled kms must give an in-process client, got nil")
+	}
+	// It must NOT be the fail-closed disabled stub — that stub returns IsDisabled
+	// errors; an in-process client (no master key) returns a master-key error.
+	_, err := deps.KMS.GetSecret(context.Background(), "any")
+	if err == nil {
+		t.Fatal("GetSecret with no master key must fail closed")
+	}
+	if clients.IsDisabled(err) {
+		t.Errorf("deps.KMS resolved to the DISABLED stub, want the in-process client: %v", err)
 	}
 }
 

cek/cek.go

@@ -0,0 +1,830 @@
+// Package cek is cloud's ONE encryption-at-rest gate for its per-subsystem
+// SQLite stores. Every store opens its database through cek.Open — the single
+// seam where a plaintext file is transparently migrated to SQLCipher and a keyed
+// *sql.DB is returned — so "encrypted at rest" is a property of the open path,
+// not something each of the ~30 stores must remember to do.
+//
+// THREAT MODEL. The DO block volume under /var/lib/cloud is provider-encrypted,
+// so the residual exposure is a COPIED PV snapshot/backup or an in-cluster
+// exec/PV read seeing plaintext customer PII (crm), the ledger (treasury), org
+// wallet maps (wallets), the audit log, team/entitlements. cek removes that
+// exposure: each file's pages are SQLCipher-encrypted under a per-database key
+// that never leaves the process in the clear and is itself wrapped by the
+// KMS-injected master key; the pre-migration plaintext copy is shredded once the
+// encrypted store is proven readable. A lifted file is useless without the key.
+//
+// SCOPE / NON-GOALS. cek provides CONFIDENTIALITY at rest against the read-only
+// exposure above (no master key ⇒ no plaintext). It is NOT integrity,
+// authenticity, or anti-rollback against a PV-WRITE (node-compromise) adversary
+// who can modify the volume: the per-file id lives in the (unauthenticated) .dek
+// sidecar, so such an adversary could swap two of OUR OWN {db,.dek} pairs or
+// replay an old snapshot. That is outside the stated model and is deliberately
+// NOT defended here (a logical-id+epoch binding would add complexity for an
+// out-of-model threat); revisit only if tenant-isolation-under-node-compromise
+// is scoped in.
+//
+// ENVELOPE (the primitives live in github.com/hanzoai/sqlite/cek.go and are
+// reused verbatim — one crypto implementation, KAT-gated there):
+//
+//   - Each database has its OWN random 256-bit DEK (the SQLCipher page key),
+//     minted once at first touch and NEVER changed, so ciphertext pages are
+//     never rewritten.
+//   - Each database also gets a random 128-bit FILE ID, stored in the clear at
+//     the head of its <db>.dek sidecar. The KEK is derived from that id, NOT the
+//     file path: KEK = HKDF-SHA256(masterKey, lp("global") || lp(hex(fileID))).
+//     The id is intrinsic to the file and travels with the sidecar, so moving
+//     the data dir or changing CLOUD_DATA_DIR can never change the KEK and brick
+//     a store. RFC-5869 HKDF via x/crypto/hkdf — NOT luxfi/crypto/kdf (a QZMQ
+//     KeySchedule, not generic HKDF; using it would brick every store).
+//   - The DEK is wrapped AES-256-GCM under the KEK, bound to the same id as AAD.
+//     Sidecar = fileID(16) || wrapped-DEK. The raw DEK is never written.
+//   - Master-key ROTATION rewraps only the sidecar: the DEK and fileID are
+//     unchanged, so no page is rewritten and no file can be bricked.
+//
+// FAIL-SECURE. On an encryption-CAPABLE build (production is CGO + libsqlcipher)
+// a missing master key is FATAL — the data plane refuses to open unencrypted,
+// the same posture the KMS store takes. A key set on a NON-encrypting build is
+// likewise fatal. An encrypted file whose sidecar is missing is refused. A
+// migration whose encrypted copy does not reproduce the source's schema AND
+// per-table content (a rowid-independent multiset hash, not just a row count)
+// leaves the plaintext untouched and errors — the caller (MountAll) fails
+// closed, so cloud never serves a half-migrated data plane.
+package cek
+
+import (
+	"context"
+	"crypto/rand"
+	"crypto/sha256"
+	"database/sql"
+	"encoding/base64"
+	"encoding/binary"
+	"encoding/hex"
+	"fmt"
+	"hash"
+	"math"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+	"sync"
+	"syscall"
+	"time"
+
+	sqlitedrv "github.com/hanzoai/sqlite"
+)
+
+// masterKeyEnv is the ONE variable that supplies the 32-byte KMS master key
+// (base64), matching the operator Deployment and clients/kms. No second gate.
+const masterKeyEnv = "CLOUD_KMS_MASTER_KEY_REF"
+
+const (
+	dekSuffix      = ".dek"       // sidecar: fileID(16) || wrapped-DEK
+	lockSuffix     = ".cek.lock"  // per-db flock guarding first-touch + migration
+	tmpSuffix      = ".cek.tmp"   // in-progress encrypted target (same volume → atomic rename)
+	plainBakSuffix = ".plain.bak" // transient pre-migration plaintext; SHREDDED after verified open
+
+	sqliteMagic = "SQLite format 3\x00" // 16-byte header of an UNENCRYPTED db
+	headerLen   = 16
+	fileIDLen   = 16 // random per-file KEK-derivation id, stored in the sidecar head
+)
+
+// principalType domain-separates cloud's platform databases from IAM's org/user
+// stores in the shared HKDF namespace.
+const principalType = sqlitedrv.PrincipalGlobal
+
+var (
+	masterOnce     sync.Once
+	masterKey      []byte
+	masterErr      error
+	masterOverride []byte
+)
+
+// SetMasterKey injects the 32-byte master key explicitly (cloud's boot resolves
+// it once from cfg and hands it here), taking precedence over the environment.
+// Call before the first Open. A wrong-length key is ignored so the env path can
+// still apply.
+func SetMasterKey(k []byte) {
+	if len(k) == 32 {
+		masterOverride = append([]byte(nil), k...)
+	}
+}
+
+// resolveMaster resolves the process master key exactly once:
+//
+//	(key, nil)   — 32-byte key AND an encryption-capable build → encrypt.
+//	(nil, nil)   — no key AND a non-encrypting (pure-Go) build → dev/CI plaintext.
+//	(nil, error) — key malformed; OR key set on a non-encrypting build; OR NO key
+//	               on an encryption-capable build. The last is the production
+//	               fail-closed: a capable binary never silently ships plaintext.
+func resolveMaster() ([]byte, error) {
+	masterOnce.Do(func() {
+		raw := masterOverride
+		if len(raw) == 0 {
+			b64 := strings.TrimSpace(os.Getenv(masterKeyEnv))
+			if b64 == "" {
+				if sqlitedrv.EncryptionAvailable() {
+					masterErr = fmt.Errorf("cek: %s is required on an encryption-capable build; "+
+						"refusing to open the data plane unencrypted (set the KMS master key, "+
+						"or run a pure-Go dev build)", masterKeyEnv)
+				}
+				return // pure-Go dev/CI: plaintext is expected (no codec linked)
+			}
+			decoded, err := base64.StdEncoding.DecodeString(b64)
+			if err != nil {
+				masterErr = fmt.Errorf("cek: %s is not valid base64: %w", masterKeyEnv, err)
+				return
+			}
+			raw = decoded
+		}
+		if len(raw) != 32 {
+			masterErr = fmt.Errorf("cek: master key must decode to 32 bytes, got %d", len(raw))
+			return
+		}
+		if !sqlitedrv.EncryptionAvailable() {
+			masterErr = fmt.Errorf("cek: %s is set but this build cannot encrypt (pure-Go sqlite); "+
+				"rebuild CGO_ENABLED=1 linked against libsqlcipher, or unset it for a dev build", masterKeyEnv)
+			return
+		}
+		masterKey = raw
+	})
+	return masterKey, masterErr
+}
+
+// Encrypting reports whether cek will encrypt at rest (a valid master key is
+// configured on an encryption-capable build). cloud calls this once at boot for
+// the posture log; a false result on a capable build means resolveMaster errored
+// and the first store Open will fail closed.
+func Encrypting() bool {
+	k, err := resolveMaster()
+	return err == nil && len(k) == 32
+}
+
+// Open returns a *sql.DB for the SQLite database at path, encrypted at rest when
+// a master key is configured. It is the single drop-in replacement for
+// sql.Open("sqlite", path) across every cloud store.
+func Open(path string) (*sql.DB, error) {
+	master, err := resolveMaster()
+	if err != nil {
+		return nil, err
+	}
+	if master == nil {
+		// Only reachable on a non-encrypting dev/CI build (a capable build with no
+		// key already errored above). Preserve the prior bare-path behavior.
+		return sql.Open("sqlite", path)
+	}
+	return openEncrypted(path, master)
+}
+
+func openEncrypted(path string, master []byte) (*sql.DB, error) {
+	unlock, err := flock(path)
+	if err != nil {
+		return nil, err
+	}
+	defer unlock()
+
+	if err := recoverInterrupted(path); err != nil {
+		return nil, err
+	}
+
+	var db *sql.DB
+	switch classify(path) {
+	case stateFresh:
+		db, err = createFresh(path, master)
+	case stateEncrypted:
+		db, err = openExisting(path, master)
+	default: // statePlaintext
+		db, err = migrateThenOpen(path, master)
+	}
+	if err != nil {
+		return nil, err
+	}
+	// No plaintext replica may survive a successful keyed open: shred any backup
+	// left by this (or a crashed prior) migration. THIS is the security objective.
+	shredPlainBak(path)
+	return db, nil
+}
+
+type fileState int
+
+const (
+	stateFresh     fileState = iota // absent or too small to be a real db → mint
+	statePlaintext                  // "SQLite format 3\0" header → migrate
+	stateEncrypted                  // db-sized, non-magic header → SQLCipher, open via sidecar
+)
+
+func classify(path string) fileState {
+	fi, err := os.Stat(path)
+	if err != nil || fi.Size() < headerLen {
+		return stateFresh
+	}
+	if isPlaintextHeader(path) {
+		return statePlaintext
+	}
+	return stateEncrypted
+}
+
+func isPlaintextHeader(path string) bool {
+	f, err := os.Open(path)
+	if err != nil {
+		return false
+	}
+	defer func() { _ = f.Close() }()
+	var hdr [headerLen]byte
+	if _, err := f.ReadAt(hdr[:], 0); err != nil {
+		return false
+	}
+	return string(hdr[:]) == sqliteMagic
+}
+
+// ── sidecar: fileID(16) || wrapped-DEK ───────────────────────────────────────
+
+// mintSidecar generates a fresh fileID + DEK, wraps the DEK under the id-derived
+// KEK, and returns the DEK and the sidecar bytes to persist.
+func mintSidecar(master []byte) (dek, sidecar []byte, err error) {
+	fileID := make([]byte, fileIDLen)
+	if _, err = rand.Read(fileID); err != nil {
+		return nil, nil, fmt.Errorf("cek: generate file id: %w", err)
+	}
+	kek, aad, err := deriveFor(master, fileID)
+	if err != nil {
+		return nil, nil, err
+	}
+	defer zero(kek)
+	if dek, err = sqlitedrv.NewDEK(); err != nil {
+		return nil, nil, fmt.Errorf("cek: new DEK: %w", err)
+	}
+	wrapped, err := sqlitedrv.WrapDEK(kek, dek, aad)
+	if err != nil {
+		zero(dek)
+		return nil, nil, fmt.Errorf("cek: wrap DEK: %w", err)
+	}
+	sidecar = append(append(make([]byte, 0, fileIDLen+len(wrapped)), fileID...), wrapped...)
+	return dek, sidecar, nil
+}
+
+// unwrapSidecar reads the fileID from the sidecar head and unwraps the DEK under
+// the id-derived KEK. A wrong master key, tampered blob, or truncated sidecar
+// fails the GCM tag and errors — never a partial/garbage key.
+func unwrapSidecar(master, sidecar []byte) ([]byte, error) {
+	if len(sidecar) <= fileIDLen {
+		return nil, fmt.Errorf("cek: sidecar too short (%d bytes)", len(sidecar))
+	}
+	fileID, wrapped := sidecar[:fileIDLen], sidecar[fileIDLen:]
+	kek, aad, err := deriveFor(master, fileID)
+	if err != nil {
+		return nil, err
+	}
+	defer zero(kek)
+	dek, err := sqlitedrv.UnwrapDEK(kek, wrapped, aad)
+	if err != nil {
+		return nil, fmt.Errorf("cek: unwrap DEK (wrong master key or corrupt sidecar): %w", err)
+	}
+	return dek, nil
+}
+
+// deriveFor derives the KEK and the wrap-AAD for a file id. Both bind to
+// hex(fileID) so the id — not any path or config value — is the sole identity.
+func deriveFor(master, fileID []byte) (kek, aad []byte, err error) {
+	id := hex.EncodeToString(fileID)
+	kek, err = sqlitedrv.DeriveKey(master, principalType, id)
+	if err != nil {
+		return nil, nil, fmt.Errorf("cek: derive KEK: %w", err)
+	}
+	return kek, sqlitedrv.PrincipalAAD(principalType, id), nil
+}
+
+// ── open paths ───────────────────────────────────────────────────────────────
+
+func createFresh(path string, master []byte) (*sql.DB, error) {
+	dekPath := path + dekSuffix
+	if fileExists(dekPath) {
+		return openExisting(path, master) // a concurrent first-touch won the lock
+	}
+	dek, sidecar, err := mintSidecar(master)
+	if err != nil {
+		return nil, err
+	}
+	defer zero(dek)
+	if err := writeFileAtomic(dekPath, sidecar, 0o600); err != nil {
+		return nil, err
+	}
+	db, err := openKeyed(path, dek)
+	if err != nil {
+		return nil, fmt.Errorf("cek: create encrypted %q: %w", path, err)
+	}
+	return db, nil
+}
+
+func openExisting(path string, master []byte) (*sql.DB, error) {
+	dekPath := path + dekSuffix
+	sidecar, err := os.ReadFile(dekPath)
+	if err != nil {
+		return nil, fmt.Errorf("cek: read sidecar %q (encrypted db, refusing to open blind): %w", dekPath, err)
+	}
+	dek, err := unwrapSidecar(master, sidecar)
+	if err != nil {
+		return nil, err
+	}
+	defer zero(dek)
+	db, err := openKeyed(path, dek)
+	if err != nil {
+		return nil, fmt.Errorf("cek: open encrypted %q: %w", path, err)
+	}
+	return db, nil
+}
+
+// migrateThenOpen converts an existing PLAINTEXT database to SQLCipher without
+// losing a row, then opens it. Crash-safe (plaintext is the source of truth
+// until an atomic rename commits) and fail-secure (the swap happens only after
+// the encrypted copy reproduces the source schema + per-table content hash +
+// integrity_check, re-opened via the exact keyed path the app uses).
+func migrateThenOpen(path string, master []byte) (*sql.DB, error) {
+	dekPath := path + dekSuffix
+	// Plaintext header ⇒ an earlier attempt did not commit: discard any stale
+	// sidecar/tmp and redo from the plaintext source of truth.
+	_ = os.Remove(dekPath)
+	tmp := path + tmpSuffix
+	removeDBFiles(tmp)
+
+	dek, sidecar, err := mintSidecar(master)
+	if err != nil {
+		return nil, err
+	}
+	defer zero(dek)
+
+	srcInv, err := exportPlaintext(path, tmp, dek)
+	if err != nil {
+		removeDBFiles(tmp)
+		return nil, err
+	}
+
+	if isPlaintextHeader(tmp) {
+		removeDBFiles(tmp)
+		return nil, fmt.Errorf("cek: migration of %q produced a plaintext file (SQLCipher not linked?)", path)
+	}
+	if err := verifyParity(tmp, dek, srcInv); err != nil {
+		removeDBFiles(tmp)
+		return nil, fmt.Errorf("cek: migration parity check failed for %q (plaintext left intact): %w", path, err)
+	}
+
+	// Commit. Order for crash-safety:
+	//  1. sidecar (the encrypted db's key),
+	//  2. plaintext → <db>.plain.bak,
+	//  3. delete the now-orphaned plaintext -wal/-shm (WAL was checkpoint-folded
+	//     into the main file, so .plain.bak is complete; removing them now closes
+	//     the window where a stale plaintext WAL sits beside the encrypted db),
+	//  4. atomic rename tmp → path.
+	// A crash between any two steps is resolved by recoverInterrupted on reboot.
+	if err := writeFileAtomic(dekPath, sidecar, 0o600); err != nil {
+		removeDBFiles(tmp)
+		return nil, err
+	}
+	if err := os.Rename(path, path+plainBakSuffix); err != nil {
+		removeDBFiles(tmp)
+		_ = os.Remove(dekPath)
+		return nil, fmt.Errorf("cek: preserve plaintext backup for %q: %w", path, err)
+	}
+	_ = os.Remove(path + "-wal")
+	_ = os.Remove(path + "-shm")
+	if err := os.Rename(tmp, path); err != nil {
+		_ = os.Rename(path+plainBakSuffix, path) // roll back
+		_ = os.Remove(dekPath)
+		return nil, fmt.Errorf("cek: swap encrypted %q into place: %w", path, err)
+	}
+	syncDir(filepath.Dir(path))
+
+	db, err := openKeyed(path, dek)
+	if err != nil {
+		return nil, fmt.Errorf("cek: open migrated %q: %w", path, err)
+	}
+	return db, nil // openEncrypted's tail shreds .plain.bak after this succeeds
+}
+
+// exportPlaintext opens the plaintext source, folds its WAL into the main file
+// (crm.db/audit.db carry MB of live WAL), records the source inventory for the
+// parity check, and copies every page into a fresh SQLCipher database at tmp via
+// SQLCipher's own sqlcipher_export with the format compat pinned. The source is
+// only read.
+func exportPlaintext(path, tmp string, dek []byte) (inventory, error) {
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Minute)
+	defer cancel()
+
+	src, err := sql.Open("sqlite", sqlitedrv.DSN(path, nil))
+	if err != nil {
+		return inventory{}, fmt.Errorf("cek: open plaintext %q: %w", path, err)
+	}
+	defer func() { _ = src.Close() }()
+	src.SetMaxOpenConns(1) // ATTACH + sqlcipher_export must run on ONE connection
+
+	conn, err := src.Conn(ctx)
+	if err != nil {
+		return inventory{}, fmt.Errorf("cek: acquire conn for %q: %w", path, err)
+	}
+	defer func() { _ = conn.Close() }()
+
+	if _, err := conn.ExecContext(ctx, "PRAGMA wal_checkpoint(TRUNCATE)"); err != nil {
+		return inventory{}, fmt.Errorf("cek: checkpoint %q: %w", path, err)
+	}
+	srcInv, err := readInventory(ctx, conn)
+	if err != nil {
+		return inventory{}, fmt.Errorf("cek: inventory source %q: %w", path, err)
+	}
+
+	// The DEK is crypto/rand hex — no injection surface; the path is a bound
+	// parameter. The reopen-via-openKeyed parity check downstream is the
+	// authoritative guard that the copy opens under the app's exact keyed path.
+	// The target is created at the runtime's SQLCipher format (the frozen
+	// libsqlcipher default), which is exactly what openKeyed reopens it under.
+	attach := fmt.Sprintf(`ATTACH DATABASE ? AS enc KEY "x'%x'"`, dek)
+	if _, err := conn.ExecContext(ctx, attach, tmp); err != nil {
+		return inventory{}, fmt.Errorf("cek: attach encrypted target: %w", err)
+	}
+	if _, err := conn.ExecContext(ctx, "SELECT sqlcipher_export('enc')"); err != nil {
+		_, _ = conn.ExecContext(ctx, "DETACH DATABASE enc")
+		return inventory{}, fmt.Errorf("cek: sqlcipher_export: %w", err)
+	}
+	if _, err := conn.ExecContext(ctx, "DETACH DATABASE enc"); err != nil {
+		return inventory{}, fmt.Errorf("cek: detach encrypted target: %w", err)
+	}
+	return srcInv, nil
+}
+
+// verifyParity re-opens the encrypted copy exactly as the running app will
+// (openKeyed) and asserts: integrity_check ok, identical schema fingerprint, and
+// — per table — identical row count AND identical rowid-independent content hash.
+// The content hash (a commutative multiset sum of per-row hashes over the USER
+// columns) is what backs the zero-loss claim: it catches any value change, NULL
+// coercion, or row add/drop that count + schema + integrity_check miss, while
+// correctly ignoring the benign implicit-rowid renumbering sqlcipher_export does.
+// It runs BEFORE the atomic swap, so any discrepancy leaves the plaintext intact.
+func verifyParity(tmp string, dek []byte, src inventory) error {
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Minute)
+	defer cancel()
+
+	db, err := openKeyed(tmp, dek)
+	if err != nil {
+		return fmt.Errorf("reopen encrypted copy: %w", err)
+	}
+	defer func() { _ = db.Close() }()
+	db.SetMaxOpenConns(1)
+	if err := db.PingContext(ctx); err != nil {
+		return fmt.Errorf("ping encrypted copy (key/compat mismatch?): %w", err)
+	}
+
+	var ic string
+	if err := db.QueryRowContext(ctx, "PRAGMA integrity_check").Scan(&ic); err != nil {
+		return fmt.Errorf("integrity_check: %w", err)
+	}
+	if ic != "ok" {
+		return fmt.Errorf("integrity_check returned %q", ic)
+	}
+
+	conn, err := db.Conn(ctx)
+	if err != nil {
+		return fmt.Errorf("acquire verify conn: %w", err)
+	}
+	defer func() { _ = conn.Close() }()
+	dst, err := readInventory(ctx, conn)
+	if err != nil {
+		return fmt.Errorf("inventory encrypted copy: %w", err)
+	}
+	if dst.schema != src.schema {
+		return fmt.Errorf("schema fingerprint mismatch")
+	}
+	if len(dst.tables) != len(src.tables) {
+		return fmt.Errorf("table set mismatch: src %d tables, dst %d", len(src.tables), len(dst.tables))
+	}
+	for tbl, s := range src.tables {
+		d, ok := dst.tables[tbl]
+		if !ok {
+			return fmt.Errorf("table %q missing in encrypted copy", tbl)
+		}
+		if d.count != s.count {
+			return fmt.Errorf("row-count mismatch in %q: src %d, dst %d", tbl, s.count, d.count)
+		}
+		if d.content != s.content {
+			return fmt.Errorf("content-hash mismatch in %q (row values differ despite equal count)", tbl)
+		}
+	}
+	return nil
+}
+
+// inventory is the parity fingerprint: a schema hash plus, per table, a row count
+// and a content hash.
+type inventory struct {
+	schema [32]byte
+	tables map[string]tableStat
+}
+
+type tableStat struct {
+	count   int64
+	content [32]byte // commutative multiset sum of per-row hashes over user columns
+}
+
+func readInventory(ctx context.Context, conn *sql.Conn) (inventory, error) {
+	rows, err := conn.QueryContext(ctx,
+		`SELECT type,name,COALESCE(tbl_name,''),COALESCE(sql,'') FROM sqlite_master `+
+			`WHERE name NOT LIKE 'sqlite_%' ORDER BY type,name`)
+	if err != nil {
+		return inventory{}, err
+	}
+	var schemaLines, tables []string
+	for rows.Next() {
+		var typ, name, tbl, ddl string
+		if err := rows.Scan(&typ, &name, &tbl, &ddl); err != nil {
+			_ = rows.Close()
+			return inventory{}, err
+		}
+		schemaLines = append(schemaLines, typ+"\x1f"+name+"\x1f"+tbl+"\x1f"+ddl)
+		if typ == "table" {
+			tables = append(tables, name)
+		}
+	}
+	if err := rows.Err(); err != nil {
+		_ = rows.Close()
+		return inventory{}, err
+	}
+	_ = rows.Close()
+
+	sort.Strings(schemaLines)
+	h := sha256.New()
+	for _, l := range schemaLines {
+		writeLP(h, []byte(l))
+	}
+	inv := inventory{tables: make(map[string]tableStat, len(tables))}
+	copy(inv.schema[:], h.Sum(nil))
+
+	for _, tbl := range tables {
+		st, err := tableContent(ctx, conn, tbl)
+		if err != nil {
+			return inventory{}, fmt.Errorf("content %q: %w", tbl, err)
+		}
+		inv.tables[tbl] = st
+	}
+	return inv, nil
+}
+
+// tableContent streams every row of a table and folds a per-row hash (over the
+// user columns, faithfully distinguishing NULL / "" / 0 / storage class) into a
+// commutative 256-bit sum. Order-independent (survives rowid-driven scan-order
+// differences) and duplicate-safe (addition, not XOR). O(1) memory per table.
+func tableContent(ctx context.Context, conn *sql.Conn, tbl string) (tableStat, error) {
+	q := `SELECT * FROM "` + strings.ReplaceAll(tbl, `"`, `""`) + `"`
+	rows, err := conn.QueryContext(ctx, q)
+	if err != nil {
+		return tableStat{}, err
+	}
+	defer func() { _ = rows.Close() }()
+	cols, err := rows.Columns()
+	if err != nil {
+		return tableStat{}, err
+	}
+	var st tableStat
+	scan := make([]any, len(cols))
+	ptrs := make([]any, len(cols))
+	for i := range scan {
+		ptrs[i] = &scan[i]
+	}
+	for rows.Next() {
+		if err := rows.Scan(ptrs...); err != nil {
+			return tableStat{}, err
+		}
+		rh := sha256.New()
+		for _, v := range scan {
+			encodeValue(rh, v)
+		}
+		var row [32]byte
+		copy(row[:], rh.Sum(nil))
+		addInto(&st.content, row)
+		st.count++
+	}
+	return st, rows.Err()
+}
+
+// encodeValue writes a type-tagged, length-prefixed, NULL-sentinel encoding of a
+// scanned SQLite value so two logically-equal rows hash identically and a NULL
+// never collides with "" or 0.
+func encodeValue(h hash.Hash, v any) {
+	switch x := v.(type) {
+	case nil:
+		h.Write([]byte{0})
+	case int64:
+		var b [8]byte
+		binary.BigEndian.PutUint64(b[:], uint64(x))
+		h.Write([]byte{1})
+		h.Write(b[:])
+	case float64:
+		var b [8]byte
+		binary.BigEndian.PutUint64(b[:], math.Float64bits(x))
+		h.Write([]byte{2})
+		h.Write(b[:])
+	case bool:
+		h.Write([]byte{3})
+		if x {
+			h.Write([]byte{1})
+		} else {
+			h.Write([]byte{0})
+		}
+	case []byte:
+		h.Write([]byte{4})
+		writeLP(h, x)
+	case string:
+		h.Write([]byte{5})
+		writeLP(h, []byte(x))
+	case time.Time:
+		h.Write([]byte{6})
+		var b [8]byte
+		binary.BigEndian.PutUint64(b[:], uint64(x.UnixNano()))
+		h.Write(b[:])
+	default:
+		h.Write([]byte{9})
+		writeLP(h, []byte(fmt.Sprintf("%v", x)))
+	}
+}
+
+// writeLP writes an 8-byte big-endian length prefix then the bytes, so
+// concatenations are unambiguous.
+func writeLP(h hash.Hash, b []byte) {
+	var n [8]byte
+	binary.BigEndian.PutUint64(n[:], uint64(len(b)))
+	h.Write(n[:])
+	h.Write(b)
+}
+
+// addInto computes acc = (acc + row) mod 2^256, big-endian — the commutative,
+// duplicate-safe multiset combiner.
+func addInto(acc *[32]byte, row [32]byte) {
+	var carry uint16
+	for i := 31; i >= 0; i-- {
+		s := uint16(acc[i]) + uint16(row[i]) + carry
+		acc[i] = byte(s)
+		carry = s >> 8
+	}
+}
+
+// recoverInterrupted resumes a migration that crashed between the commit steps,
+// keying only on files (no config). It also scrubs any stale plaintext -wal/-shm
+// so a half-committed state can never leave one beside an encrypted db.
+func recoverInterrupted(path string) error {
+	dekPath := path + dekSuffix
+	tmp := path + tmpSuffix
+	if fileExists(path) {
+		// If the live file is already encrypted, a leftover tmp is a dead
+		// migration attempt — discard it. (A plaintext live file is handled by
+		// migrateThenOpen, which clears tmp itself.)
+		if !isPlaintextHeader(path) {
+			removeDBFiles(tmp)
+		}
+		return nil
+	}
+	switch {
+	case fileExists(tmp) && fileExists(dekPath):
+		// Crashed after the sidecar+backup were written but before/during the swap
+		// rename: finish it. The sidecar matches tmp.
+		if err := os.Rename(tmp, path); err != nil {
+			return fmt.Errorf("cek: resume migration swap for %q: %w", path, err)
+		}
+		_ = os.Remove(path + "-wal")
+		_ = os.Remove(path + "-shm")
+		syncDir(filepath.Dir(path))
+	case fileExists(path + plainBakSuffix):
+		// Swap never happened; restore the plaintext original for a clean redo.
+		if err := os.Rename(path+plainBakSuffix, path); err != nil {
+			return fmt.Errorf("cek: restore plaintext backup for %q: %w", path, err)
+		}
+		removeDBFiles(tmp)
+		_ = os.Remove(dekPath)
+	}
+	return nil
+}
+
+// openKeyed opens a keyed SQLCipher database via the driver's ONE blessed keyed
+// open (the key rides the URI so it is applied at sqlite3_open_v2, before mattn's
+// pragma battery touches the header — a post-open PRAGMA key would be too late).
+//
+// CROSS-VERSION SAFETY. SQLCipher's on-disk format is fixed by the libsqlcipher
+// major the arcd image links; that version is FROZEN in the Dockerfile (see the
+// runbook) so an image rebuild cannot silently change the default cipher format
+// and orphan a store. An at-open `cipher_compatibility` pin is NOT usable here
+// (the URI param is silently ignored, and a post-open pragma runs after mattn has
+// already read the header) — the version freeze is the control. If a mismatch
+// ever occurs it FAILS CLOSED: openExisting returns "file is not a database" and
+// MountAll aborts — never a silent downgrade or corruption.
+func openKeyed(path string, dek []byte) (*sql.DB, error) {
+	db, err := sqlitedrv.OpenDB(path, dek)
+	if err != nil {
+		return nil, fmt.Errorf("cek: open keyed %q: %w", path, err) // no dsn (holds key)
+	}
+	return db, nil
+}
+
+// ── shred + boring helpers ───────────────────────────────────────────────────
+
+// shredPlainBak overwrites and removes the transient pre-migration plaintext
+// backup once the encrypted store is proven readable. Overwrite-then-remove is
+// defense-in-depth (best-effort on a copy-on-write/journalled fs; the block
+// volume is provider-encrypted regardless). Idempotent no-op when absent.
+func shredPlainBak(path string) {
+	bak := path + plainBakSuffix
+	fi, err := os.Stat(bak)
+	if err != nil {
+		return
+	}
+	if f, err := os.OpenFile(bak, os.O_WRONLY, 0); err == nil {
+		overwrite(f, fi.Size())
+		_ = f.Sync()
+		_ = f.Close()
+	}
+	_ = os.Remove(bak)
+}
+
+func overwrite(f *os.File, size int64) {
+	const chunk = 1 << 20
+	buf := make([]byte, chunk)
+	for remaining := size; remaining > 0; {
+		n := int64(chunk)
+		if remaining < n {
+			n = remaining
+		}
+		if _, err := rand.Read(buf[:n]); err != nil {
+			return
+		}
+		if _, err := f.Write(buf[:n]); err != nil {
+			return
+		}
+		remaining -= n
+	}
+}
+
+func fileExists(p string) bool {
+	_, err := os.Stat(p)
+	return err == nil
+}
+
+func removeDBFiles(base string) {
+	for _, s := range []string{"", "-wal", "-shm"} {
+		_ = os.Remove(base + s)
+	}
+}
+
+func writeFileAtomic(dst string, data []byte, perm os.FileMode) error {
+	tmp := dst + ".tmp"
+	f, err := os.OpenFile(tmp, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, perm)
+	if err != nil {
+		return fmt.Errorf("cek: create %q: %w", tmp, err)
+	}
+	if _, err := f.Write(data); err != nil {
+		_ = f.Close()
+		_ = os.Remove(tmp)
+		return fmt.Errorf("cek: write %q: %w", tmp, err)
+	}
+	if err := f.Sync(); err != nil {
+		_ = f.Close()
+		_ = os.Remove(tmp)
+		return fmt.Errorf("cek: sync %q: %w", tmp, err)
+	}
+	if err := f.Close(); err != nil {
+		_ = os.Remove(tmp)
+		return fmt.Errorf("cek: close %q: %w", tmp, err)
+	}
+	if err := os.Rename(tmp, dst); err != nil {
+		_ = os.Remove(tmp)
+		return fmt.Errorf("cek: rename %q→%q: %w", tmp, dst, err)
+	}
+	return nil
+}
+
+func syncDir(dir string) {
+	if d, err := os.Open(dir); err == nil {
+		_ = d.Sync()
+		_ = d.Close()
+	}
+}
+
+// flock takes an exclusive advisory lock on <path>.cek.lock, serializing
+// first-touch and migration for the SAME database across processes/goroutines
+// (different databases never contend). Returns an unlock func.
+func flock(path string) (func(), error) {
+	lockPath := path + lockSuffix
+	if err := os.MkdirAll(filepath.Dir(lockPath), 0o700); err != nil {
+		return nil, fmt.Errorf("cek: create lock dir: %w", err)
+	}
+	f, err := os.OpenFile(lockPath, os.O_CREATE|os.O_RDWR, 0o600)
+	if err != nil {
+		return nil, fmt.Errorf("cek: open lock %q: %w", lockPath, err)
+	}
+	if err := syscall.Flock(int(f.Fd()), syscall.LOCK_EX); err != nil {
+		_ = f.Close()
+		return nil, fmt.Errorf("cek: acquire lock %q: %w", lockPath, err)
+	}
+	return func() {
+		_ = syscall.Flock(int(f.Fd()), syscall.LOCK_UN)
+		_ = f.Close()
+	}, nil
+}
+
+func zero(b []byte) {
+	for i := range b {
+		b[i] = 0
+	}
+}

cek/cek_test.go

@@ -0,0 +1,439 @@
+package cek
+
+import (
+	"context"
+	"database/sql"
+	"encoding/hex"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sync"
+	"testing"
+
+	sqlitedrv "github.com/hanzoai/sqlite"
+)
+
+// resetMaster clears the once-resolved master so a test can choose a posture.
+// White-box tests only; production never resets.
+func resetMaster(key []byte) {
+	masterOnce = sync.Once{}
+	masterKey = nil
+	masterErr = nil
+	masterOverride = nil
+	if key != nil {
+		SetMasterKey(key)
+	}
+}
+
+func testMaster(t *testing.T) []byte {
+	t.Helper()
+	k := make([]byte, 32)
+	for i := range k {
+		k[i] = byte(i*7 + 1)
+	}
+	return k
+}
+
+// requireCipher skips when the build cannot produce REAL ciphertext (a mis-linked
+// cgo build silently writes plaintext), probing rather than trusting the flag.
+// With SQLITE_REQUIRE_CODEC=1 (the Docker image build sets it) a would-be skip
+// becomes a FAILURE, so the in-image gate is airtight standalone.
+func requireCipher(t *testing.T) {
+	t.Helper()
+	skipOrFail := func(msg string) {
+		if os.Getenv("SQLITE_REQUIRE_CODEC") == "1" {
+			t.Fatal(msg)
+		}
+		t.Skip(msg)
+	}
+	if !sqlitedrv.EncryptionAvailable() {
+		skipOrFail("sqlite build cannot encrypt (pure-Go); run with CGO + libsqlcipher")
+		return
+	}
+	probe := filepath.Join(t.TempDir(), "probe.db")
+	dek, _ := sqlitedrv.NewDEK()
+	db, err := openKeyed(probe, dek)
+	if err != nil {
+		t.Fatalf("probe open: %v", err)
+	}
+	if _, err := db.Exec(`CREATE TABLE t(x)`); err != nil {
+		t.Fatalf("probe ddl: %v", err)
+	}
+	_ = db.Close()
+	if isPlaintextHeader(probe) {
+		skipOrFail("cgo build is NOT linked against libsqlcipher (keyed db is plaintext)")
+		return
+	}
+}
+
+// makePlaintextDB writes a genuine UNENCRYPTED SQLite db with known rows in WAL
+// mode (exercising exportPlaintext's WAL fold), returning per-table row counts.
+func makePlaintextDB(t *testing.T, path string, companies, contacts int) map[string]int64 {
+	t.Helper()
+	db, err := sql.Open("sqlite", path)
+	if err != nil {
+		t.Fatalf("open plaintext: %v", err)
+	}
+	for _, p := range []string{"PRAGMA journal_mode=WAL", "PRAGMA wal_autocheckpoint=0"} {
+		if _, err := db.Exec(p); err != nil {
+			t.Fatalf("pragma %q: %v", p, err)
+		}
+	}
+	if _, err := db.Exec(`
+CREATE TABLE crm_companies(id TEXT PRIMARY KEY, org TEXT, name TEXT, arr INTEGER);
+CREATE INDEX ix_co_org ON crm_companies(org);
+CREATE TABLE crm_contacts(id TEXT PRIMARY KEY, org TEXT, email TEXT, note TEXT);`); err != nil {
+		t.Fatalf("ddl: %v", err)
+	}
+	for i := 0; i < companies; i++ {
+		if _, err := db.Exec(`INSERT INTO crm_companies VALUES(?,?,?,?)`,
+			fmt.Sprintf("co-%d", i), "maxpower", fmt.Sprintf("Co %d", i), int64(i*1000)); err != nil {
+			t.Fatalf("insert company: %v", err)
+		}
+	}
+	for i := 0; i < contacts; i++ {
+		// note is NULL on evens to exercise NULL fidelity in the content hash.
+		if i%2 == 0 {
+			_, err = db.Exec(`INSERT INTO crm_contacts(id,org,email) VALUES(?,?,?)`,
+				fmt.Sprintf("ct-%d", i), "maxpower", fmt.Sprintf("u%d@x.io", i))
+		} else {
+			_, err = db.Exec(`INSERT INTO crm_contacts VALUES(?,?,?,?)`,
+				fmt.Sprintf("ct-%d", i), "maxpower", fmt.Sprintf("u%d@x.io", i), "vip")
+		}
+		if err != nil {
+			t.Fatalf("insert contact: %v", err)
+		}
+	}
+	if !isPlaintextHeader(path) {
+		t.Fatalf("precondition: freshly created db is not plaintext")
+	}
+	_ = db.Close()
+	return map[string]int64{"crm_companies": int64(companies), "crm_contacts": int64(contacts)}
+}
+
+func rowCount(t *testing.T, db *sql.DB, table string) int64 {
+	t.Helper()
+	var n int64
+	if err := db.QueryRow(`SELECT COUNT(*) FROM ` + table).Scan(&n); err != nil {
+		t.Fatalf("count %s: %v", table, err)
+	}
+	return n
+}
+
+func firstBytes(t *testing.T, path string, n int) []byte {
+	t.Helper()
+	f, err := os.Open(path)
+	if err != nil {
+		t.Fatalf("open %s: %v", path, err)
+	}
+	defer func() { _ = f.Close() }()
+	b := make([]byte, n)
+	if _, err := f.ReadAt(b, 0); err != nil {
+		t.Fatalf("read %s: %v", path, err)
+	}
+	return b
+}
+
+// TestMigratePlaintextToCipher is the keystone: plaintext → SQLCipher with a
+// ciphertext header, exact row parity, an unwrappable sidecar, readable data,
+// and — per RED HIGH — NO surviving plaintext backup (shredded after verify).
+func TestMigratePlaintextToCipher(t *testing.T) {
+	requireCipher(t)
+	dir := t.TempDir()
+	path := filepath.Join(dir, "crm.db")
+	want := makePlaintextDB(t, path, 37, 91)
+
+	resetMaster(testMaster(t))
+	db, err := Open(path)
+	if err != nil {
+		t.Fatalf("cek.Open (migrate): %v", err)
+	}
+	defer func() { _ = db.Close() }()
+
+	if isPlaintextHeader(path) {
+		t.Fatalf("FAIL: %s still plaintext after migration", path)
+	}
+	t.Logf("migrated header (hex): %s", hex.EncodeToString(firstBytes(t, path, 16)))
+
+	for tbl, n := range want {
+		if got := rowCount(t, db, tbl); got != n {
+			t.Errorf("row-count mismatch %s: want %d got %d", tbl, n, got)
+		}
+	}
+
+	// sidecar unwraps under the id-derived KEK (path plays no role).
+	sidecar, err := os.ReadFile(path + dekSuffix)
+	if err != nil {
+		t.Fatalf("read sidecar: %v", err)
+	}
+	if dek, err := unwrapSidecar(testMaster(t), sidecar); err != nil || len(dek) != 32 {
+		t.Fatalf("unwrap sidecar: dek=%d err=%v", len(dek), err)
+	}
+
+	// RED HIGH: the plaintext backup must be GONE (shredded), not lingering.
+	if fileExists(path + plainBakSuffix) {
+		t.Errorf("SECURITY: plaintext backup %s survived migration (must be shredded)", path+plainBakSuffix)
+	}
+
+	var name string
+	if err := db.QueryRow(`SELECT name FROM crm_companies WHERE id='co-5'`).Scan(&name); err != nil || name != "Co 5" {
+		t.Errorf("content check: got %q err %v", name, err)
+	}
+}
+
+// TestOpenIdempotent: a second Open of an already-migrated db is a no-op.
+func TestOpenIdempotent(t *testing.T) {
+	requireCipher(t)
+	path := filepath.Join(t.TempDir(), "treasury.db")
+	want := makePlaintextDB(t, path, 5, 5)
+
+	resetMaster(testMaster(t))
+	db1, err := Open(path)
+	if err != nil {
+		t.Fatalf("first open: %v", err)
+	}
+	_ = db1.Close()
+	hdr1 := firstBytes(t, path, 16)
+
+	db2, err := Open(path)
+	if err != nil {
+		t.Fatalf("second open: %v", err)
+	}
+	defer func() { _ = db2.Close() }()
+	if isPlaintextHeader(path) {
+		t.Fatalf("db became plaintext on reopen")
+	}
+	for tbl, n := range want {
+		if got := rowCount(t, db2, tbl); got != n {
+			t.Errorf("reopen row-count %s: want %d got %d", tbl, n, got)
+		}
+	}
+	if string(hdr1) != string(firstBytes(t, path, 16)) {
+		t.Errorf("header changed on reopen (pages rewritten?)")
+	}
+}
+
+// TestFreshCreateEncrypted: a brand-new db is born encrypted.
+func TestFreshCreateEncrypted(t *testing.T) {
+	requireCipher(t)
+	path := filepath.Join(t.TempDir(), "wallets.db")
+	resetMaster(testMaster(t))
+	db, err := Open(path)
+	if err != nil {
+		t.Fatalf("open fresh: %v", err)
+	}
+	if _, err := db.Exec(`CREATE TABLE w(addr TEXT, org TEXT)`); err != nil {
+		t.Fatalf("ddl: %v", err)
+	}
+	_ = db.Close()
+	if isPlaintextHeader(path) {
+		t.Fatalf("fresh db is plaintext")
+	}
+	if !fileExists(path + dekSuffix) {
+		t.Fatalf("fresh db has no sidecar")
+	}
+}
+
+// TestWrongMasterFailsClosed: a sidecar minted under one master cannot open under
+// another — a lifted file + wrong key yields an error, never plaintext.
+func TestWrongMasterFailsClosed(t *testing.T) {
+	requireCipher(t)
+	path := filepath.Join(t.TempDir(), "audit.db")
+	makePlaintextDB(t, path, 3, 3)
+
+	resetMaster(testMaster(t))
+	db, err := Open(path)
+	if err != nil {
+		t.Fatalf("migrate: %v", err)
+	}
+	_ = db.Close()
+
+	other := make([]byte, 32)
+	for i := range other {
+		other[i] = 0xAB
+	}
+	resetMaster(other)
+	if _, err := Open(path); err == nil {
+		t.Fatalf("SECURITY: opened encrypted db under the WRONG master key")
+	}
+}
+
+// TestDataDirMoveNoBrick (RED MED #2, PoC): the KEK binds to the sidecar fileID,
+// NOT CLOUD_DATA_DIR, so changing/unsetting the data dir — or moving the file to
+// a different path — must NOT brick the store.
+func TestDataDirMoveNoBrick(t *testing.T) {
+	requireCipher(t)
+	dir1 := t.TempDir()
+	pathA := filepath.Join(dir1, "crm.db")
+	want := makePlaintextDB(t, pathA, 8, 8)
+
+	t.Setenv("CLOUD_DATA_DIR", dir1)
+	resetMaster(testMaster(t))
+	db, err := Open(pathA)
+	if err != nil {
+		t.Fatalf("migrate under dir1: %v", err)
+	}
+	_ = db.Close()
+
+	// Simulate a data-dir change AND a physical move to a different filename.
+	dir2 := t.TempDir()
+	pathB := filepath.Join(dir2, "moved.db")
+	copyFile(t, pathA, pathB)
+	copyFile(t, pathA+dekSuffix, pathB+dekSuffix)
+	t.Setenv("CLOUD_DATA_DIR", "/some/other/root") // the old brick trigger
+
+	db2, err := Open(pathB) // KEK from fileID → must still open
+	if err != nil {
+		t.Fatalf("AVAILABILITY: data-dir change bricked the store: %v", err)
+	}
+	defer func() { _ = db2.Close() }()
+	for tbl, n := range want {
+		if got := rowCount(t, db2, tbl); got != n {
+			t.Errorf("moved db row-count %s: want %d got %d", tbl, n, got)
+		}
+	}
+}
+
+// TestMissingKeyFatalOnCapableBuild (RED MED #3): an encryption-capable build
+// with NO master key must FAIL CLOSED, never silently open plaintext. On a
+// pure-Go build the same absence is dev-mode plaintext.
+func TestMissingKeyFatalOnCapableBuild(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "settings.db")
+	resetMaster(nil)
+	os.Unsetenv(masterKeyEnv)
+
+	_, err := Open(path)
+	if sqlitedrv.EncryptionAvailable() {
+		if err == nil {
+			t.Fatalf("SECURITY: capable build opened the data plane with NO master key (silent plaintext)")
+		}
+		if fileExists(path) {
+			t.Fatalf("SECURITY: a db file was created despite the fatal missing-key error")
+		}
+	} else {
+		if err != nil {
+			t.Fatalf("pure-Go dev build should allow plaintext when no key: %v", err)
+		}
+	}
+}
+
+// TestContentHashCatchesMutation (RED MED #4): the content hash catches a value
+// change that row-count + schema + integrity_check all miss, AND does NOT
+// false-positive on the benign implicit-rowid renumbering sqlcipher_export does.
+func TestContentHashCatchesMutation(t *testing.T) {
+	requireCipher(t)
+	a := filepath.Join(t.TempDir(), "a.db")
+	b := filepath.Join(t.TempDir(), "b.db")
+	makePlaintextDB(t, a, 10, 10)
+	makePlaintextDB(t, b, 10, 10)
+	if inventoryOf(t, a).tables["crm_contacts"].content != inventoryOf(t, b).tables["crm_contacts"].content {
+		t.Fatalf("identical data produced different content hashes")
+	}
+
+	// Mutate ONE value in b (same row count, same schema, integrity stays ok).
+	base := inventoryOf(t, a).tables["crm_contacts"]
+	mutate(t, b, `UPDATE crm_contacts SET email='HIJACKED' WHERE id='ct-3'`)
+	after := inventoryOf(t, b).tables["crm_contacts"]
+	if after.count != base.count {
+		t.Fatalf("mutation changed the row count; test would not isolate content")
+	}
+	if base.content == after.content {
+		t.Fatalf("SECURITY: content hash did NOT catch a value mutation (count-blind gate)")
+	}
+
+	// Benign rowid renumber (delete+reinsert identical row, VACUUM) must NOT change it.
+	c := filepath.Join(t.TempDir(), "c.db")
+	makePlaintextDB(t, c, 10, 10)
+	before := inventoryOf(t, c).tables["crm_contacts"].content
+	mutate(t, c, `DELETE FROM crm_contacts WHERE id='ct-0'; INSERT INTO crm_contacts(id,org,email) VALUES('ct-0','maxpower','u0@x.io'); VACUUM`)
+	if before != inventoryOf(t, c).tables["crm_contacts"].content {
+		t.Errorf("content hash false-positived on a rowid renumber (re-inserted identical row)")
+	}
+}
+
+// TestCorruptSidecarFailsClosed (RED re-test #5, safety net): any undecryptable
+// state — a corrupted or missing .dek sidecar, the family a libsqlcipher format
+// mismatch would land in — FAILS CLOSED (errors), never silently opening
+// plaintext or a garbage db. (Cross-version format stability itself is enforced
+// by freezing the libsqlcipher version in the build; an at-open cipher_compat
+// pin is infeasible with mattn's URI-key requirement — see openKeyed.)
+func TestCorruptSidecarFailsClosed(t *testing.T) {
+	requireCipher(t)
+	path := filepath.Join(t.TempDir(), "audit.db")
+	makePlaintextDB(t, path, 4, 4)
+
+	resetMaster(testMaster(t))
+	db, err := Open(path)
+	if err != nil {
+		t.Fatalf("migrate: %v", err)
+	}
+	_ = db.Close()
+
+	// Flip a byte in the wrapped-DEK region of the sidecar → GCM tag fails.
+	sc, err := os.ReadFile(path + dekSuffix)
+	if err != nil {
+		t.Fatalf("read sidecar: %v", err)
+	}
+	sc[len(sc)-1] ^= 0xFF
+	if err := os.WriteFile(path+dekSuffix, sc, 0o600); err != nil {
+		t.Fatalf("write sidecar: %v", err)
+	}
+	resetMaster(testMaster(t))
+	if _, err := Open(path); err == nil {
+		t.Fatalf("SECURITY: opened an encrypted db with a corrupted DEK sidecar")
+	}
+
+	// A missing sidecar over an encrypted db must also refuse (never open blind).
+	if err := os.Remove(path + dekSuffix); err != nil {
+		t.Fatalf("rm sidecar: %v", err)
+	}
+	resetMaster(testMaster(t))
+	if _, err := Open(path); err == nil {
+		t.Fatalf("SECURITY: opened an encrypted db with NO DEK sidecar")
+	}
+}
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+func inventoryOf(t *testing.T, path string) inventory {
+	t.Helper()
+	db, err := sql.Open("sqlite", sqlitedrv.DSN(path, nil))
+	if err != nil {
+		t.Fatalf("open for inventory: %v", err)
+	}
+	defer func() { _ = db.Close() }()
+	db.SetMaxOpenConns(1)
+	conn, err := db.Conn(context.Background())
+	if err != nil {
+		t.Fatalf("conn: %v", err)
+	}
+	defer func() { _ = conn.Close() }()
+	inv, err := readInventory(context.Background(), conn)
+	if err != nil {
+		t.Fatalf("readInventory: %v", err)
+	}
+	return inv
+}
+
+func mutate(t *testing.T, path, sqlText string) {
+	t.Helper()
+	db, err := sql.Open("sqlite", sqlitedrv.DSN(path, nil))
+	if err != nil {
+		t.Fatalf("open mutate: %v", err)
+	}
+	defer func() { _ = db.Close() }()
+	if _, err := db.Exec(sqlText); err != nil {
+		t.Fatalf("mutate %q: %v", sqlText, err)
+	}
+}
+
+func copyFile(t *testing.T, src, dst string) {
+	t.Helper()
+	b, err := os.ReadFile(src)
+	if err != nil {
+		t.Fatalf("read %s: %v", src, err)
+	}
+	if err := os.WriteFile(dst, b, 0o600); err != nil {
+		t.Fatalf("write %s: %v", dst, err)
+	}
+}

cek/frozen_test.go

@@ -0,0 +1,100 @@
+package cek
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+// The frozen fixture pins the SQLCipher on-disk FORMAT the data plane is written
+// with. A committed encrypted store (created under the build's frozen
+// libsqlcipher) is opened by TestFrozenFixtureOpens; if a future libsqlcipher
+// upgrade changes the default cipher format, opening a store written under the
+// old format FAILS — turning a silent prod brick into a red CI. (Build-time
+// SQLITE_REQUIRE_CODEC only proves a FRESH db encrypts; it cannot detect a format
+// change against pre-existing stores — the fixture is what does.)
+
+const frozenCanary = "cek-format-canary-v1"
+
+// frozenMaster is a FIXED, obviously-fake test key (0x00..0x1f) used only to wrap
+// the committed fixture's DEK. Not a secret; never used in production.
+func frozenMaster() []byte {
+	k := make([]byte, 32)
+	for i := range k {
+		k[i] = byte(i)
+	}
+	return k
+}
+
+const frozenDir = "testdata/frozen"
+
+// TestGenerateFrozenFixture (re)writes the committed fixture. Gated on
+// CEK_GEN_FIXTURE=1 and run by hand ONLY when the format is intentionally rev'd;
+// the committed bytes are otherwise frozen.
+func TestGenerateFrozenFixture(t *testing.T) {
+	if os.Getenv("CEK_GEN_FIXTURE") != "1" {
+		t.Skip("set CEK_GEN_FIXTURE=1 to regenerate the frozen fixture")
+	}
+	requireCipher(t)
+	if err := os.MkdirAll(frozenDir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	dbPath := filepath.Join(frozenDir, "store.db")
+	for _, s := range []string{"", dekSuffix, "-wal", "-shm"} {
+		_ = os.Remove(dbPath + s)
+	}
+	dek, sidecar, err := mintSidecar(frozenMaster())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(dbPath+dekSuffix, sidecar, 0o600); err != nil {
+		t.Fatal(err)
+	}
+	h, err := openKeyed(dbPath, dek)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := h.Exec(`CREATE TABLE frozen(id INTEGER PRIMARY KEY, note TEXT)`); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := h.Exec(`INSERT INTO frozen VALUES(1,?)`, frozenCanary); err != nil {
+		t.Fatal(err)
+	}
+	_, _ = h.Exec(`PRAGMA wal_checkpoint(TRUNCATE)`) // fold into the main .db
+	_ = h.Close()
+	_ = os.Remove(dbPath + "-wal")
+	_ = os.Remove(dbPath + "-shm")
+	if isPlaintextHeader(dbPath) {
+		t.Fatal("generated fixture is plaintext")
+	}
+	t.Logf("wrote frozen fixture %s (+%s)", dbPath, dekSuffix)
+}
+
+// TestFrozenFixtureOpens opens the COMMITTED encrypted fixture (copied to temp so
+// the committed bytes are never mutated) and reads its canary row. A libsqlcipher
+// format change makes this fail — a red CI instead of a silent prod brick.
+func TestFrozenFixtureOpens(t *testing.T) {
+	requireCipher(t)
+	src := filepath.Join(frozenDir, "store.db")
+	if !fileExists(src) {
+		t.Fatal("frozen fixture missing — regenerate with CEK_GEN_FIXTURE=1 and commit testdata/frozen/")
+	}
+	dir := t.TempDir()
+	dst := filepath.Join(dir, "store.db")
+	copyFile(t, src, dst)
+	copyFile(t, src+dekSuffix, dst+dekSuffix)
+
+	resetMaster(frozenMaster())
+	db, err := Open(dst)
+	if err != nil {
+		t.Fatalf("FORMAT DRIFT: frozen fixture failed to open (libsqlcipher format changed?): %v", err)
+	}
+	defer func() { _ = db.Close() }()
+	var note string
+	if err := db.QueryRow(`SELECT note FROM frozen WHERE id=1`).Scan(&note); err != nil {
+		t.Fatalf("read canary: %v", err)
+	}
+	if note != frozenCanary {
+		t.Fatalf("canary mismatch: got %q want %q", note, frozenCanary)
+	}
+}

cli/agent.go

@@ -0,0 +1,74 @@
+package cli
+
+// agent.go — `hanzo agent`: invoke a managed Hanzo agent with a task.
+//
+// An agent is a managed capability (its own /v1/agents subsystem, self-metered),
+// NOT your artifact — so it is a peer verb of `hanzo run`, not a run kind. This is
+// the HEADLESS flavor: a task/tool/code agent, no computer. The computer-using
+// flavor (a booted desktop/terminal) is `hanzo bot` (see bot.go).
+//
+//	hanzo agent run <ref> "<task>"  → POST /v1/agents/:ref/run
+//
+// Thin client: one authenticated call over the IAM token + env.CloudURL, reusing
+// cloudCall (run.go). See docs/architecture/compute-ladder.md.
+
+import (
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+
+	"github.com/spf13/cobra"
+)
+
+// AgentRunReq is the POST /v1/agents/:ref/run body — a task for a managed agent.
+type AgentRunReq struct {
+	Task    string `json:"task"`
+	GPU     bool   `json:"gpu,omitempty"`
+	Timeout string `json:"timeout,omitempty"`
+	Repo    string `json:"repo,omitempty"`
+}
+
+// AgentRunResult is the agent-run acceptance.
+type AgentRunResult struct {
+	RunID  string `json:"runId"`
+	Status string `json:"status"`
+	URL    string `json:"url"`
+}
+
+func newAgentCmd(envOf func() *Env, _ *globalFlags) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "agent",
+		Short: "Invoke a managed Hanzo agent to run a task (headless)",
+		Long: "Invoke a managed agent by ref (e.g. a coding or tool agent) to run a task on\n" +
+			"Hanzo compute — metered per run. For a computer-using agent (booted desktop\n" +
+			"or terminal), use `hanzo bot`.",
+	}
+	cmd.AddCommand(newAgentRunCmd(envOf))
+	return cmd
+}
+
+func newAgentRunCmd(envOf func() *Env) *cobra.Command {
+	var req AgentRunReq
+	c := &cobra.Command{
+		Use:   "run <ref> <task>",
+		Short: "Run a task with the named agent (POST /v1/agents/:ref/run)",
+		Args:  cobra.MinimumNArgs(2),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			env := envOf()
+			ref := args[0]
+			req.Task = strings.Join(args[1:], " ")
+			out := &AgentRunResult{}
+			if err := cloudCall(cmd.Context(), env, http.MethodPost, "/v1/agents/"+ref+"/run", &req, out); err != nil {
+				return err
+			}
+			return env.emit(out, func(w io.Writer) {
+				fmt.Fprintf(w, "%s\t%s\t%s\n", out.RunID, out.Status, out.URL)
+			})
+		},
+	}
+	c.Flags().BoolVar(&req.GPU, "gpu", false, "run the agent on a GPU node")
+	c.Flags().StringVar(&req.Timeout, "timeout", "", "max wall-clock (e.g. 30m)")
+	c.Flags().StringVar(&req.Repo, "repo", "", "a repo/checkout the agent operates on")
+	return c
+}

cli/auth.go

@@ -0,0 +1,381 @@
+package cli
+
+import (
+	"bufio"
+	"context"
+	"encoding/base64"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"os"
+	"strings"
+	"time"
+
+	"github.com/spf13/cobra"
+	"golang.org/x/term"
+)
+
+// iamClient is a thin client over the Hanzo IAM OAuth2 surface at
+// {issuer}/v1/iam/oauth/*. It speaks only the standard token + userinfo
+// endpoints; it holds no IAM business logic.
+type iamClient struct {
+	issuer   string
+	clientID string
+	http     *http.Client
+}
+
+func newIAMClient(issuer, clientID string) *iamClient {
+	return &iamClient{
+		issuer:   strings.TrimRight(issuer, "/"),
+		clientID: clientID,
+		http:     &http.Client{Timeout: 30 * time.Second},
+	}
+}
+
+// tokenResp is the OAuth2 token endpoint response (success or RFC-6749 error).
+type tokenResp struct {
+	AccessToken  string `json:"access_token"`
+	RefreshToken string `json:"refresh_token"`
+	TokenType    string `json:"token_type"`
+	ExpiresIn    int64  `json:"expires_in"`
+	Scope        string `json:"scope"`
+	Error        string `json:"error"`
+	ErrorDesc    string `json:"error_description"`
+}
+
+// postForm performs an x-www-form-urlencoded POST to an oauth endpoint and
+// decodes the token response, surfacing OAuth errors as Go errors.
+func (c *iamClient) postForm(ctx context.Context, endpoint string, form url.Values) (*tokenResp, error) {
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, c.issuer+endpoint, strings.NewReader(form.Encode()))
+	if err != nil {
+		return nil, err
+	}
+	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+	req.Header.Set("Accept", "application/json")
+	req.Header.Set("User-Agent", "hanzo-cli/"+Version)
+
+	resp, err := c.http.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+	body, _ := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
+
+	var tr tokenResp
+	if err := json.Unmarshal(body, &tr); err != nil {
+		return nil, fmt.Errorf("iam %s: HTTP %d: %s", endpoint, resp.StatusCode, strings.TrimSpace(string(body)))
+	}
+	if tr.Error != "" {
+		return nil, fmt.Errorf("iam %s: %s: %s", endpoint, tr.Error, tr.ErrorDesc)
+	}
+	if tr.AccessToken == "" {
+		return nil, fmt.Errorf("iam %s: HTTP %d: no access_token in response", endpoint, resp.StatusCode)
+	}
+	return &tr, nil
+}
+
+// passwordGrant exchanges username+password for a token (the live IAM client
+// supports password grant; device_code is hard-rejected server-side).
+func (c *iamClient) passwordGrant(ctx context.Context, username, password, scope string) (*tokenResp, error) {
+	return c.postForm(ctx, "/v1/iam/oauth/access_token", url.Values{
+		"grant_type": {"password"},
+		"client_id":  {c.clientID},
+		"username":   {username},
+		"password":   {password},
+		"scope":      {scope},
+	})
+}
+
+// refreshGrant exchanges a refresh token for a fresh access token.
+func (c *iamClient) refreshGrant(ctx context.Context, refreshToken string) (*tokenResp, error) {
+	return c.postForm(ctx, "/v1/iam/oauth/refresh_token", url.Values{
+		"grant_type":    {"refresh_token"},
+		"client_id":     {c.clientID},
+		"refresh_token": {refreshToken},
+	})
+}
+
+// decodeJWTClaims base64url-decodes a JWT's payload segment WITHOUT verifying
+// the signature — used only to display the user's own token claims locally.
+func decodeJWTClaims(token string) (map[string]any, error) {
+	parts := strings.Split(token, ".")
+	if len(parts) < 2 {
+		return nil, fmt.Errorf("not a JWT (need 3 dot-separated segments)")
+	}
+	payload, err := base64.RawURLEncoding.DecodeString(strings.TrimRight(parts[1], "="))
+	if err != nil {
+		return nil, fmt.Errorf("decode JWT payload: %w", err)
+	}
+	var claims map[string]any
+	if err := json.Unmarshal(payload, &claims); err != nil {
+		return nil, fmt.Errorf("parse JWT claims: %w", err)
+	}
+	return claims, nil
+}
+
+// claimString reads a string claim, tolerating absence.
+func claimString(claims map[string]any, key string) string {
+	if v, ok := claims[key].(string); ok {
+		return v
+	}
+	return ""
+}
+
+// credsFromToken builds a Credentials carrying the token plus the identity
+// fields decoded from its claims. expiresIn (token endpoint) wins for expiry;
+// otherwise the JWT `exp` claim is used.
+func credsFromToken(tr *tokenResp) *Credentials {
+	c := &Credentials{
+		AccessToken:  tr.AccessToken,
+		RefreshToken: tr.RefreshToken,
+		TokenType:    firstNonEmpty(tr.TokenType, "Bearer"),
+	}
+	if claims, err := decodeJWTClaims(tr.AccessToken); err == nil {
+		c.Subject = firstNonEmpty(claimString(claims, "email"), claimString(claims, "sub"))
+		c.Owner = claimString(claims, "owner")
+		if exp, ok := claims["exp"].(float64); ok {
+			c.Expiry = int64(exp)
+		}
+	}
+	if tr.ExpiresIn > 0 {
+		c.Expiry = time.Now().Add(time.Duration(tr.ExpiresIn) * time.Second).Unix()
+	}
+	return c
+}
+
+// ---------------------------------------------------------------------------
+// Commands: login / logout / whoami, grouped under `auth`.
+// ---------------------------------------------------------------------------
+
+// loginFlags are shared by `hanzo login` and `hanzo auth login`.
+type loginFlags struct {
+	username      string
+	passwordStdin bool
+	token         string
+	platformToken string
+	buildToken    string
+	scope         string
+}
+
+func runLogin(env *Env, lf *loginFlags, cmd *cobra.Command) error {
+	creds, err := LoadCredentials()
+	if err != nil {
+		return err
+	}
+
+	switch {
+	case lf.token != "":
+		// Paste an externally-minted token. Decode claims for identity.
+		tr := &tokenResp{AccessToken: lf.token, TokenType: "Bearer"}
+		creds = credsFromToken(tr)
+	default:
+		username := lf.username
+		if username == "" {
+			username, err = prompt(cmd, "Email: ")
+			if err != nil {
+				return err
+			}
+		}
+		password, err := readPassword(cmd, lf.passwordStdin)
+		if err != nil {
+			return err
+		}
+		iam := newIAMClient(env.IAMIssuer, env.ClientID)
+		tr, err := iam.passwordGrant(cmd.Context(), username, password, lf.scope)
+		if err != nil {
+			return err
+		}
+		creds = credsFromToken(tr)
+	}
+
+	// Optional machine-to-machine tokens for the platform control plane,
+	// stored alongside the identity so apps/deploy work post-login.
+	if lf.platformToken != "" {
+		creds.PlatformToken = lf.platformToken
+	}
+	if lf.buildToken != "" {
+		creds.BuildToken = lf.buildToken
+	}
+
+	if err := creds.Save(); err != nil {
+		return err
+	}
+	who := firstNonEmpty(creds.Subject, "(unknown)")
+	if creds.Owner != "" {
+		who += " @ " + creds.Owner
+	}
+	fmt.Fprintf(cmd.OutOrStdout(), "Logged in as %s (token expires %s)\n", who, shortTime(creds.Expiry))
+	return nil
+}
+
+func newLoginCmd(envOf func() *Env, _ *globalFlags) *cobra.Command {
+	lf := &loginFlags{}
+	cmd := &cobra.Command{
+		Use:   "login",
+		Short: "Authenticate against Hanzo IAM and store a token",
+		Long: "Authenticate against Hanzo IAM (hanzo.id) via the password grant and store\n" +
+			"the token in ~/.hanzo/credentials.json (mode 0600). Use --token to store an\n" +
+			"externally-minted token instead, and --platform-token to store the platform\n" +
+			"control-plane service token needed by apps/deploy/clusters.",
+		Args: cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error { return runLogin(envOf(), lf, cmd) },
+	}
+	bindLoginFlags(cmd, lf)
+	return cmd
+}
+
+func bindLoginFlags(cmd *cobra.Command, lf *loginFlags) {
+	f := cmd.Flags()
+	f.StringVarP(&lf.username, "username", "u", "", "IAM username/email")
+	f.BoolVar(&lf.passwordStdin, "password-stdin", false, "read the password from stdin (for automation)")
+	f.StringVar(&lf.token, "token", "", "store this access token directly (skip the password grant)")
+	f.StringVar(&lf.platformToken, "platform-token", "", "also store the platform control-plane service token")
+	f.StringVar(&lf.buildToken, "build-token", "", "also store the platform build-enqueue token")
+	f.StringVar(&lf.scope, "scope", "openid profile email", "OAuth scope")
+}
+
+func newLogoutCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:               "logout",
+		Short:             "Remove stored credentials",
+		Args:              cobra.NoArgs,
+		PersistentPreRunE: func(*cobra.Command, []string) error { return nil },
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			if err := DeleteCredentials(); err != nil {
+				return err
+			}
+			fmt.Fprintln(cmd.OutOrStdout(), "Logged out.")
+			return nil
+		},
+	}
+}
+
+func newWhoamiCmd(envOf func() *Env) *cobra.Command {
+	var verify bool
+	cmd := &cobra.Command{
+		Use:   "whoami",
+		Short: "Show the current identity from the stored token",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			env := envOf()
+			tok := env.accessToken()
+			if tok == "" {
+				return fmt.Errorf("not logged in: run `hanzo login`")
+			}
+			claims, err := decodeJWTClaims(tok)
+			if err != nil {
+				return err
+			}
+			if verify {
+				if err := verifyUserInfo(cmd.Context(), env, tok); err != nil {
+					return fmt.Errorf("token rejected by IAM: %w", err)
+				}
+			}
+			return env.emit(claims, func(w io.Writer) {
+				fmt.Fprintf(w, "email:   %s\n", claimString(claims, "email"))
+				fmt.Fprintf(w, "name:    %s\n", firstNonEmpty(claimString(claims, "displayName"), claimString(claims, "name")))
+				fmt.Fprintf(w, "org:     %s\n", claimString(claims, "owner"))
+				fmt.Fprintf(w, "subject: %s\n", claimString(claims, "sub"))
+				fmt.Fprintf(w, "issuer:  %s\n", claimString(claims, "iss"))
+				if exp, ok := claims["exp"].(float64); ok {
+					fmt.Fprintf(w, "expires: %s\n", shortTime(int64(exp)))
+				}
+				if verify {
+					fmt.Fprintln(w, "verified: yes (IAM userinfo accepted the token)")
+				}
+			})
+		},
+	}
+	cmd.Flags().BoolVar(&verify, "verify", false, "verify the token against the IAM userinfo endpoint")
+	return cmd
+}
+
+// verifyUserInfo calls the IAM userinfo endpoint with the bearer token; a 2xx
+// means IAM accepts the token as live.
+func verifyUserInfo(ctx context.Context, env *Env, token string) error {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, env.IAMIssuer+"/v1/iam/oauth/userinfo", nil)
+	if err != nil {
+		return err
+	}
+	req.Header.Set("Authorization", "Bearer "+token)
+	req.Header.Set("User-Agent", "hanzo-cli/"+Version)
+	resp, err := (&http.Client{Timeout: 20 * time.Second}).Do(req)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode/100 != 2 {
+		body, _ := io.ReadAll(io.LimitReader(resp.Body, 1<<16))
+		return fmt.Errorf("HTTP %d: %s", resp.StatusCode, strings.TrimSpace(string(body)))
+	}
+	return nil
+}
+
+// newAuthCmd is the `auth` group: login/logout/whoami plus `token` (print the
+// stored access token, for piping into other tools).
+func newAuthCmd(envOf func() *Env, gf *globalFlags) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "auth",
+		Short: "Manage authentication",
+	}
+	tokenCmd := &cobra.Command{
+		Use:   "token",
+		Short: "Print the stored access token",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			tok := envOf().accessToken()
+			if tok == "" {
+				return fmt.Errorf("not logged in: run `hanzo login`")
+			}
+			fmt.Fprintln(cmd.OutOrStdout(), tok)
+			return nil
+		},
+	}
+	cmd.AddCommand(newLoginCmd(envOf, gf), newLogoutCmd(), newWhoamiCmd(envOf), tokenCmd)
+	return cmd
+}
+
+// ---------------------------------------------------------------------------
+// Terminal helpers.
+// ---------------------------------------------------------------------------
+
+// prompt writes a prompt to stderr and reads a trimmed line from stdin.
+func prompt(cmd *cobra.Command, label string) (string, error) {
+	fmt.Fprint(cmd.ErrOrStderr(), label)
+	r := bufio.NewReader(cmd.InOrStdin())
+	line, err := r.ReadString('\n')
+	if err != nil && err != io.EOF {
+		return "", err
+	}
+	return strings.TrimSpace(line), nil
+}
+
+// readPassword reads a password without echo from the terminal, or as a plain
+// line from stdin when --password-stdin is set (automation) or stdin is not a
+// terminal.
+func readPassword(cmd *cobra.Command, fromStdin bool) (string, error) {
+	if fromStdin {
+		r := bufio.NewReader(cmd.InOrStdin())
+		line, err := r.ReadString('\n')
+		if err != nil && err != io.EOF {
+			return "", err
+		}
+		return strings.TrimRight(line, "\r\n"), nil
+	}
+	if f, ok := cmd.InOrStdin().(*os.File); ok && term.IsTerminal(int(f.Fd())) {
+		fmt.Fprint(cmd.ErrOrStderr(), "Password: ")
+		b, err := term.ReadPassword(int(f.Fd()))
+		fmt.Fprintln(cmd.ErrOrStderr())
+		return string(b), err
+	}
+	// Non-terminal stdin without --password-stdin: read a line so piped input
+	// still works, but nudge toward the explicit flag.
+	r := bufio.NewReader(cmd.InOrStdin())
+	line, err := r.ReadString('\n')
+	if err != nil && err != io.EOF {
+		return "", err
+	}
+	return strings.TrimRight(line, "\r\n"), nil
+}

cli/auth_test.go

@@ -0,0 +1,210 @@
+package cli
+
+import (
+	"bytes"
+	"context"
+	"encoding/base64"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+)
+
+// makeJWT builds an unsigned JWT (alg=none) carrying claims — enough to test
+// the local, signature-free claim decode the CLI uses for display.
+func makeJWT(claims map[string]any) string {
+	hdr := base64.RawURLEncoding.EncodeToString([]byte(`{"alg":"none","typ":"JWT"}`))
+	p, _ := json.Marshal(claims)
+	return hdr + "." + base64.RawURLEncoding.EncodeToString(p) + ".sig"
+}
+
+func TestDecodeJWTClaims(t *testing.T) {
+	tok := makeJWT(map[string]any{"email": "z@hanzo.ai", "owner": "hanzo", "sub": "abc", "exp": float64(1783110016)})
+	claims, err := decodeJWTClaims(tok)
+	if err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if claimString(claims, "email") != "z@hanzo.ai" || claimString(claims, "owner") != "hanzo" {
+		t.Fatalf("claims wrong: %+v", claims)
+	}
+	if _, err := decodeJWTClaims("not-a-jwt"); err == nil {
+		t.Fatalf("expected error for non-JWT")
+	}
+}
+
+func TestCredsFromToken(t *testing.T) {
+	tok := makeJWT(map[string]any{"email": "z@hanzo.ai", "owner": "hanzo", "exp": float64(2000000000)})
+	// expires_in present → wins over exp.
+	c := credsFromToken(&tokenResp{AccessToken: tok, RefreshToken: "r", ExpiresIn: 3600})
+	if c.Subject != "z@hanzo.ai" || c.Owner != "hanzo" || c.RefreshToken != "r" {
+		t.Fatalf("identity not extracted: %+v", c)
+	}
+	if c.Expiry == 2000000000 {
+		t.Fatalf("expires_in should win over exp claim")
+	}
+	// No expires_in → falls back to exp claim.
+	c2 := credsFromToken(&tokenResp{AccessToken: tok})
+	if c2.Expiry != 2000000000 {
+		t.Fatalf("exp claim fallback failed: %d", c2.Expiry)
+	}
+}
+
+func TestPasswordGrant(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/v1/iam/oauth/access_token" {
+			t.Errorf("path = %s", r.URL.Path)
+		}
+		_ = r.ParseForm()
+		if r.Form.Get("grant_type") != "password" || r.Form.Get("client_id") != "hanzo-console" ||
+			r.Form.Get("username") != "z@hanzo.ai" || r.Form.Get("password") != "pw" {
+			t.Errorf("bad form: %v", r.Form)
+		}
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"access_token":  makeJWT(map[string]any{"email": "z@hanzo.ai"}),
+			"token_type":    "Bearer",
+			"expires_in":    3600,
+			"refresh_token": "r",
+		})
+	}))
+	defer srv.Close()
+
+	c := newIAMClient(srv.URL, "hanzo-console")
+	tr, err := c.passwordGrant(context.Background(), "z@hanzo.ai", "pw", "openid")
+	if err != nil {
+		t.Fatalf("passwordGrant: %v", err)
+	}
+	if tr.AccessToken == "" || tr.RefreshToken != "r" {
+		t.Fatalf("token resp bad: %+v", tr)
+	}
+}
+
+func TestPasswordGrantError(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(400)
+		_ = json.NewEncoder(w).Encode(map[string]any{"error": "invalid_grant", "error_description": "bad password"})
+	}))
+	defer srv.Close()
+	c := newIAMClient(srv.URL, "hanzo-console")
+	_, err := c.passwordGrant(context.Background(), "u", "p", "openid")
+	if err == nil || !strings.Contains(err.Error(), "invalid_grant") {
+		t.Fatalf("expected invalid_grant error, got %v", err)
+	}
+}
+
+func TestRefreshGrant(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		_ = r.ParseForm()
+		if r.URL.Path != "/v1/iam/oauth/refresh_token" || r.Form.Get("grant_type") != "refresh_token" || r.Form.Get("refresh_token") != "rt" {
+			t.Errorf("bad refresh request: %s %v", r.URL.Path, r.Form)
+		}
+		_ = json.NewEncoder(w).Encode(map[string]any{"access_token": makeJWT(nil), "token_type": "Bearer"})
+	}))
+	defer srv.Close()
+	c := newIAMClient(srv.URL, "hanzo-console")
+	if _, err := c.refreshGrant(context.Background(), "rt"); err != nil {
+		t.Fatalf("refreshGrant: %v", err)
+	}
+}
+
+// runRoot executes the cobra root with args, returning stdout and any error.
+// stderr is discarded; stdin is provided for password prompts.
+func runRoot(t *testing.T, stdin string, args ...string) (string, error) {
+	t.Helper()
+	root := newRootCmd()
+	var out bytes.Buffer
+	root.SetOut(&out)
+	root.SetErr(new(bytes.Buffer))
+	root.SetIn(strings.NewReader(stdin))
+	root.SetArgs(args)
+	err := root.Execute()
+	return out.String(), err
+}
+
+func TestLoginCommandPasswordStdin(t *testing.T) {
+	sandbox(t)
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"access_token": makeJWT(map[string]any{"email": "z@hanzo.ai", "owner": "hanzo"}),
+			"token_type":   "Bearer", "expires_in": 3600,
+		})
+	}))
+	defer srv.Close()
+
+	out, err := runRoot(t, "pw\n", "login", "-u", "z@hanzo.ai", "--password-stdin", "--iam-issuer", srv.URL)
+	if err != nil {
+		t.Fatalf("login: %v", err)
+	}
+	if !strings.Contains(out, "Logged in as z@hanzo.ai @ hanzo") {
+		t.Fatalf("login output: %q", out)
+	}
+	creds, _ := LoadCredentials()
+	if creds.AccessToken == "" || creds.Subject != "z@hanzo.ai" {
+		t.Fatalf("credentials not persisted: %+v", creds)
+	}
+}
+
+func TestLoginTokenPasteAndPlatformToken(t *testing.T) {
+	sandbox(t)
+	tok := makeJWT(map[string]any{"email": "ops@hanzo.ai", "owner": "hanzo"})
+	out, err := runRoot(t, "", "login", "--token", tok, "--platform-token", "svc-123")
+	if err != nil {
+		t.Fatalf("login --token: %v", err)
+	}
+	if !strings.Contains(out, "ops@hanzo.ai") {
+		t.Fatalf("login output: %q", out)
+	}
+	creds, _ := LoadCredentials()
+	if creds.AccessToken != tok || creds.PlatformToken != "svc-123" {
+		t.Fatalf("creds not stored: %+v", creds)
+	}
+}
+
+func TestWhoamiCommand(t *testing.T) {
+	sandbox(t)
+	creds := credsFromToken(&tokenResp{AccessToken: makeJWT(map[string]any{
+		"email": "z@hanzo.ai", "name": "z", "owner": "hanzo", "sub": "u-1", "iss": "https://hanzo.id",
+	})})
+	if err := creds.Save(); err != nil {
+		t.Fatal(err)
+	}
+	out, err := runRoot(t, "", "whoami")
+	if err != nil {
+		t.Fatalf("whoami: %v", err)
+	}
+	for _, want := range []string{"z@hanzo.ai", "hanzo", "u-1", "https://hanzo.id"} {
+		if !strings.Contains(out, want) {
+			t.Fatalf("whoami missing %q in %q", want, out)
+		}
+	}
+}
+
+func TestWhoamiLoggedOut(t *testing.T) {
+	sandbox(t)
+	if _, err := runRoot(t, "", "whoami"); err == nil {
+		t.Fatalf("expected error when logged out")
+	}
+}
+
+func TestLogoutCommand(t *testing.T) {
+	sandbox(t)
+	(&Credentials{AccessToken: "x"}).Save()
+	if _, err := runRoot(t, "", "logout"); err != nil {
+		t.Fatalf("logout: %v", err)
+	}
+	if c, _ := LoadCredentials(); c.AccessToken != "" {
+		t.Fatalf("logout did not clear credentials")
+	}
+}
+
+func TestAuthTokenCommand(t *testing.T) {
+	sandbox(t)
+	(&Credentials{AccessToken: "the-token"}).Save()
+	out, err := runRoot(t, "", "auth", "token")
+	if err != nil {
+		t.Fatalf("auth token: %v", err)
+	}
+	if strings.TrimSpace(out) != "the-token" {
+		t.Fatalf("auth token output: %q", out)
+	}
+}

cli/bot.go

@@ -0,0 +1,82 @@
+package cli
+
+// bot.go — `hanzo bot`: launch a computer-using agent (a "bot").
+//
+// A bot is the COMPUTER-USING flavor of an agent: it quick-boots a terminal or
+// desktop sandbox on the operative stack (Hanzo's computer-use runtime — noVNC
+// desktop, shell, browser, tools), provisioned by visor, and drives that machine
+// to do the task. The headless flavor (no computer) is `hanzo agent` (agent.go).
+//
+//	hanzo bot run "<task>"            → boot a desktop bot, run the task
+//	hanzo bot run --terminal "<task>" → boot a terminal-only bot
+//
+// Thin client over the IAM token + env.CloudURL (reuses cloudCall, run.go). The
+// operative runtime + visor-provisioned machine do the work; the CLI only starts
+// the run and reports the live session URL. See docs/architecture/compute-ladder.md.
+
+import (
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+
+	"github.com/spf13/cobra"
+)
+
+// BotRunReq is the boot-a-computer-using-agent body. Surface selects the sandbox
+// the operative runtime drives: "desktop" (noVNC GUI) or "terminal" (shell only).
+type BotRunReq struct {
+	Task    string `json:"task"`
+	Surface string `json:"surface"` // desktop | terminal
+	GPU     bool   `json:"gpu,omitempty"`
+	Timeout string `json:"timeout,omitempty"`
+}
+
+// BotRunResult carries the live session: a URL to watch/attach (noVNC / terminal)
+// plus the run id.
+type BotRunResult struct {
+	RunID      string `json:"runId"`
+	Status     string `json:"status"`
+	SessionURL string `json:"sessionUrl"`
+}
+
+func newBotCmd(envOf func() *Env, _ *globalFlags) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "bot",
+		Short: "Launch a computer-using agent (booted desktop or terminal)",
+		Long: "Quick-boot a terminal or desktop sandbox on the operative computer-use\n" +
+			"runtime (visor-provisioned) and have an agent drive it to do a task —\n" +
+			"metered like any run. For a headless task agent, use `hanzo agent`.",
+	}
+	cmd.AddCommand(newBotRunCmd(envOf))
+	return cmd
+}
+
+func newBotRunCmd(envOf func() *Env) *cobra.Command {
+	var req BotRunReq
+	var terminal bool
+	c := &cobra.Command{
+		Use:   "run <task>",
+		Short: "Boot a computer-using bot and run the task",
+		Args:  cobra.MinimumNArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			env := envOf()
+			req.Task = strings.Join(args, " ")
+			req.Surface = "desktop"
+			if terminal {
+				req.Surface = "terminal"
+			}
+			out := &BotRunResult{}
+			if err := cloudCall(cmd.Context(), env, http.MethodPost, "/v1/bots/run", &req, out); err != nil {
+				return err
+			}
+			return env.emit(out, func(w io.Writer) {
+				fmt.Fprintf(w, "%s\t%s\t%s\n", out.RunID, out.Status, out.SessionURL)
+			})
+		},
+	}
+	c.Flags().BoolVar(&terminal, "terminal", false, "boot a terminal-only sandbox (default: desktop)")
+	c.Flags().BoolVar(&req.GPU, "gpu", false, "boot on a GPU machine")
+	c.Flags().StringVar(&req.Timeout, "timeout", "", "max wall-clock (e.g. 30m)")
+	return c
+}

cli/cli.go

@@ -0,0 +1,566 @@
+// Package cli is the Hanzo cloud-control CLI — the gcloud/doctl-class client
+// half of the `hanzo` binary.
+//
+// `hanzo <subsystem>` SERVES a subsystem (server mode, cmd/hanzo dispatch);
+// `hanzo <verb>` CONTROLS the live estate (client mode, this package):
+//
+//	hanzo login | auth        identity against hanzo.id (IAM)
+//	hanzo apps  list|get      the platform apps board (declared/running/drift)
+//	hanzo deploy              drive a platform redeploy (rolling, zero-downtime)
+//	hanzo clusters …          provision/list/select dedicated DOKS clusters
+//	hanzo build               enqueue a platform-native build (runner fabric)
+//	hanzo k8s …               current deploy target helpers
+//	hanzo config …            ~/.hanzo/config preferences
+//
+// It is a THIN client over surfaces that already exist — Hanzo IAM
+// (hanzo.id /v1/iam/oauth/*), the platform REST control plane
+// (platform.hanzo.ai /v1/*), and the cloud /v1 API. It invents no parallel
+// API and holds no business logic; every command is one HTTP call shaped by
+// resolved configuration. Secrets live only in ~/.hanzo (0600) or the
+// environment — never in source, never logged.
+package cli
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+	"time"
+
+	"github.com/spf13/cobra"
+)
+
+// Version is the binary version, set by cmd/hanzo from its -ldflags value so
+// the CLI and the server report one string. Used in the User-Agent.
+var Version = "dev"
+
+// Default endpoints. Overridable per-field via config / env / flag.
+const (
+	defaultIAMIssuer   = "https://hanzo.id"
+	defaultPlatformURL = "https://platform.hanzo.ai"
+	defaultCloudURL    = "https://api.hanzo.ai"
+	// hanzo-console is the only live IAM client that accepts the password
+	// grant today; a dedicated `hanzo-cli` client is a one-line IAM seed
+	// follow-up. Override with `--client-id` / HANZO_CLIENT_ID / config.
+	defaultClientID = "hanzo-console"
+)
+
+// controlCommands maps every client-mode verb to its one-line help. cmd/hanzo
+// reads this both to ROUTE (a first token in here means client mode) and to
+// list the commands in `hanzo help`, so the verb set is defined exactly once.
+var controlCommands = map[string]string{
+	"login":    "authenticate against Hanzo IAM (hanzo.id) and store a token",
+	"logout":   "remove stored credentials",
+	"whoami":   "show the current identity from the stored token",
+	"auth":     "manage authentication (login, logout, whoami, token)",
+	"apps":     "list/get the platform apps board (declared/running/drift)",
+	"deploy":   "drive a platform redeploy (rolling restart, zero-downtime)",
+	"clusters": "provision/list/select dedicated DOKS clusters",
+	"build":    "enqueue a platform-native build (runner fabric)",
+	"k8s":      "deploy-target helpers (current target)",
+	"config":   "view/edit ~/.hanzo/config preferences",
+	"security": "scan files for hardcoded secrets (local guardrail; no server/auth)",
+	"gpu":      "connect this machine's GPU to the Hanzo cloud fleet (connect/status/disconnect)",
+	"engine":   "run a local hanzo-engine (OpenAI + Anthropic model server)",
+	"runner":   "run this machine as a JIT CI runner for your org (GitHub Actions)",
+	"run":      "launch a workload on Hanzo compute (container or function)",
+	"agent":    "invoke a managed Hanzo agent to run a task (headless)",
+	"bot":      "launch a computer-using agent (booted desktop or terminal)",
+}
+
+// IsControlVerb reports whether sub is a client-mode command (and therefore
+// must be routed to this package, not the server dispatcher).
+func IsControlVerb(sub string) bool {
+	_, ok := controlCommands[sub]
+	return ok
+}
+
+// ControlCommands returns the verb→description map for `hanzo help`.
+func ControlCommands() map[string]string { return controlCommands }
+
+// Execute runs the control CLI with args (already stripped of "hanzo"). It is
+// the single entrypoint cmd/hanzo calls for client-mode verbs.
+func Execute(args []string) error {
+	root := newRootCmd()
+	root.SetArgs(args)
+	return root.Execute()
+}
+
+// ---------------------------------------------------------------------------
+// Config — non-secret preferences, ~/.hanzo/config (JSON).
+// ---------------------------------------------------------------------------
+
+// Config holds non-secret CLI preferences. Every field is optional; empty
+// fields fall back to the built-in defaults at resolution time.
+type Config struct {
+	Org         string `json:"org,omitempty"`
+	Output      string `json:"output,omitempty"` // "table" (default) | "json"
+	IAMIssuer   string `json:"iam_issuer,omitempty"`
+	PlatformURL string `json:"platform_url,omitempty"`
+	CloudURL    string `json:"cloud_url,omitempty"`
+	ClientID    string `json:"client_id,omitempty"`
+}
+
+// Credentials holds secret material, ~/.hanzo/credentials.json, mode 0600.
+// AccessToken/RefreshToken are the IAM user identity (from `hanzo login`);
+// PlatformToken/BuildToken are the machine-to-machine tokens the platform
+// REST control plane requires (it cannot validate IAM user tokens).
+type Credentials struct {
+	AccessToken   string `json:"access_token,omitempty"`
+	RefreshToken  string `json:"refresh_token,omitempty"`
+	TokenType     string `json:"token_type,omitempty"`
+	Expiry        int64  `json:"expiry,omitempty"` // unix seconds
+	Subject       string `json:"subject,omitempty"`
+	Owner         string `json:"owner,omitempty"` // org slug from the token
+	PlatformToken string `json:"platform_token,omitempty"`
+	BuildToken    string `json:"build_token,omitempty"`
+}
+
+// hanzoDir is ~/.hanzo, created 0700 if missing. Overridable with HANZO_HOME
+// (used by tests to sandbox the credential store).
+func hanzoDir() (string, error) {
+	if h := os.Getenv("HANZO_HOME"); h != "" {
+		return h, os.MkdirAll(h, 0o700)
+	}
+	home, err := os.UserHomeDir()
+	if err != nil {
+		return "", err
+	}
+	dir := filepath.Join(home, ".hanzo")
+	return dir, os.MkdirAll(dir, 0o700)
+}
+
+func configPath() (string, error) {
+	dir, err := hanzoDir()
+	if err != nil {
+		return "", err
+	}
+	if p := os.Getenv("HANZO_CONFIG"); p != "" {
+		return p, nil
+	}
+	return filepath.Join(dir, "config"), nil
+}
+
+func credentialsPath() (string, error) {
+	dir, err := hanzoDir()
+	if err != nil {
+		return "", err
+	}
+	return filepath.Join(dir, "credentials.json"), nil
+}
+
+// loadJSON reads a JSON file into v; a missing file is not an error (v is left
+// at its zero value) so first-run with no config/credentials just works.
+func loadJSON(path string, v any) error {
+	b, err := os.ReadFile(path)
+	if os.IsNotExist(err) {
+		return nil
+	}
+	if err != nil {
+		return err
+	}
+	if len(b) == 0 {
+		return nil
+	}
+	return json.Unmarshal(b, v)
+}
+
+// writeJSON writes v as indented JSON at path with the given mode, via a
+// temp-file rename so a crash mid-write never truncates the store.
+func writeJSON(path string, v any, mode os.FileMode) error {
+	b, err := json.MarshalIndent(v, "", "  ")
+	if err != nil {
+		return err
+	}
+	tmp := path + ".tmp"
+	if err := os.WriteFile(tmp, append(b, '\n'), mode); err != nil {
+		return err
+	}
+	return os.Rename(tmp, path)
+}
+
+// LoadConfig reads ~/.hanzo/config (or HANZO_CONFIG).
+func LoadConfig() (*Config, error) {
+	p, err := configPath()
+	if err != nil {
+		return nil, err
+	}
+	c := &Config{}
+	return c, loadJSON(p, c)
+}
+
+// Save persists the config (mode 0644 — non-secret).
+func (c *Config) Save() error {
+	p, err := configPath()
+	if err != nil {
+		return err
+	}
+	return writeJSON(p, c, 0o644)
+}
+
+// LoadCredentials reads ~/.hanzo/credentials.json.
+func LoadCredentials() (*Credentials, error) {
+	p, err := credentialsPath()
+	if err != nil {
+		return nil, err
+	}
+	c := &Credentials{}
+	return c, loadJSON(p, c)
+}
+
+// Save persists credentials with mode 0600 (owner read/write only).
+func (c *Credentials) Save() error {
+	p, err := credentialsPath()
+	if err != nil {
+		return err
+	}
+	return writeJSON(p, c, 0o600)
+}
+
+// DeleteCredentials removes the credential store (used by logout).
+func DeleteCredentials() error {
+	p, err := credentialsPath()
+	if err != nil {
+		return err
+	}
+	if err := os.Remove(p); err != nil && !os.IsNotExist(err) {
+		return err
+	}
+	return nil
+}
+
+// ---------------------------------------------------------------------------
+// Env — the effective, resolved settings a command operates with.
+// ---------------------------------------------------------------------------
+
+// Env is the fully-resolved runtime context for a command: config + creds
+// merged with environment and the global flags. Built once in the root's
+// PersistentPreRunE and read by every subcommand.
+type Env struct {
+	cfg   *Config
+	creds *Credentials
+
+	Org         string
+	Output      string
+	IAMIssuer   string
+	PlatformURL string
+	CloudURL    string
+	ClientID    string
+
+	out io.Writer
+}
+
+// flag values bound by the persistent flags (empty == unset, fall through).
+type globalFlags struct {
+	org, output, platformURL, iamIssuer, cloudURL, clientID, platformToken string
+}
+
+// firstNonEmpty returns the first non-empty argument, or "".
+func firstNonEmpty(vs ...string) string {
+	for _, v := range vs {
+		if v != "" {
+			return v
+		}
+	}
+	return ""
+}
+
+// resolve merges flags > env > config > built-in defaults into an Env. It is
+// pure given its inputs (config/creds are loaded by the caller) so it is
+// directly unit-testable.
+func resolve(cfg *Config, creds *Credentials, f globalFlags) *Env {
+	e := &Env{cfg: cfg, creds: creds, out: os.Stdout}
+	e.Output = firstNonEmpty(f.output, os.Getenv("HANZO_OUTPUT"), cfg.Output, "table")
+	e.IAMIssuer = strings.TrimRight(firstNonEmpty(f.iamIssuer, os.Getenv("HANZO_IAM_ISSUER"), cfg.IAMIssuer, defaultIAMIssuer), "/")
+	e.PlatformURL = strings.TrimRight(firstNonEmpty(f.platformURL, os.Getenv("HANZO_PLATFORM_URL"), cfg.PlatformURL, defaultPlatformURL), "/")
+	e.CloudURL = strings.TrimRight(firstNonEmpty(f.cloudURL, os.Getenv("HANZO_CLOUD_URL"), cfg.CloudURL, defaultCloudURL), "/")
+	e.ClientID = firstNonEmpty(f.clientID, os.Getenv("HANZO_CLIENT_ID"), cfg.ClientID, defaultClientID)
+	// Org for platform calls is the platform organization id (a distinct
+	// namespace from the IAM token's `owner` slug), so it comes only from
+	// flag/env/config — never silently from the token.
+	e.Org = firstNonEmpty(f.org, os.Getenv("HANZO_ORG"), cfg.Org)
+	return e
+}
+
+// accessToken is the IAM user token (identity / cloud calls).
+func (e *Env) accessToken() string {
+	return firstNonEmpty(os.Getenv("HANZO_TOKEN"), e.creds.AccessToken)
+}
+
+// platformToken resolves the platform control-plane service token. The
+// platform REST surface is machine-to-machine (it cannot validate IAM user
+// tokens), so apps/clusters/redeploy authenticate with this, sourced from
+// (in precedence) the bound --platform-token flag, the environment, then the
+// credential store. Never hardcoded.
+func (e *Env) platformToken(flagVal string) string {
+	return firstNonEmpty(
+		flagVal,
+		os.Getenv("HANZO_PLATFORM_TOKEN"),
+		os.Getenv("PLATFORM_SERVICE_TOKEN"),
+		os.Getenv("PAAS_SERVICE_TOKEN"),
+		e.creds.PlatformToken,
+	)
+}
+
+// buildToken resolves the platform build-enqueue token (a distinct credential
+// from the service token — see /v1/runner).
+func (e *Env) buildToken(flagVal string) string {
+	return firstNonEmpty(
+		flagVal,
+		os.Getenv("HANZO_BUILD_TOKEN"),
+		os.Getenv("PLATFORM_BUILD_CALLBACK_TOKEN"),
+		e.creds.BuildToken,
+	)
+}
+
+// requireOrg returns the resolved org or a clear error telling the user how to
+// set it.
+func (e *Env) requireOrg() (string, error) {
+	if e.Org == "" {
+		return "", fmt.Errorf("no org set: pass --org, set HANZO_ORG, or run `hanzo config set org <org>`")
+	}
+	return e.Org, nil
+}
+
+// ---------------------------------------------------------------------------
+// Output helpers — one place decides JSON vs human-readable tables.
+// ---------------------------------------------------------------------------
+
+// emit prints v as JSON when --output=json, otherwise calls table to render a
+// human view. This is the single output branch for every command.
+func (e *Env) emit(v any, table func(w io.Writer)) error {
+	if e.Output == "json" {
+		enc := json.NewEncoder(e.out)
+		enc.SetIndent("", "  ")
+		return enc.Encode(v)
+	}
+	table(e.out)
+	return nil
+}
+
+// ---------------------------------------------------------------------------
+// Root command + global flags.
+// ---------------------------------------------------------------------------
+
+func newRootCmd() *cobra.Command {
+	var f globalFlags
+	var env *Env
+
+	root := &cobra.Command{
+		Use:           "hanzo",
+		Short:         "Hanzo cloud control — manage the live Hanzo estate",
+		Long:          "hanzo — gcloud/doctl-class control for the Hanzo platform (IAM, apps, deploys, clusters, builds).",
+		SilenceUsage:  true,
+		SilenceErrors: false,
+		PersistentPreRunE: func(cmd *cobra.Command, _ []string) error {
+			cfg, err := LoadConfig()
+			if err != nil {
+				return fmt.Errorf("load config: %w", err)
+			}
+			creds, err := LoadCredentials()
+			if err != nil {
+				return fmt.Errorf("load credentials: %w", err)
+			}
+			env = resolve(cfg, creds, f)
+			env.out = cmd.OutOrStdout()
+			return nil
+		},
+	}
+
+	pf := root.PersistentFlags()
+	pf.StringVar(&f.org, "org", "", "organization (overrides config / HANZO_ORG)")
+	pf.StringVarP(&f.output, "output", "o", "", "output format: table|json")
+	pf.StringVar(&f.platformURL, "platform-url", "", "platform base URL (default "+defaultPlatformURL+")")
+	pf.StringVar(&f.iamIssuer, "iam-issuer", "", "IAM issuer (default "+defaultIAMIssuer+")")
+	pf.StringVar(&f.cloudURL, "cloud-url", "", "cloud API base URL (default "+defaultCloudURL+")")
+	pf.StringVar(&f.clientID, "client-id", "", "IAM OAuth client id (default "+defaultClientID+")")
+	pf.StringVar(&f.platformToken, "platform-token", "", "platform control-plane service token (else env/credential store)")
+
+	// envOf returns the resolved Env for a command's RunE (always non-nil after
+	// PersistentPreRunE).
+	envOf := func() *Env { return env }
+
+	root.AddCommand(
+		newVersionCmd(),
+		newAuthCmd(envOf, &f),
+		newLoginCmd(envOf, &f),
+		newLogoutCmd(),
+		newWhoamiCmd(envOf),
+		newAppsCmd(envOf, &f),
+		newDeployCmd(envOf, &f),
+		newClustersCmd(envOf, &f),
+		newBuildCmd(envOf, &f),
+		newK8sCmd(envOf, &f),
+		newConfigCmd(),
+		newSecurityCmd(envOf),
+		newGPUCmd(envOf, &f),
+		newEngineCmd(envOf, &f),
+		newRunnerCmd(envOf, &f),
+		newRunCmd(envOf, &f),
+		newAgentCmd(envOf, &f),
+		newBotCmd(envOf, &f),
+	)
+	return root
+}
+
+func newVersionCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:               "version",
+		Short:             "Print the hanzo version",
+		Args:              cobra.NoArgs,
+		PersistentPreRunE: func(*cobra.Command, []string) error { return nil },
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			fmt.Fprintf(cmd.OutOrStdout(), "hanzo %s\n", Version)
+			return nil
+		},
+	}
+}
+
+// ---------------------------------------------------------------------------
+// config command — view/edit the non-secret preference file.
+// ---------------------------------------------------------------------------
+
+func newConfigCmd() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:               "config",
+		Short:             "View/edit ~/.hanzo/config preferences",
+		PersistentPreRunE: func(*cobra.Command, []string) error { return nil },
+	}
+
+	configKeys := []string{"org", "output", "iam_issuer", "platform_url", "cloud_url", "client_id"}
+
+	get := &cobra.Command{
+		Use:   "get <key>",
+		Short: "Print one config value",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			cfg, err := LoadConfig()
+			if err != nil {
+				return err
+			}
+			v, err := cfg.field(args[0])
+			if err != nil {
+				return err
+			}
+			fmt.Fprintln(cmd.OutOrStdout(), v)
+			return nil
+		},
+	}
+
+	set := &cobra.Command{
+		Use:   "set <key> <value>",
+		Short: "Set one config value (keys: " + strings.Join(configKeys, ", ") + ")",
+		Args:  cobra.ExactArgs(2),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			cfg, err := LoadConfig()
+			if err != nil {
+				return err
+			}
+			if err := cfg.setField(args[0], args[1]); err != nil {
+				return err
+			}
+			if err := cfg.Save(); err != nil {
+				return err
+			}
+			fmt.Fprintf(cmd.OutOrStdout(), "set %s = %s\n", args[0], args[1])
+			return nil
+		},
+	}
+
+	list := &cobra.Command{
+		Use:   "list",
+		Short: "Print the full config",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			cfg, err := LoadConfig()
+			if err != nil {
+				return err
+			}
+			enc := json.NewEncoder(cmd.OutOrStdout())
+			enc.SetIndent("", "  ")
+			return enc.Encode(cfg)
+		},
+	}
+
+	path := &cobra.Command{
+		Use:   "path",
+		Short: "Print the config file path",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			p, err := configPath()
+			if err != nil {
+				return err
+			}
+			fmt.Fprintln(cmd.OutOrStdout(), p)
+			return nil
+		},
+	}
+
+	cmd.AddCommand(get, set, list, path)
+	return cmd
+}
+
+// field returns the named config value as a string.
+func (c *Config) field(key string) (string, error) {
+	switch key {
+	case "org":
+		return c.Org, nil
+	case "output":
+		return c.Output, nil
+	case "iam_issuer":
+		return c.IAMIssuer, nil
+	case "platform_url":
+		return c.PlatformURL, nil
+	case "cloud_url":
+		return c.CloudURL, nil
+	case "client_id":
+		return c.ClientID, nil
+	default:
+		return "", fmt.Errorf("unknown config key %q", key)
+	}
+}
+
+// setField sets the named config value.
+func (c *Config) setField(key, val string) error {
+	switch key {
+	case "org":
+		c.Org = val
+	case "output":
+		if val != "table" && val != "json" {
+			return fmt.Errorf("output must be table|json")
+		}
+		c.Output = val
+	case "iam_issuer":
+		c.IAMIssuer = val
+	case "platform_url":
+		c.PlatformURL = val
+	case "cloud_url":
+		c.CloudURL = val
+	case "client_id":
+		c.ClientID = val
+	default:
+		return fmt.Errorf("unknown config key %q", key)
+	}
+	return nil
+}
+
+// shortTime renders a unix timestamp for human tables; "" for zero.
+func shortTime(unix int64) string {
+	if unix == 0 {
+		return ""
+	}
+	return time.Unix(unix, 0).Format(time.RFC3339)
+}
+
+// sortedKeys returns the keys of m, sorted — for deterministic help output.
+func sortedKeys(m map[string]string) []string {
+	ks := make([]string, 0, len(m))
+	for k := range m {
+		ks = append(ks, k)
+	}
+	sort.Strings(ks)
+	return ks
+}

cli/cli_test.go

@@ -0,0 +1,240 @@
+package cli
+
+import (
+	"bytes"
+	"encoding/json"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// TestMain restores stdout (quiet.go redirected it to stderr at init) so go
+// test's own reporting stays on stdout.
+func TestMain(m *testing.M) {
+	RestoreStdout()
+	os.Exit(m.Run())
+}
+
+// sandbox isolates the credential/config store in a temp dir and clears every
+// env var resolve() consults, so tests are deterministic and never touch the
+// developer's real ~/.hanzo.
+func sandbox(t *testing.T) string {
+	t.Helper()
+	dir := t.TempDir()
+	t.Setenv("HANZO_HOME", dir)
+	for _, k := range []string{
+		"HANZO_CONFIG", "HANZO_OUTPUT", "HANZO_IAM_ISSUER", "HANZO_PLATFORM_URL",
+		"HANZO_CLOUD_URL", "HANZO_CLIENT_ID", "HANZO_ORG", "HANZO_TOKEN",
+		"HANZO_PLATFORM_TOKEN", "PLATFORM_SERVICE_TOKEN", "PAAS_SERVICE_TOKEN",
+		"HANZO_BUILD_TOKEN", "PLATFORM_BUILD_CALLBACK_TOKEN",
+	} {
+		t.Setenv(k, "")
+	}
+	return dir
+}
+
+func TestConfigRoundTrip(t *testing.T) {
+	sandbox(t)
+	in := &Config{Org: "acme", Output: "json", PlatformURL: "https://p.example", ClientID: "hanzo-console"}
+	if err := in.Save(); err != nil {
+		t.Fatalf("save: %v", err)
+	}
+	out, err := LoadConfig()
+	if err != nil {
+		t.Fatalf("load: %v", err)
+	}
+	if *out != *in {
+		t.Fatalf("round-trip mismatch: %+v != %+v", out, in)
+	}
+}
+
+func TestCredentialsRoundTripAndPerms(t *testing.T) {
+	dir := sandbox(t)
+	in := &Credentials{AccessToken: "tok", RefreshToken: "ref", TokenType: "Bearer", Subject: "z@hanzo.ai", Owner: "hanzo", PlatformToken: "pt"}
+	if err := in.Save(); err != nil {
+		t.Fatalf("save: %v", err)
+	}
+	fi, err := os.Stat(filepath.Join(dir, "credentials.json"))
+	if err != nil {
+		t.Fatalf("stat: %v", err)
+	}
+	if perm := fi.Mode().Perm(); perm != 0o600 {
+		t.Fatalf("credentials perm = %o, want 0600", perm)
+	}
+	out, err := LoadCredentials()
+	if err != nil {
+		t.Fatalf("load: %v", err)
+	}
+	if *out != *in {
+		t.Fatalf("round-trip mismatch: %+v != %+v", out, in)
+	}
+	if err := DeleteCredentials(); err != nil {
+		t.Fatalf("delete: %v", err)
+	}
+	if out, _ := LoadCredentials(); out.AccessToken != "" {
+		t.Fatalf("credentials not deleted")
+	}
+}
+
+func TestLoadMissingFilesIsZeroValue(t *testing.T) {
+	sandbox(t)
+	cfg, err := LoadConfig()
+	if err != nil || cfg.Org != "" {
+		t.Fatalf("missing config should be zero value, got %+v err %v", cfg, err)
+	}
+	creds, err := LoadCredentials()
+	if err != nil || creds.AccessToken != "" {
+		t.Fatalf("missing credentials should be zero value, got %+v err %v", creds, err)
+	}
+}
+
+func TestResolveDefaults(t *testing.T) {
+	sandbox(t)
+	e := resolve(&Config{}, &Credentials{}, globalFlags{})
+	if e.IAMIssuer != defaultIAMIssuer || e.PlatformURL != defaultPlatformURL ||
+		e.CloudURL != defaultCloudURL || e.ClientID != defaultClientID || e.Output != "table" {
+		t.Fatalf("defaults not applied: %+v", e)
+	}
+}
+
+func TestResolvePrecedenceFlagOverEnvOverConfig(t *testing.T) {
+	sandbox(t)
+	t.Setenv("HANZO_ORG", "env-org")
+	cfg := &Config{Org: "cfg-org", Output: "json"}
+	// Flag wins.
+	if e := resolve(cfg, &Credentials{}, globalFlags{org: "flag-org"}); e.Org != "flag-org" {
+		t.Fatalf("flag should win: %q", e.Org)
+	}
+	// Env beats config.
+	if e := resolve(cfg, &Credentials{}, globalFlags{}); e.Org != "env-org" {
+		t.Fatalf("env should beat config: %q", e.Org)
+	}
+	// Config used when no flag/env.
+	t.Setenv("HANZO_ORG", "")
+	if e := resolve(cfg, &Credentials{}, globalFlags{}); e.Org != "cfg-org" {
+		t.Fatalf("config should be used: %q", e.Org)
+	}
+}
+
+func TestPlatformTokenPrecedence(t *testing.T) {
+	sandbox(t)
+	e := resolve(&Config{}, &Credentials{PlatformToken: "from-creds"}, globalFlags{})
+	if got := e.platformToken(""); got != "from-creds" {
+		t.Fatalf("creds token: %q", got)
+	}
+	t.Setenv("PAAS_SERVICE_TOKEN", "from-paas")
+	if got := e.platformToken(""); got != "from-paas" {
+		t.Fatalf("PAAS env should beat creds: %q", got)
+	}
+	t.Setenv("PLATFORM_SERVICE_TOKEN", "from-platform")
+	if got := e.platformToken(""); got != "from-platform" {
+		t.Fatalf("PLATFORM env should beat PAAS: %q", got)
+	}
+	t.Setenv("HANZO_PLATFORM_TOKEN", "from-hanzo")
+	if got := e.platformToken(""); got != "from-hanzo" {
+		t.Fatalf("HANZO_PLATFORM_TOKEN should beat all envs: %q", got)
+	}
+	if got := e.platformToken("from-flag"); got != "from-flag" {
+		t.Fatalf("flag should beat everything: %q", got)
+	}
+}
+
+func TestBuildTokenPrecedence(t *testing.T) {
+	sandbox(t)
+	e := resolve(&Config{}, &Credentials{BuildToken: "creds"}, globalFlags{})
+	if got := e.buildToken(""); got != "creds" {
+		t.Fatalf("creds build token: %q", got)
+	}
+	t.Setenv("PLATFORM_BUILD_CALLBACK_TOKEN", "cb")
+	if got := e.buildToken(""); got != "cb" {
+		t.Fatalf("callback env: %q", got)
+	}
+	if got := e.buildToken("flag"); got != "flag" {
+		t.Fatalf("flag wins: %q", got)
+	}
+}
+
+func TestAccessTokenFromEnvOverCreds(t *testing.T) {
+	sandbox(t)
+	e := resolve(&Config{}, &Credentials{AccessToken: "creds"}, globalFlags{})
+	if got := e.accessToken(); got != "creds" {
+		t.Fatalf("creds token: %q", got)
+	}
+	t.Setenv("HANZO_TOKEN", "env")
+	if got := e.accessToken(); got != "env" {
+		t.Fatalf("env token should win: %q", got)
+	}
+}
+
+func TestRequireOrg(t *testing.T) {
+	sandbox(t)
+	e := resolve(&Config{}, &Credentials{}, globalFlags{})
+	if _, err := e.requireOrg(); err == nil {
+		t.Fatalf("expected error when org unset")
+	}
+	e = resolve(&Config{Org: "acme"}, &Credentials{}, globalFlags{})
+	if org, err := e.requireOrg(); err != nil || org != "acme" {
+		t.Fatalf("org=%q err=%v", org, err)
+	}
+}
+
+func TestConfigFieldGetSet(t *testing.T) {
+	c := &Config{}
+	if err := c.setField("org", "acme"); err != nil || c.Org != "acme" {
+		t.Fatalf("set org: %v", err)
+	}
+	if v, _ := c.field("org"); v != "acme" {
+		t.Fatalf("get org: %q", v)
+	}
+	if err := c.setField("output", "xml"); err == nil {
+		t.Fatalf("invalid output should error")
+	}
+	if err := c.setField("nope", "x"); err == nil {
+		t.Fatalf("unknown key should error")
+	}
+	if _, err := c.field("nope"); err == nil {
+		t.Fatalf("unknown key get should error")
+	}
+}
+
+func TestIsControlVerb(t *testing.T) {
+	for _, v := range []string{"login", "apps", "deploy", "clusters", "build", "k8s", "config", "auth", "whoami", "logout"} {
+		if !IsControlVerb(v) {
+			t.Errorf("%q should be a control verb", v)
+		}
+	}
+	for _, v := range []string{"iam", "kms", "cloud", "gateway", "datastore", "nope"} {
+		if IsControlVerb(v) {
+			t.Errorf("%q must NOT be a control verb (server mode)", v)
+		}
+	}
+}
+
+func TestEmitJSONvsTable(t *testing.T) {
+	// JSON branch: encodes the value, ignores the table func.
+	var jbuf bytes.Buffer
+	ej := &Env{Output: "json", out: &jbuf}
+	called := false
+	if err := ej.emit(map[string]string{"k": "v"}, func(_ io.Writer) { called = true }); err != nil {
+		t.Fatalf("emit json: %v", err)
+	}
+	if called {
+		t.Fatalf("table func must not run in json mode")
+	}
+	var got map[string]string
+	if err := json.Unmarshal(jbuf.Bytes(), &got); err != nil || got["k"] != "v" {
+		t.Fatalf("json output bad: %q (%v)", jbuf.String(), err)
+	}
+
+	// Table branch: runs the table func, does not emit JSON.
+	var tbuf bytes.Buffer
+	et := &Env{Output: "table", out: &tbuf}
+	if err := et.emit(map[string]string{"k": "v"}, func(w io.Writer) { _, _ = w.Write([]byte("ROW")) }); err != nil {
+		t.Fatalf("emit table: %v", err)
+	}
+	if !strings.Contains(tbuf.String(), "ROW") {
+		t.Fatalf("table output missing: %q", tbuf.String())
+	}
+}

cli/commands.go

@@ -0,0 +1,450 @@
+package cli
+
+import (
+	"fmt"
+	"io"
+	"text/tabwriter"
+
+	"github.com/spf13/cobra"
+)
+
+// platform builds a platform REST client from the resolved env + the global
+// --platform-token flag. The token may be empty here; the client surfaces a
+// precise error on first use.
+func (e *Env) platform(gf *globalFlags) *Platform {
+	return newPlatform(e.PlatformURL, e.platformToken(gf.platformToken))
+}
+
+// deref renders a *string for a table cell, "-" when nil/empty.
+func deref(p *string) string {
+	if p == nil || *p == "" {
+		return "-"
+	}
+	return *p
+}
+
+// yesno renders a bool for a table cell.
+func yesno(b bool) string {
+	if b {
+		return "yes"
+	}
+	return "no"
+}
+
+// newTab returns a tabwriter writing to w with a 2-space gutter.
+func newTab(w io.Writer) *tabwriter.Writer {
+	return tabwriter.NewWriter(w, 0, 0, 2, ' ', 0)
+}
+
+// ---------------------------------------------------------------------------
+// apps — the observe surface.
+// ---------------------------------------------------------------------------
+
+func newAppsCmd(envOf func() *Env, gf *globalFlags) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "apps",
+		Short: "List/get the platform apps board (declared/running/latest/drift)",
+	}
+
+	var envFilter, healthFilter string
+	var driftOnly bool
+
+	list := &cobra.Command{
+		Use:   "list",
+		Short: "List apps with declared/running tags, health and drift",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			e := envOf()
+			res, err := e.platform(gf).Apps(cmd.Context(), AppsQuery{
+				Org:    e.Org, // empty == all (single-tenant default)
+				Env:    envFilter,
+				Health: healthFilter,
+				Drift:  driftOnly,
+			})
+			if err != nil {
+				return err
+			}
+			return e.emit(res, func(w io.Writer) {
+				tw := newTab(w)
+				fmt.Fprintln(tw, "ORG\tAPP\tENV\tDECLARED\tRUNNING\tHEALTH\tDRIFT")
+				for _, a := range res.Apps {
+					fmt.Fprintf(tw, "%s\t%s\t%s\t%s\t%s\t%s\t%s\n",
+						a.Org, a.App, a.Env, deref(a.DeclaredTag), deref(a.RunningTag),
+						deref(a.Health), driftSeverity(a.Drift))
+				}
+				tw.Flush()
+				fmt.Fprintf(w, "\n%d apps  (ok=%d yellow=%d red=%d)\n",
+					res.Summary.Total, res.Summary.ByDrift["ok"],
+					res.Summary.ByDrift["yellow"], res.Summary.ByDrift["red"])
+			})
+		},
+	}
+	list.Flags().StringVar(&envFilter, "env", "", "filter by env: dev|test|main")
+	list.Flags().StringVar(&healthFilter, "health", "", "filter by health: green|yellow|red")
+	list.Flags().BoolVar(&driftOnly, "drift", false, "only rows that are drifting")
+
+	get := &cobra.Command{
+		Use:   "get <org/app/env>",
+		Short: "Get one app row by its <org>/<app>/<env> id",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			e := envOf()
+			a, err := e.platform(gf).App(cmd.Context(), args[0], e.Org)
+			if err != nil {
+				return err
+			}
+			return e.emit(a, func(w io.Writer) {
+				tw := newTab(w)
+				fmt.Fprintf(tw, "id:\t%s\n", a.ID)
+				fmt.Fprintf(tw, "org:\t%s\n", a.Org)
+				fmt.Fprintf(tw, "app:\t%s\n", a.App)
+				fmt.Fprintf(tw, "env:\t%s\n", a.Env)
+				fmt.Fprintf(tw, "repo:\t%s\n", a.Repo)
+				fmt.Fprintf(tw, "registry:\t%s\n", a.Registry)
+				fmt.Fprintf(tw, "declared:\t%s\n", deref(a.DeclaredTag))
+				fmt.Fprintf(tw, "running:\t%s\n", deref(a.RunningTag))
+				fmt.Fprintf(tw, "latest:\t%s\n", deref(a.LatestTag))
+				fmt.Fprintf(tw, "health:\t%s\n", deref(a.Health))
+				fmt.Fprintf(tw, "drift:\t%s\n", driftSeverity(a.Drift))
+				fmt.Fprintf(tw, "cluster:\t%s\n", deref(a.Cluster))
+				fmt.Fprintf(tw, "namespace:\t%s\n", deref(a.Namespace))
+				fmt.Fprintf(tw, "updated:\t%s\n", a.UpdatedAt)
+				tw.Flush()
+			})
+		},
+	}
+
+	sync := &cobra.Command{
+		Use:   "sync",
+		Short: "Trigger an inventory refresh of the apps board",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			e := envOf()
+			if err := e.platform(gf).SyncApps(cmd.Context()); err != nil {
+				return err
+			}
+			fmt.Fprintln(cmd.OutOrStdout(), "apps sync triggered")
+			return nil
+		},
+	}
+
+	cmd.AddCommand(list, get, sync)
+	return cmd
+}
+
+// ---------------------------------------------------------------------------
+// deploy — the drive surface (rolling restart, zero-downtime).
+// ---------------------------------------------------------------------------
+
+func newDeployCmd(envOf func() *Env, gf *globalFlags) *cobra.Command {
+	var project, environment string
+	cmd := &cobra.Command{
+		Use:   "deploy <container>",
+		Short: "Redeploy a container (rolling restart, zero-downtime)",
+		Long: "Drive a platform redeploy: a rolling restart of the container's k8s\n" +
+			"Deployment (re-pulls the image, recreates pods, zero downtime). Coordinates\n" +
+			"are exact — org (--org/config), project (--project), env (--env) and the\n" +
+			"container id (positional). This is the canonical PaaS-driven deploy.",
+		Args: cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			e := envOf()
+			org, err := e.requireOrg()
+			if err != nil {
+				return err
+			}
+			if project == "" || environment == "" {
+				return fmt.Errorf("--project and --env are required (the container's project/environment ids)")
+			}
+			container := args[0]
+			if err := e.platform(gf).Redeploy(cmd.Context(), org, project, environment, container); err != nil {
+				return err
+			}
+			fmt.Fprintf(cmd.OutOrStdout(), "redeployed %s (org=%s project=%s env=%s)\n", container, org, project, environment)
+			return nil
+		},
+	}
+	cmd.Flags().StringVar(&project, "project", "", "project id")
+	cmd.Flags().StringVar(&environment, "env", "", "environment id")
+	return cmd
+}
+
+// ---------------------------------------------------------------------------
+// clusters — dedicated DOKS cluster lifecycle.
+// ---------------------------------------------------------------------------
+
+func newClustersCmd(envOf func() *Env, gf *globalFlags) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:     "clusters",
+		Aliases: []string{"cluster"},
+		Short:   "Provision/list/select dedicated DOKS clusters",
+	}
+
+	list := &cobra.Command{
+		Use:   "list",
+		Short: "List the org's dedicated clusters",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			e := envOf()
+			org, err := e.requireOrg()
+			if err != nil {
+				return err
+			}
+			cs, err := e.platform(gf).Clusters(cmd.Context(), org)
+			if err != nil {
+				return err
+			}
+			return e.emit(cs, func(w io.Writer) {
+				tw := newTab(w)
+				fmt.Fprintln(tw, "NAME\tID\tREGION\tSTATUS\tPHASE\tACTIVE\tOPERATOR\tBASELINE")
+				for _, c := range cs {
+					fmt.Fprintf(tw, "%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n",
+						c.Name, c.DoksClusterID, c.Region, c.Status, c.Phase,
+						yesno(c.Active), yesno(c.OperatorInstalled), yesno(c.BaselineInstalled))
+				}
+				tw.Flush()
+				if len(cs) == 0 {
+					fmt.Fprintln(w, "(no dedicated clusters)")
+				}
+			})
+		},
+	}
+
+	get := &cobra.Command{
+		Use:   "get <cluster-id>",
+		Short: "Show one cluster",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			e := envOf()
+			org, err := e.requireOrg()
+			if err != nil {
+				return err
+			}
+			cs, err := e.platform(gf).Clusters(cmd.Context(), org)
+			if err != nil {
+				return err
+			}
+			for _, c := range cs {
+				if c.DoksClusterID == args[0] || c.Name == args[0] {
+					return e.emit(c, func(w io.Writer) { printCluster(w, c) })
+				}
+			}
+			return fmt.Errorf("cluster %q not found in org %s", args[0], org)
+		},
+	}
+
+	var region, nodeSize string
+	var ha bool
+	var nodeCount int
+	create := &cobra.Command{
+		Use:   "create",
+		Short: "Provision a new dedicated DOKS cluster for the org",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			e := envOf()
+			org, err := e.requireOrg()
+			if err != nil {
+				return err
+			}
+			c, err := e.platform(gf).ProvisionCluster(cmd.Context(), org, ProvisionReq{
+				Region: region, HA: ha, NodeSize: nodeSize, NodeCount: nodeCount,
+			})
+			if err != nil {
+				return err
+			}
+			return e.emit(c, func(w io.Writer) {
+				fmt.Fprintf(w, "provisioning cluster %s (%s)\n", c.Name, c.DoksClusterID)
+				printCluster(w, *c)
+			})
+		},
+	}
+	create.Flags().StringVar(&region, "region", "", "DO region (default sfo3)")
+	create.Flags().BoolVar(&ha, "ha", false, "highly-available control plane")
+	create.Flags().StringVar(&nodeSize, "node-size", "", "node size slug (e.g. s-2vcpu-4gb)")
+	create.Flags().IntVar(&nodeCount, "node-count", 0, "node count")
+
+	var shared bool
+	selectCmd := &cobra.Command{
+		Use:   "select <cluster-id>",
+		Short: "Set the org's active deploy target (or --shared to revert)",
+		Args:  cobra.MaximumNArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			e := envOf()
+			org, err := e.requireOrg()
+			if err != nil {
+				return err
+			}
+			var clusterID *string
+			switch {
+			case shared:
+				clusterID = nil
+			case len(args) == 1:
+				clusterID = &args[0]
+			default:
+				return fmt.Errorf("give a cluster id, or --shared to revert to the shared cluster")
+			}
+			t, err := e.platform(gf).SelectTarget(cmd.Context(), org, clusterID)
+			if err != nil {
+				return err
+			}
+			return e.emit(t, func(w io.Writer) { printTarget(w, t) })
+		},
+	}
+	selectCmd.Flags().BoolVar(&shared, "shared", false, "revert to the shared cluster")
+
+	installBaseline := &cobra.Command{
+		Use:   "install-baseline <cluster-id>",
+		Short: "Install the hanzo-operator + per-tenant baseline on a cluster",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			e := envOf()
+			org, err := e.requireOrg()
+			if err != nil {
+				return err
+			}
+			if err := e.platform(gf).InstallBaseline(cmd.Context(), org, args[0]); err != nil {
+				return err
+			}
+			fmt.Fprintf(cmd.OutOrStdout(), "baseline install requested for %s\n", args[0])
+			return nil
+		},
+	}
+
+	target := &cobra.Command{
+		Use:   "target",
+		Short: "Show the org's current resolved deploy target",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			e := envOf()
+			org, err := e.requireOrg()
+			if err != nil {
+				return err
+			}
+			t, err := e.platform(gf).Target(cmd.Context(), org)
+			if err != nil {
+				return err
+			}
+			return e.emit(t, func(w io.Writer) { printTarget(w, t) })
+		},
+	}
+
+	cmd.AddCommand(list, get, create, selectCmd, installBaseline, target)
+	return cmd
+}
+
+func printCluster(w io.Writer, c Cluster) {
+	tw := newTab(w)
+	fmt.Fprintf(tw, "id:\t%s\n", c.DoksClusterID)
+	fmt.Fprintf(tw, "name:\t%s\n", c.Name)
+	fmt.Fprintf(tw, "region:\t%s\n", c.Region)
+	fmt.Fprintf(tw, "status:\t%s\n", c.Status)
+	fmt.Fprintf(tw, "phase:\t%s\n", c.Phase)
+	fmt.Fprintf(tw, "active:\t%s\n", yesno(c.Active))
+	fmt.Fprintf(tw, "operatorInstalled:\t%s\n", yesno(c.OperatorInstalled))
+	fmt.Fprintf(tw, "baselineInstalled:\t%s\n", yesno(c.BaselineInstalled))
+	fmt.Fprintf(tw, "endpoint:\t%s\n", deref(c.Endpoint))
+	fmt.Fprintf(tw, "k8sVersion:\t%s\n", deref(c.K8sVersion))
+	fmt.Fprintf(tw, "created:\t%s\n", c.CreatedAt)
+	if c.BaselineError != nil && *c.BaselineError != "" {
+		fmt.Fprintf(tw, "baselineError:\t%s\n", *c.BaselineError)
+	}
+	tw.Flush()
+}
+
+func printTarget(w io.Writer, t *Target) {
+	tw := newTab(w)
+	kind := "shared"
+	if t.Dedicated {
+		kind = "dedicated"
+	}
+	fmt.Fprintf(tw, "cluster:\t%s\n", t.Cluster)
+	fmt.Fprintf(tw, "kind:\t%s\n", kind)
+	for ns, env := range t.Namespaces {
+		fmt.Fprintf(tw, "namespace:\t%s -> %s\n", ns, env)
+	}
+	tw.Flush()
+}
+
+// ---------------------------------------------------------------------------
+// build — platform-native build (runner fabric) enqueue.
+// ---------------------------------------------------------------------------
+
+func newBuildCmd(envOf func() *Env, gf *globalFlags) *cobra.Command {
+	var br BuildReq
+	var buildToken string
+	cmd := &cobra.Command{
+		Use:   "build <repo>",
+		Short: "Enqueue a platform-native build on the runner fabric (no GitHub builders)",
+		Long: "Enqueue a build on the platform's native runner fabric. Builds and pushes\n" +
+			"the named image at a SHA; on completion the platform patches the operator\n" +
+			"Service CR (build-job → deploy). Requires a live registered runner for the\n" +
+			"target pool (409 otherwise).",
+		Args: cobra.MaximumNArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			e := envOf()
+			if len(args) == 1 {
+				br.Repo = args[0]
+			}
+			if br.Repo == "" || br.SHA == "" || br.Image == "" {
+				return fmt.Errorf("--repo (or positional), --sha and --image are required")
+			}
+			if br.OrganizationID == "" {
+				br.OrganizationID = e.Org // optional; server defaults to DEFAULT_BUILD_ORG_ID
+			}
+			job, err := e.platform(gf).EnqueueBuild(cmd.Context(), br, e.buildToken(buildToken))
+			if err != nil {
+				return err
+			}
+			return e.emit(job, func(w io.Writer) {
+				tw := newTab(w)
+				fmt.Fprintf(tw, "buildJobId:\t%s\n", job.BuildJobID)
+				fmt.Fprintf(tw, "status:\t%s\n", job.Status)
+				fmt.Fprintf(tw, "runnerPool:\t%s\n", job.RunnerPool)
+				fmt.Fprintf(tw, "image:\t%s\n", job.Image)
+				fmt.Fprintf(tw, "target:\t%s\n", job.Target)
+				tw.Flush()
+			})
+		},
+	}
+	f := cmd.Flags()
+	f.StringVar(&br.Repo, "repo", "", "owner/name (e.g. hanzoai/pricing)")
+	f.StringVar(&br.SHA, "sha", "", "commit SHA to build")
+	f.StringVar(&br.Image, "image", "", "image to build+push (e.g. ghcr.io/hanzoai/pricing:<tag>)")
+	f.StringVar(&br.Branch, "branch", "", "branch (default main)")
+	f.StringVar(&br.Dockerfile, "dockerfile", "", "Dockerfile path")
+	f.StringVar(&br.Context, "context", "", "build context")
+	f.StringVar(&br.DockerTarget, "target", "", "Docker build stage (--target)")
+	f.StringVar(&br.OS, "os", "", "linux|darwin|windows (default linux)")
+	f.StringVar(&br.Arch, "arch", "", "amd64|arm64 (default amd64)")
+	f.StringVar(&buildToken, "build-token", "", "platform build-enqueue token (else env/credential store)")
+	return cmd
+}
+
+// ---------------------------------------------------------------------------
+// k8s — deploy-target helpers.
+// ---------------------------------------------------------------------------
+
+func newK8sCmd(envOf func() *Env, gf *globalFlags) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "k8s",
+		Short: "Kubernetes deploy-target helpers",
+	}
+	target := &cobra.Command{
+		Use:   "target",
+		Short: "Show the org's current resolved deploy target (cluster + namespaces)",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			e := envOf()
+			org, err := e.requireOrg()
+			if err != nil {
+				return err
+			}
+			t, err := e.platform(gf).Target(cmd.Context(), org)
+			if err != nil {
+				return err
+			}
+			return e.emit(t, func(w io.Writer) { printTarget(w, t) })
+		},
+	}
+	cmd.AddCommand(target)
+	return cmd
+}

cli/commands_test.go

@@ -0,0 +1,171 @@
+package cli
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+)
+
+// withPlatform points the CLI at an httptest platform via env (HANZO_PLATFORM_URL
+// + HANZO_PLATFORM_TOKEN), the same resolution path the real binary uses.
+func withPlatform(t *testing.T, h http.HandlerFunc) string {
+	t.Helper()
+	sandbox(t)
+	srv := httptest.NewServer(h)
+	t.Cleanup(srv.Close)
+	t.Setenv("HANZO_PLATFORM_URL", srv.URL)
+	t.Setenv("HANZO_PLATFORM_TOKEN", "svc-tok")
+	return srv.URL
+}
+
+func TestAppsListCommandTable(t *testing.T) {
+	withPlatform(t, func(w http.ResponseWriter, _ *http.Request) {
+		_ = json.NewEncoder(w).Encode(AppsList{
+			Apps: []AppView{
+				{Org: "hanzoai", App: "iam", Env: "main", DeclaredTag: strptr("v1.2.3"), RunningTag: strptr("v1.2.3"), Health: strptr("green"), Drift: json.RawMessage(`{"severity":"ok"}`)},
+			},
+			Summary: struct {
+				Total   int            `json:"total"`
+				ByDrift map[string]int `json:"byDrift"`
+			}{Total: 1, ByDrift: map[string]int{"ok": 1}},
+		})
+	})
+	out, err := runRoot(t, "", "apps", "list")
+	if err != nil {
+		t.Fatalf("apps list: %v", err)
+	}
+	for _, want := range []string{"APP", "iam", "v1.2.3", "green", "ok", "1 apps"} {
+		if !strings.Contains(out, want) {
+			t.Fatalf("apps list table missing %q in:\n%s", want, out)
+		}
+	}
+}
+
+func TestAppsListCommandJSON(t *testing.T) {
+	withPlatform(t, func(w http.ResponseWriter, _ *http.Request) {
+		_ = json.NewEncoder(w).Encode(AppsList{Apps: []AppView{{Org: "hanzoai", App: "iam", Env: "main"}}})
+	})
+	out, err := runRoot(t, "", "apps", "list", "-o", "json")
+	if err != nil {
+		t.Fatalf("apps list json: %v", err)
+	}
+	var res AppsList
+	if err := json.Unmarshal([]byte(out), &res); err != nil {
+		t.Fatalf("output is not valid JSON: %v\n%s", err, out)
+	}
+	if len(res.Apps) != 1 || res.Apps[0].App != "iam" {
+		t.Fatalf("json decode wrong: %+v", res.Apps)
+	}
+}
+
+func TestDeployCommand(t *testing.T) {
+	withPlatform(t, func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/v1/org/acme/project/p1/env/e1/container/app-x/redeploy" {
+			t.Errorf("redeploy path = %s", r.URL.Path)
+		}
+		_ = json.NewEncoder(w).Encode(map[string]bool{"ok": true})
+	})
+	out, err := runRoot(t, "", "deploy", "app-x", "--org", "acme", "--project", "p1", "--env", "e1")
+	if err != nil {
+		t.Fatalf("deploy: %v", err)
+	}
+	if !strings.Contains(out, "redeployed app-x") {
+		t.Fatalf("deploy output: %q", out)
+	}
+}
+
+func TestDeployRequiresProjectEnv(t *testing.T) {
+	withPlatform(t, func(w http.ResponseWriter, _ *http.Request) { w.WriteHeader(200) })
+	if _, err := runRoot(t, "", "deploy", "app-x", "--org", "acme"); err == nil {
+		t.Fatalf("deploy must require --project/--env")
+	}
+}
+
+func TestDeployRequiresOrg(t *testing.T) {
+	withPlatform(t, func(w http.ResponseWriter, _ *http.Request) { w.WriteHeader(200) })
+	if _, err := runRoot(t, "", "deploy", "app-x", "--project", "p1", "--env", "e1"); err == nil {
+		t.Fatalf("deploy must require an org")
+	}
+}
+
+func TestClustersListCommand(t *testing.T) {
+	withPlatform(t, func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/v1/org/acme/cluster" {
+			t.Errorf("path = %s", r.URL.Path)
+		}
+		_ = json.NewEncoder(w).Encode(map[string]any{"clusters": []Cluster{
+			{DoksClusterID: "c1", Name: "hanzo-acme", Region: "sfo3", Status: "running", Phase: "ready", Active: true, OperatorInstalled: true, BaselineInstalled: true},
+		}})
+	})
+	out, err := runRoot(t, "", "clusters", "list", "--org", "acme")
+	if err != nil {
+		t.Fatalf("clusters list: %v", err)
+	}
+	for _, want := range []string{"NAME", "hanzo-acme", "c1", "ready", "yes"} {
+		if !strings.Contains(out, want) {
+			t.Fatalf("clusters list missing %q in:\n%s", want, out)
+		}
+	}
+}
+
+func TestK8sTargetCommand(t *testing.T) {
+	withPlatform(t, func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/v1/org/acme/cluster/select" {
+			t.Errorf("path = %s", r.URL.Path)
+		}
+		_ = json.NewEncoder(w).Encode(map[string]any{"target": Target{Cluster: "hanzo-k8s", Dedicated: false, Namespaces: map[string]string{"hanzo": "main"}}})
+	})
+	out, err := runRoot(t, "", "k8s", "target", "--org", "acme")
+	if err != nil {
+		t.Fatalf("k8s target: %v", err)
+	}
+	if !strings.Contains(out, "hanzo-k8s") || !strings.Contains(out, "shared") {
+		t.Fatalf("k8s target output: %q", out)
+	}
+}
+
+func TestBuildCommandValidation(t *testing.T) {
+	withPlatform(t, func(w http.ResponseWriter, _ *http.Request) { w.WriteHeader(202) })
+	// Missing --sha/--image → validation error before any HTTP call.
+	if _, err := runRoot(t, "", "build", "hanzoai/pricing"); err == nil {
+		t.Fatalf("build must require --sha and --image")
+	}
+}
+
+func TestBuildCommand(t *testing.T) {
+	withPlatform(t, func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/v1/runner" {
+			t.Errorf("path = %s", r.URL.Path)
+		}
+		if got := r.Header.Get("Authorization"); got != "Bearer bt" {
+			t.Errorf("build auth = %q", got)
+		}
+		w.WriteHeader(202)
+		_ = json.NewEncoder(w).Encode(BuildJob{BuildJobID: "bj-9", Status: "queued", Image: "ghcr.io/hanzoai/pricing:t"})
+	})
+	out, err := runRoot(t, "", "build", "hanzoai/pricing", "--sha", "abc", "--image", "ghcr.io/hanzoai/pricing:t", "--build-token", "bt")
+	if err != nil {
+		t.Fatalf("build: %v", err)
+	}
+	if !strings.Contains(out, "bj-9") {
+		t.Fatalf("build output: %q", out)
+	}
+}
+
+func TestConfigSetGetCommand(t *testing.T) {
+	sandbox(t)
+	if _, err := runRoot(t, "", "config", "set", "org", "acme"); err != nil {
+		t.Fatalf("config set: %v", err)
+	}
+	out, err := runRoot(t, "", "config", "get", "org")
+	if err != nil {
+		t.Fatalf("config get: %v", err)
+	}
+	if strings.TrimSpace(out) != "acme" {
+		t.Fatalf("config get = %q", out)
+	}
+}
+
+func strptr(s string) *string { return &s }

cli/engine.go

@@ -0,0 +1,199 @@
+package cli
+
+// engine.go — `hanzo engine install|serve|status`: manage a local hanzo-engine
+// (the `hanzoai` OpenAI + Anthropic model server) on THIS machine.
+//
+// One source of truth for install logic: `install` runs the SAME install.sh /
+// install.ps1 the `curl … | sh` one-liner uses (it downloads the prebuilt,
+// cosign-signed binary from the latest github.com/hanzoai/engine release), so the
+// CLI never re-implements platform detection or verification. `serve` launches the
+// installed binary (`hanzoai --port P run -m MODEL`); `status` probes it, reusing
+// the same /v1/models probe `hanzo gpu connect --serve-engine` advertises with.
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"time"
+
+	"github.com/spf13/cobra"
+)
+
+const (
+	installScriptSh = "https://raw.githubusercontent.com/hanzoai/engine/main/install.sh"
+	installScriptPS = "https://raw.githubusercontent.com/hanzoai/engine/main/install.ps1"
+	engineBinName   = "hanzoai"
+)
+
+func newEngineCmd(envOf func() *Env, _ *globalFlags) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "engine",
+		Short: "Run a local hanzo-engine (OpenAI + Anthropic model server)",
+		Long: "Install, serve, and inspect a local hanzo-engine on this machine.\n" +
+			"`install` downloads the prebuilt, signed `hanzoai` binary; `serve` runs it on\n" +
+			":1234; `status` shows whether it is up and which models it serves.",
+	}
+
+	// install ----------------------------------------------------------------
+	var version, dir string
+	install := &cobra.Command{
+		Use:   "install",
+		Short: "Download + install the prebuilt hanzoai binary (runs the canonical install script)",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			return runEngineInstall(cmd, version, dir)
+		},
+	}
+	install.Flags().StringVar(&version, "engine-version", "", "install a specific release tag (default: latest)")
+	install.Flags().StringVar(&dir, "dir", "", "install directory (default: /usr/local/bin or ~/.local/bin)")
+
+	// serve ------------------------------------------------------------------
+	var model string
+	var port int
+	serve := &cobra.Command{
+		Use:   "serve",
+		Short: "Serve a model with the local hanzoai binary (hanzoai --port P run -m MODEL)",
+		Long: "Launch the installed hanzoai server. Any args after `--` are passed through to\n" +
+			"the underlying `hanzoai … run` invocation (e.g. `-- --max-seqs 32`).",
+		Args: cobra.ArbitraryArgs,
+		RunE: func(cmd *cobra.Command, extra []string) error {
+			return runEngineServe(cmd, model, port, extra)
+		},
+	}
+	serve.Flags().StringVarP(&model, "model", "m", "Qwen/Qwen3-4B", "model to serve (HF repo id or local path)")
+	serve.Flags().IntVarP(&port, "port", "p", 1234, "port to serve the OpenAI + Anthropic API on")
+
+	// status -----------------------------------------------------------------
+	var url string
+	status := &cobra.Command{
+		Use:   "status",
+		Short: "Show whether a local hanzo-engine is up and what it serves",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			return runEngineStatus(cmd, envOf(), firstNonEmpty(url, defaultEngineURL))
+		},
+	}
+	status.Flags().StringVar(&url, "url", defaultEngineURL, "local engine URL to probe (GET /v1/models)")
+
+	cmd.AddCommand(install, serve, status)
+	return cmd
+}
+
+// runEngineInstall shells out to the canonical install script so there is exactly
+// one implementation of platform detection + signature verification.
+func runEngineInstall(cmd *cobra.Command, version, dir string) error {
+	env := os.Environ()
+	if version != "" {
+		env = append(env, "HANZOAI_VERSION="+version)
+	}
+	if dir != "" {
+		env = append(env, "HANZOAI_INSTALL_DIR="+dir)
+	}
+
+	var sh *exec.Cmd
+	if runtime.GOOS == "windows" {
+		sh = exec.CommandContext(cmd.Context(), "powershell", "-NoProfile", "-Command",
+			"irm "+installScriptPS+" | iex")
+	} else {
+		// curl … | sh — the exact one-liner documented in the README.
+		sh = exec.CommandContext(cmd.Context(), "sh", "-c",
+			"curl -fsSL "+installScriptSh+" | sh")
+	}
+	sh.Env = env
+	sh.Stdin, sh.Stdout, sh.Stderr = os.Stdin, cmd.OutOrStdout(), cmd.ErrOrStderr()
+	if err := sh.Run(); err != nil {
+		return fmt.Errorf("install script failed: %w", err)
+	}
+	return nil
+}
+
+// runEngineServe execs the installed hanzoai binary. On Unix it replaces this
+// process (syscall.Exec) so signals + exit code flow straight through; on Windows
+// it runs as a child with inherited stdio.
+func runEngineServe(cmd *cobra.Command, model string, port int, extra []string) error {
+	bin, err := findEngineBinary()
+	if err != nil {
+		return err
+	}
+	args := []string{bin, "--port", fmt.Sprintf("%d", port), "run", "-m", model}
+	args = append(args, extra...)
+	fmt.Fprintf(cmd.ErrOrStderr(), "→ %s\n", exec.Command(bin, args[1:]...).String())
+	return execEngine(bin, args)
+}
+
+// runEngineStatus probes the local engine and prints (or JSON-emits) its state,
+// reusing the same /v1/models probe the fleet advertisement uses.
+func runEngineStatus(cmd *cobra.Command, env *Env, url string) error {
+	ctx, cancel := context.WithTimeout(cmd.Context(), 6*time.Second)
+	defer cancel()
+
+	adv := &engineAdvertisement{URL: url, APIs: []string{"openai", "anthropic"}}
+	if models, perr := probeEngine(ctx, url); perr != nil {
+		adv.Status = "unreachable"
+	} else {
+		adv.Status = "ready"
+		adv.Models = models
+	}
+	bin, _ := findEngineBinary()
+
+	return env.emit(map[string]any{"url": url, "status": adv.Status, "models": adv.Models, "binary": bin},
+		func(out io.Writer) {
+			fmt.Fprintf(out, "engine   %s — %s\n", adv.URL, describeEngine(adv))
+			if len(adv.Models) > 0 {
+				for _, m := range adv.Models {
+					fmt.Fprintf(out, "  model  %s\n", m)
+				}
+			}
+			if bin != "" {
+				fmt.Fprintf(out, "binary   %s\n", bin)
+			} else {
+				fmt.Fprintln(out, "binary   not installed — run `hanzo engine install`")
+			}
+			if adv.Status != "ready" {
+				fmt.Fprintf(out, "hint     start it with `hanzo engine serve -m Qwen/Qwen3-4B --port %s`\n",
+					portOf(url))
+			}
+		})
+}
+
+// findEngineBinary locates the installed hanzoai binary: PATH first, then the
+// directories install.sh / install.ps1 write to.
+func findEngineBinary() (string, error) {
+	name := engineBinName
+	if runtime.GOOS == "windows" {
+		name += ".exe"
+	}
+	if p, err := exec.LookPath(name); err == nil {
+		return p, nil
+	}
+	home, _ := os.UserHomeDir()
+	var dirs []string
+	if runtime.GOOS == "windows" {
+		if la := os.Getenv("LOCALAPPDATA"); la != "" {
+			dirs = append(dirs, filepath.Join(la, "Hanzo", "bin"))
+		}
+	} else {
+		dirs = append(dirs, "/usr/local/bin", filepath.Join(home, ".local", "bin"), filepath.Join(home, ".hanzo", "bin"))
+	}
+	for _, d := range dirs {
+		p := filepath.Join(d, name)
+		if fi, err := os.Stat(p); err == nil && !fi.IsDir() {
+			return p, nil
+		}
+	}
+	return "", fmt.Errorf("hanzoai not found on PATH or in the default install dirs — run `hanzo engine install`")
+}
+
+func portOf(url string) string {
+	// best-effort: pull the ":<port>" tail for the hint
+	for i := len(url) - 1; i >= 0; i-- {
+		if url[i] == ':' {
+			return url[i+1:]
+		}
+	}
+	return "1234"
+}

cli/engine_exec_unix.go

@@ -0,0 +1,14 @@
+//go:build !windows
+
+package cli
+
+import (
+	"os"
+	"syscall"
+)
+
+// execEngine replaces the current process with hanzoai so signals (Ctrl-C) and
+// the exit code flow straight through — `hanzo engine serve` becomes hanzoai.
+func execEngine(bin string, args []string) error {
+	return syscall.Exec(bin, args, os.Environ())
+}

cli/engine_exec_windows.go

@@ -0,0 +1,16 @@
+//go:build windows
+
+package cli
+
+import (
+	"os"
+	"os/exec"
+)
+
+// execEngine runs hanzoai as a child with inherited stdio (Windows has no exec()).
+// The child shares the console, so Ctrl-C reaches it; we return its exit error.
+func execEngine(bin string, args []string) error {
+	c := exec.Command(bin, args[1:]...)
+	c.Stdin, c.Stdout, c.Stderr = os.Stdin, os.Stdout, os.Stderr
+	return c.Run()
+}

cli/engine_test.go

@@ -0,0 +1,96 @@
+package cli
+
+import (
+	"bytes"
+	"context"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"testing"
+
+	"github.com/spf13/cobra"
+)
+
+// TestEngineCmdWiring asserts `hanzo engine` exposes install/serve/status with the
+// documented flags — the contract install.sh and the docs promise.
+func TestEngineCmdWiring(t *testing.T) {
+	env := &Env{Output: "table"}
+	cmd := newEngineCmd(func() *Env { return env }, &globalFlags{})
+
+	want := map[string]bool{"install": false, "serve": false, "status": false}
+	for _, sub := range cmd.Commands() {
+		if _, ok := want[sub.Name()]; ok {
+			want[sub.Name()] = true
+		}
+	}
+	for name, found := range want {
+		if !found {
+			t.Fatalf("engine subcommand %q missing", name)
+		}
+	}
+
+	serve, _, _ := cmd.Find([]string{"serve"})
+	if serve.Flags().Lookup("model") == nil || serve.Flags().Lookup("port") == nil {
+		t.Fatalf("serve must have --model and --port")
+	}
+	status, _, _ := cmd.Find([]string{"status"})
+	if status.Flags().Lookup("url") == nil {
+		t.Fatalf("status must have --url")
+	}
+}
+
+// TestEngineStatusReady probes a stub engine and reports it ready with its models.
+func TestEngineStatusReady(t *testing.T) {
+	engine := stubEngine(t, "default", "zen-omni-30b")
+	defer engine.Close()
+
+	var buf bytes.Buffer
+	env := &Env{Output: "table", out: &buf}
+	cmd := &cobra.Command{}
+	cmd.SetContext(context.Background())
+
+	if err := runEngineStatus(cmd, env, engine.URL); err != nil {
+		t.Fatalf("status: %v", err)
+	}
+	out := buf.String()
+	if !strings.Contains(out, "ready") || !strings.Contains(out, "zen-omni-30b") {
+		t.Fatalf("status output missing ready/model:\n%s", out)
+	}
+}
+
+// TestEngineStatusUnreachable reports a down engine as unreachable (not an error).
+func TestEngineStatusUnreachable(t *testing.T) {
+	var buf bytes.Buffer
+	env := &Env{Output: "table", out: &buf}
+	cmd := &cobra.Command{}
+	cmd.SetContext(context.Background())
+
+	// A port with nothing listening.
+	if err := runEngineStatus(cmd, env, "http://127.0.0.1:1"); err != nil {
+		t.Fatalf("status should not error on a down engine: %v", err)
+	}
+	if !strings.Contains(buf.String(), "unreachable") {
+		t.Fatalf("expected 'unreachable', got:\n%s", buf.String())
+	}
+}
+
+// TestFindEngineBinary finds hanzoai on PATH.
+func TestFindEngineBinary(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("PATH exe probe differs on Windows")
+	}
+	dir := t.TempDir()
+	bin := filepath.Join(dir, engineBinName)
+	if err := os.WriteFile(bin, []byte("#!/bin/sh\n"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("PATH", dir)
+	got, err := findEngineBinary()
+	if err != nil {
+		t.Fatalf("findEngineBinary: %v", err)
+	}
+	if got != bin {
+		t.Fatalf("found %q, want %q", got, bin)
+	}
+}

cli/gpu_engine_test.go

@@ -0,0 +1,247 @@
+package cli
+
+// gpu_engine_test.go — the `--serve-engine` capability: probing a local hanzo-engine
+// and assembling the fleet advertisement + provider registration. Uses an httptest
+// stub for the engine so no model (or GPU) is needed.
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+)
+
+// stubEngine stands in for hanzo-engine's OpenAI-shaped GET /v1/models.
+func stubEngine(t *testing.T, models ...string) *httptest.Server {
+	t.Helper()
+	mux := http.NewServeMux()
+	mux.HandleFunc("/v1/models", func(w http.ResponseWriter, _ *http.Request) {
+		data := make([]map[string]any, 0, len(models))
+		for _, m := range models {
+			data = append(data, map[string]any{"id": m, "object": "model", "owned_by": "local"})
+		}
+		_ = json.NewEncoder(w).Encode(map[string]any{"object": "list", "data": data})
+	})
+	return httptest.NewServer(mux)
+}
+
+func TestProbeEngine(t *testing.T) {
+	srv := stubEngine(t, "default", "zen-omni-30b")
+	defer srv.Close()
+
+	got, err := probeEngine(context.Background(), srv.URL)
+	if err != nil {
+		t.Fatalf("probeEngine: %v", err)
+	}
+	if len(got) != 2 || got[0] != "default" || got[1] != "zen-omni-30b" {
+		t.Fatalf("models = %v, want [default zen-omni-30b]", got)
+	}
+}
+
+func TestProbeEngineDown(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		http.Error(w, "loading", http.StatusServiceUnavailable)
+	}))
+	defer srv.Close()
+
+	if _, err := probeEngine(context.Background(), srv.URL); err == nil {
+		t.Fatal("probeEngine: want error for a 503 engine, got nil")
+	}
+}
+
+func TestRefreshEngineAdvertises(t *testing.T) {
+	srv := stubEngine(t, "default")
+	defer srv.Close()
+
+	w := &worker{
+		identity:     "gb10",
+		hostname:     "gb10",
+		jobsNS:       "gpu-jobs",
+		serveEngine:  true,
+		engineURL:    srv.URL,
+		engineAdvURL: "http://node.example:1234",
+	}
+
+	if changed := w.refreshEngine(context.Background()); !changed {
+		t.Fatal("first refreshEngine should report a change (nil -> ready)")
+	}
+	if w.engine == nil || w.engine.Status != "ready" {
+		t.Fatalf("engine = %+v, want status ready", w.engine)
+	}
+	if w.engine.URL != "http://node.example:1234" {
+		t.Fatalf("advertised URL = %q, want the endpoint, not the local probe URL", w.engine.URL)
+	}
+	if !contains(w.engine.APIs, "openai") || !contains(w.engine.APIs, "anthropic") {
+		t.Fatalf("APIs = %v, want both openai and anthropic (hanzo-engine serves both)", w.engine.APIs)
+	}
+	if len(w.engine.Models) != 1 || w.engine.Models[0] != "default" {
+		t.Fatalf("models = %v, want [default]", w.engine.Models)
+	}
+	// A second probe with an unchanged engine is a no-op (no needless re-register).
+	if changed := w.refreshEngine(context.Background()); changed {
+		t.Fatal("second refreshEngine with an unchanged engine should report no change")
+	}
+}
+
+func TestRefreshEngineUnreachable(t *testing.T) {
+	w := &worker{
+		identity:     "gb10",
+		serveEngine:  true,
+		engineURL:    "http://127.0.0.1:0", // nothing listening
+		engineAdvURL: "http://127.0.0.1:0",
+	}
+	w.refreshEngine(context.Background())
+	if w.engine == nil || w.engine.Status != "unreachable" {
+		t.Fatalf("engine = %+v, want status unreachable", w.engine)
+	}
+}
+
+func TestBuildRegistrationCarriesEngine(t *testing.T) {
+	srv := stubEngine(t, "default")
+	defer srv.Close()
+
+	w := &worker{
+		identity:     "gb10",
+		hostname:     "gb10",
+		jobsNS:       "gpu-jobs",
+		gpus:         []gpuInfo{{Name: "NVIDIA GB10", MemoryTotal: "122880 MiB"}},
+		serveEngine:  true,
+		engineURL:    srv.URL,
+		engineAdvURL: "http://node.example:1234",
+	}
+	w.refreshEngine(context.Background())
+
+	reg := w.buildRegistration()
+	if !contains(reg.Capabilities, studioCap) || !contains(reg.Capabilities, engineCap) {
+		t.Fatalf("capabilities = %v, want both %q and %q", reg.Capabilities, studioCap, engineCap)
+	}
+	if reg.Engine == nil || reg.Engine.URL != "http://node.example:1234" {
+		t.Fatalf("registration engine = %+v, want the advertised endpoint", reg.Engine)
+	}
+
+	// The presence record's Input must carry the endpoint so GET /v1/fleet/workers
+	// (which decodes this exact JSON) can advertise it.
+	raw, err := json.Marshal(reg)
+	if err != nil {
+		t.Fatalf("marshal registration: %v", err)
+	}
+	for _, want := range []string{`"engine.serve"`, `"http://node.example:1234"`, `"openai"`, `"anthropic"`} {
+		if !strings.Contains(string(raw), want) {
+			t.Fatalf("registration JSON missing %s:\n%s", want, raw)
+		}
+	}
+}
+
+func TestCapabilitiesWithoutEngine(t *testing.T) {
+	w := &worker{serveEngine: false}
+	caps := w.capabilities()
+	if len(caps) != 1 || caps[0] != studioCap {
+		t.Fatalf("capabilities = %v, want just [%q] when not serving an engine", caps, studioCap)
+	}
+}
+
+func TestProviderBodyIsOpenAICompatible(t *testing.T) {
+	w := &worker{
+		identity: "gb10",
+		engine:   &engineAdvertisement{URL: "http://node.example:1234", Status: "ready", Models: []string{"zen-omni-30b"}},
+	}
+	body := w.providerBody()
+	if body["type"] != "Local" {
+		t.Fatalf("type = %v, want Local (OpenAI-compatible; gateway auto-appends /v1)", body["type"])
+	}
+	if body["providerUrl"] != "http://node.example:1234" {
+		t.Fatalf("providerUrl = %v", body["providerUrl"])
+	}
+	if body["name"] != "gpu-gb10" {
+		t.Fatalf("name = %v, want gpu-gb10", body["name"])
+	}
+	if body["subType"] != "zen-omni-30b" {
+		t.Fatalf("subType = %v, want the served model", body["subType"])
+	}
+}
+
+// TestConnectServeEngineRoundTrip closes the loop end-to-end on this box, no model
+// and no production: a stub hanzo-engine (GET /v1/models) + a stub cloud that stores
+// the presence Input and serves it back on GET /v1/fleet/workers. It exercises the
+// real chain — probe → build registration → POST the fleet activity → GET
+// /v1/fleet/workers → the engine endpoint is advertised.
+func TestConnectServeEngineRoundTrip(t *testing.T) {
+	engine := stubEngine(t, "default", "zen-omni-30b")
+	defer engine.Close()
+
+	var storedInput registration // what the CLI POSTed as the presence record's Input
+	cloud := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch {
+		case r.Method == http.MethodPost && strings.HasSuffix(r.URL.Path, "/fleet/activities"):
+			var body struct {
+				Input registration `json:"input"`
+			}
+			_ = json.NewDecoder(r.Body).Decode(&body)
+			storedInput = body.Input
+			w.WriteHeader(http.StatusOK)
+		case r.Method == http.MethodGet && r.URL.Path == "/v1/fleet/workers":
+			// Fold the stored registration into the fleet worker shape, exactly as
+			// clients/visor/fleet.go byoWorkers does.
+			_ = json.NewEncoder(w).Encode(map[string]any{"workers": []fleetWorker{{
+				ID: "gb10", Hostname: storedInput.Hostname, Provider: "byo", Status: "online",
+				GPUs: storedInput.GPUs, Capabilities: storedInput.Capabilities, Engine: storedInput.Engine,
+			}}})
+		default: // namespace ensure + anything else
+			w.WriteHeader(http.StatusOK)
+		}
+	}))
+	defer cloud.Close()
+
+	t.Setenv("HANZO_TOKEN", "test-token") // ensureToken honors this; no `hanzo login` needed
+
+	w := &worker{
+		env:          &Env{CloudURL: cloud.URL},
+		http:         &http.Client{Timeout: 5 * time.Second},
+		baseURL:      cloud.URL,
+		identity:     "gb10",
+		hostname:     "gb10",
+		jobsNS:       "gpu-jobs",
+		gpus:         []gpuInfo{{Name: "NVIDIA GB10", MemoryTotal: "122880 MiB"}},
+		handlers:     map[string]jobHandler{},
+		serveEngine:  true,
+		engineURL:    engine.URL,
+		engineAdvURL: "http://node.example:1234",
+	}
+	ctx := context.Background()
+	w.refreshEngine(ctx)
+	if err := w.register(ctx); err != nil {
+		t.Fatalf("register: %v", err)
+	}
+
+	var resp struct {
+		Workers []fleetWorker `json:"workers"`
+	}
+	if _, err := w.call(ctx, http.MethodGet, "/v1/fleet/workers", nil, &resp); err != nil {
+		t.Fatalf("GET /v1/fleet/workers: %v", err)
+	}
+	if len(resp.Workers) != 1 {
+		t.Fatalf("workers = %d, want 1", len(resp.Workers))
+	}
+	fw := resp.Workers[0]
+	if !contains(fw.Capabilities, engineCap) {
+		t.Fatalf("fleet worker capabilities = %v, want engine.serve", fw.Capabilities)
+	}
+	if fw.Engine == nil || fw.Engine.URL != "http://node.example:1234" || fw.Engine.Status != "ready" {
+		t.Fatalf("fleet worker engine = %+v, want the advertised ready endpoint", fw.Engine)
+	}
+	if len(fw.Engine.Models) != 2 {
+		t.Fatalf("fleet worker engine models = %v, want 2", fw.Engine.Models)
+	}
+}
+
+func contains(xs []string, v string) bool {
+	for _, x := range xs {
+		if x == v {
+			return true
+		}
+	}
+	return false
+}

cli/gpu_policy_test.go

@@ -0,0 +1,109 @@
+package cli
+
+import (
+	"encoding/json"
+	"testing"
+)
+
+func TestSharePolicyReject(t *testing.T) {
+	studioInput := json.RawMessage(`{"prompt":{},"org":"karma","project":"swimwear"}`)
+	engineInput := json.RawMessage(`{"model":"Qwen/Qwen3-4B","org":"hanzo"}`)
+
+	cases := []struct {
+		name    string
+		policy  *SharePolicy
+		jobType string
+		input   json.RawMessage
+		allow   bool // true == reject() returns ""
+	}{
+		{"nil policy is permissive", nil, "studio.render", studioInput, true},
+		{"empty policy is permissive", &SharePolicy{}, "studio.render", studioInput, true},
+		{
+			"job type allowed",
+			&SharePolicy{AllowedJobTypes: []string{"studio.render"}},
+			"studio.render", studioInput, true,
+		},
+		{
+			"job type not allowed",
+			&SharePolicy{AllowedJobTypes: []string{"engine.serve"}},
+			"studio.render", studioInput, false,
+		},
+		{
+			"org allowed",
+			&SharePolicy{AllowedOrgs: []string{"karma", "hanzo"}},
+			"studio.render", studioInput, true,
+		},
+		{
+			"org not allowed",
+			&SharePolicy{AllowedOrgs: []string{"hanzo"}},
+			"studio.render", studioInput, false,
+		},
+		{
+			"project not allowed",
+			&SharePolicy{AllowedProjects: []string{"lifestyle"}},
+			"studio.render", studioInput, false,
+		},
+		{
+			"model allowed",
+			&SharePolicy{AllowedModels: []string{"Qwen/Qwen3-4B"}},
+			"engine.serve", engineInput, true,
+		},
+		{
+			"model not allowed",
+			&SharePolicy{AllowedModels: []string{"meta/llama-3"}},
+			"engine.serve", engineInput, false,
+		},
+		{
+			"absent field skips its gate (input has no project)",
+			&SharePolicy{AllowedProjects: []string{"lifestyle"}},
+			"engine.serve", engineInput, true,
+		},
+		{
+			"combined: all gates pass",
+			&SharePolicy{
+				AllowedJobTypes: []string{"studio.render"},
+				AllowedOrgs:     []string{"karma"},
+				AllowedProjects: []string{"swimwear"},
+			},
+			"studio.render", studioInput, true,
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			reason := tc.policy.reject(tc.jobType, tc.input)
+			if got := reason == ""; got != tc.allow {
+				t.Fatalf("reject()=%q; want allow=%v", reason, tc.allow)
+			}
+		})
+	}
+}
+
+func TestLoadSharePolicyInline(t *testing.T) {
+	t.Setenv("HANZO_GPU_POLICY", `{"allowedJobTypes":["studio.render"],"allowedOrgs":["karma"],"maxConcurrent":2}`)
+	p, err := loadSharePolicy()
+	if err != nil {
+		t.Fatalf("loadSharePolicy: %v", err)
+	}
+	if p == nil {
+		t.Fatal("expected a policy, got nil")
+	}
+	if len(p.AllowedJobTypes) != 1 || p.AllowedJobTypes[0] != "studio.render" {
+		t.Fatalf("AllowedJobTypes=%v", p.AllowedJobTypes)
+	}
+	if p.MaxConcurrent != 2 {
+		t.Fatalf("MaxConcurrent=%d", p.MaxConcurrent)
+	}
+	if p.reject("engine.serve", json.RawMessage(`{}`)) == "" {
+		t.Fatal("expected engine.serve to be rejected by studio.render-only policy")
+	}
+}
+
+func TestLoadSharePolicyUnset(t *testing.T) {
+	t.Setenv("HANZO_GPU_POLICY", "")
+	t.Setenv("HANZO_GPU_POLICY_FILE", "")
+	p, err := loadSharePolicy()
+	if err != nil || p != nil {
+		t.Fatalf("unset policy: got (%v, %v), want (nil, nil)", p, err)
+	}
+}

cli/gpu_upload_test.go

@@ -0,0 +1,55 @@
+package cli
+
+import (
+	"context"
+	"net/http"
+	"os"
+	"testing"
+	"time"
+)
+
+// TestUploadOutputsIntegration exercises the real BYO-GPU result-upload path:
+// fetchLocalOutput pulls a finished render from the LOCAL studio's /view and
+// postGalleryOutput POSTs it to the org studio's /upload/output with the user's
+// IAM token, landing it in orgs/{org}/output (the gallery, S3-mirrored).
+//
+// It is a live integration test, skipped unless the box is wired for it:
+//
+//	HANZO_TOKEN=<iam bearer> \
+//	HANZO_UPLOAD_IT_FILE=<name of a file the local studio serves at /view?type=output> \
+//	HANZO_STUDIO_UPLOAD_URL=<org studio base, e.g. https://studio.hanzo.ai> \
+//	go test ./cli -run TestUploadOutputsIntegration -v
+//
+// The local studio is assumed at localComfyUI (127.0.0.1:8188).
+func TestUploadOutputsIntegration(t *testing.T) {
+	tok := os.Getenv("HANZO_TOKEN")
+	file := os.Getenv("HANZO_UPLOAD_IT_FILE")
+	if tok == "" || file == "" {
+		t.Skip("set HANZO_TOKEN and HANZO_UPLOAD_IT_FILE to run the live upload integration test")
+	}
+	uploadURL := firstNonEmpty(os.Getenv("HANZO_STUDIO_UPLOAD_URL"), defaultStudioUploadURL)
+
+	w := &worker{
+		env:             &Env{}, // ensureToken reads HANZO_TOKEN first, so no creds needed
+		http:            &http.Client{Timeout: 60 * time.Second},
+		studioUploadURL: uploadURL,
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
+	defer cancel()
+
+	subfolder := os.Getenv("HANZO_UPLOAD_IT_SUBFOLDER") // "" == top of output
+	out := file
+	if subfolder != "" {
+		out = subfolder + "/" + file
+	}
+
+	gallery, err := w.uploadOutputs(ctx, []string{out}, uploadURL, "karma")
+	if err != nil {
+		t.Fatalf("uploadOutputs(%q -> %s): %v", out, uploadURL, err)
+	}
+	if len(gallery) != 1 {
+		t.Fatalf("expected 1 gallery path, got %d: %v", len(gallery), gallery)
+	}
+	t.Logf("uploaded %q -> %s gallery path %q", out, uploadURL, gallery[0])
+}

cli/platform.go

@@ -0,0 +1,348 @@
+package cli
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"strings"
+	"time"
+)
+
+// Platform is a thin client over the platform.hanzo.ai /v1 control plane. That
+// surface is machine-to-machine (service-token, "No OIDC" — it cannot validate
+// IAM user tokens), so the token here is the platform service token, resolved
+// from flag/env/credential store by the caller; the build endpoint takes its
+// own token per call.
+type Platform struct {
+	baseURL string
+	token   string
+	http    *http.Client
+}
+
+func newPlatform(baseURL, token string) *Platform {
+	return &Platform{
+		baseURL: strings.TrimRight(baseURL, "/"),
+		token:   token,
+		http:    &http.Client{Timeout: 60 * time.Second},
+	}
+}
+
+// apiError carries the HTTP status + server message for a failed call so
+// commands can give precise diagnostics (e.g. 401 → token problem).
+type apiError struct {
+	status  int
+	message string
+	path    string
+}
+
+func (e *apiError) Error() string {
+	msg := e.message
+	if msg == "" {
+		msg = http.StatusText(e.status)
+	}
+	hint := ""
+	if e.status == http.StatusUnauthorized {
+		hint = " (set the platform service token: --platform-token, HANZO_PLATFORM_TOKEN, or `hanzo login --platform-token`)"
+	}
+	return fmt.Sprintf("platform %s: HTTP %d: %s%s", e.path, e.status, msg, hint)
+}
+
+// do performs one JSON request with the given bearer token, decoding a 2xx body
+// into out (when non-nil) and mapping a non-2xx into an *apiError.
+func (p *Platform) do(ctx context.Context, method, path, token string, body, out any) error {
+	if token == "" {
+		return fmt.Errorf("no platform token: pass --platform-token, set HANZO_PLATFORM_TOKEN, or run `hanzo login --platform-token <tok>`")
+	}
+	var rdr io.Reader
+	if body != nil {
+		b, err := json.Marshal(body)
+		if err != nil {
+			return err
+		}
+		rdr = bytes.NewReader(b)
+	}
+	req, err := http.NewRequestWithContext(ctx, method, p.baseURL+path, rdr)
+	if err != nil {
+		return err
+	}
+	req.Header.Set("Authorization", "Bearer "+token)
+	req.Header.Set("Accept", "application/json")
+	req.Header.Set("User-Agent", "hanzo-cli/"+Version)
+	if body != nil {
+		req.Header.Set("Content-Type", "application/json")
+	}
+
+	resp, err := p.http.Do(req)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+	raw, _ := io.ReadAll(io.LimitReader(resp.Body, 8<<20))
+
+	if resp.StatusCode/100 != 2 {
+		return &apiError{status: resp.StatusCode, message: serverMessage(raw), path: path}
+	}
+	if out != nil && len(raw) > 0 {
+		if err := json.Unmarshal(raw, out); err != nil {
+			return fmt.Errorf("platform %s: decode response: %w", path, err)
+		}
+	}
+	return nil
+}
+
+// serverMessage pulls the `{ "message": … }` field platform errors use, falling
+// back to the raw (truncated) body.
+func serverMessage(raw []byte) string {
+	var e struct {
+		Message string `json:"message"`
+		Error   string `json:"error"`
+	}
+	if json.Unmarshal(raw, &e) == nil {
+		if e.Message != "" {
+			return e.Message
+		}
+		if e.Error != "" {
+			return e.Error
+		}
+	}
+	s := strings.TrimSpace(string(raw))
+	if len(s) > 240 {
+		s = s[:240] + "…"
+	}
+	return s
+}
+
+// ---------------------------------------------------------------------------
+// Apps board — GET /v1/apps, GET /v1/apps/{id}, POST /v1/apps/sync.
+// ---------------------------------------------------------------------------
+
+// AppView mirrors the platform apps-lifecycle DTO. Nullable columns are *string
+// so JSON null round-trips; Drift is kept raw so --json is byte-faithful and
+// the drift schema can evolve without a client bump.
+type AppView struct {
+	ID            string          `json:"id"`
+	Org           string          `json:"org"`
+	App           string          `json:"app"`
+	Env           string          `json:"env"`
+	Repo          string          `json:"repo"`
+	Registry      string          `json:"registry"`
+	DeclaredTag   *string         `json:"declaredTag"`
+	RunningTag    *string         `json:"runningTag"`
+	LatestTag     *string         `json:"latestTag"`
+	ReleaseURL    *string         `json:"releaseUrl"`
+	ReleaseAssets int             `json:"releaseAssets"`
+	Health        *string         `json:"health"`
+	Cluster       *string         `json:"cluster"`
+	Namespace     *string         `json:"namespace"`
+	LastObserved  *string         `json:"lastObserved"`
+	UpdatedAt     string          `json:"updatedAt"`
+	Drift         json.RawMessage `json:"drift"`
+}
+
+// AppsList is the /v1/apps envelope: ordered rows + a drift summary.
+type AppsList struct {
+	Apps    []AppView `json:"apps"`
+	Summary struct {
+		Total   int            `json:"total"`
+		ByDrift map[string]int `json:"byDrift"`
+	} `json:"summary"`
+}
+
+// AppsQuery are the optional /v1/apps filters.
+type AppsQuery struct {
+	Org    string
+	Env    string
+	Health string
+	Drift  bool
+}
+
+func (p *Platform) Apps(ctx context.Context, q AppsQuery) (*AppsList, error) {
+	v := url.Values{}
+	if q.Org != "" {
+		v.Set("org", q.Org)
+	}
+	if q.Env != "" {
+		v.Set("env", q.Env)
+	}
+	if q.Health != "" {
+		v.Set("health", q.Health)
+	}
+	if q.Drift {
+		v.Set("drift", "1")
+	}
+	path := "/v1/apps"
+	if len(v) > 0 {
+		path += "?" + v.Encode()
+	}
+	out := &AppsList{}
+	return out, p.do(ctx, http.MethodGet, path, p.token, nil, out)
+}
+
+func (p *Platform) App(ctx context.Context, id, org string) (*AppView, error) {
+	path := "/v1/apps/" + id
+	if org != "" {
+		path += "?org=" + url.QueryEscape(org)
+	}
+	out := &AppView{}
+	return out, p.do(ctx, http.MethodGet, path, p.token, nil, out)
+}
+
+func (p *Platform) SyncApps(ctx context.Context) error {
+	return p.do(ctx, http.MethodPost, "/v1/apps/sync", p.token, nil, nil)
+}
+
+// driftSeverity extracts the severity string from the raw drift object.
+func driftSeverity(raw json.RawMessage) string {
+	var d struct {
+		Severity string `json:"severity"`
+	}
+	if json.Unmarshal(raw, &d) == nil && d.Severity != "" {
+		return d.Severity
+	}
+	return "-"
+}
+
+// ---------------------------------------------------------------------------
+// Dedicated clusters — /v1/org/{org}/cluster[ /select | /{id}/install-baseline ].
+// ---------------------------------------------------------------------------
+
+// Cluster mirrors a doks_cluster record. `status` is DigitalOcean state; `phase`
+// is the platform provisioning lifecycle — orthogonal (a DO-running cluster is
+// not a usable target until phase=ready).
+type Cluster struct {
+	DoksClusterID     string          `json:"doksClusterId"`
+	Name              string          `json:"name"`
+	DoClusterID       *string         `json:"doClusterId"`
+	Region            string          `json:"region"`
+	Status            string          `json:"status"`
+	Endpoint          *string         `json:"endpoint"`
+	K8sVersion        *string         `json:"k8sVersion"`
+	HA                bool            `json:"ha"`
+	Phase             string          `json:"phase"`
+	OperatorInstalled bool            `json:"operatorInstalled"`
+	BaselineInstalled bool            `json:"baselineInstalled"`
+	Active            bool            `json:"active"`
+	BaselineError     *string         `json:"baselineError"`
+	OrganizationID    string          `json:"organizationId"`
+	CreatedAt         string          `json:"createdAt"`
+	Tags              []string        `json:"tags"`
+	MaintenancePolicy json.RawMessage `json:"maintenancePolicy,omitempty"`
+}
+
+// ProvisionReq is the dedicated-cluster provisioning body (org forced by path).
+type ProvisionReq struct {
+	Region    string `json:"region,omitempty"`
+	HA        bool   `json:"ha,omitempty"`
+	NodeSize  string `json:"nodeSize,omitempty"`
+	NodeCount int    `json:"nodeCount,omitempty"`
+}
+
+// Target is the redacted ClusterTargetView — the kubeconfig is never present.
+type Target struct {
+	Cluster    string            `json:"cluster"`
+	Namespaces map[string]string `json:"namespaces"`
+	Dedicated  bool              `json:"dedicated"`
+}
+
+func (p *Platform) Clusters(ctx context.Context, org string) ([]Cluster, error) {
+	var out struct {
+		Clusters []Cluster `json:"clusters"`
+	}
+	err := p.do(ctx, http.MethodGet, "/v1/org/"+url.PathEscape(org)+"/cluster", p.token, nil, &out)
+	return out.Clusters, err
+}
+
+func (p *Platform) ProvisionCluster(ctx context.Context, org string, req ProvisionReq) (*Cluster, error) {
+	var out struct {
+		Cluster Cluster `json:"cluster"`
+	}
+	err := p.do(ctx, http.MethodPost, "/v1/org/"+url.PathEscape(org)+"/cluster", p.token, req, &out)
+	return &out.Cluster, err
+}
+
+func (p *Platform) Target(ctx context.Context, org string) (*Target, error) {
+	var out struct {
+		Target Target `json:"target"`
+	}
+	err := p.do(ctx, http.MethodGet, "/v1/org/"+url.PathEscape(org)+"/cluster/select", p.token, nil, &out)
+	return &out.Target, err
+}
+
+// SelectTarget activates a dedicated cluster as the org's deploy target, or
+// reverts to the shared cluster when clusterID is nil.
+func (p *Platform) SelectTarget(ctx context.Context, org string, clusterID *string) (*Target, error) {
+	var out struct {
+		Target Target `json:"target"`
+	}
+	body := map[string]any{"doksClusterId": clusterID}
+	err := p.do(ctx, http.MethodPost, "/v1/org/"+url.PathEscape(org)+"/cluster/select", p.token, body, &out)
+	return &out.Target, err
+}
+
+func (p *Platform) InstallBaseline(ctx context.Context, org, clusterID string) error {
+	path := "/v1/org/" + url.PathEscape(org) + "/cluster/" + url.PathEscape(clusterID) + "/install-baseline"
+	return p.do(ctx, http.MethodPost, path, p.token, nil, nil)
+}
+
+// ---------------------------------------------------------------------------
+// Deploy — POST …/container/{id}/redeploy (rolling restart, zero-downtime).
+// ---------------------------------------------------------------------------
+
+// Redeploy triggers a rolling restart of the container's k8s Deployment. The
+// coordinates are exact (the platform validates org+project+env+container scope).
+func (p *Platform) Redeploy(ctx context.Context, org, project, env, container string) error {
+	path := fmt.Sprintf("/v1/org/%s/project/%s/env/%s/container/%s/redeploy",
+		url.PathEscape(org), url.PathEscape(project), url.PathEscape(env), url.PathEscape(container))
+	var out struct {
+		OK bool `json:"ok"`
+	}
+	if err := p.do(ctx, http.MethodPost, path, p.token, nil, &out); err != nil {
+		return err
+	}
+	if !out.OK {
+		return fmt.Errorf("redeploy did not report ok")
+	}
+	return nil
+}
+
+// ---------------------------------------------------------------------------
+// Build — POST /v1/runner (platform-native CI, no GitHub builders).
+// ---------------------------------------------------------------------------
+
+// BuildReq is the direct-enqueue body. Repo/SHA/Image are required.
+type BuildReq struct {
+	Repo           string `json:"repo"`
+	SHA            string `json:"sha"`
+	Image          string `json:"image"`
+	Branch         string `json:"branch,omitempty"`
+	Ref            string `json:"ref,omitempty"`
+	Dockerfile     string `json:"dockerfile,omitempty"`
+	Context        string `json:"context,omitempty"`
+	DockerTarget   string `json:"dockerTarget,omitempty"`
+	OS             string `json:"os,omitempty"`
+	Arch           string `json:"arch,omitempty"`
+	OrganizationID string `json:"organizationId,omitempty"`
+}
+
+// BuildJob is the enqueue acceptance (HTTP 202).
+type BuildJob struct {
+	BuildJobID string `json:"buildJobId"`
+	Status     string `json:"status"`
+	RunnerPool string `json:"runnerPool"`
+	Image      string `json:"image"`
+	Target     string `json:"target"`
+}
+
+// EnqueueBuild enqueues a native build. It authenticates with the dedicated
+// build-callback token, not the service token.
+func (p *Platform) EnqueueBuild(ctx context.Context, req BuildReq, buildToken string) (*BuildJob, error) {
+	if buildToken == "" {
+		return nil, fmt.Errorf("no build token: set HANZO_BUILD_TOKEN / PLATFORM_BUILD_CALLBACK_TOKEN or `hanzo login --build-token <tok>`")
+	}
+	out := &BuildJob{}
+	return out, p.do(ctx, http.MethodPost, "/v1/runner", buildToken, req, out)
+}

cli/platform_test.go

@@ -0,0 +1,220 @@
+package cli
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+)
+
+// platformStub spins an httptest server whose handler is provided by the test,
+// plus a client pointed at it with the given token.
+func platformStub(t *testing.T, token string, h http.HandlerFunc) (*Platform, func()) {
+	t.Helper()
+	srv := httptest.NewServer(h)
+	return newPlatform(srv.URL, token), srv.Close
+}
+
+func TestPlatformAuthHeaderAndApps(t *testing.T) {
+	p, done := platformStub(t, "svc-tok", func(w http.ResponseWriter, r *http.Request) {
+		if got := r.Header.Get("Authorization"); got != "Bearer svc-tok" {
+			t.Errorf("auth header = %q", got)
+		}
+		if r.URL.Path != "/v1/apps" {
+			t.Errorf("path = %s", r.URL.Path)
+		}
+		if r.URL.Query().Get("env") != "main" || r.URL.Query().Get("drift") != "1" {
+			t.Errorf("query = %s", r.URL.RawQuery)
+		}
+		_ = json.NewEncoder(w).Encode(AppsList{
+			Apps: []AppView{{ID: "hanzoai/iam/main", Org: "hanzoai", App: "iam", Env: "main", Drift: json.RawMessage(`{"severity":"red"}`)}},
+		})
+	})
+	defer done()
+
+	res, err := p.Apps(context.Background(), AppsQuery{Env: "main", Drift: true})
+	if err != nil {
+		t.Fatalf("Apps: %v", err)
+	}
+	if len(res.Apps) != 1 || res.Apps[0].App != "iam" {
+		t.Fatalf("apps wrong: %+v", res.Apps)
+	}
+	if driftSeverity(res.Apps[0].Drift) != "red" {
+		t.Fatalf("drift severity = %q", driftSeverity(res.Apps[0].Drift))
+	}
+}
+
+func TestPlatformApp(t *testing.T) {
+	p, done := platformStub(t, "t", func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/v1/apps/hanzoai/iam/main" {
+			t.Errorf("path = %s", r.URL.Path)
+		}
+		if r.URL.Query().Get("org") != "hanzoai" {
+			t.Errorf("org query = %s", r.URL.RawQuery)
+		}
+		_ = json.NewEncoder(w).Encode(AppView{ID: "hanzoai/iam/main", App: "iam"})
+	})
+	defer done()
+	a, err := p.App(context.Background(), "hanzoai/iam/main", "hanzoai")
+	if err != nil || a.App != "iam" {
+		t.Fatalf("App: %v %+v", err, a)
+	}
+}
+
+func TestPlatformSyncApps(t *testing.T) {
+	p, done := platformStub(t, "t", func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodPost || r.URL.Path != "/v1/apps/sync" {
+			t.Errorf("sync = %s %s", r.Method, r.URL.Path)
+		}
+		w.WriteHeader(200)
+	})
+	defer done()
+	if err := p.SyncApps(context.Background()); err != nil {
+		t.Fatalf("SyncApps: %v", err)
+	}
+}
+
+func TestPlatformClustersAndProvision(t *testing.T) {
+	p, done := platformStub(t, "t", func(w http.ResponseWriter, r *http.Request) {
+		switch {
+		case r.Method == http.MethodGet && r.URL.Path == "/v1/org/acme/cluster":
+			_ = json.NewEncoder(w).Encode(map[string]any{"clusters": []Cluster{{DoksClusterID: "c1", Name: "hanzo-acme", Region: "sfo3", Status: "running", Phase: "ready", Active: true}}})
+		case r.Method == http.MethodPost && r.URL.Path == "/v1/org/acme/cluster":
+			body, _ := io.ReadAll(r.Body)
+			var req ProvisionReq
+			_ = json.Unmarshal(body, &req)
+			if req.Region != "sfo3" || !req.HA {
+				t.Errorf("provision body = %+v", req)
+			}
+			w.WriteHeader(201)
+			_ = json.NewEncoder(w).Encode(map[string]any{"cluster": Cluster{DoksClusterID: "c2", Name: "new", Phase: "requested"}})
+		default:
+			t.Errorf("unexpected %s %s", r.Method, r.URL.Path)
+		}
+	})
+	defer done()
+
+	cs, err := p.Clusters(context.Background(), "acme")
+	if err != nil || len(cs) != 1 || cs[0].DoksClusterID != "c1" {
+		t.Fatalf("Clusters: %v %+v", err, cs)
+	}
+	c, err := p.ProvisionCluster(context.Background(), "acme", ProvisionReq{Region: "sfo3", HA: true})
+	if err != nil || c.DoksClusterID != "c2" {
+		t.Fatalf("ProvisionCluster: %v %+v", err, c)
+	}
+}
+
+func TestPlatformTargetAndSelect(t *testing.T) {
+	p, done := platformStub(t, "t", func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/v1/org/acme/cluster/select" {
+			t.Errorf("path = %s", r.URL.Path)
+		}
+		if r.Method == http.MethodPost {
+			body, _ := io.ReadAll(r.Body)
+			var m map[string]any
+			_ = json.Unmarshal(body, &m)
+			if m["doksClusterId"] != "c1" {
+				t.Errorf("select body = %v", m)
+			}
+		}
+		_ = json.NewEncoder(w).Encode(map[string]any{"target": Target{Cluster: "hanzo-acme", Dedicated: true, Namespaces: map[string]string{"acme": "main"}}})
+	})
+	defer done()
+
+	tg, err := p.Target(context.Background(), "acme")
+	if err != nil || tg.Cluster != "hanzo-acme" || !tg.Dedicated {
+		t.Fatalf("Target: %v %+v", err, tg)
+	}
+	id := "c1"
+	if _, err := p.SelectTarget(context.Background(), "acme", &id); err != nil {
+		t.Fatalf("SelectTarget: %v", err)
+	}
+}
+
+func TestPlatformInstallBaseline(t *testing.T) {
+	p, done := platformStub(t, "t", func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodPost || r.URL.Path != "/v1/org/acme/cluster/c1/install-baseline" {
+			t.Errorf("install-baseline = %s %s", r.Method, r.URL.Path)
+		}
+		w.WriteHeader(200)
+	})
+	defer done()
+	if err := p.InstallBaseline(context.Background(), "acme", "c1"); err != nil {
+		t.Fatalf("InstallBaseline: %v", err)
+	}
+}
+
+func TestPlatformRedeploy(t *testing.T) {
+	p, done := platformStub(t, "t", func(w http.ResponseWriter, r *http.Request) {
+		want := "/v1/org/acme/project/p1/env/e1/container/app-x/redeploy"
+		if r.Method != http.MethodPost || r.URL.Path != want {
+			t.Errorf("redeploy path = %s %s", r.Method, r.URL.Path)
+		}
+		_ = json.NewEncoder(w).Encode(map[string]bool{"ok": true})
+	})
+	defer done()
+	if err := p.Redeploy(context.Background(), "acme", "p1", "e1", "app-x"); err != nil {
+		t.Fatalf("Redeploy: %v", err)
+	}
+}
+
+func TestPlatformRedeployNotOK(t *testing.T) {
+	p, done := platformStub(t, "t", func(w http.ResponseWriter, _ *http.Request) {
+		_ = json.NewEncoder(w).Encode(map[string]bool{"ok": false})
+	})
+	defer done()
+	if err := p.Redeploy(context.Background(), "o", "p", "e", "c"); err == nil {
+		t.Fatalf("expected error when ok=false")
+	}
+}
+
+func TestPlatformEnqueueBuild(t *testing.T) {
+	p, done := platformStub(t, "svc-tok", func(w http.ResponseWriter, r *http.Request) {
+		// The build endpoint must use the BUILD token, not the service token.
+		if got := r.Header.Get("Authorization"); got != "Bearer build-tok" {
+			t.Errorf("build auth header = %q (must use build token)", got)
+		}
+		if r.URL.Path != "/v1/runner" {
+			t.Errorf("path = %s", r.URL.Path)
+		}
+		body, _ := io.ReadAll(r.Body)
+		var req BuildReq
+		_ = json.Unmarshal(body, &req)
+		if req.Repo != "hanzoai/pricing" || req.SHA != "abc123" || req.Image == "" {
+			t.Errorf("build body = %+v", req)
+		}
+		w.WriteHeader(202)
+		_ = json.NewEncoder(w).Encode(BuildJob{BuildJobID: "bj-1", Status: "queued", RunnerPool: "runner-pool-32g", Image: req.Image})
+	})
+	defer done()
+
+	job, err := p.EnqueueBuild(context.Background(), BuildReq{Repo: "hanzoai/pricing", SHA: "abc123", Image: "ghcr.io/hanzoai/pricing:t"}, "build-tok")
+	if err != nil || job.BuildJobID != "bj-1" {
+		t.Fatalf("EnqueueBuild: %v %+v", err, job)
+	}
+	if _, err := p.EnqueueBuild(context.Background(), BuildReq{Repo: "r", SHA: "s", Image: "i"}, ""); err == nil {
+		t.Fatalf("expected error with empty build token")
+	}
+}
+
+func TestPlatformError401Hint(t *testing.T) {
+	p, done := platformStub(t, "bad", func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(401)
+		_ = json.NewEncoder(w).Encode(map[string]string{"message": "Unauthorized"})
+	})
+	defer done()
+	_, err := p.Apps(context.Background(), AppsQuery{})
+	if err == nil || !strings.Contains(err.Error(), "HTTP 401") || !strings.Contains(err.Error(), "platform service token") {
+		t.Fatalf("401 error should carry a token hint, got %v", err)
+	}
+}
+
+func TestPlatformNoTokenError(t *testing.T) {
+	p := newPlatform("https://platform.hanzo.ai", "")
+	if _, err := p.Apps(context.Background(), AppsQuery{}); err == nil || !strings.Contains(err.Error(), "no platform token") {
+		t.Fatalf("expected no-token error, got %v", err)
+	}
+}

cli/quiet.go

@@ -0,0 +1,24 @@
+package cli
+
+import "os"
+
+// realStdout is the process's true stdout, captured at this package's init
+// before the server-graph dependencies (iam/beego, kms) run their own init()
+// functions — several of which emit warnings to stdout (e.g. the IAM registry
+// signing-key loader). To keep the CLI's stdout machine-readable (so
+// `hanzo apps list -o json | jq` is never corrupted by a dependency's startup
+// chatter), this init redirects stdout to stderr for the duration of process
+// initialization; RestoreStdout puts the real stdout back before any command
+// writes a byte.
+//
+// This is best-effort: it only helps when this package initializes before the
+// noisy dependency (cmd/hanzo imports cli first) AND that dependency reads the
+// os.Stdout variable at log time rather than capturing it earlier. main always
+// calls RestoreStdout, so correctness never depends on the redirect taking.
+var realStdout = os.Stdout
+
+func init() { os.Stdout = os.Stderr }
+
+// RestoreStdout restores the real process stdout. cmd/hanzo calls this as its
+// first statement so every command writes to the genuine stdout.
+func RestoreStdout() { os.Stdout = realStdout }

cli/run.go

@@ -0,0 +1,185 @@
+package cli
+
+// run.go — `hanzo run`: launch a workload on Hanzo compute through one verb.
+//
+// A "run" is a workload value = {artifact, shape}, dispatched by kind onto the
+// one API host (api.hanzo.ai/v1) and the one binary (cloud):
+//
+//	hanzo run <image>              → POST /v1/run   container service (autoscaled)
+//	hanzo run fn <src>             → POST /v1/fn    source function   (scale-to-zero)
+//
+// `run` launches YOUR artifact (container/source/site) on Hanzo compute. Invoking
+// a managed agent with a task is a peer verb, `hanzo agent` (see agent.go), not a
+// run kind. It is a THIN client: kind-dispatch + one authenticated HTTP call each,
+// over the IAM access token and env.CloudURL, exactly like the fleet worker
+// (gpu.go) — it invents no parallel API. See docs/architecture/compute-ladder.md.
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+
+	"github.com/spf13/cobra"
+)
+
+// cloudCall performs one authenticated JSON request against env.CloudURL
+// (api.hanzo.ai), decoding a 2xx body into out. It is the api.hanzo.ai analog of
+// Platform.do (which targets platform.hanzo.ai); the two converge as the platform
+// control plane folds into cloud. Mirrors the fleet worker's call idiom.
+func cloudCall(ctx context.Context, env *Env, method, path string, body, out any) error {
+	tok, err := env.ensureToken(ctx)
+	if err != nil {
+		return err
+	}
+	var rdr io.Reader
+	if body != nil {
+		b, err := json.Marshal(body)
+		if err != nil {
+			return err
+		}
+		rdr = bytes.NewReader(b)
+	}
+	req, err := http.NewRequestWithContext(ctx, method, env.CloudURL+path, rdr)
+	if err != nil {
+		return err
+	}
+	req.Header.Set("Authorization", "Bearer "+tok)
+	req.Header.Set("Accept", "application/json")
+	req.Header.Set("User-Agent", "hanzo-cli/"+Version)
+	if body != nil {
+		req.Header.Set("Content-Type", "application/json")
+	}
+	resp, err := (&http.Client{}).Do(req)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+	raw, _ := io.ReadAll(io.LimitReader(resp.Body, 8<<20))
+	if resp.StatusCode/100 != 2 {
+		return fmt.Errorf("cloud %s %s: HTTP %d: %s", method, path, resp.StatusCode, serverMessage(raw))
+	}
+	if out != nil && len(raw) > 0 {
+		if err := json.Unmarshal(raw, out); err != nil {
+			return fmt.Errorf("cloud %s: decode response: %w", path, err)
+		}
+	}
+	return nil
+}
+
+// RunSpec is the POST /v1/run (container) / /v1/fn (source) body. Shape selects
+// the execution model: "service" (autoscaled, long-lived), "function"
+// (per-request, scale-to-zero), or "task" (run-to-completion).
+type RunSpec struct {
+	Name    string            `json:"name,omitempty"`
+	Image   string            `json:"image,omitempty"`  // container artifact (run)
+	Source  string            `json:"source,omitempty"` // source ref/path (fn)
+	Runtime string            `json:"runtime,omitempty"`
+	Port    int               `json:"port,omitempty"`
+	Shape   string            `json:"shape"` // service | function | task
+	Min     int               `json:"minScale"`
+	Max     int               `json:"maxScale"`
+	GPU     bool              `json:"gpu,omitempty"`
+	Env     map[string]string `json:"env,omitempty"`
+}
+
+// RunResult is the enqueue/creation acceptance.
+type RunResult struct {
+	ID     string `json:"id"`
+	Name   string `json:"name"`
+	URL    string `json:"url"`
+	Status string `json:"status"`
+	Shape  string `json:"shape"`
+}
+
+func newRunCmd(envOf func() *Env, _ *globalFlags) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "run",
+		Short: "Launch a workload on Hanzo compute (container, function, or agent task)",
+		Long: "One verb, dispatched by kind, all on api.hanzo.ai/v1 — k8s is abstracted away:\n" +
+			"  hanzo run <image>    a container service (autoscaled)\n" +
+			"  hanzo run fn <src>   a source function (scale-to-zero)\n" +
+			"To invoke a managed agent use `hanzo agent`; a computer-using one, `hanzo bot`.\n" +
+			"For a declared, long-running or stateful service use `hanzo deploy`; for raw\n" +
+			"cluster access use `hanzo k8s`.",
+	}
+	cmd.AddCommand(newRunContainerCmd(envOf), newRunFnCmd(envOf))
+	return cmd
+}
+
+// newRunContainerCmd is `hanzo run <image>` (default) AND `hanzo run container <image>`.
+func newRunContainerCmd(envOf func() *Env) *cobra.Command {
+	var spec RunSpec
+	var envKV []string
+	c := &cobra.Command{
+		Use:   "container <image>",
+		Short: "Run a container as an autoscaled service (POST /v1/run)",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			env := envOf()
+			spec.Image = args[0]
+			spec.Shape = firstNonEmpty(spec.Shape, "service")
+			spec.Env = parseEnvKV(envKV)
+			out := &RunResult{}
+			if err := cloudCall(cmd.Context(), env, http.MethodPost, "/v1/run", &spec, out); err != nil {
+				return err
+			}
+			return env.emit(out, func(w io.Writer) {
+				fmt.Fprintf(w, "%s\t%s\t%s\n", out.Name, out.Status, out.URL)
+			})
+		},
+	}
+	c.Flags().StringVar(&spec.Name, "name", "", "workload name (default: derived from image)")
+	c.Flags().IntVar(&spec.Port, "port", 8080, "container port to route traffic to")
+	c.Flags().StringVar(&spec.Shape, "shape", "service", "service | task (run-to-completion)")
+	c.Flags().IntVar(&spec.Min, "min", 0, "min replicas (0 = scale-to-zero when supported)")
+	c.Flags().IntVar(&spec.Max, "max", 20, "max replicas (autoscale ceiling)")
+	c.Flags().BoolVar(&spec.GPU, "gpu", false, "schedule on a GPU node")
+	c.Flags().StringArrayVarP(&envKV, "env", "e", nil, "environment variable KEY=VALUE (repeatable)")
+	return c
+}
+
+func newRunFnCmd(envOf func() *Env) *cobra.Command {
+	var spec RunSpec
+	var envKV []string
+	c := &cobra.Command{
+		Use:   "fn <source>",
+		Short: "Run a source function, scale-to-zero (POST /v1/functions)",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			env := envOf()
+			spec.Source = args[0]
+			spec.Shape = "function"
+			spec.Env = parseEnvKV(envKV)
+			out := &RunResult{}
+			if err := cloudCall(cmd.Context(), env, http.MethodPost, "/v1/functions", &spec, out); err != nil {
+				return err
+			}
+			return env.emit(out, func(w io.Writer) {
+				fmt.Fprintf(w, "%s\t%s\t%s\n", out.Name, out.Status, out.URL)
+			})
+		},
+	}
+	c.Flags().StringVar(&spec.Name, "name", "", "function name")
+	c.Flags().StringVar(&spec.Runtime, "runtime", "", "runtime env (e.g. python312, node20, rust)")
+	c.Flags().BoolVar(&spec.GPU, "gpu", false, "use a GPU function environment")
+	c.Flags().StringArrayVarP(&envKV, "env", "e", nil, "environment variable KEY=VALUE (repeatable)")
+	return c
+}
+
+// parseEnvKV turns []{"K=V"} into a map, ignoring malformed entries.
+func parseEnvKV(kv []string) map[string]string {
+	if len(kv) == 0 {
+		return nil
+	}
+	m := make(map[string]string, len(kv))
+	for _, e := range kv {
+		if i := strings.IndexByte(e, '='); i > 0 {
+			m[e[:i]] = e[i+1:]
+		}
+	}
+	return m
+}

cli/runner.go

@@ -0,0 +1,43 @@
+package cli
+
+// runner.go — `hanzo runner`: turn THIS machine into a JIT CI runner for your
+// org's GitHub Actions. The host role of the arc daemon, migrated from
+// arc-runner/arc (cmd/arcd) into cloud/runner: a GitHub App polls each configured
+// org for queued workflow jobs and spawns ephemeral, auto-exiting actions-runner
+// subprocesses tagged with this box's labels (GPU / vulkan aware). Outbound only —
+// nothing listens for inbound. Completes the trifecta: `engine` serves models,
+// `gpu connect` shares compute, `runner` claims CI — one binary, one org login.
+
+import (
+	"os/signal"
+	"syscall"
+
+	"github.com/hanzoai/cloud/runner"
+	"github.com/spf13/cobra"
+)
+
+func newRunnerCmd(_ func() *Env, _ *globalFlags) *cobra.Command {
+	runner.Version = Version // propagate the cloud build version into the daemon
+	var configPath string
+	cmd := &cobra.Command{
+		Use:   "runner",
+		Short: "Run this machine as a JIT CI runner for your org (GitHub Actions)",
+		Long: "Turn this box into an ephemeral, GPU-aware GitHub Actions runner for your\n" +
+			"org(s). A GitHub App polls for queued jobs and spawns auto-exiting runner\n" +
+			"subprocesses labelled with this machine's tags. Outbound-only; nothing\n" +
+			"listens for inbound. Config defaults to ~/.arcd/config.yaml (app_id, orgs,\n" +
+			"labels, runner_dir).",
+		Args: cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			cfg, err := runner.LoadConfig(configPath)
+			if err != nil {
+				return err
+			}
+			ctx, stop := signal.NotifyContext(cmd.Context(), syscall.SIGINT, syscall.SIGTERM)
+			defer stop()
+			return runner.RunHost(ctx, cfg)
+		},
+	}
+	cmd.Flags().StringVar(&configPath, "config", "", "runner config.yaml (default: ~/.arcd/config.yaml)")
+	return cmd
+}

cli/security.go

@@ -0,0 +1,259 @@
+package cli
+
+import (
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+
+	"github.com/hanzoai/cloud/clients/security/detect"
+	"github.com/spf13/cobra"
+)
+
+// `hanzo security scan` is the LOCAL guardrail-at-generation: it walks a path,
+// runs the SAME detect engine the /v1/security server surface uses (one engine,
+// two surfaces — see clients/security/detect), and exits non-zero when a finding
+// at or above the fail threshold is present. No server, no auth, no network — so
+// it drops straight into a pre-commit hook, a CI step, or an agent's shell the
+// moment code is written. It never prints a raw secret: findings carry the
+// engine's masked preview only.
+
+// skipDirs are never descended into — vendored / generated / VCS trees that
+// would drown real findings in noise (and, for node_modules, minified blobs
+// that trip entropy heuristics).
+var skipDirs = map[string]bool{
+	".git": true, "node_modules": true, "vendor": true, "dist": true,
+	"build": true, "out": true, ".vscode-test": true, "target": true,
+	".next": true, "__pycache__": true, ".venv": true, "venv": true,
+}
+
+// maxScanFileBytes caps a single file read; a source file over this is almost
+// certainly a data/blob artifact, not code a human wrote a secret into.
+const maxScanFileBytes = 2 << 20 // 2 MiB
+
+func newSecurityCmd(envOf func() *Env) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "security",
+		Short: "Code-security tools (local secret scanning)",
+		// No PersistentPreRunE override: the root's runs, resolving config/creds
+		// into env so envOf() (used for -o json) is non-nil. It is local-only —
+		// scan requires no login or network.
+	}
+
+	var failOn string
+	scan := &cobra.Command{
+		Use:   "scan [path ...]",
+		Short: "Scan files/directories for hardcoded secrets (default: current dir)",
+		Long: "Walk each path and report hardcoded secrets using the native Hanzo\n" +
+			"detection engine (the same one behind /v1/security). Exits non-zero when a\n" +
+			"finding at or above --fail-on is present, so it gates a pre-commit hook or CI\n" +
+			"step. Secrets are never printed — only a masked preview.",
+		// We print our own findings + a clean "N secrets" error; no cobra usage
+		// dump on a policy failure.
+		SilenceUsage:  true,
+		SilenceErrors: true,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			paths := args
+			if len(paths) == 0 {
+				paths = []string{"."}
+			}
+			floor := strings.ToLower(strings.TrimSpace(failOn))
+			if floor == "" {
+				floor = "low"
+			}
+			if floor != "none" && detect.SeverityRank(floor) == 0 {
+				return fmt.Errorf("invalid --fail-on %q (want critical|high|medium|low|none)", failOn)
+			}
+
+			findings, scanned, err := scanPaths(paths)
+			if err != nil {
+				return err
+			}
+
+			e := envOf()
+			result := scanResult{
+				FilesScanned: scanned,
+				Findings:     findings,
+				Summary:      tally(findings),
+			}
+			if err := e.emit(result, func(w io.Writer) { renderScan(w, result) }); err != nil {
+				return err
+			}
+
+			// Policy gate: fail when any finding is at/above the floor.
+			if floor != "none" {
+				bad := 0
+				for _, f := range findings {
+					if detect.SeverityRank(f.Severity) >= detect.SeverityRank(floor) {
+						bad++
+					}
+				}
+				if bad > 0 {
+					return fmt.Errorf("%d secret(s) at or above %q severity", bad, floor)
+				}
+			}
+			return nil
+		},
+	}
+	scan.Flags().StringVar(&failOn, "fail-on", "low",
+		"minimum severity that fails the command: critical|high|medium|low|none")
+
+	rules := &cobra.Command{
+		Use:   "rules",
+		Short: "List the detection rules the scanner applies",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			e := envOf()
+			rv := detect.Rules()
+			return e.emit(rv, func(w io.Writer) {
+				tw := newTab(w)
+				fmt.Fprintln(tw, "SEVERITY\tID\tNAME")
+				for _, r := range rv {
+					fmt.Fprintf(tw, "%s\t%s\t%s\n", r.Severity, r.ID, r.Name)
+				}
+				tw.Flush()
+				fmt.Fprintf(w, "\n%d rules\n", len(rv))
+			})
+		},
+	}
+
+	cmd.AddCommand(scan, rules)
+	return cmd
+}
+
+// scanFinding is a CLI finding: the engine finding with the file path it was
+// found in (the engine echoes the path it was handed, which is what we want).
+type scanResult struct {
+	FilesScanned int              `json:"filesScanned"`
+	Findings     []detect.Finding `json:"findings"`
+	Summary      scanSummary      `json:"summary"`
+}
+
+type scanSummary struct {
+	Total    int `json:"total"`
+	Critical int `json:"critical"`
+	High     int `json:"high"`
+	Medium   int `json:"medium"`
+	Low      int `json:"low"`
+}
+
+func tally(fs []detect.Finding) scanSummary {
+	var s scanSummary
+	for _, f := range fs {
+		s.Total++
+		switch f.Severity {
+		case detect.SeverityCritical:
+			s.Critical++
+		case detect.SeverityHigh:
+			s.High++
+		case detect.SeverityMedium:
+			s.Medium++
+		case detect.SeverityLow:
+			s.Low++
+		}
+	}
+	return s
+}
+
+// scanPaths walks each path and runs the engine over every readable text file,
+// returning findings sorted worst-first (by severity, then path, then line).
+func scanPaths(paths []string) ([]detect.Finding, int, error) {
+	var findings []detect.Finding
+	scanned := 0
+	for _, root := range paths {
+		info, err := os.Stat(root)
+		if err != nil {
+			return nil, 0, fmt.Errorf("stat %q: %w", root, err)
+		}
+		if !info.IsDir() {
+			fs, ok := scanOneFile(root)
+			if ok {
+				scanned++
+				findings = append(findings, fs...)
+			}
+			continue
+		}
+		walkErr := filepath.WalkDir(root, func(p string, d os.DirEntry, err error) error {
+			if err != nil {
+				return nil // unreadable entry — skip, don't abort the whole walk
+			}
+			if d.IsDir() {
+				if skipDirs[d.Name()] {
+					return filepath.SkipDir
+				}
+				return nil
+			}
+			if fs, ok := scanOneFile(p); ok {
+				scanned++
+				findings = append(findings, fs...)
+			}
+			return nil
+		})
+		if walkErr != nil {
+			return nil, 0, fmt.Errorf("walk %q: %w", root, walkErr)
+		}
+	}
+	sort.SliceStable(findings, func(i, j int) bool {
+		a, b := findings[i], findings[j]
+		if ra, rb := detect.SeverityRank(a.Severity), detect.SeverityRank(b.Severity); ra != rb {
+			return ra > rb
+		}
+		if a.Path != b.Path {
+			return a.Path < b.Path
+		}
+		return a.Line < b.Line
+	})
+	return findings, scanned, nil
+}
+
+// scanOneFile reads a file (bounded, text-only) and runs the engine. Returns
+// ok=false for a file that was skipped (too big, binary, unreadable) so it is
+// not counted as scanned.
+func scanOneFile(path string) ([]detect.Finding, bool) {
+	info, err := os.Stat(path)
+	if err != nil || info.Size() > maxScanFileBytes {
+		return nil, false
+	}
+	b, err := os.ReadFile(path)
+	if err != nil {
+		return nil, false
+	}
+	if isBinary(b) {
+		return nil, false
+	}
+	return detect.ScanContent(path, string(b)), true
+}
+
+// isBinary reports whether b looks like a non-text blob — a NUL byte in the
+// first 8 KiB is the same heuristic git uses. Skipping binaries avoids both
+// false positives and wasted work on assets.
+func isBinary(b []byte) bool {
+	n := len(b)
+	if n > 8192 {
+		n = 8192
+	}
+	for i := 0; i < n; i++ {
+		if b[i] == 0 {
+			return true
+		}
+	}
+	return false
+}
+
+func renderScan(w io.Writer, r scanResult) {
+	if len(r.Findings) == 0 {
+		fmt.Fprintf(w, "✓ no secrets found (%d files scanned)\n", r.FilesScanned)
+		return
+	}
+	tw := newTab(w)
+	fmt.Fprintln(tw, "SEVERITY\tRULE\tLOCATION\tPREVIEW")
+	for _, f := range r.Findings {
+		fmt.Fprintf(tw, "%s\t%s\t%s:%d\t%s\n", f.Severity, f.RuleID, f.Path, f.Line, f.Preview)
+	}
+	tw.Flush()
+	fmt.Fprintf(w, "\n%d finding(s) in %d files  (critical=%d high=%d medium=%d low=%d)\n",
+		r.Summary.Total, r.FilesScanned, r.Summary.Critical, r.Summary.High,
+		r.Summary.Medium, r.Summary.Low)
+}

cli/security_test.go

@@ -0,0 +1,176 @@
+package cli
+
+import (
+	"bytes"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// runSecurity executes `security <args>` through the real root command with an
+// isolated $HOME, capturing stdout. Returns output + the Execute error (the
+// non-zero-exit signal).
+func runSecurity(t *testing.T, args ...string) (string, error) {
+	t.Helper()
+	sandbox(t)
+	root := newRootCmd()
+	var out bytes.Buffer
+	root.SetOut(&out)
+	root.SetErr(&out)
+	root.SetArgs(append([]string{"security"}, args...))
+	err := root.Execute()
+	return out.String(), err
+}
+
+// TestSecurityScanFindsAndFails proves scan detects a planted secret, exits
+// non-zero at the default fail threshold, and never prints the raw secret.
+func TestSecurityScanFindsAndFails(t *testing.T) {
+	dir := t.TempDir()
+	secret := "AKIAIOSFODNN7EXAMPLE"
+	must(t, os.WriteFile(filepath.Join(dir, "config.py"),
+		[]byte("aws_key = \""+secret+"\"\nok = 1\n"), 0o644))
+	// a clean file that must NOT trip anything
+	must(t, os.WriteFile(filepath.Join(dir, "clean.go"),
+		[]byte("package main\nfunc main() {}\n"), 0o644))
+
+	out, err := runSecurity(t, "scan", dir)
+	if err == nil {
+		t.Fatalf("expected non-zero exit on a found secret; out:\n%s", out)
+	}
+	if !strings.Contains(err.Error(), "at or above") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if strings.Contains(out, secret) {
+		t.Fatalf("output leaked the raw secret:\n%s", out)
+	}
+	if !strings.Contains(out, "aws-access-key-id") {
+		t.Fatalf("expected the aws rule id in output:\n%s", out)
+	}
+}
+
+// TestSecurityScanCleanPasses proves a clean tree exits zero with the ok line.
+func TestSecurityScanCleanPasses(t *testing.T) {
+	dir := t.TempDir()
+	must(t, os.WriteFile(filepath.Join(dir, "app.go"),
+		[]byte("package main\nfunc main() { println(\"hi\") }\n"), 0o644))
+
+	out, err := runSecurity(t, "scan", dir)
+	if err != nil {
+		t.Fatalf("clean tree should exit zero, got %v\n%s", err, out)
+	}
+	if !strings.Contains(out, "no secrets found") {
+		t.Fatalf("expected the clean message:\n%s", out)
+	}
+}
+
+// TestSecurityScanFailOnNone proves --fail-on=none reports findings but exits
+// zero (report-only mode).
+func TestSecurityScanFailOnNone(t *testing.T) {
+	dir := t.TempDir()
+	must(t, os.WriteFile(filepath.Join(dir, "s.py"),
+		[]byte(`k = "AKIAIOSFODNN7EXAMPLE"`), 0o644))
+
+	out, err := runSecurity(t, "scan", "--fail-on", "none", dir)
+	if err != nil {
+		t.Fatalf("--fail-on=none should exit zero, got %v\n%s", err, out)
+	}
+	if !strings.Contains(out, "aws-access-key-id") {
+		t.Fatalf("report-only should still list the finding:\n%s", out)
+	}
+}
+
+// TestSecurityScanFailOnThreshold proves a medium finding does NOT fail when
+// --fail-on=critical, but a critical one does.
+func TestSecurityScanFailOnThreshold(t *testing.T) {
+	dir := t.TempDir()
+	// a jwt is medium severity
+	must(t, os.WriteFile(filepath.Join(dir, "t.txt"),
+		[]byte("tok = eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhYmMifQ.SGVsbG9TaWduYXR1cmU\n"), 0o644))
+
+	if out, err := runSecurity(t, "scan", "--fail-on", "critical", dir); err != nil {
+		t.Fatalf("medium finding must not fail at --fail-on=critical, got %v\n%s", err, out)
+	}
+	// now add a critical
+	must(t, os.WriteFile(filepath.Join(dir, "k.py"),
+		[]byte(`k = "AKIAIOSFODNN7EXAMPLE"`), 0o644))
+	if _, err := runSecurity(t, "scan", "--fail-on", "critical", dir); err == nil {
+		t.Fatal("a critical finding must fail at --fail-on=critical")
+	}
+}
+
+// TestSecurityScanJSON proves -o json emits a machine-readable result with the
+// summary and no raw secret.
+func TestSecurityScanJSON(t *testing.T) {
+	dir := t.TempDir()
+	secret := "AKIAIOSFODNN7EXAMPLE"
+	must(t, os.WriteFile(filepath.Join(dir, "s.py"), []byte(`k = "`+secret+`"`), 0o644))
+
+	out, _ := runSecurity(t, "scan", "-o", "json", "--fail-on", "none", dir)
+	var res scanResult
+	if err := json.Unmarshal([]byte(out), &res); err != nil {
+		t.Fatalf("json parse: %v\n%s", err, out)
+	}
+	if res.Summary.Critical < 1 || res.Summary.Total < 1 {
+		t.Fatalf("summary missing the critical: %+v", res.Summary)
+	}
+	if strings.Contains(out, secret) {
+		t.Fatalf("json leaked the secret:\n%s", out)
+	}
+}
+
+// TestSecurityScanSkipsVendorAndBinary proves the walker skips skipDirs and
+// binary files (a secret inside node_modules or a NUL-laden blob is ignored).
+func TestSecurityScanSkipsVendorAndBinary(t *testing.T) {
+	dir := t.TempDir()
+	nm := filepath.Join(dir, "node_modules")
+	must(t, os.MkdirAll(nm, 0o755))
+	must(t, os.WriteFile(filepath.Join(nm, "dep.js"),
+		[]byte(`k = "AKIAIOSFODNN7EXAMPLE"`), 0o644))
+	must(t, os.WriteFile(filepath.Join(dir, "blob.bin"),
+		append([]byte{0, 1, 2}, []byte(`AKIAIOSFODNN7EXAMPLE`)...), 0o644))
+
+	out, err := runSecurity(t, "scan", dir)
+	if err != nil {
+		t.Fatalf("vendored + binary secrets should be skipped → clean exit, got %v\n%s", err, out)
+	}
+	if !strings.Contains(out, "no secrets found") {
+		t.Fatalf("expected clean (skipped) result:\n%s", out)
+	}
+}
+
+// TestSecurityScanBadFailOn proves an invalid --fail-on is a clean error.
+func TestSecurityScanBadFailOn(t *testing.T) {
+	dir := t.TempDir()
+	_, err := runSecurity(t, "scan", "--fail-on", "nope", dir)
+	if err == nil || !strings.Contains(err.Error(), "invalid --fail-on") {
+		t.Fatalf("want invalid --fail-on error, got %v", err)
+	}
+}
+
+// TestSecurityRules proves the rules subcommand lists the catalog.
+func TestSecurityRules(t *testing.T) {
+	out, err := runSecurity(t, "rules")
+	if err != nil {
+		t.Fatalf("rules failed: %v", err)
+	}
+	if !strings.Contains(out, "aws-access-key-id") || !strings.Contains(out, "rules") {
+		t.Fatalf("rules output missing content:\n%s", out)
+	}
+}
+
+// TestSecurityIsControlVerb proves `security` routes to the CLI, not the server
+// dispatcher.
+func TestSecurityIsControlVerb(t *testing.T) {
+	if !IsControlVerb("security") {
+		t.Fatal("security must be a control verb")
+	}
+}
+
+func must(t *testing.T, err error) {
+	t.Helper()
+	if err != nil {
+		t.Fatal(err)
+	}
+}

clients/account/account.go

@@ -0,0 +1,520 @@
+// Package account mounts the signed-in caller's OWN account self-service surface
+// natively in the unified cloud binary — the Go port of the console's two NON-proxy
+// Next server routes (app/keys + app/onboard) plus the money/store data bridges the
+// statically-exported console needs (task #41, "True 1-binary FE"). It replaces the
+// retired /v1/console/* namespace: "console" is just the cloud FE name, so there is NO
+// /v1/console API domain — every route lives on its REAL domain.
+//
+// WHY THESE ROUTES (and not the pure passthrough proxies). The console's PURE BFF
+// reverse-proxies — app/cloud, app/ai — vanish in the one-binary model: the SPA calls
+// the canonical /v1/* on its own origin and the already-mounted subsystems answer. The
+// routes ported HERE do REAL server work a static SPA cannot: keys/onboard run
+// privileged IAM logic as the confidential `hanzo-console` client; embed-status/topup
+// do server-side verification; and the billing/commerce bridges inject the commerce
+// SERVICE token and pin the caller's own subject SERVER-SIDE (a passthrough would leak
+// cross-tenant ledgers). Each has no pure-proxy equivalent, so it must be ported.
+//
+// SURFACE — each route on its REAL domain (every one requires a VALIDATED principal — a
+// gateway-minted, IAM-verified X-User-Id; a client-forged X-Org-Id on the bearer-less
+// path is refused):
+//
+//	GET    /v1/iam/keys              — whether the caller has an `hk-` key (+ prefix/mtime); no secret.
+//	POST   /v1/iam/keys              — mint/rotate the key; returns { accessKey } ONCE.
+//	DELETE /v1/iam/keys              — revoke the key.
+//	POST   /v1/iam/onboard           — create the caller's org (+ move them in on first run).
+//	GET    /v1/csrf                  — mint the anti-CSRF token the SPA echoes on money writes (csrf.go).
+//	GET    /v1/embed-status          — brand-app embed entitlement + reachability probe (embed.go).
+//	POST   /v1/commerce/topup/wallet — HUSD on-chain verify → commerce credit (topup.go).
+//	GET    /v1/billing/*             — per-tenant billing read, SCOPED to the validated caller (billing.go).
+//	…      /v1/commerce/*            — per-tenant STORE CRUD, SCOPED to the validated caller's org (commerce.go).
+//
+// TWO SUBSYSTEM REGISTRATIONS FROM ONE PACKAGE. A route-ordering constraint forces the
+// split (Fiber matches by registration order — the earliest-mounted route wins):
+//   - `account` (order 48) mounts the SPECIFIC self-service routes. keys/onboard MUST
+//     win over clients/iam's /v1/iam/* WILDCARD (order 50), and topup MUST win over the
+//     commerce embed (order 100) + the /v1/commerce/* bridge — so they mount EARLY.
+//   - `account-bridge` (order 122) mounts the CATCH-ALL data bridges. /v1/billing/* must
+//     sit AFTER clients/billing's specific routes (order 121) and /v1/commerce/* after
+//     the commerce embed (order 100) — so they mount LATE.
+//
+// Both share one state shape + the process-wide CSRF key (csrf.go), so a token minted at
+// /v1/csrf verifies on the /v1/billing|commerce writes.
+//
+// TENANCY. The caller is resolved from the VALIDATED identity headers ONLY
+// (principal.Validated / c.Org() / c.User()), the same trust boundary every mutating
+// subsystem uses. The IAM id targeted is DERIVED as `<owner>/<name>` from those
+// validated claims — never taken from the request body/query — so a caller can only ever
+// mint/revoke their OWN key and onboard THEMSELVES; there is no path to name a
+// third-party subject. When the confidential client is unwired the surface is honestly
+// "not configured" (501), never a fabricated key or org.
+package account
+
+import (
+	"encoding/base64"
+	"errors"
+	"fmt"
+	"net/http"
+	"os"
+	"strings"
+
+	"github.com/hanzoai/cloud"
+	"github.com/hanzoai/cloud/clients/principal"
+	"github.com/zap-proto/zip"
+)
+
+// adminOrg is THE SuperAdmin / IAM-system org that owns every customer org row —
+// standardized as "admin" across the whole stack (IAM, commerce, ai, gateway all
+// gate cross-tenant on owner=="admin"). A created customer org is owned by it.
+const adminOrg = "admin"
+
+// errNotConfigured is returned by the IAM client when the confidential
+// `hanzo-console` credential is unset; handlers map it to a 501 (honest "not
+// configured on this deployment", mirroring identity.ts's mintConfigured() gate).
+var errNotConfigured = errors.New("iam confidential client not configured")
+
+// errNotFound is a not-present sentinel (e.g. the user row IAM cannot return).
+var errNotFound = errors.New("not found")
+
+// state is account's own data; shared deps live in the embedded cloud.Base. Both
+// subsystem registrations (account @48, account-bridge @122) build their own value;
+// the CSRF key is the process-wide singleton (csrf.go) so a token minted by one
+// verifies on the other.
+type state struct {
+	iam      *iamClient
+	csrfKey  []byte       // keyed-BLAKE3 MAC key for the money-write CSRF token (csrf.go)
+	writesRL *rateLimiter // per-IP abuse cap on the money-write routes (ratelimit.go)
+}
+
+// keysWriteRatePerMin caps money-write frequency per client IP (mint/rotate/revoke
+// key, wallet top-up). Generous enough for real UI bursts, tight enough to blunt
+// brute-force / enumeration when a caller reaches cloud directly (gateway bypassed).
+const keysWriteRatePerMin = 30
+
+// newService builds the shared subsystem value. Both subsystem Mounts construct one;
+// the CSRF key is the process-wide singleton (csrf.go) so account (order 48) and
+// account-bridge (order 122) verify each other's tokens.
+func newService(deps cloud.Deps) *cloud.Service[state] {
+	b := cloud.NewBase(deps, "account")
+	st := state{iam: newIAMClient()}
+	st.csrfKey = sharedCSRFKey(b.Log)
+	st.writesRL = newRateLimiter(keysWriteRatePerMin)
+	return &cloud.Service[state]{Base: b, State: st}
+}
+
+// MountAccount wires the SPECIFIC self-service routes (order 48) — the ones that must
+// win over the IAM /v1/iam/* wildcard (50) and the commerce embed (100).
+func MountAccount(app *zip.App, deps cloud.Deps) error {
+	if app == nil {
+		return fmt.Errorf("account.MountAccount: nil zip.App")
+	}
+	if deps.Logger == nil {
+		return fmt.Errorf("account.MountAccount: nil deps.Logger")
+	}
+	s := newService(deps)
+	routesAccount(s, app)
+	s.Log.Info("account self-service surface mounted",
+		"iam", s.State.iam.base, "configured", s.State.iam.configured(), "brand", s.Brand)
+	return nil
+}
+
+// MountBridge wires the CATCH-ALL data bridges (order 122) — the /v1/billing/* and
+// /v1/commerce/* proxies that must sit AFTER clients/billing (121) + the commerce embed.
+func MountBridge(app *zip.App, deps cloud.Deps) error {
+	if app == nil {
+		return fmt.Errorf("account.MountBridge: nil zip.App")
+	}
+	if deps.Logger == nil {
+		return fmt.Errorf("account.MountBridge: nil deps.Logger")
+	}
+	s := newService(deps)
+	routesBridge(s, app)
+	s.Log.Info("account data bridges mounted", "prefixes", "/v1/billing/*,/v1/commerce/*", "brand", s.Brand)
+	return nil
+}
+
+// routesAccount wires the specific self-service routes (order 48).
+func routesAccount(s *cloud.Service[state], app *zip.App) {
+	// GET /v1/csrf issues the anti-CSRF token the embedded SPA echoes as X-CSRF-Token on
+	// every money write (csrf.go). Safe (read-only), same-origin.
+	app.Get("/v1/csrf", cloud.Handle(s, issueCSRFToken))
+	// The caller's own `hk-` Cloud API key — IAM self-service. These SPECIFIC routes MUST
+	// register before clients/iam's /v1/iam/* wildcard (order 50 > 48) so Fiber's
+	// first-match scan hits the native handler, not the wildcard (TestIAMKeysBeatsWildcard).
+	// Reads are open; every state-changing WRITE is wrapped: requireCSRF blocks a
+	// cross-site ambient-cookie forgery, and rateLimit caps per-IP frequency (cloud is
+	// reachable off-gateway).
+	app.Get("/v1/iam/keys", cloud.Handle(s, getKey))
+	app.Post("/v1/iam/keys", rateLimit(s, s.State.writesRL, requireCSRF(s, cloud.Handle(s, mintKey))))
+	app.Delete("/v1/iam/keys", rateLimit(s, s.State.writesRL, requireCSRF(s, cloud.Handle(s, revokeKey))))
+	app.Post("/v1/iam/onboard", requireCSRF(s, cloud.Handle(s, onboard)))
+	// Console module embed-entitlement + reachability probe (embed.go).
+	app.Get("/v1/embed-status", cloud.Handle(s, embedStatus))
+	// HUSD wallet top-up (on-chain verify → commerce credit). A SPECIFIC commerce route
+	// that must beat the /v1/commerce/* bridge (122) AND the commerce embed (100) — so it
+	// mounts here at 48, ahead of both.
+	app.Post("/v1/commerce/topup/wallet", rateLimit(s, s.State.writesRL, requireCSRF(s, cloud.Handle(s, walletTopup))))
+}
+
+// routesBridge wires the per-tenant catch-all data bridges (order 122).
+func routesBridge(s *cloud.Service[state], app *zip.App) {
+	// Per-tenant billing DATA bridge — the canonical /v1/billing/* the statically-exported
+	// console calls, forwarded to commerce with the admin service token and SCOPED to the
+	// validated caller's own subject (billing.go). Registered AFTER clients/billing's
+	// specific routes (121 < 122) so those win and this catches the rest. GET+POST only.
+	app.Get("/v1/billing/*", cloud.Handle(s, billingData))
+	app.Post("/v1/billing/*", requireCSRF(s, cloud.Handle(s, billingData)))
+	// Per-tenant STORE DATA bridge — the canonical /v1/commerce/* the console calls,
+	// forwarded to commerce's bare store surface /v1/<kind> with the admin service token
+	// and SCOPED to the validated caller's own org (commerce.go). Registered AFTER the
+	// commerce embed (100 < 122) so the embed wins when enabled. Full CRUD.
+	app.Get("/v1/commerce/*", cloud.Handle(s, commerceData))
+	app.Post("/v1/commerce/*", requireCSRF(s, cloud.Handle(s, commerceData)))
+	app.Put("/v1/commerce/*", requireCSRF(s, cloud.Handle(s, commerceData)))
+	app.Patch("/v1/commerce/*", requireCSRF(s, cloud.Handle(s, commerceData)))
+	app.Delete("/v1/commerce/*", requireCSRF(s, cloud.Handle(s, commerceData)))
+}
+
+// ── caller resolution (the tenancy boundary) ─────────────────────────────────
+
+// caller is the signed-in user resolved from the VALIDATED identity headers. id is
+// the `<owner>/<name>` composite IAM's privileged ops parse (GetOwnerAndNameFromId
+// requires it — a bare token count of 1 throws "wrong token count"); owner is the
+// org (X-Org-Id).
+type caller struct {
+	id       string // <owner>/<name> (or the bare user id when owner-less)
+	owner    string // validated org (may be "" for a zero-org, first-run user)
+	name     string // == X-User-Id: the stable user id (a UUID on the direct path)
+	username string // IAM username (X-User-Name); the `name` half IAM's user-key ops parse
+}
+
+// keyID is the `<owner>/<username>` composite IAM's user-key ops (mint/get/revoke
+// user AccessKey) parse via GetOwnerAndNameFromId. It uses the IAM USERNAME, not
+// name (== X-User-Id): on the in-binary direct-Bearer path X-User-Id is the UUID
+// subject and `<owner>/<uuid>` fails IAM's user lookup ("password or code is
+// incorrect"). On the gateway path username==name so keyID()==id — no change.
+// Owner-less (first-run) callers can't own a key, so this is only reached with a
+// validated owner; it falls back to id defensively.
+func (cr caller) keyID() string {
+	if cr.owner != "" && cr.username != "" {
+		return cr.owner + "/" + cr.username
+	}
+	return cr.id
+}
+
+// resolveCaller derives the caller from the validated identity, or (zero,false)
+// when there is no validated principal. requireOwner=true refuses a user with no
+// org yet (used by the key ops, which must act scoped); onboarding passes
+// requireOwner=false so a first-run zero-org user can create their first org. The id
+// is ALWAYS derived from the validated claims, never a request value.
+func resolveCaller(c *zip.Ctx, requireOwner bool) (caller, bool) {
+	if !principal.Validated(c) {
+		return caller{}, false // no gateway-minted, IAM-verified principal — refuse
+	}
+	name := strings.TrimSpace(c.User())
+	if name == "" {
+		return caller{}, false
+	}
+	owner := strings.TrimSpace(c.Org())
+	if requireOwner && owner == "" {
+		return caller{}, false
+	}
+	// IAM parses `<owner>/<name>`; prefer it, fall back to the bare id for an
+	// owner-less (first-run) user. Same id semantics as identity.ts.
+	id := name
+	if owner != "" {
+		id = owner + "/" + name
+	}
+	// username is the IAM USERNAME, kept DISTINCT from name (== X-User-Id) so the
+	// billing/topup subjects (which key on name) are byte-identical to today — this
+	// value narrows the blast radius to the IAM user-key ops alone (keyID()). It
+	// prefers X-User-Name (stamped from the validated `name` claim by
+	// SanitizeIdentity), because on the in-binary direct-Bearer path X-User-Id is the
+	// UUID subject and <owner>/<uuid> fails IAM's mint-user-keys/get-user lookup.
+	// Falls back to name for the gateway path (which mints X-User-Id==username). Both
+	// inputs are gateway/SanitizeIdentity-minted from a verified principal.
+	username := strings.TrimSpace(c.Header("X-User-Name"))
+	if username == "" {
+		username = name
+	}
+	return caller{id: id, owner: owner, name: name, username: username}, true
+}
+
+// ── keys (the per-user `hk-` Cloud API key) ──────────────────────────────────
+
+type keyStatus struct {
+	HasKey    bool   `json:"hasKey"`
+	KeyPrefix string `json:"keyPrefix,omitempty"`
+	CreatedAt string `json:"createdAt,omitempty"`
+}
+
+// getKey reports whether the caller has an `hk-` key, its public prefix, and when
+// the key row last changed — NO secret material. Reads IAM authoritatively (not the
+// session claim, which lags a fresh key). Mirrors GET app/keys/route.ts.
+func getKey(s *cloud.Service[state], c *zip.Ctx) error {
+	cr, ok := resolveCaller(c, true)
+	if !ok {
+		return zip.ErrForbidden("sign in to manage API keys")
+	}
+	if !s.State.iam.configured() {
+		return notConfigured("API key management")
+	}
+	uk, err := s.State.iam.getUserKey(c.Context(), cr.keyID())
+	if err != nil {
+		// Fail-soft on a transient IAM read: report "no key" rather than 5xx, so the
+		// page shows the honest empty state (never a fabricated key). The mint path
+		// still 502s loudly on a real failure — reads degrade, writes do not.
+		s.Log.Warn("get key: iam read failed (reporting no key)", "err", err)
+		return c.JSON(http.StatusOK, keyStatus{HasKey: false})
+	}
+	if uk.AccessKey == "" {
+		return c.JSON(http.StatusOK, keyStatus{HasKey: false})
+	}
+	prefix := uk.AccessKey
+	if len(prefix) > 11 {
+		prefix = prefix[:11]
+	}
+	return c.JSON(http.StatusOK, keyStatus{HasKey: true, KeyPrefix: prefix, CreatedAt: uk.UpdatedTime})
+}
+
+// mintKey (re)generates the caller's `hk-` key and returns it ONCE (show-once). A
+// real IAM failure surfaces as 502 (never a fabricated key). Mirrors POST app/keys.
+func mintKey(s *cloud.Service[state], c *zip.Ctx) error {
+	cr, ok := resolveCaller(c, true)
+	if !ok {
+		return zip.ErrForbidden("sign in to manage API keys")
+	}
+	if !s.State.iam.configured() {
+		return notConfigured("API key management")
+	}
+	key, err := s.State.iam.mintUserKey(c.Context(), cr.keyID())
+	if err != nil {
+		return zip.Errorf(http.StatusBadGateway, "could not mint an API key: %v", err)
+	}
+	return c.JSON(http.StatusOK, map[string]string{"accessKey": key})
+}
+
+// revokeKey clears the caller's `hk-` key. Mirrors DELETE app/keys.
+func revokeKey(s *cloud.Service[state], c *zip.Ctx) error {
+	cr, ok := resolveCaller(c, true)
+	if !ok {
+		return zip.ErrForbidden("sign in to manage API keys")
+	}
+	if !s.State.iam.configured() {
+		return notConfigured("API key management")
+	}
+	if err := s.State.iam.revokeUserKey(c.Context(), cr.keyID()); err != nil {
+		return zip.Errorf(http.StatusBadGateway, "could not revoke the API key: %v", err)
+	}
+	return c.JSON(http.StatusOK, map[string]bool{"ok": true})
+}
+
+// ── onboard (create the caller's org) ────────────────────────────────────────
+
+type onboardReq struct {
+	Name     string `json:"name"`
+	Personal bool   `json:"personal"`
+}
+
+type onboardResp struct {
+	Org         string `json:"org"`
+	DisplayName string `json:"displayName"`
+	Additional  bool   `json:"additional"`
+}
+
+// onboard creates the caller's organization. Two flows, keyed on whether the caller
+// already has a home org (mirrors app/onboard/route.ts):
+//
+//   - FIRST-RUN (no owner): create + MOVE the user in as admin, so their next JWT
+//     carries the new owner and the cloud scopes everything to it.
+//   - ADDITIONAL (owner set): create the org but do NOT move the user — a move
+//     changes their IAM owner (stripping a SuperAdmin's status + orphaning their
+//     current org). They reach the new org via the OrgSwitcher, which re-scopes
+//     X-Org-Id without touching IAM membership. A personal-org request from someone
+//     who already has an org is meaningless → 409.
+func onboard(s *cloud.Service[state], c *zip.Ctx) error {
+	cr, ok := resolveCaller(c, false) // first-run onboarding allows a zero-org user
+	if !ok {
+		return zip.ErrForbidden("sign in to create an organization")
+	}
+	if !s.State.iam.configured() {
+		return notConfigured("organization creation")
+	}
+	var body onboardReq
+	if len(c.Body()) > 0 {
+		if err := c.Bind(&body); err != nil {
+			return err
+		}
+	}
+
+	additional := cr.owner != ""
+	if additional && body.Personal {
+		return zip.ErrConflict("you already have an organization; name the new one explicitly")
+	}
+
+	baseSlug, displayName, herr := resolveOnboardName(s, body, cr)
+	if herr != nil {
+		return herr
+	}
+
+	// Resolve a unique slug. Personal orgs auto-suffix to stay unique; an explicit
+	// name that's taken is an honest conflict the user resolves by renaming.
+	slug, herr := uniqueSlug(s, c, baseSlug, body.Personal)
+	if herr != nil {
+		return herr
+	}
+
+	// Create the org (cloning the caller's current org for password/locale
+	// compatibility), then — first-run only — move the zero-org user in as admin.
+	org := buildOrg(s, c, slug, displayName, body.Personal, cr.owner)
+	if err := s.State.iam.createOrganization(c.Context(), org); err != nil {
+		return zip.Errorf(http.StatusBadGateway, "could not create the organization: %v", err)
+	}
+	if !additional {
+		if err := s.State.iam.moveUserToOrg(c.Context(), cr.id, slug); err != nil {
+			return zip.Errorf(http.StatusBadGateway, "org created but could not assign you to it: %v", err)
+		}
+	}
+	return c.JSON(http.StatusOK, onboardResp{Org: slug, DisplayName: displayName, Additional: additional})
+}
+
+// resolveOnboardName derives the base slug + display name from the request, or a
+// mapped HTTP error. Personal orgs derive from the username; a named org validates
+// through the shared policy (onboarding.go).
+func resolveOnboardName(s *cloud.Service[state], body onboardReq, cr caller) (baseSlug, displayName string, err error) {
+	if body.Personal {
+		baseSlug = personalOrgSlug(cr.name)
+		if len(baseSlug) < minOrgSlug || isReservedOrg(baseSlug) {
+			baseSlug = "org-" + firstNonEmpty(slugifyOrg(cr.name), "workspace")
+		}
+		return baseSlug, humanize(cr.name), nil
+	}
+	v := validateOrgName(body.Name)
+	if !v.ok {
+		return "", "", zip.ErrBadRequest(v.error)
+	}
+	return v.slug, strings.TrimSpace(body.Name), nil
+}
+
+// uniqueSlug returns a free slug at/after base. A named org that's taken is a 409;
+// a personal org auto-suffixes (base, base-2, …) up to a small bound.
+func uniqueSlug(s *cloud.Service[state], c *zip.Ctx, base string, personal bool) (string, error) {
+	existing, err := s.State.iam.getOrganization(c.Context(), base)
+	if err != nil {
+		return "", zip.Errorf(http.StatusBadGateway, "could not check organization availability: %v", err)
+	}
+	if existing == nil {
+		return base, nil
+	}
+	if !personal {
+		return "", zip.Errorf(http.StatusConflict, "“%s” is taken; choose a different name", base)
+	}
+	free, err := freeSlug(s, c, base)
+	if err != nil {
+		return "", err
+	}
+	if free == "" {
+		return "", zip.Errorf(http.StatusConflict, "could not find an available name")
+	}
+	return free, nil
+}
+
+// freeSlug finds the first free slug at/after base (base, base-2, … base-20), or ""
+// if all are taken. Mirrors identity.ts's freeSlug bound of 20.
+func freeSlug(s *cloud.Service[state], c *zip.Ctx, base string) (string, error) {
+	for i := 2; i <= 20; i++ {
+		trimmed := base
+		if len(trimmed) > maxOrgSlug-3 {
+			trimmed = trimmed[:maxOrgSlug-3]
+		}
+		candidate := strings.Trim(fmt.Sprintf("%s-%d", strings.TrimRight(trimmed, "-"), i), "-")
+		if len(candidate) < minOrgSlug || isReservedOrg(candidate) {
+			continue
+		}
+		existing, err := s.State.iam.getOrganization(c.Context(), candidate)
+		if err != nil {
+			return "", zip.Errorf(http.StatusBadGateway, "could not check organization availability: %v", err)
+		}
+		if existing == nil {
+			return candidate, nil
+		}
+	}
+	return "", nil
+}
+
+// buildOrg assembles the new customer org owned by the `admin` org, cloning
+// password/locale settings from the caller's current org (best-effort; a nil source
+// just yields a minimal org IAM completes with its defaults) and clearing all
+// instance-specific material. Mirrors identity.ts's createOrganization body.
+func buildOrg(s *cloud.Service[state], c *zip.Ctx, slug, displayName string, personal bool, sourceOwner string) iamOrg {
+	org := iamOrg{Owner: adminOrg, Name: slug, DisplayName: displayName, IsPersonal: personal}
+	if sourceOwner == "" {
+		return org
+	}
+	src, err := s.State.iam.getOrganization(c.Context(), sourceOwner)
+	if err != nil || src == nil {
+		return org // clone is best-effort; IAM applies its org defaults otherwise
+	}
+	org.PasswordType = src.PasswordType
+	org.PasswordSalt = src.PasswordSalt
+	org.PasswordObfuscatorType = src.PasswordObfuscatorType
+	org.PasswordObfuscatorKey = src.PasswordObfuscatorKey
+	org.PasswordOptions = src.PasswordOptions
+	org.CountryCodes = src.CountryCodes
+	org.Languages = src.Languages
+	org.DefaultAvatar = src.DefaultAvatar
+	return org
+}
+
+// ── shared helpers ────────────────────────────────────────────────────────────
+
+// notConfigured is the honest 501 for a surface whose confidential client is
+// unwired — the deployment simply lacks the `hanzo-console` credential.
+func notConfigured(surface string) error {
+	return zip.Errorf(http.StatusNotImplemented, "%s is not configured on this deployment (IAM client unset)", surface)
+}
+
+// humanize title-cases the base of a username for a personal org's display name
+// (dave.smith@x.com → "Dave Smith"). Mirrors identity/onboard humanize().
+func humanize(username string) string {
+	base := username
+	// Split on '@' anywhere (mirrors identity.ts humanize's `includes('@')`), so a
+	// bare "@" collapses to "" → "Personal". (personalOrgSlug intentionally uses
+	// `> 0` instead, matching its own TS source.)
+	if at := strings.IndexByte(base, '@'); at >= 0 {
+		base = base[:at]
+	}
+	base = strings.TrimSpace(strings.Map(func(r rune) rune {
+		if r == '.' || r == '_' || r == '-' {
+			return ' '
+		}
+		return r
+	}, base))
+	if base == "" {
+		return "Personal"
+	}
+	parts := strings.Fields(base)
+	for i, p := range parts {
+		parts[i] = strings.ToUpper(p[:1]) + p[1:]
+	}
+	return strings.Join(parts, " ")
+}
+
+func firstNonEmpty(vals ...string) string {
+	for _, v := range vals {
+		if v != "" {
+			return v
+		}
+	}
+	return ""
+}
+
+func getenv(key, dflt string) string {
+	if v := strings.TrimSpace(os.Getenv(key)); v != "" {
+		return v
+	}
+	return dflt
+}
+
+func basicToken(id, secret string) string {
+	return base64.StdEncoding.EncodeToString([]byte(id + ":" + secret))
+}

clients/account/account_test.go

@@ -0,0 +1,555 @@
+package account
+
+import (
+	"encoding/base64"
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"testing"
+
+	"github.com/hanzoai/cloud"
+	luxlog "github.com/luxfi/log"
+	"github.com/zap-proto/zip"
+)
+
+// fakeIAM is a stand-in for Hanzo IAM's /v1/iam/* management surface. It records
+// the confidential-client Basic auth it received (so a test can assert the console
+// authenticates as `hanzo-console`, NOT as the caller) and the exact `id` each
+// privileged op targeted (so a test can prove the console only ever acts on the
+// validated caller's own `<owner>/<name>`). It never needs a real cluster.
+type fakeIAM struct {
+	mu sync.Mutex
+
+	// state
+	keys map[string]string         // id → current hk- key ("" = none)
+	orgs map[string]map[string]any // slug → org row (nil map = absent)
+	user map[string]map[string]any // id → full user row (for the move)
+
+	// captured
+	gotAuth     string   // Authorization header on the last request
+	mintedFor   []string // ids mint-user-keys was called with
+	revokedFor  []string
+	movedTo     map[string]string // id → new owner (from update-user)
+	createdOrgs []map[string]any
+	failAddOrg  bool // when true, add-organization answers status!=ok
+	failMintKey bool
+}
+
+func newFakeIAM() *fakeIAM {
+	return &fakeIAM{
+		keys:    map[string]string{},
+		orgs:    map[string]map[string]any{},
+		user:    map[string]map[string]any{},
+		movedTo: map[string]string{},
+	}
+}
+
+func (f *fakeIAM) server(t *testing.T) *httptest.Server {
+	t.Helper()
+	mux := http.NewServeMux()
+
+	ok := func(w http.ResponseWriter, data any) {
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(map[string]any{"status": "ok", "msg": "", "data": data})
+	}
+	bad := func(w http.ResponseWriter, msg string) {
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(map[string]any{"status": "error", "msg": msg, "data": nil})
+	}
+
+	mux.HandleFunc("/v1/iam/get-user", func(w http.ResponseWriter, r *http.Request) {
+		f.capture(r)
+		id := r.URL.Query().Get("id")
+		f.mu.Lock()
+		defer f.mu.Unlock()
+		if row, present := f.user[id]; present {
+			// A configured user row wins (used by the onboarding move).
+			out := map[string]any{}
+			for k, v := range row {
+				out[k] = v
+			}
+			if key, has := f.keys[id]; has {
+				out["accessKey"] = key
+			}
+			ok(w, out)
+			return
+		}
+		// Otherwise synthesize a thin row carrying just the key state.
+		ok(w, map[string]any{"accessKey": f.keys[id], "updatedTime": "2026-01-02T03:04:05Z"})
+	})
+
+	mux.HandleFunc("/v1/iam/mint-user-keys", func(w http.ResponseWriter, r *http.Request) {
+		f.capture(r)
+		id := r.URL.Query().Get("id")
+		f.mu.Lock()
+		defer f.mu.Unlock()
+		f.mintedFor = append(f.mintedFor, id)
+		if f.failMintKey {
+			bad(w, "mint failed")
+			return
+		}
+		key := "hk-" + strings.ReplaceAll(id, "/", "-") + "-SECRET"
+		f.keys[id] = key
+		ok(w, map[string]any{"accessKey": key})
+	})
+
+	mux.HandleFunc("/v1/iam/revoke-user-keys", func(w http.ResponseWriter, r *http.Request) {
+		f.capture(r)
+		id := r.URL.Query().Get("id")
+		f.mu.Lock()
+		defer f.mu.Unlock()
+		f.revokedFor = append(f.revokedFor, id)
+		f.keys[id] = ""
+		ok(w, map[string]any{})
+	})
+
+	mux.HandleFunc("/v1/iam/get-organization", func(w http.ResponseWriter, r *http.Request) {
+		f.capture(r)
+		id := r.URL.Query().Get("id") // admin/<slug>
+		slug := id
+		if i := strings.IndexByte(id, '/'); i >= 0 {
+			slug = id[i+1:]
+		}
+		f.mu.Lock()
+		defer f.mu.Unlock()
+		if row, present := f.orgs[slug]; present && row != nil {
+			ok(w, row)
+			return
+		}
+		bad(w, "organization does not exist") // not-ok ⇒ getOrganization returns (nil,nil)
+	})
+
+	mux.HandleFunc("/v1/iam/add-organization", func(w http.ResponseWriter, r *http.Request) {
+		f.capture(r)
+		body, _ := io.ReadAll(r.Body)
+		var row map[string]any
+		_ = json.Unmarshal(body, &row)
+		f.mu.Lock()
+		defer f.mu.Unlock()
+		if f.failAddOrg {
+			bad(w, "add-organization denied")
+			return
+		}
+		f.createdOrgs = append(f.createdOrgs, row)
+		if name, _ := row["name"].(string); name != "" {
+			f.orgs[name] = row
+		}
+		ok(w, map[string]any{})
+	})
+
+	mux.HandleFunc("/v1/iam/update-user", func(w http.ResponseWriter, r *http.Request) {
+		f.capture(r)
+		id := r.URL.Query().Get("id")
+		body, _ := io.ReadAll(r.Body)
+		var row map[string]any
+		_ = json.Unmarshal(body, &row)
+		f.mu.Lock()
+		defer f.mu.Unlock()
+		if owner, _ := row["owner"].(string); owner != "" {
+			f.movedTo[id] = owner
+		}
+		ok(w, map[string]any{})
+	})
+
+	srv := httptest.NewServer(mux)
+	t.Cleanup(srv.Close)
+	return srv
+}
+
+func (f *fakeIAM) capture(r *http.Request) {
+	f.mu.Lock()
+	f.gotAuth = r.Header.Get("Authorization")
+	f.mu.Unlock()
+}
+
+// mountApp mounts the account surface against the fake IAM at base, with the
+// confidential client wired (unless creds are ""). Returns the app.
+func mountApp(t *testing.T, base, clientID, clientSecret string) *zip.App {
+	t.Helper()
+	t.Setenv("IAM_URL", base)
+	t.Setenv("IAM_MINT_CLIENT_ID", clientID)
+	t.Setenv("IAM_MINT_CLIENT_SECRET", clientSecret)
+	return mountBoth(t, "hanzo")
+}
+
+// mountBoth mounts BOTH account subsystems (self-service + data bridges) on one app —
+// exactly what production registers (account@48 then account-bridge@122), so a test
+// exercises the full surface with the shared CSRF key. The caller sets the IAM env
+// (IAM_URL / IAM_MINT_CLIENT_*) before calling.
+func mountBoth(t *testing.T, brand string) *zip.App {
+	t.Helper()
+	app := zip.New(zip.Config{Logger: luxlog.New("test")})
+	deps := cloud.Deps{Logger: luxlog.New("test"), Brand: brand}
+	if err := MountAccount(app, deps); err != nil {
+		t.Fatalf("MountAccount: %v", err)
+	}
+	if err := MountBridge(app, deps); err != nil {
+		t.Fatalf("MountBridge: %v", err)
+	}
+	return app
+}
+
+// callH drives a request with arbitrary VALIDATED-identity headers (the gateway sets
+// these only from a verified credential). Mirrors `call` but lets a test inject
+// X-User-Email / X-User-IsAdmin, which the ported routes read.
+func callH(t *testing.T, app *zip.App, method, path string, headers map[string]string, body string) (int, []byte) {
+	t.Helper()
+	var rdr io.Reader
+	if body != "" {
+		rdr = strings.NewReader(body)
+	}
+	req := httptest.NewRequest(method, path, rdr)
+	if body != "" {
+		req.Header.Set("Content-Type", "application/json")
+	}
+	for k, v := range headers {
+		if v != "" {
+			req.Header.Set(k, v)
+		}
+	}
+	resp, err := app.Fiber().Test(req)
+	if err != nil {
+		t.Fatalf("Test %s %s: %v", method, path, err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+	b, _ := io.ReadAll(resp.Body)
+	return resp.StatusCode, b
+}
+
+// call drives a request through the mounted app. When user is non-empty it injects
+// a VALIDATED principal (X-User-Id set — the gateway sets this ONLY from a verified
+// credential) with org as X-Org-Id. body is an optional JSON string.
+func call(t *testing.T, app *zip.App, method, path, user, org, body string) (int, []byte) {
+	t.Helper()
+	var rdr io.Reader
+	if body != "" {
+		rdr = strings.NewReader(body)
+	}
+	req := httptest.NewRequest(method, path, rdr)
+	if body != "" {
+		req.Header.Set("Content-Type", "application/json")
+	}
+	if user != "" {
+		req.Header.Set("X-User-Id", user)
+	}
+	if org != "" {
+		req.Header.Set("X-Org-Id", org)
+	}
+	resp, err := app.Fiber().Test(req)
+	if err != nil {
+		t.Fatalf("Test %s %s: %v", method, path, err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+	b, _ := io.ReadAll(resp.Body)
+	return resp.StatusCode, b
+}
+
+// ── keys ──────────────────────────────────────────────────────────────────────
+
+func TestKeys_RequireValidatedPrincipal(t *testing.T) {
+	f := newFakeIAM()
+	app := mountApp(t, f.server(t).URL, "hanzo-console", "s3cr3t")
+
+	// No X-User-Id → no validated principal → 403, and IAM is never touched, even if
+	// a forged X-Org-Id is present (the bearer-less data path must not mint a key).
+	for _, m := range []string{http.MethodGet, http.MethodPost, http.MethodDelete} {
+		code, _ := call(t, app, m, "/v1/iam/keys", "", "victim", "")
+		if code != http.StatusForbidden {
+			t.Fatalf("%s /keys with forged org but no principal: want 403, got %d", m, code)
+		}
+	}
+	if len(f.mintedFor) != 0 || len(f.revokedFor) != 0 {
+		t.Fatalf("IAM privileged op reached on the unauthenticated path: minted=%v revoked=%v", f.mintedFor, f.revokedFor)
+	}
+}
+
+func TestKeys_MintGetRevoke_ScopedToCaller(t *testing.T) {
+	f := newFakeIAM()
+	app := mountApp(t, f.server(t).URL, "hanzo-console", "s3cr3t")
+
+	// GET before mint → hasKey:false (authoritative IAM read, not the claim).
+	code, body := call(t, app, http.MethodGet, "/v1/iam/keys", "alice", "acme", "")
+	if code != http.StatusOK {
+		t.Fatalf("get pre-mint: want 200, got %d (%s)", code, body)
+	}
+	var st keyStatus
+	mustJSON(t, body, &st)
+	if st.HasKey {
+		t.Fatalf("pre-mint hasKey should be false: %s", body)
+	}
+
+	// POST → mint; the key is returned ONCE, and IAM was targeted with the DERIVED
+	// `<owner>/<name>` id — never a request value.
+	code, body = call(t, app, http.MethodPost, "/v1/iam/keys", "alice", "acme", "")
+	if code != http.StatusOK {
+		t.Fatalf("mint: want 200, got %d (%s)", code, body)
+	}
+	var minted struct {
+		AccessKey string `json:"accessKey"`
+	}
+	mustJSON(t, body, &minted)
+	if minted.AccessKey != "hk-acme-alice-SECRET" {
+		t.Fatalf("mint returned wrong key: %q", minted.AccessKey)
+	}
+	if len(f.mintedFor) != 1 || f.mintedFor[0] != "acme/alice" {
+		t.Fatalf("mint should target the derived id acme/alice, got %v", f.mintedFor)
+	}
+
+	// The confidential client authenticated as `hanzo-console` (Basic), NOT as the
+	// caller — the whole point of the app-on-behalf boundary.
+	wantAuth := "Basic " + base64.StdEncoding.EncodeToString([]byte("hanzo-console:s3cr3t"))
+	if f.gotAuth != wantAuth {
+		t.Fatalf("IAM auth: want confidential-client Basic, got %q", f.gotAuth)
+	}
+
+	// GET after mint → hasKey:true with the public prefix only (no secret material).
+	code, body = call(t, app, http.MethodGet, "/v1/iam/keys", "alice", "acme", "")
+	mustJSON(t, body, &st)
+	if code != http.StatusOK || !st.HasKey || st.KeyPrefix != "hk-acme-ali" {
+		t.Fatalf("get post-mint: want hasKey + 11-char prefix, got %d %s", code, body)
+	}
+	if strings.Contains(string(body), "SECRET") {
+		t.Fatalf("GET /keys leaked the secret: %s", body)
+	}
+
+	// DELETE → revoke, targeting the same derived id.
+	code, _ = call(t, app, http.MethodDelete, "/v1/iam/keys", "alice", "acme", "")
+	if code != http.StatusOK || len(f.revokedFor) != 1 || f.revokedFor[0] != "acme/alice" {
+		t.Fatalf("revoke: want 200 targeting acme/alice, got %d %v", code, f.revokedFor)
+	}
+}
+
+// TestKeys_DirectBearerPath_MintsByUsernameNotUUID is the regression guard for the
+// cloud-direct hk- mint 502. On the in-binary direct-Bearer path SanitizeIdentity
+// stamps X-User-Id = the JWT subject (a UUID) and, distinctly, X-User-Name = the IAM
+// username. The user-key ops must target <owner>/<username> ("hanzo/z"), NOT
+// <owner>/<uuid> — which failed IAM's GetOwnerAndNameFromId user lookup ("password
+// or code is incorrect", surfaced as 502). The gateway path (no X-User-Name;
+// X-User-Id == username) must be UNCHANGED (keyID falls back to owner/name).
+func TestKeys_DirectBearerPath_MintsByUsernameNotUUID(t *testing.T) {
+	f := newFakeIAM()
+	app := mountApp(t, f.server(t).URL, "hanzo-console", "s3cr3t")
+
+	const uuid = "2d4d67ab-30f1-474e-b81f-f60461852259"
+	req := httptest.NewRequest(http.MethodPost, "/v1/iam/keys", nil)
+	req.Header.Set("X-User-Id", uuid)  // direct-path stamp: the subject UUID
+	req.Header.Set("X-User-Name", "z") // direct-path stamp: the IAM username
+	req.Header.Set("X-Org-Id", "hanzo")
+	resp, err := app.Fiber().Test(req)
+	if err != nil {
+		t.Fatalf("Test: %v", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+	b, _ := io.ReadAll(resp.Body)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("direct-path mint: want 200, got %d (%s)", resp.StatusCode, b)
+	}
+	if len(f.mintedFor) != 1 || f.mintedFor[0] != "hanzo/z" {
+		t.Fatalf("direct-path mint must target hanzo/z (username), never hanzo/<uuid>: got %v", f.mintedFor)
+	}
+	var minted struct {
+		AccessKey string `json:"accessKey"`
+	}
+	mustJSON(t, b, &minted)
+	if minted.AccessKey != "hk-hanzo-z-SECRET" {
+		t.Fatalf("direct-path mint returned wrong key: %q", minted.AccessKey)
+	}
+}
+
+func TestKeys_NotConfigured_501(t *testing.T) {
+	f := newFakeIAM()
+	app := mountApp(t, f.server(t).URL, "", "") // confidential client unwired
+	code, body := call(t, app, http.MethodPost, "/v1/iam/keys", "alice", "acme", "")
+	if code != http.StatusNotImplemented {
+		t.Fatalf("unconfigured mint: want 501, got %d (%s)", code, body)
+	}
+}
+
+func TestKeys_MintUpstreamFailure_502(t *testing.T) {
+	f := newFakeIAM()
+	f.failMintKey = true
+	app := mountApp(t, f.server(t).URL, "hanzo-console", "s3cr3t")
+	code, body := call(t, app, http.MethodPost, "/v1/iam/keys", "alice", "acme", "")
+	if code != http.StatusBadGateway {
+		t.Fatalf("mint upstream failure: want 502, got %d (%s)", code, body)
+	}
+}
+
+// ── onboard ─────────────────────────────────────────────────────────────────
+
+func TestOnboard_FirstRun_CreatesAndMoves(t *testing.T) {
+	f := newFakeIAM()
+	// The zero-org user (empty X-Org-Id ⇒ bare id "dave") has a real user row so the
+	// move can re-submit it.
+	f.user["dave"] = map[string]any{"owner": "", "name": "dave", "type": "normal-user"}
+	app := mountApp(t, f.server(t).URL, "hanzo-console", "s3cr3t")
+
+	// First-run: the caller has NO org (empty X-Org-Id) but IS validated. onboard
+	// must allow it (requireOwner=false), create the org, and MOVE the user in.
+	code, body := call(t, app, http.MethodPost, "/v1/iam/onboard", "dave", "", `{"name":"Acme Rockets"}`)
+	if code != http.StatusOK {
+		t.Fatalf("first-run onboard: want 200, got %d (%s)", code, body)
+	}
+	var resp onboardResp
+	mustJSON(t, body, &resp)
+	if resp.Org != "acme-rockets" || resp.Additional {
+		t.Fatalf("onboard result wrong: %+v", resp)
+	}
+	if len(f.createdOrgs) != 1 {
+		t.Fatalf("want 1 org created, got %d", len(f.createdOrgs))
+	}
+	if owner, _ := f.createdOrgs[0]["owner"].(string); owner != "admin" {
+		t.Fatalf("created org must be owned by admin, got %q", owner)
+	}
+	if f.movedTo["dave"] != "acme-rockets" {
+		t.Fatalf("first-run must move the user into the new org, movedTo=%v", f.movedTo)
+	}
+}
+
+func TestOnboard_Additional_CreatesWithoutMoving(t *testing.T) {
+	f := newFakeIAM()
+	app := mountApp(t, f.server(t).URL, "hanzo-console", "s3cr3t")
+
+	// The caller ALREADY has an org. onboard must create the new org but NOT move
+	// them (a move would strip their owner + orphan their current org).
+	code, body := call(t, app, http.MethodPost, "/v1/iam/onboard", "alice", "acme", `{"name":"Side Project"}`)
+	if code != http.StatusOK {
+		t.Fatalf("additional onboard: want 200, got %d (%s)", code, body)
+	}
+	var resp onboardResp
+	mustJSON(t, body, &resp)
+	if resp.Org != "side-project" || !resp.Additional {
+		t.Fatalf("additional onboard result wrong: %+v", resp)
+	}
+	if len(f.movedTo) != 0 {
+		t.Fatalf("additional onboard must NOT move the user, movedTo=%v", f.movedTo)
+	}
+}
+
+func TestOnboard_ReservedAndTaken(t *testing.T) {
+	f := newFakeIAM()
+	f.orgs["taken"] = map[string]any{"owner": "admin", "name": "taken"}
+	app := mountApp(t, f.server(t).URL, "hanzo-console", "s3cr3t")
+
+	// A reserved brand/system name is a 400 (policy), before any IAM create.
+	code, _ := call(t, app, http.MethodPost, "/v1/iam/onboard", "alice", "acme", `{"name":"Hanzo"}`)
+	if code != http.StatusBadRequest {
+		t.Fatalf("reserved name: want 400, got %d", code)
+	}
+	// An explicit name that's taken is an honest 409.
+	code, _ = call(t, app, http.MethodPost, "/v1/iam/onboard", "alice", "acme", `{"name":"Taken"}`)
+	if code != http.StatusConflict {
+		t.Fatalf("taken name: want 409, got %d", code)
+	}
+	if len(f.createdOrgs) != 0 {
+		t.Fatalf("no org should be created for reserved/taken names, got %d", len(f.createdOrgs))
+	}
+}
+
+func TestOnboard_Personal_AutoSuffixesOnCollision(t *testing.T) {
+	f := newFakeIAM()
+	f.user["dave"] = map[string]any{"owner": "", "name": "dave"}
+	f.orgs["dave"] = map[string]any{"owner": "admin", "name": "dave"} // base personal slug already taken
+	app := mountApp(t, f.server(t).URL, "hanzo-console", "s3cr3t")
+
+	// personal:true (zero-org user) with the base slug taken → auto-suffix to dave-2,
+	// first-run move.
+	code, body := call(t, app, http.MethodPost, "/v1/iam/onboard", "dave", "", `{"personal":true}`)
+	if code != http.StatusOK {
+		t.Fatalf("personal onboard: want 200, got %d (%s)", code, body)
+	}
+	var resp onboardResp
+	mustJSON(t, body, &resp)
+	if resp.Org != "dave-2" {
+		t.Fatalf("personal collision should auto-suffix to dave-2, got %q", resp.Org)
+	}
+}
+
+func TestOnboard_PersonalWhenAlreadyOrged_409(t *testing.T) {
+	f := newFakeIAM()
+	app := mountApp(t, f.server(t).URL, "hanzo-console", "s3cr3t")
+	// A user WITH an org asking for a personal org is meaningless → 409.
+	code, _ := call(t, app, http.MethodPost, "/v1/iam/onboard", "alice", "acme", `{"personal":true}`)
+	if code != http.StatusConflict {
+		t.Fatalf("personal-while-orged: want 409, got %d", code)
+	}
+}
+
+func TestOnboard_Unauthenticated_403(t *testing.T) {
+	f := newFakeIAM()
+	app := mountApp(t, f.server(t).URL, "hanzo-console", "s3cr3t")
+	code, _ := call(t, app, http.MethodPost, "/v1/iam/onboard", "", "", `{"name":"x"}`)
+	if code != http.StatusForbidden {
+		t.Fatalf("unauth onboard: want 403, got %d", code)
+	}
+}
+
+// ── route ordering: the native /v1/iam surface beats clients/iam's wildcard ───
+
+// TestIAMKeysBeatsWildcard proves the ACTUAL route-match precedence: with the account
+// self-service routes mounted FIRST (order 48) and clients/iam's /v1/iam/* WILDCARD
+// mounted AFTER (order 50) — the exact production mount order — a request to /v1/iam/keys
+// reaches the NATIVE handler, not the wildcard. A path the native surface does NOT own
+// still falls through to the wildcard, proving it is really mounted and only the specific
+// route shadows it.
+func TestIAMKeysBeatsWildcard(t *testing.T) {
+	f := newFakeIAM()
+	t.Setenv("IAM_URL", f.server(t).URL)
+	t.Setenv("IAM_MINT_CLIENT_ID", "hanzo-console")
+	t.Setenv("IAM_MINT_CLIENT_SECRET", "s3cr3t")
+
+	app := zip.New(zip.Config{Logger: luxlog.New("test")})
+	deps := cloud.Deps{Logger: luxlog.New("test"), Brand: "hanzo"}
+	// account (order 48) mounts its SPECIFIC /v1/iam/keys + /v1/iam/onboard FIRST.
+	if err := MountAccount(app, deps); err != nil {
+		t.Fatalf("MountAccount: %v", err)
+	}
+	// clients/iam (order 50) mounts its /v1/iam/* WILDCARD AFTER — the exact prod order.
+	const sentinel = 599
+	app.All("/v1/iam/*", func(c *zip.Ctx) error {
+		return c.JSON(sentinel, map[string]string{"handler": "iam-wildcard"})
+	})
+
+	// GET /v1/iam/keys must hit the NATIVE handler (keyStatus 200), never the wildcard.
+	code, body := call(t, app, http.MethodGet, "/v1/iam/keys", "alice", "acme", "")
+	if code != http.StatusOK {
+		t.Fatalf("/v1/iam/keys must hit the native handler (200), got %d (%s) — wildcard shadowed it", code, body)
+	}
+	if strings.Contains(string(body), "iam-wildcard") {
+		t.Fatalf("/v1/iam/keys reached the wildcard, not the native handler: %s", body)
+	}
+	var st keyStatus
+	mustJSON(t, body, &st) // native response shape
+
+	// POST /v1/iam/keys (mint) must ALSO hit the native handler and target the derived id.
+	code, body = call(t, app, http.MethodPost, "/v1/iam/keys", "alice", "acme", "")
+	if code != http.StatusOK || strings.Contains(string(body), "iam-wildcard") {
+		t.Fatalf("POST /v1/iam/keys must mint via the native handler, got %d (%s)", code, body)
+	}
+	if len(f.mintedFor) != 1 || f.mintedFor[0] != "acme/alice" {
+		t.Fatalf("native mint must target acme/alice, got %v", f.mintedFor)
+	}
+
+	// /v1/iam/onboard is likewise native (not the wildcard).
+	code, _ = call(t, app, http.MethodPost, "/v1/iam/onboard", "dave", "", `{"name":"Acme Rockets"}`)
+	if code == sentinel {
+		t.Fatalf("/v1/iam/onboard reached the wildcard (%d) — the native handler must win", sentinel)
+	}
+
+	// A path the native surface does NOT own falls through to the wildcard (proof it IS
+	// mounted and only the specific /v1/iam/keys + /v1/iam/onboard routes shadow it).
+	code, _ = call(t, app, http.MethodGet, "/v1/iam/oauth/token", "alice", "acme", "")
+	if code != sentinel {
+		t.Fatalf("/v1/iam/oauth/token must reach the /v1/iam/* wildcard (%d), got %d", sentinel, code)
+	}
+}
+
+func mustJSON(t *testing.T, body []byte, v any) {
+	t.Helper()
+	if err := json.Unmarshal(body, v); err != nil {
+		t.Fatalf("decode %T: %v (%s)", v, err, body)
+	}
+}

clients/account/billing.go

@@ -0,0 +1,208 @@
+// billing.go — the per-tenant billing DATA bridge, the Go port of console's
+// app/billing/v1/[...path]/route.ts (task #41, the BFF catch-all sweep). It lets the
+// statically-exported console reach its own money surface at the CANONICAL same-origin
+// /v1/billing/* (nothing before /v1/): GET|POST /v1/billing/<path> forwards to
+// commerce's /v1/billing/<path> with the admin COMMERCE_SERVICE_TOKEN, SCOPING every
+// request to the VALIDATED caller's own billing subject — so a tenant can only ever
+// read/act on its OWN ledger (balance / usage / invoices / subscriptions /
+// payment-methods / spend-alerts / …), never another's.
+//
+// WHY A SERVER HANDLER (not a same-origin passthrough). Commerce's billing surface is
+// service-token-gated and filters DIFFERENT endpoints on DIFFERENT subject params —
+// subscriptions on ?userId, payment-methods on ?customerId, usage on ?user. Pinning
+// only ONE leaves the others UNFILTERED, so a request with no (or a forged) param
+// returns every subject's rows in the namespace. This handler pins ALL of them to the
+// server-resolved subject (and drops ?org), on the query AND the write body — exactly
+// mirroring console's billing-scope.ts and commerce's own edge-auth billingSubjectKeys.
+//
+// IDOR-safe: the subject is derived from the VALIDATED identity (resolveCaller →
+// principal.Validated / c.Org() / c.User()), NEVER a client-supplied userId/org. A
+// bearer-less request with a forged X-Org-Id has no validated principal and is refused.
+package account
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/url"
+	"strings"
+	"unicode"
+
+	"github.com/hanzoai/cloud"
+	"github.com/zap-proto/zip"
+)
+
+// billingSubjectKeys — every query/body param through which a commerce billing endpoint
+// identifies its subject. Kept identical to commerce's edge-auth billingSubjectKeys
+// {user,userId,customerId} AND console's billing-scope.ts BILLING_SUBJECT_KEYS. Change
+// all three together — pinning ALL of them is what scopes EVERY endpoint no matter which
+// param it filters on.
+var billingSubjectKeys = []string{"user", "userId", "customerId"}
+
+func isSubjectKey(k string) bool {
+	for _, s := range billingSubjectKeys {
+		if s == k {
+			return true
+		}
+	}
+	return false
+}
+
+// personalBillingOrgs — orgs whose members bill per-USER (the shared catch-all).
+// Mirrors commerce's PERSONAL_BILLING_ORGS and billing-scope.ts personalBillingOrgs:
+// default "hanzo"; PERSONAL_BILLING_ORGS or HANZO_DEFAULT_ORG overrides (comma list).
+func personalBillingOrgs() map[string]bool {
+	raw := getenv("PERSONAL_BILLING_ORGS", getenv("HANZO_DEFAULT_ORG", "hanzo"))
+	out := map[string]bool{}
+	for _, p := range strings.Split(raw, ",") {
+		if p = strings.ToLower(strings.TrimSpace(p)); p != "" {
+			out[p] = true
+		}
+	}
+	return out
+}
+
+// billingSubject — the commerce billing subject for an org+user, the SAME subject the
+// gateway debits: a member of a personal-billing org bills per-user as "<org>/<name>";
+// a dedicated org bills per-org as "<org>". Mirrors billing-scope.ts billingSubject.
+func billingSubject(org, name string) string {
+	o := strings.ToLower(strings.TrimSpace(org))
+	if o == "" {
+		return ""
+	}
+	if personalBillingOrgs()[o] {
+		if n := strings.ToLower(strings.TrimSpace(name)); n != "" {
+			return o + "/" + n
+		}
+	}
+	return o
+}
+
+// scopedBillingSearch — pin every billingSubjectKey to subject (OVERWRITING any client
+// value — the browser cannot widen scope) and DROP org. Every OTHER param (currency,
+// status, date range) passes through untouched. Mirrors billing-scope.ts.
+func scopedBillingSearch(in url.Values, subject string) url.Values {
+	out := url.Values{}
+	for k, v := range in {
+		if k == "org" || isSubjectKey(k) {
+			continue // org dropped; subject keys set authoritatively below
+		}
+		out[k] = v
+	}
+	for _, k := range billingSubjectKeys {
+		out.Set(k, subject)
+	}
+	return out
+}
+
+// scopedBillingBody — pin every billingSubjectKey on a top-level JSON object to subject
+// (commerce reads the subject from the JSON body on writes like create-spend-alert). A
+// non-JSON / non-object / empty body is returned UNCHANGED — this only ever narrows a
+// JSON object to the caller; it never invents a body. Mirrors billing-scope.ts.
+func scopedBillingBody(raw []byte, subject string) []byte {
+	if len(bytes.TrimSpace(raw)) == 0 {
+		return raw
+	}
+	var obj map[string]json.RawMessage
+	if err := json.Unmarshal(raw, &obj); err != nil {
+		return raw // JSON array / scalar / form / binary — leave untouched
+	}
+	subj, err := json.Marshal(subject)
+	if err != nil {
+		return raw
+	}
+	for _, k := range billingSubjectKeys {
+		obj[k] = subj
+	}
+	out, err := json.Marshal(obj)
+	if err != nil {
+		return raw
+	}
+	return out
+}
+
+// isSafeSegment reports whether a path segment is safe to forward. It is the ONE segment
+// guard for this package (the billing AND commerce bridges): a segment is safe only if
+// it is non-empty, not "." / "..", and free of any character a downstream router could
+// re-split or re-decode into traversal — slash, backslash, percent-escape (`%2f`/`%2e`,
+// single- or N-encoded), matrix param (`;`), or a control char (incl. null). The router
+// leaves `%2f`/`%2e` UNdecoded in the wildcard param, but the Go http client — and
+// commerce's own router — WILL decode+normalize them downstream, turning
+// `x/..%2fbilling` into `/v1/billing`: a tunnel PAST the allow-list into the money
+// surface. Rejecting `%`/`;` at the segment makes single-, double-, and N-encoded
+// traversal impossible. Billing endpoints / commerce ids are opaque + escape-free, so
+// this never over-blocks. Mirrors console's bearer-proxy pathIsClean.
+func isSafeSegment(s string) bool {
+	if s == "" || s == "." || s == ".." {
+		return false
+	}
+	for _, r := range s {
+		if r == '/' || r == '\\' || r == '%' || r == ';' || unicode.IsControl(r) {
+			return false
+		}
+	}
+	return true
+}
+
+// commerceCreds resolves the commerce base + admin S2S token from server-only env
+// (COMMERCE_URL default the public gateway; COMMERCE_SERVICE_TOKEN sourced from KMS —
+// never a browser value). Same wiring as clients/admin + topup.go's HUSD credit.
+func commerceCreds() (base, token string) {
+	base = strings.TrimRight(getenv("COMMERCE_URL", "https://api.hanzo.ai"), "/")
+	token = getenv("COMMERCE_SERVICE_TOKEN", "")
+	return
+}
+
+// billingData forwards GET|POST /v1/billing/<path> to commerce's /v1/billing/<path>,
+// scoped to the caller's OWN subject. Mirrors GET/POST app/billing/v1/[...path]/route.ts.
+func billingData(s *cloud.Service[state], c *zip.Ctx) error {
+	// IDOR boundary: the subject is the VALIDATED caller's own org/user, never a client
+	// value. requireOwner=true — billing is always org-scoped (a zero-org user has none).
+	cr, ok := resolveCaller(c, true)
+	if !ok {
+		return zip.ErrForbidden("sign in to view billing")
+	}
+
+	method := c.Method()
+	if method != http.MethodGet && method != http.MethodPost {
+		return zip.Errorf(http.StatusMethodNotAllowed, "method not allowed")
+	}
+
+	base, token := commerceCreds()
+	if token == "" {
+		// Honest "not configured" (mirrors the Node route's 501 when COMMERCE_TOKEN
+		// is unset) — the console shows a truthful state, never a fabricated balance.
+		return zip.Errorf(http.StatusNotImplemented, "billing is not configured on this deployment (COMMERCE_SERVICE_TOKEN unset)")
+	}
+
+	sub := strings.Trim(strings.TrimPrefix(c.Fiber().Params("*"), "/"), "/")
+	if sub == "" {
+		return zip.Errorf(http.StatusNotFound, "billing endpoint required")
+	}
+	for _, seg := range strings.Split(sub, "/") {
+		if !isSafeSegment(seg) {
+			return zip.ErrBadRequest("invalid billing path")
+		}
+	}
+
+	// Scope EVERY request to the caller's OWN subject — query AND write body — so
+	// commerce's per-tenant isolation can never be crossed from the browser.
+	subject := billingSubject(cr.owner, cr.name)
+	inQuery, _ := url.ParseQuery(string(c.Fiber().Request().URI().QueryString()))
+	q := scopedBillingSearch(inQuery, subject)
+
+	var body []byte
+	if method == http.MethodPost {
+		body = scopedBillingBody(c.Body(), subject)
+	}
+
+	raw, status, err := commerceDo(c.Context(), base, token, method, "/v1/billing/"+sub, q, cr.owner, body)
+	if err != nil {
+		return zip.Errorf(http.StatusBadGateway, "billing upstream unreachable: %v", err)
+	}
+	// A per-tenant money response must NEVER be cached (a stale balance after a
+	// completion/top-up); commerce answers JSON, so pin JSON + no-store.
+	c.SetHeader("Content-Type", "application/json")
+	c.SetHeader("Cache-Control", "no-store, must-revalidate")
+	return c.Bytes(status, raw)
+}

clients/account/billing_test.go

@@ -0,0 +1,208 @@
+package account
+
+import (
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"sync"
+	"testing"
+)
+
+// billing_test.go — the per-tenant billing bridge (billing.go). Proves the tenant
+// scoping that prevents cross-tenant billing reads (the Go port of console's
+// billing-scope.test.ts) AND the IDOR-safe handler forwarding.
+
+// ── pure scoping ─────────────────────────────────────────────────────────────
+
+func TestBillingSubject(t *testing.T) {
+	t.Setenv("PERSONAL_BILLING_ORGS", "hanzo")
+	cases := []struct{ org, name, want string }{
+		{"acme", "alice", "acme"},       // dedicated org bills per-ORG
+		{"hanzo", "Dave", "hanzo/dave"}, // personal-billing org bills per-USER (lowercased)
+		{"hanzo", "", "hanzo"},          // personal org, no name → org
+		{"", "x", ""},                   // no org → empty subject
+	}
+	for _, c := range cases {
+		if got := billingSubject(c.org, c.name); got != c.want {
+			t.Fatalf("billingSubject(%q,%q): want %q, got %q", c.org, c.name, c.want, got)
+		}
+	}
+}
+
+func TestScopedBillingSearch_PinsSubjectDropsOrgKeepsRest(t *testing.T) {
+	in := url.Values{}
+	in.Set("userId", "victim")     // forged subject — must be OVERWRITTEN
+	in.Set("customerId", "victim") // forged subject — must be OVERWRITTEN
+	in.Set("user", "victim")       // forged subject — must be OVERWRITTEN
+	in.Set("org", "othercorp")     // must be DROPPED (cannot widen scope)
+	in.Set("currency", "usd")      // non-subject — must PASS THROUGH
+	in.Set("start", "2026-01-01")  // non-subject — must PASS THROUGH
+
+	out := scopedBillingSearch(in, "acme")
+
+	for _, k := range billingSubjectKeys {
+		if out.Get(k) != "acme" {
+			t.Fatalf("subject key %s must be pinned to acme, got %q", k, out.Get(k))
+		}
+	}
+	if out.Has("org") {
+		t.Fatal("org must be dropped")
+	}
+	if out.Get("currency") != "usd" || out.Get("start") != "2026-01-01" {
+		t.Fatalf("non-subject params must pass through, got %v", out)
+	}
+}
+
+func TestScopedBillingBody(t *testing.T) {
+	// a forged subject in a JSON object write is OVERWRITTEN; other fields survive.
+	out := scopedBillingBody([]byte(`{"userId":"victim","amount":500,"note":"x"}`), "acme")
+	var obj map[string]any
+	if err := json.Unmarshal(out, &obj); err != nil {
+		t.Fatalf("scoped body is not JSON: %v", err)
+	}
+	for _, k := range billingSubjectKeys {
+		if obj[k] != "acme" {
+			t.Fatalf("body subject key %s must be pinned to acme, got %v", k, obj[k])
+		}
+	}
+	if obj["amount"].(float64) != 500 || obj["note"] != "x" {
+		t.Fatalf("non-subject body fields must survive, got %v", obj)
+	}
+
+	// non-object / empty bodies pass through untouched (never invent a body).
+	for _, raw := range []string{"not json", `[1,2,3]`, `"scalar"`, ""} {
+		if got := string(scopedBillingBody([]byte(raw), "acme")); got != raw {
+			t.Fatalf("non-object body %q must pass through, got %q", raw, got)
+		}
+	}
+}
+
+// ── handler (IDOR + forwarding) ──────────────────────────────────────────────
+
+// fakeBilling records exactly what the handler forwarded to commerce.
+type fakeBilling struct {
+	mu    sync.Mutex
+	path  string
+	query url.Values
+	body  map[string]any
+	org   string
+	auth  string
+}
+
+func (f *fakeBilling) server(t *testing.T) *httptest.Server {
+	t.Helper()
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		f.mu.Lock()
+		f.path, f.query = r.URL.Path, r.URL.Query()
+		f.org, f.auth = r.Header.Get("X-Org-Id"), r.Header.Get("Authorization")
+		if raw, _ := io.ReadAll(r.Body); len(raw) > 0 {
+			_ = json.Unmarshal(raw, &f.body)
+		}
+		f.mu.Unlock()
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = io.WriteString(w, `{"balance":123}`)
+	}))
+	t.Cleanup(srv.Close)
+	return srv
+}
+
+func TestBilling_RequiresValidatedPrincipal(t *testing.T) {
+	t.Setenv("COMMERCE_SERVICE_TOKEN", "svc-tok")
+	app := mountApp(t, "http://iam.invalid", "", "")
+	// A forged X-Org-Id with NO validated X-User-Id is the exact forge — refuse it
+	// BEFORE any commerce call (no cross-tenant ledger read on a victim org).
+	code, _ := callH(t, app, http.MethodGet, "/v1/billing/balance", map[string]string{"X-Org-Id": "victim"}, "")
+	if code != http.StatusForbidden {
+		t.Fatalf("no validated principal: want 403, got %d", code)
+	}
+}
+
+func TestBilling_NotConfiguredWithoutToken(t *testing.T) {
+	t.Setenv("COMMERCE_SERVICE_TOKEN", "")
+	app := mountApp(t, "http://iam.invalid", "", "")
+	code, _ := callH(t, app, http.MethodGet, "/v1/billing/balance", alice, "")
+	if code != http.StatusNotImplemented {
+		t.Fatalf("no commerce token: want 501, got %d", code)
+	}
+}
+
+func TestBilling_ScopesQueryToCallerAndForwards(t *testing.T) {
+	f := &fakeBilling{}
+	t.Setenv("COMMERCE_URL", f.server(t).URL)
+	t.Setenv("COMMERCE_SERVICE_TOKEN", "svc-tok")
+	t.Setenv("PERSONAL_BILLING_ORGS", "hanzo") // acme is a DEDICATED org → subject "acme"
+	app := mountApp(t, "http://iam.invalid", "", "")
+
+	// alice/acme with a FORGED ?userId=victim & ?org=othercorp: the handler must pin
+	// every subject key to the caller's own subject (acme) and drop org.
+	code, body := callH(t, app, http.MethodGet,
+		"/v1/billing/invoices?userId=victim&customerId=victim&org=othercorp&status=open", alice, "")
+	if code != http.StatusOK {
+		t.Fatalf("want 200, got %d (%s)", code, body)
+	}
+	if f.path != "/v1/billing/invoices" {
+		t.Fatalf("forwarded path: want /v1/billing/invoices, got %q", f.path)
+	}
+	for _, k := range billingSubjectKeys {
+		if f.query.Get(k) != "acme" {
+			t.Fatalf("commerce must receive %s=acme (the caller's subject), got %q", k, f.query.Get(k))
+		}
+	}
+	if f.query.Has("org") {
+		t.Fatal("org must be dropped before commerce")
+	}
+	if f.query.Get("status") != "open" {
+		t.Fatalf("non-subject filter must pass through, got %q", f.query.Get("status"))
+	}
+	if f.org != "acme" || f.auth != "Bearer svc-tok" {
+		t.Fatalf("S2S must send X-Org-Id=acme + the service token, got org=%q auth=%q", f.org, f.auth)
+	}
+}
+
+func TestBilling_ScopesWriteBodyToCaller(t *testing.T) {
+	f := &fakeBilling{}
+	t.Setenv("COMMERCE_URL", f.server(t).URL)
+	t.Setenv("COMMERCE_SERVICE_TOKEN", "svc-tok")
+	t.Setenv("PERSONAL_BILLING_ORGS", "hanzo")
+	app := mountApp(t, "http://iam.invalid", "", "")
+
+	// a POST with a forged userId in the body must be overwritten to acme.
+	code, _ := callH(t, app, http.MethodPost, "/v1/billing/spend-alerts", alice,
+		`{"userId":"victim","threshold":5000}`)
+	if code != http.StatusOK {
+		t.Fatalf("want 200, got %d", code)
+	}
+	if f.body["userId"] != "acme" {
+		t.Fatalf("write-body subject must be pinned to acme, got %v", f.body["userId"])
+	}
+	if f.body["threshold"].(float64) != 5000 {
+		t.Fatalf("non-subject body field must survive, got %v", f.body["threshold"])
+	}
+}
+
+func TestBilling_RejectsTraversalSegment(t *testing.T) {
+	f := &fakeBilling{}
+	t.Setenv("COMMERCE_URL", f.server(t).URL)
+	t.Setenv("COMMERCE_SERVICE_TOKEN", "svc-tok")
+	app := mountApp(t, "http://iam.invalid", "", "")
+	// Every traversal form — literal `..`, encoded slash (`%2f`), encoded dot
+	// (`%2e%2e`), matrix param (`;`) — must be REFUSED (400) and must NEVER reach
+	// commerce. Without the percent-escape rejection, `invoices/..%2fadmin` decodes
+	// downstream to `/v1/admin`, tunneling PAST /v1/billing into another surface.
+	for _, p := range []string{
+		"/v1/billing/invoices/../admin",   // literal ..
+		"/v1/billing/invoices/..%2fadmin", // encoded slash (%2f)
+		"/v1/billing/%2e%2e/admin",        // encoded dots (%2e%2e)
+		"/v1/billing/invoices;statement",  // matrix param (;)
+	} {
+		code, _ := callH(t, app, http.MethodGet, p, alice, "")
+		if code != http.StatusBadRequest {
+			t.Fatalf("traversal %q: want 400, got %d", p, code)
+		}
+	}
+	if f.path != "" {
+		t.Fatalf("a traversal must never reach commerce, but upstream saw %q", f.path)
+	}
+}

clients/account/commerce.go

@@ -0,0 +1,147 @@
+// commerce.go — the per-tenant STORE data bridge, the Go port of console's
+// app/commerce/[...path]/route.ts (task #41, the BFF catch-all sweep; the store twin
+// of billing.go). It lets the statically-exported console reach its merchant store at
+// the CANONICAL same-origin /v1/commerce/* (nothing before /v1/): GET|POST|PUT|PATCH|
+// DELETE /v1/commerce/<path> forwards to commerce's bare store surface /v1/<path> with
+// the admin COMMERCE_SERVICE_TOKEN, SCOPING every request to the VALIDATED caller's own
+// org — so a merchant only ever reads/writes its OWN org's catalog (products / orders /
+// customers / variants / collections / discounts / storefront), never another's.
+//
+// WHY /v1/commerce/<x> → commerce /v1/<x> (the `commerce` segment is DROPPED, not
+// preserved like billing's /v1/billing/<x> → /v1/billing/<x>). The DEPLOYED commerce
+// binary (hanzoai/commerce cmd/commerced) mounts its whole REST surface with
+// `api.Route(router.Group("/v1"))`: the store models live at BARE /v1/<kind>
+// (/v1/product, /v1/order, /v1/user, …) while money lives at /v1/billing/*. The
+// console namespaces the store under /v1/commerce/* only to keep the generic store
+// heads (product/order/user/store) from colliding with the rest of the /v1 surface;
+// this bridge strips that console-side namespace and forwards to commerce's real bare
+// head — EXACTLY the mapping console's next.config rewrite already proved live
+// (`/v1/commerce/:path*` → `/commerce/v1/:path*` → commerce.svc/v1/:path*).
+//
+// WHY A SERVER HANDLER (not a same-origin passthrough). Commerce's store is
+// service-token-gated: its EdgeAuth resolves the org from the X-Org-Id header ONLY
+// after it verifies the bearer is the COMMERCE_SERVICE_TOKEN, then scopes every store
+// row to that org. A browser passthrough would have to carry that admin token (a
+// cross-tenant skeleton key) or a per-tenant selector the browser could forge — either
+// leaks another org's store. This handler injects the token SERVER-SIDE and pins the
+// org to the caller's own, so tenancy can never be crossed from the browser.
+//
+// IDOR-safe: the org is derived from the VALIDATED identity (resolveCaller →
+// principal.Validated / c.Org() / c.User()), NEVER a client-supplied value. A
+// bearer-less request with a forged X-Org-Id has no validated principal and is refused
+// (403) BEFORE any commerce call — the exact off-gateway forge principal.Validated
+// closes. Least privilege on the path: only the merchant store heads are reachable, so
+// this bridge can NOT tunnel to /v1/billing (its own subject-scoped bridge), /v1/checkout
+// (the money path), or /v1/_/commerce/tenants (tenant admin) — mirroring console's
+// proxy-allow.ts allowCommerceSurface.
+package account
+
+import (
+	"net/http"
+	"net/url"
+	"strings"
+
+	"github.com/hanzoai/cloud"
+	"github.com/zap-proto/zip"
+)
+
+// commerceStoreHeads — the merchant store REST heads reachable through /v1/commerce/*.
+// Kept IDENTICAL to console's proxy-allow.ts COMMERCE_HEADS (the same defense-in-depth
+// allow-list the Node /commerce proxy enforced), matching commerce's `rest.New(<kind>{})`
+// route names. Change both together. This is what keeps the bridge a STORE proxy: a head
+// not in this set (billing, checkout, namespace, _) is 404'd before any upstream call, so
+// the store token can never reach the money or tenant-admin surfaces that share commerce's
+// binary — those have their OWN scoped bridges (billing.go) or are unreachable.
+var commerceStoreHeads = map[string]bool{
+	"product":       true, // products
+	"variant":       true, // inventory / SKUs
+	"collection":    true, // catalog collections
+	"order":         true, // orders
+	"user":          true, // customers
+	"discount":      true, // promotions & discounts
+	"coupon":        true, // discount codes
+	"saleschannel":  true, // sales channels
+	"stocklocation": true, // stock locations
+	"store":         true, // storefront settings
+}
+
+// isCommerceStoreHead reports whether sub (the path after /v1/commerce/) targets an
+// allow-listed store head — the FIRST segment, so `product`, `product/<id>`, and
+// `store/current` all resolve to their head (`product`, `store`).
+func isCommerceStoreHead(sub string) bool {
+	head := sub
+	if i := strings.IndexByte(sub, '/'); i >= 0 {
+		head = sub[:i]
+	}
+	return commerceStoreHeads[head]
+}
+
+// commerceData forwards GET|POST|PUT|PATCH|DELETE /v1/commerce/<path> to commerce's
+// store surface /v1/<path>, scoped to the caller's OWN org. Mirrors the five method
+// exports of app/commerce/[...path]/route.ts (the store dashboard reads AND writes:
+// create/delete a product, etc. — full CRUD, unlike billing's read-mostly GET|POST).
+func commerceData(s *cloud.Service[state], c *zip.Ctx) error {
+	// IDOR boundary: the org is the VALIDATED caller's own, never a client value.
+	// requireOwner=true — the store is always org-scoped (a zero-org user has none).
+	cr, ok := resolveCaller(c, true)
+	if !ok {
+		return zip.ErrForbidden("sign in to manage your store")
+	}
+
+	switch c.Method() {
+	case http.MethodGet, http.MethodPost, http.MethodPut, http.MethodPatch, http.MethodDelete:
+	default:
+		return zip.Errorf(http.StatusMethodNotAllowed, "method not allowed")
+	}
+
+	base, token := commerceCreds()
+	if token == "" {
+		// Honest "not configured" (mirrors billing.go's 501 when the token is unset) —
+		// the console shows a truthful state, never a fabricated store.
+		return zip.Errorf(http.StatusNotImplemented, "commerce is not configured on this deployment (COMMERCE_SERVICE_TOKEN unset)")
+	}
+
+	sub := strings.Trim(strings.TrimPrefix(c.Fiber().Params("*"), "/"), "/")
+	if sub == "" {
+		return zip.Errorf(http.StatusNotFound, "commerce endpoint required")
+	}
+	for _, seg := range strings.Split(sub, "/") {
+		// isSafeSegment is the ONE guard (billing.go): it rejects empty/./../slash/
+		// backslash/control AND percent-escape/matrix-param, so encoded traversal
+		// (`product/..%2fbilling` → downstream `/v1/billing`) can never tunnel PAST the
+		// store-head allow-list into the money surface.
+		if !isSafeSegment(seg) {
+			return zip.ErrBadRequest("invalid commerce path")
+		}
+	}
+	// Least privilege: only the merchant store heads (defense in depth). A non-store
+	// head (billing/checkout/namespace/…) is 404'd here, so this bridge can never be a
+	// general tunnel into commerce's money / tenant-admin surfaces.
+	if !isCommerceStoreHead(sub) {
+		return zip.Errorf(http.StatusNotFound, "not a commerce store endpoint")
+	}
+
+	// The store query (limit/page/q/sort) passes through verbatim — commerce scopes the
+	// store by the X-Org-Id header (bound below), not a query param, so there is no
+	// subject to pin as in billing. The org is NEVER read from the query.
+	q, _ := url.ParseQuery(string(c.Fiber().Request().URI().QueryString()))
+
+	// Forward the write body verbatim on mutating methods (commerce validates it).
+	var body []byte
+	if c.Method() != http.MethodGet && len(c.Body()) > 0 {
+		body = c.Body()
+	}
+
+	// commerceDo binds X-Org-Id = the caller's OWN validated org + the admin service
+	// token; commerce's EdgeAuth trusts that org ONLY behind the token and scopes the
+	// store to it. This is the SAME S2S transport billing.go / topup.go share.
+	raw, status, err := commerceDo(c.Context(), base, token, c.Method(), "/v1/"+sub, q, cr.owner, body)
+	if err != nil {
+		return zip.Errorf(http.StatusBadGateway, "commerce upstream unreachable: %v", err)
+	}
+	// A per-tenant store response must never be cached across tenants; commerce answers
+	// JSON, so pin JSON + no-store (identical to billing.go).
+	c.SetHeader("Content-Type", "application/json")
+	c.SetHeader("Cache-Control", "no-store, must-revalidate")
+	return c.Bytes(status, raw)
+}

clients/account/commerce_test.go

@@ -0,0 +1,188 @@
+package account
+
+import (
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"sync"
+	"testing"
+)
+
+// commerce_test.go — the per-tenant STORE bridge (commerce.go). Proves the org
+// scoping that prevents cross-tenant store access, the /v1/commerce/<x> → /v1/<x>
+// remap, the store-head least-privilege gate, and the IDOR-safe forwarding — the
+// store twin of billing_test.go.
+
+// ── pure allow-list ──────────────────────────────────────────────────────────
+
+func TestIsCommerceStoreHead(t *testing.T) {
+	// Every store head (and its sub-paths) is admitted; a non-store head is not, so
+	// the bridge can never tunnel to the money / tenant-admin surfaces.
+	allow := []string{"product", "product/abc", "store/current", "order", "user", "variant"}
+	deny := []string{"billing", "billing/balance", "checkout", "checkout/session", "namespace", "_", "tenants", ""}
+	for _, p := range allow {
+		if !isCommerceStoreHead(p) {
+			t.Fatalf("store head %q must be admitted", p)
+		}
+	}
+	for _, p := range deny {
+		if isCommerceStoreHead(p) {
+			t.Fatalf("non-store path %q must be refused", p)
+		}
+	}
+}
+
+// ── handler (IDOR + forwarding) ──────────────────────────────────────────────
+
+// fakeStore records exactly what the handler forwarded to commerce.
+type fakeStore struct {
+	mu     sync.Mutex
+	method string
+	path   string
+	query  url.Values
+	body   map[string]any
+	org    string
+	auth   string
+}
+
+func (f *fakeStore) server(t *testing.T) *httptest.Server {
+	t.Helper()
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		f.mu.Lock()
+		f.method, f.path, f.query = r.Method, r.URL.Path, r.URL.Query()
+		f.org, f.auth = r.Header.Get("X-Org-Id"), r.Header.Get("Authorization")
+		if raw, _ := io.ReadAll(r.Body); len(raw) > 0 {
+			_ = json.Unmarshal(raw, &f.body)
+		}
+		f.mu.Unlock()
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = io.WriteString(w, `{"models":[],"count":0}`)
+	}))
+	t.Cleanup(srv.Close)
+	return srv
+}
+
+func TestCommerce_RequiresValidatedPrincipal(t *testing.T) {
+	t.Setenv("COMMERCE_SERVICE_TOKEN", "svc-tok")
+	app := mountApp(t, "http://iam.invalid", "", "")
+	// A forged X-Org-Id with NO validated X-User-Id is the exact forge — refuse it
+	// BEFORE any commerce call (no cross-tenant store read on a victim org). Cover a
+	// mutating method too: a forged write must 403, never reach the store.
+	for _, m := range []string{http.MethodGet, http.MethodPost, http.MethodDelete} {
+		code, _ := callH(t, app, m, "/v1/commerce/product", map[string]string{"X-Org-Id": "victim"}, "")
+		if code != http.StatusForbidden {
+			t.Fatalf("%s no validated principal: want 403, got %d", m, code)
+		}
+	}
+}
+
+func TestCommerce_NotConfiguredWithoutToken(t *testing.T) {
+	t.Setenv("COMMERCE_SERVICE_TOKEN", "")
+	app := mountApp(t, "http://iam.invalid", "", "")
+	code, _ := callH(t, app, http.MethodGet, "/v1/commerce/product", alice, "")
+	if code != http.StatusNotImplemented {
+		t.Fatalf("no commerce token: want 501, got %d", code)
+	}
+}
+
+func TestCommerce_ForwardsToBareStoreScopedToCaller(t *testing.T) {
+	f := &fakeStore{}
+	t.Setenv("COMMERCE_URL", f.server(t).URL)
+	t.Setenv("COMMERCE_SERVICE_TOKEN", "svc-tok")
+	app := mountApp(t, "http://iam.invalid", "", "")
+
+	// alice/acme lists products: the console-side /v1/commerce/product must reach
+	// commerce's BARE /v1/product (the `commerce` namespace stripped), scoped to acme.
+	code, body := callH(t, app, http.MethodGet, "/v1/commerce/product?limit=100&q=shirt", alice, "")
+	if code != http.StatusOK {
+		t.Fatalf("want 200, got %d (%s)", code, body)
+	}
+	if f.path != "/v1/product" {
+		t.Fatalf("forwarded path: want /v1/product (bare, namespace stripped), got %q", f.path)
+	}
+	if f.query.Get("limit") != "100" || f.query.Get("q") != "shirt" {
+		t.Fatalf("store query must pass through verbatim, got %v", f.query)
+	}
+	if f.org != "acme" || f.auth != "Bearer svc-tok" {
+		t.Fatalf("S2S must send X-Org-Id=acme (validated org) + the service token, got org=%q auth=%q", f.org, f.auth)
+	}
+}
+
+func TestCommerce_ForwardsSubPathAndWriteBody(t *testing.T) {
+	f := &fakeStore{}
+	t.Setenv("COMMERCE_URL", f.server(t).URL)
+	t.Setenv("COMMERCE_SERVICE_TOKEN", "svc-tok")
+	app := mountApp(t, "http://iam.invalid", "", "")
+
+	// createProduct: POST /v1/commerce/product with a body → commerce /v1/product,
+	// body forwarded verbatim, org bound to the caller.
+	code, _ := callH(t, app, http.MethodPost, "/v1/commerce/product", alice,
+		`{"name":"Tee","sku":"TEE-1","slug":"tee"}`)
+	if code != http.StatusOK {
+		t.Fatalf("POST want 200, got %d", code)
+	}
+	if f.method != http.MethodPost || f.path != "/v1/product" {
+		t.Fatalf("want POST /v1/product, got %s %s", f.method, f.path)
+	}
+	if f.body["name"] != "Tee" || f.body["sku"] != "TEE-1" {
+		t.Fatalf("write body must pass through verbatim, got %v", f.body)
+	}
+	if f.org != "acme" {
+		t.Fatalf("write must be scoped to the caller's org acme, got %q", f.org)
+	}
+
+	// deleteProduct: DELETE /v1/commerce/product/<id> → commerce /v1/product/<id>.
+	code, _ = callH(t, app, http.MethodDelete, "/v1/commerce/product/p_123", alice, "")
+	if code != http.StatusOK {
+		t.Fatalf("DELETE want 200, got %d", code)
+	}
+	if f.method != http.MethodDelete || f.path != "/v1/product/p_123" {
+		t.Fatalf("want DELETE /v1/product/p_123, got %s %s", f.method, f.path)
+	}
+}
+
+func TestCommerce_RefusesNonStoreHead(t *testing.T) {
+	f := &fakeStore{}
+	t.Setenv("COMMERCE_URL", f.server(t).URL)
+	t.Setenv("COMMERCE_SERVICE_TOKEN", "svc-tok")
+	app := mountApp(t, "http://iam.invalid", "", "")
+
+	// The bridge must NOT tunnel to commerce's money / tenant-admin surfaces: a
+	// /v1/commerce/billing/* or /v1/commerce/checkout/* is 404'd BEFORE any upstream
+	// call (billing has its OWN subject-scoped bridge; checkout is unreachable here).
+	for _, p := range []string{"/v1/commerce/billing/balance", "/v1/commerce/checkout/session", "/v1/commerce/namespace"} {
+		code, _ := callH(t, app, http.MethodGet, p, alice, "")
+		if code != http.StatusNotFound {
+			t.Fatalf("%s: want 404 (not a store endpoint), got %d", p, code)
+		}
+	}
+	if f.path != "" {
+		t.Fatalf("a refused head must never reach commerce, but upstream saw %q", f.path)
+	}
+}
+
+func TestCommerce_RejectsTraversalSegment(t *testing.T) {
+	f := &fakeStore{}
+	t.Setenv("COMMERCE_URL", f.server(t).URL)
+	t.Setenv("COMMERCE_SERVICE_TOKEN", "svc-tok")
+	app := mountApp(t, "http://iam.invalid", "", "")
+	// Every traversal form — literal `..`, encoded slash (`%2f`), encoded dot
+	// (`%2e%2e`) — must be REFUSED (400) and must NEVER reach commerce. Without the
+	// percent-escape rejection, `product/..%2fbilling` decodes downstream to
+	// `/v1/billing`, tunneling PAST the store-head allow-list into the money surface.
+	for _, p := range []string{
+		"/v1/commerce/product/../billing",
+		"/v1/commerce/product/..%2fbilling",
+		"/v1/commerce/%2e%2e/billing",
+	} {
+		code, _ := callH(t, app, http.MethodGet, p, alice, "")
+		if code != http.StatusBadRequest {
+			t.Fatalf("traversal %q: want 400, got %d", p, code)
+		}
+	}
+	if f.path != "" {
+		t.Fatalf("a traversal must never reach commerce, but upstream saw %q", f.path)
+	}
+}

clients/account/csrf.go

@@ -0,0 +1,188 @@
+package account
+
+// CSRF protection for the console money-WRITE surface (mint/revoke key, topup,
+// onboard, and the billing/commerce write verbs).
+//
+// THREAT. The forward-perfect money path is the embed same-origin session bridge
+// (middleware_identity.sessionAccessToken): a browser write is authenticated from its
+// httpOnly session COOKIE, which is AMBIENT — a cross-site page's request to our
+// origin carries it too. The bridge's Sec-Fetch-Site check is a NEGATIVE heuristic
+// that passes VACUOUSLY when Origin/Referer/Sec-Fetch-Site are all absent (RED). So a
+// state-changing write gets a POSITIVE control: a token the caller can obtain ONLY by
+// reading a same-origin response (the Same-Origin Policy blocks a cross-site page from
+// reading GET /v1/csrf) and MUST echo in a CUSTOM header (a cross-site simple/
+// form request cannot set X-CSRF-Token without a CORS preflight the server never
+// grants).
+//
+// SCOPE — only the AMBIENT path. A Bearer/Basic-authenticated request is immune to
+// CSRF (a cross-site attacker cannot set the Authorization header), and the gateway
+// path forwards minted identity HEADERS with no browser cookie. requireCSRF therefore
+// enforces ONLY when the request carries NO explicit Authorization/X-Authorization AND
+// a Cookie is present — i.e. exactly the ambient-cookie/embed browser write. Every
+// other caller (API/machine Bearer, gateway-fronted, the header-injected tests) is
+// unaffected. Fail-secure: an ambient write with a missing/invalid token is refused.
+//
+// TOKEN — base64url( ts_be64(8) || mac(16) ), where
+//   mac = KeyedBLAKE3(csrfKey, domain \x00 uid \x00 org \x00 ts)[:16]  (luxfi/crypto).
+// It is BOUND to the validated principal (X-User-Id + X-Org-Id) so a token minted for
+// one identity cannot authorize a write as another, and it EXPIRES after csrfTTL. The
+// key is server-only (KMS-sourced env CONSOLE_CSRF_KEY); no key ⇒ a per-process random
+// key (tokens then reset on restart — the SPA re-fetches on a 403).
+
+import (
+	"crypto/rand"
+	"crypto/subtle"
+	"encoding/base64"
+	"encoding/binary"
+	"encoding/hex"
+	"net/http"
+	"os"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/hanzoai/cloud"
+	"github.com/luxfi/crypto/blake3"
+	luxlog "github.com/luxfi/log"
+	"github.com/zap-proto/zip"
+)
+
+const (
+	csrfDomain    = "hanzo-console-csrf-v1"
+	csrfMACLen    = 16             // 128-bit truncated BLAKE3 MAC — ample for a bound, expiring token
+	csrfTTL       = 12 * time.Hour // token lifetime; SPA re-fetches on expiry/403
+	csrfClockSkew = 120            // seconds of future tolerance
+	csrfTokenLen  = 8 + csrfMACLen // ts || mac
+)
+
+// csrfKeyOnce guards the process-wide CSRF MAC key. It is shared across BOTH account
+// subsystems (account@48 issues GET /v1/csrf; account-bridge@122 verifies the token on
+// the /v1/billing|commerce writes), so a token minted by one verifies on the other —
+// even in the ephemeral (no CONSOLE_CSRF_KEY) case where each Mount would otherwise
+// generate its own random key. Deterministic from CONSOLE_CSRF_KEY (KMS) in prod.
+var (
+	csrfKeyOnce sync.Once
+	csrfKeyVal  []byte
+)
+
+// sharedCSRFKey returns the process-wide keyed-BLAKE3 MAC key, loaded ONCE.
+func sharedCSRFKey(log luxlog.Logger) []byte {
+	csrfKeyOnce.Do(func() { csrfKeyVal = loadCSRFKey(log) })
+	return csrfKeyVal
+}
+
+// loadCSRFKey returns the 32-byte keyed-BLAKE3 MAC key. Prefers the server-only env
+// CONSOLE_CSRF_KEY (KMS-sourced; hex or base64-std, must decode to exactly 32 bytes);
+// otherwise a per-process random key with a WARN (single-replica tolerable — tokens
+// reset on restart, the SPA transparently re-fetches on a 403).
+func loadCSRFKey(log luxlog.Logger) []byte {
+	if raw := strings.TrimSpace(os.Getenv("CONSOLE_CSRF_KEY")); raw != "" {
+		if b, err := hex.DecodeString(raw); err == nil && len(b) == 32 {
+			return b
+		}
+		if b, err := base64.StdEncoding.DecodeString(raw); err == nil && len(b) == 32 {
+			return b
+		}
+		if log != nil {
+			log.Warn("CONSOLE_CSRF_KEY set but not a 32-byte hex/base64 value; using an ephemeral per-process key")
+		}
+	} else if log != nil {
+		log.Warn("CONSOLE_CSRF_KEY unset; using an ephemeral per-process CSRF key (set it from KMS for multi-replica/restart-stable tokens)")
+	}
+	k := make([]byte, 32)
+	if _, err := rand.Read(k); err != nil {
+		// crypto/rand failure is catastrophic; a zero key would be forgeable, so panic.
+		panic("console: cannot generate CSRF key: " + err.Error())
+	}
+	return k
+}
+
+// csrfMAC computes the bound, truncated keyed-BLAKE3 MAC for (uid, org, ts).
+func csrfMAC(s *cloud.Service[state], uid, org string, ts int64) []byte {
+	var msg []byte
+	msg = append(msg, csrfDomain...)
+	msg = append(msg, 0)
+	msg = append(msg, uid...)
+	msg = append(msg, 0)
+	msg = append(msg, org...)
+	msg = append(msg, 0)
+	var t [8]byte
+	binary.BigEndian.PutUint64(t[:], uint64(ts))
+	msg = append(msg, t[:]...)
+	sum, err := blake3.KeyedHash(s.State.csrfKey, msg)
+	if err != nil {
+		// Only errors on a bad key length; loadCSRFKey guarantees 32 bytes.
+		panic("console: CSRF MAC: " + err.Error())
+	}
+	return sum[:csrfMACLen]
+}
+
+// issueCSRF mints a token bound to (uid, org) valid for csrfTTL. Returns the token and
+// its lifetime in seconds.
+func issueCSRF(s *cloud.Service[state], uid, org string) (string, int64) {
+	ts := time.Now().Unix()
+	var out [csrfTokenLen]byte
+	binary.BigEndian.PutUint64(out[:8], uint64(ts))
+	copy(out[8:], csrfMAC(s, uid, org, ts))
+	return base64.RawURLEncoding.EncodeToString(out[:]), int64(csrfTTL / time.Second)
+}
+
+// verifyCSRF checks a token against the CURRENT request's validated (uid, org) and its
+// expiry, in constant time.
+func verifyCSRF(s *cloud.Service[state], token, uid, org string) bool {
+	raw, err := base64.RawURLEncoding.DecodeString(strings.TrimSpace(token))
+	if err != nil || len(raw) != csrfTokenLen {
+		return false
+	}
+	ts := int64(binary.BigEndian.Uint64(raw[:8]))
+	now := time.Now().Unix()
+	if ts > now+csrfClockSkew || now-ts > int64(csrfTTL/time.Second) {
+		return false
+	}
+	return subtle.ConstantTimeCompare(raw[8:], csrfMAC(s, uid, org, ts)) == 1
+}
+
+// ambientCookieAuth reports whether the request is authenticated by an AMBIENT
+// credential (a browser cookie) rather than an explicit one. Only such requests are
+// CSRF-able. Explicit Authorization/X-Authorization (Bearer/Basic) ⇒ not ambient; no
+// Cookie at all (gateway header-injection, the tests) ⇒ not ambient.
+func ambientCookieAuth(c *zip.Ctx) bool {
+	if strings.TrimSpace(c.Header("Authorization")) != "" || strings.TrimSpace(c.Header("X-Authorization")) != "" {
+		return false
+	}
+	return len(c.Fiber().Request().Header.Peek("Cookie")) > 0
+}
+
+// requireCSRF wraps a state-changing handler, enforcing a valid X-CSRF-Token on the
+// ambient-cookie path only (see package note). A validated principal is required for
+// the ambient path to mean anything; the wrapped handler still does its own
+// resolveCaller, so this only ADDS the anti-CSRF gate.
+func requireCSRF(s *cloud.Service[state], next zip.Handler) zip.Handler {
+	return func(c *zip.Ctx) error {
+		if !ambientCookieAuth(c) {
+			return next(c) // Bearer/Basic/gateway/API — not CSRF-able
+		}
+		tok := strings.TrimSpace(c.Header("X-CSRF-Token"))
+		if tok == "" {
+			return zip.ErrForbidden("missing CSRF token (GET /v1/csrf and echo it in X-CSRF-Token)")
+		}
+		if !verifyCSRF(s, tok, strings.TrimSpace(c.User()), strings.TrimSpace(c.Org())) {
+			return zip.ErrForbidden("invalid or expired CSRF token")
+		}
+		return next(c)
+	}
+}
+
+// issueCSRFToken serves GET /v1/csrf: for a VALIDATED caller, a fresh token
+// bound to their identity. no-store so it is never cached by a shared proxy. This is
+// the same-origin endpoint the embedded SPA reads (its response body is unreadable to
+// a cross-site page), then echoes on every money write.
+func issueCSRFToken(s *cloud.Service[state], c *zip.Ctx) error {
+	cr, ok := resolveCaller(c, false) // a zero-org (first-run) user may still need a token
+	if !ok {
+		return zip.ErrForbidden("sign in to obtain a CSRF token")
+	}
+	token, ttl := issueCSRF(s, cr.name, cr.owner)
+	c.Fiber().Set("Cache-Control", "no-store")
+	return c.JSON(http.StatusOK, map[string]any{"csrfToken": token, "expiresIn": ttl})
+}

clients/account/csrf_test.go

@@ -0,0 +1,167 @@
+package account
+
+import (
+	"fmt"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/zap-proto/zip"
+)
+
+// req drives one request with arbitrary headers through the mounted app.
+func req(t *testing.T, app *zip.App, method, path string, hdr map[string]string, body string) (int, []byte) {
+	t.Helper()
+	var rdr io.Reader
+	if body != "" {
+		rdr = strings.NewReader(body)
+	}
+	r := httptest.NewRequest(method, path, rdr)
+	if body != "" {
+		r.Header.Set("Content-Type", "application/json")
+	}
+	for k, v := range hdr {
+		r.Header.Set(k, v)
+	}
+	resp, err := app.Fiber().Test(r)
+	if err != nil {
+		t.Fatalf("Test %s %s: %v", method, path, err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+	b, _ := io.ReadAll(resp.Body)
+	return resp.StatusCode, b
+}
+
+// csrfToken fetches a CSRF token for (user, org) from the issue endpoint.
+func csrfToken(t *testing.T, app *zip.App, user, org string) string {
+	t.Helper()
+	code, body := req(t, app, http.MethodGet, "/v1/csrf",
+		map[string]string{"X-User-Id": user, "X-Org-Id": org}, "")
+	if code != http.StatusOK {
+		t.Fatalf("GET /v1/csrf: want 200, got %d (%s)", code, body)
+	}
+	var r struct {
+		CsrfToken string `json:"csrfToken"`
+	}
+	mustJSON(t, body, &r)
+	if r.CsrfToken == "" {
+		t.Fatalf("empty csrfToken: %s", body)
+	}
+	return r.CsrfToken
+}
+
+// TestCSRF_AmbientWriteWithoutTokenIsRefused: a cookie-authenticated (ambient) write
+// with no X-CSRF-Token is 403, and IAM is never touched.
+func TestCSRF_AmbientWriteWithoutTokenIsRefused(t *testing.T) {
+	f := newFakeIAM()
+	app := mountApp(t, f.server(t).URL, "hanzo-console", "s3cr3t")
+
+	code, _ := req(t, app, http.MethodPost, "/v1/iam/keys", map[string]string{
+		"X-User-Id": "alice", "X-Org-Id": "acme",
+		"Cookie": "iam_access_token=opaque-sid", // ambient credential
+	}, "")
+	if code != http.StatusForbidden {
+		t.Fatalf("ambient write w/o CSRF token: want 403, got %d", code)
+	}
+	if len(f.mintedFor) != 0 {
+		t.Fatalf("IAM mint reached without a CSRF token: %v", f.mintedFor)
+	}
+}
+
+// TestCSRF_AmbientWriteWithValidTokenAllows: same request WITH a valid token mints.
+func TestCSRF_AmbientWriteWithValidTokenAllows(t *testing.T) {
+	f := newFakeIAM()
+	app := mountApp(t, f.server(t).URL, "hanzo-console", "s3cr3t")
+
+	tok := csrfToken(t, app, "alice", "acme")
+	code, body := req(t, app, http.MethodPost, "/v1/iam/keys", map[string]string{
+		"X-User-Id": "alice", "X-Org-Id": "acme",
+		"Cookie":       "iam_access_token=opaque-sid",
+		"X-CSRF-Token": tok,
+	}, "")
+	if code != http.StatusOK {
+		t.Fatalf("ambient write with valid CSRF token: want 200, got %d (%s)", code, body)
+	}
+	if len(f.mintedFor) != 1 || f.mintedFor[0] != "acme/alice" {
+		t.Fatalf("mint should target acme/alice: %v", f.mintedFor)
+	}
+}
+
+// TestCSRF_TokenBoundToIdentity: a token minted for alice cannot authorize a write as
+// mallory — the MAC binds (X-User-Id, X-Org-Id).
+func TestCSRF_TokenBoundToIdentity(t *testing.T) {
+	f := newFakeIAM()
+	app := mountApp(t, f.server(t).URL, "hanzo-console", "s3cr3t")
+
+	aliceTok := csrfToken(t, app, "alice", "acme")
+	code, _ := req(t, app, http.MethodPost, "/v1/iam/keys", map[string]string{
+		"X-User-Id": "mallory", "X-Org-Id": "acme", // different principal
+		"Cookie":       "iam_access_token=opaque-sid",
+		"X-CSRF-Token": aliceTok, // stolen/replayed token bound to alice
+	}, "")
+	if code != http.StatusForbidden {
+		t.Fatalf("cross-identity CSRF token replay: want 403, got %d", code)
+	}
+	if len(f.mintedFor) != 0 {
+		t.Fatalf("mint reached on a cross-identity token: %v", f.mintedFor)
+	}
+}
+
+// TestCSRF_BearerAuthSkipsCSRF: an explicit Bearer credential is not CSRF-able, so no
+// token is required (API/machine callers unaffected).
+func TestCSRF_BearerAuthSkipsCSRF(t *testing.T) {
+	f := newFakeIAM()
+	app := mountApp(t, f.server(t).URL, "hanzo-console", "s3cr3t")
+
+	code, body := req(t, app, http.MethodPost, "/v1/iam/keys", map[string]string{
+		"X-User-Id": "alice", "X-Org-Id": "acme",
+		"Authorization": "Bearer some.jwt.token", // explicit (non-ambient) credential
+		"Cookie":        "iam_access_token=opaque-sid",
+	}, "")
+	if code != http.StatusOK {
+		t.Fatalf("Bearer write should skip CSRF and mint: want 200, got %d (%s)", code, body)
+	}
+	if len(f.mintedFor) != 1 {
+		t.Fatalf("Bearer write should have minted: %v", f.mintedFor)
+	}
+}
+
+// TestRateLimit_PerPrincipalBurstThen429: the money-write cap keys on the VALIDATED
+// principal (un-spoofable), returns 429 past the burst, and a DIFFERENT principal is
+// NOT throttled by the first's flood — and a forged X-Forwarded-For does not reset it.
+func TestRateLimit_PerPrincipalBurstThen429(t *testing.T) {
+	f := newFakeIAM()
+	app := mountApp(t, f.server(t).URL, "hanzo-console", "s3cr3t")
+
+	// alice floods, sending a FRESH X-Forwarded-For each request (the old XFF keying
+	// would have reset the bucket every time — it must NOT now).
+	var got429 bool
+	for i := 0; i < keysWriteRatePerMin+5; i++ {
+		code, _ := req(t, app, http.MethodPost, "/v1/iam/keys", map[string]string{
+			"X-User-Id": "alice", "X-Org-Id": "acme",
+			"Authorization":   "Bearer j.w.t",                     // skip CSRF, isolate the limiter
+			"X-Forwarded-For": fmt.Sprintf("203.0.113.%d", i%250), // attacker rotates XFF
+		}, "")
+		if code == 429 {
+			got429 = true
+			break
+		}
+		if code != http.StatusOK {
+			t.Fatalf("req %d: unexpected %d", i, code)
+		}
+	}
+	if !got429 {
+		t.Fatalf("expected 429 after alice's per-principal burst of %d (XFF rotation must not reset it)", keysWriteRatePerMin)
+	}
+
+	// bob (a different validated principal) is unaffected by alice's exhausted bucket.
+	code, body := req(t, app, http.MethodPost, "/v1/iam/keys", map[string]string{
+		"X-User-Id": "bob", "X-Org-Id": "acme",
+		"Authorization": "Bearer j.w.t",
+	}, "")
+	if code != http.StatusOK {
+		t.Fatalf("bob must have his own bucket, not alice's: want 200, got %d (%s)", code, body)
+	}
+}

clients/account/embed.go

@@ -0,0 +1,147 @@
+// embed.go ports console's app/embed-status/route.ts into the unified binary at
+// GET /v1/embed-status (task #41). It answers ONE question for the console's
+// data-product modules (Content Studio / ERP / Help Center): is this brand's shared
+// embedded app provisioned and reachable, so the module can decide embed-vs-provision
+// panel? A cross-origin browser can't read another origin's status (SOP + CORS), so
+// this server route probes it once and returns an honest verdict.
+//
+// TWO real jobs (why it is a handler, not a vanishing proxy):
+//
+//   - ENTITLEMENT (server-authoritative). cms/erp/help are each a SINGLE shared
+//     per-BRAND instance, so only a member of the owning brand org — or a
+//     SuperAdmin — may frame them; a customer org gets the honest provision panel, never
+//     a cross-tenant frame. The caller's org is the VALIDATED X-Org-Id (never a
+//     browser claim); the owning org is the deployment brand.
+//
+//   - SSRF SAFETY. The probe target is ALWAYS `<app>.<brand-domain>` where the brand
+//     is the deployment's OWN brand (deps.Brand, fixed at deploy) and app ∈
+//     {cms,erp,help}. There is NO client-controlled host in the target at all — a
+//     forged Host header can never steer this into probing an arbitrary origin
+//     (strictly tighter than route.ts, which clamped a client Host).
+package account
+
+import (
+	"context"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/hanzoai/cloud"
+	"github.com/zap-proto/zip"
+)
+
+// embedApps are the apps this route resolves and the in-app landing path each
+// embeds. Mirrors embed-probe.ts EMBED_APPS (verified ground truth).
+var embedApps = map[string]string{
+	"cms":  "/admin",    // Payload admin
+	"erp":  "/app",      // ERPNext desk
+	"help": "/helpdesk", // Frappe Helpdesk
+}
+
+// embedBrandDomains maps a deployment brand to the registrable domain its shared
+// apps live on. These are the app-hosting (`.cloud`) domains, DISTINCT from a
+// brand's marketing domain (brand.go's Domain) — lux apps are on lux.cloud, not
+// lux.network. Mirrors embed-probe.ts KNOWN_BRAND_DOMAINS/DEFAULT_BRAND_DOMAIN.
+var embedBrandDomains = map[string]string{
+	"hanzo": "hanzo.ai",
+	"lux":   "lux.cloud",
+	"zoo":   "zoo.cloud",
+	"pars":  "pars.cloud",
+}
+
+const defaultEmbedDomain = "hanzo.ai"
+
+// embedBrandDomain returns the app-hosting domain for a brand, defaulting to the
+// hanzo domain for an unknown brand (the SSRF-safe fallback).
+func embedBrandDomain(brand string) string {
+	if d, ok := embedBrandDomains[strings.ToLower(strings.TrimSpace(brand))]; ok {
+		return d
+	}
+	return defaultEmbedDomain
+}
+
+// embedUp classifies a probe HTTP status as "app is up": a 2xx/3xx (landing or SSO
+// redirect) or an app-level 401/403 (running, wants login) is up; 404 (no such app)
+// or any 5xx (the unprovisioned 502/503/504 state) is down. Mirrors embed-probe.ts
+// isUp. A network/timeout error is handled by the caller as down.
+func embedUp(status int) bool {
+	if status >= 500 || status == 404 {
+		return false
+	}
+	return status > 0
+}
+
+// embedStatusResp is the verdict the module reads. Mirrors the route.ts JSON.
+type embedStatusResp struct {
+	App       string `json:"app"`
+	Origin    string `json:"origin"`
+	EmbedURL  string `json:"embedUrl"`
+	Reachable bool   `json:"reachable"`
+	Entitled  bool   `json:"entitled"`
+	Phase     string `json:"phase"`
+}
+
+// reachProbe reports whether an embed origin answers "up". It is a package var so
+// the handler's entitlement + shaping logic is testable without a live network hop;
+// Mount uses the real, time-boxed probe.
+var reachProbe = liveReachProbe
+
+// embedStatus is GET /v1/embed-status?app=cms|erp|help. Mirrors
+// GET app/embed-status/route.ts.
+func embedStatus(s *cloud.Service[state], c *zip.Ctx) error {
+	cr, ok := resolveCaller(c, false) // validated; a customer org (owner set) is fine
+	if !ok {
+		return zip.ErrForbidden("sign in to continue")
+	}
+	app := strings.ToLower(strings.TrimSpace(c.Query("app")))
+	landing, known := embedApps[app]
+	if !known {
+		return zip.ErrBadRequest("unknown embed app")
+	}
+
+	origin := "https://" + app + "." + embedBrandDomain(s.Brand)
+	embedURL := origin + landing
+
+	// SERVER-SIDE entitlement gate: a brand-owned app frames only for a member of the
+	// owning brand org (cr.owner == deps.Brand) or a SuperAdmin. A non-entitled
+	// caller NEVER receives the embed URL and we don't even probe — the module shows
+	// the provision panel. This is the authoritative gate (the client check only
+	// avoids a flash).
+	entitled := (cr.owner != "" && cr.owner == strings.ToLower(strings.TrimSpace(s.Brand))) || c.IsAdmin()
+	if !entitled {
+		return c.JSON(http.StatusOK, embedStatusResp{App: app, Origin: origin, EmbedURL: "", Reachable: false, Entitled: false, Phase: "not-entitled"})
+	}
+
+	up := reachProbe(c.Context(), origin)
+	phase := "not-provisioned"
+	if up {
+		phase = "ready"
+	}
+	return c.JSON(http.StatusOK, embedStatusResp{App: app, Origin: origin, EmbedURL: embedURL, Reachable: up, Entitled: true, Phase: phase})
+}
+
+// liveReachProbe does a time-boxed GET of the origin root. `redirect: manual` so an
+// SSO 302 counts as up (we don't follow it — only the liveness signal is needed). A
+// DNS failure / refused connection / timeout is down (app not provisioned yet).
+func liveReachProbe(ctx context.Context, origin string) bool {
+	cctx, cancel := context.WithTimeout(ctx, 4500*time.Millisecond)
+	defer cancel()
+	req, err := http.NewRequestWithContext(cctx, http.MethodGet, origin, nil)
+	if err != nil {
+		return false
+	}
+	req.Header.Set("Accept", "text/html")
+	resp, err := noRedirectClient.Do(req)
+	if err != nil {
+		return false
+	}
+	defer resp.Body.Close()
+	return embedUp(resp.StatusCode)
+}
+
+// noRedirectClient never follows a redirect — an SSO 302 is a liveness signal, not a
+// hop to chase (chasing it could itself become an SSRF vector).
+var noRedirectClient = &http.Client{
+	Timeout:       5 * time.Second,
+	CheckRedirect: func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse },
+}

clients/account/embed_test.go

@@ -0,0 +1,142 @@
+package account
+
+import (
+	"context"
+	"net/http"
+	"testing"
+
+	"github.com/zap-proto/zip"
+)
+
+// mountBrand mounts the account surface for a given deployment brand (the embed
+// entitlement + app-domain derivation are brand-scoped). IAM is unwired — embed-status
+// does not use the confidential client.
+func mountBrand(t *testing.T, brand string) *zip.App {
+	t.Helper()
+	t.Setenv("IAM_MINT_CLIENT_ID", "")
+	t.Setenv("IAM_MINT_CLIENT_SECRET", "")
+	return mountBoth(t, brand)
+}
+
+// stubProbe swaps the reachability probe for the duration of a test, recording how
+// many times it ran (to prove a non-entitled caller is never probed).
+func stubProbe(t *testing.T, up bool) *int {
+	t.Helper()
+	calls := 0
+	prev := reachProbe
+	reachProbe = func(context.Context, string) bool { calls++; return up }
+	t.Cleanup(func() { reachProbe = prev })
+	return &calls
+}
+
+func TestEmbedStatus_RequiresValidatedPrincipal(t *testing.T) {
+	stubProbe(t, true)
+	app := mountBrand(t, "hanzo")
+	code, _ := callH(t, app, http.MethodGet, "/v1/embed-status?app=cms", nil, "")
+	if code != http.StatusForbidden {
+		t.Fatalf("no principal: want 403, got %d", code)
+	}
+}
+
+func TestEmbedStatus_UnknownApp_400(t *testing.T) {
+	stubProbe(t, true)
+	app := mountBrand(t, "hanzo")
+	code, _ := callH(t, app, http.MethodGet, "/v1/embed-status?app=nope",
+		map[string]string{"X-User-Id": "alice", "X-Org-Id": "hanzo"}, "")
+	if code != http.StatusBadRequest {
+		t.Fatalf("unknown app: want 400, got %d", code)
+	}
+}
+
+func TestEmbedStatus_BrandMemberEntitled_Reachable(t *testing.T) {
+	calls := stubProbe(t, true)
+	app := mountBrand(t, "hanzo")
+	// A member of the owning brand org (hanzo) is entitled; the probe says up.
+	code, body := callH(t, app, http.MethodGet, "/v1/embed-status?app=cms",
+		map[string]string{"X-User-Id": "z", "X-Org-Id": "hanzo"}, "")
+	if code != http.StatusOK {
+		t.Fatalf("brand member: want 200, got %d (%s)", code, body)
+	}
+	var r embedStatusResp
+	mustJSON(t, body, &r)
+	if !r.Entitled || !r.Reachable || r.Phase != "ready" {
+		t.Fatalf("entitled+reachable expected: %+v", r)
+	}
+	if r.Origin != "https://cms.hanzo.ai" || r.EmbedURL != "https://cms.hanzo.ai/admin" {
+		t.Fatalf("origin/embedUrl wrong: %+v", r)
+	}
+	if *calls != 1 {
+		t.Fatalf("entitled caller must be probed exactly once, got %d", *calls)
+	}
+}
+
+func TestEmbedStatus_SuperAdminEntitled(t *testing.T) {
+	stubProbe(t, false)
+	app := mountBrand(t, "hanzo")
+	// A SuperAdmin from a DIFFERENT org is still entitled (isSuperAdmin bypass);
+	// the probe says down → not-provisioned but entitled with the embed URL.
+	code, body := callH(t, app, http.MethodGet, "/v1/embed-status?app=erp",
+		map[string]string{"X-User-Id": "root", "X-Org-Id": "acme", "X-User-IsAdmin": "true"}, "")
+	if code != http.StatusOK {
+		t.Fatalf("admin: want 200, got %d", code)
+	}
+	var r embedStatusResp
+	mustJSON(t, body, &r)
+	if !r.Entitled || r.Reachable || r.Phase != "not-provisioned" || r.EmbedURL != "https://erp.hanzo.ai/app" {
+		t.Fatalf("admin entitled + not-provisioned expected: %+v", r)
+	}
+}
+
+func TestEmbedStatus_CustomerOrgNotEntitled_NotProbed(t *testing.T) {
+	calls := stubProbe(t, true)
+	app := mountBrand(t, "hanzo")
+	// A customer org (not the brand, not admin) is NOT entitled: no embed URL, no
+	// probe, honest not-entitled phase — never a cross-tenant frame.
+	code, body := callH(t, app, http.MethodGet, "/v1/embed-status?app=help",
+		map[string]string{"X-User-Id": "alice", "X-Org-Id": "acme"}, "")
+	if code != http.StatusOK {
+		t.Fatalf("customer: want 200, got %d", code)
+	}
+	var r embedStatusResp
+	mustJSON(t, body, &r)
+	if r.Entitled || r.Reachable || r.EmbedURL != "" || r.Phase != "not-entitled" {
+		t.Fatalf("customer must be not-entitled with no url: %+v", r)
+	}
+	if *calls != 0 {
+		t.Fatalf("a non-entitled caller must NEVER be probed, got %d probes", *calls)
+	}
+}
+
+func TestEmbedStatus_BrandDomainPerBrand(t *testing.T) {
+	stubProbe(t, true)
+	// lux apps live on lux.cloud (the app-hosting domain), NOT lux.network.
+	app := mountBrand(t, "lux")
+	code, body := callH(t, app, http.MethodGet, "/v1/embed-status?app=cms",
+		map[string]string{"X-User-Id": "z", "X-Org-Id": "lux"}, "")
+	if code != http.StatusOK {
+		t.Fatalf("lux brand member: want 200, got %d", code)
+	}
+	var r embedStatusResp
+	mustJSON(t, body, &r)
+	if r.Origin != "https://cms.lux.cloud" {
+		t.Fatalf("lux embed origin: want https://cms.lux.cloud, got %q", r.Origin)
+	}
+}
+
+func TestEmbedUp_Classification(t *testing.T) {
+	up := map[int]bool{200: true, 302: true, 401: true, 403: true, 404: false, 500: false, 502: false, 503: false, 0: false}
+	for status, want := range up {
+		if got := embedUp(status); got != want {
+			t.Fatalf("embedUp(%d): want %v, got %v", status, want, got)
+		}
+	}
+}
+
+func TestEmbedBrandDomain_Fallback(t *testing.T) {
+	if d := embedBrandDomain("zoo"); d != "zoo.cloud" {
+		t.Fatalf("zoo domain: want zoo.cloud, got %q", d)
+	}
+	if d := embedBrandDomain("unknown-brand"); d != defaultEmbedDomain {
+		t.Fatalf("unknown brand must fall back to %q, got %q", defaultEmbedDomain, d)
+	}
+}

clients/account/iam.go

@@ -0,0 +1,278 @@
+// iam.go is the ONE HTTP path from the console subsystem to Hanzo IAM, acting as
+// the confidential first-party `hanzo-console` client (client_secret_basic). It
+// ports the privileged IAM primitives that console's server-only
+// src/lib/server/identity.ts drove — mint/revoke/get the per-user `hk-` key and
+// create/read/update an organization — so those standalone Next server routes can
+// be retired and console statically exported (task #41, "True 1-binary FE").
+//
+// WHY A CONFIDENTIAL CLIENT (and not the caller's own token). These ops are
+// privileged: `mint-user-keys` writes a user's AccessKey, `add-organization`
+// creates a tenant and moves the user in. IAM authorizes them for an app that is
+// allow-listed (IAM_KEY_MINT_ALLOWED_APPS / IAM_ORG_ADMIN_APPS /
+// IAM_USER_ADMIN_APPS) — the `hanzo-console` client — NOT for an arbitrary user
+// bearer. So this client authenticates as that app (Basic id:secret) and always
+// targets the ALREADY-VALIDATED caller (the handler resolves the principal from
+// the gateway-minted X-User-Id/X-Org-Id before calling here); the caller can only
+// ever act on their OWN id, never a third party's.
+//
+// CREDENTIALS come from server-only env (IAM_MINT_CLIENT_ID / IAM_MINT_CLIENT_SECRET,
+// sourced from KMS by the deployment), never a NEXT_PUBLIC value and never the
+// browser. When they are unset the subsystem is honestly "not configured" (501),
+// exactly as identity.ts's mintConfigured() gate behaved — no fabricated key/org.
+package account
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"os"
+	"strings"
+	"time"
+)
+
+// defaultIAMBase is the in-cluster IAM service; overridable by IAM_URL for other
+// environments and by tests (an httptest.Server URL). Mirrors identity.ts's IAM_URL.
+const defaultIAMBase = "http://iam.hanzo.svc.cluster.local:8000"
+
+// iamMaxBody bounds an IAM response read — these are small JSON envelopes (a key,
+// a user row, an org row), never blobs.
+const iamMaxBody = 4 << 20
+
+// iamClient is the confidential-client caller. clientID/clientSecret authenticate
+// as the `hanzo-console` app; an empty pair means "not configured" (handlers 501).
+type iamClient struct {
+	base         string
+	clientID     string
+	clientSecret string
+	http         *http.Client
+}
+
+func newIAMClient() *iamClient {
+	base := strings.TrimRight(strings.TrimSpace(getenv("IAM_URL", defaultIAMBase)), "/")
+	return &iamClient{
+		base:         base,
+		clientID:     strings.TrimSpace(os.Getenv("IAM_MINT_CLIENT_ID")),
+		clientSecret: strings.TrimSpace(os.Getenv("IAM_MINT_CLIENT_SECRET")),
+		http:         &http.Client{Timeout: 15 * time.Second},
+	}
+}
+
+// configured reports whether the confidential client is wired. Handlers 501 when
+// false — the deployment simply lacks the `hanzo-console` credential (the honest
+// "not configured on this deployment" state, never a fabricated result).
+func (c *iamClient) configured() bool { return c != nil && c.clientID != "" && c.clientSecret != "" }
+
+// basicAuth is the client_secret_basic header for the confidential client.
+func (c *iamClient) basicAuth() string {
+	return "Basic " + basicToken(c.clientID, c.clientSecret)
+}
+
+// iamEnvelope is the uniform /v1/iam response shape ({status,msg,data}). A non-ok
+// status is an error surfaced honestly to the caller.
+type iamEnvelope struct {
+	Status string          `json:"status"`
+	Msg    string          `json:"msg"`
+	Data   json.RawMessage `json:"data"`
+}
+
+// do performs one authenticated IAM request and decodes the /v1 envelope. body is
+// an optional JSON payload (nil for GET/param-only POST). A 401/403 from IAM maps
+// to a distinct denied error; a non-envelope or non-ok status is an error with the
+// upstream msg. The response body is size-bounded and never logged (it may carry a
+// freshly-minted key).
+func (c *iamClient) do(ctx context.Context, method, path string, q url.Values, body []byte) (iamEnvelope, error) {
+	if !c.configured() {
+		return iamEnvelope{}, errNotConfigured
+	}
+	u := c.base + path
+	if enc := q.Encode(); enc != "" {
+		u += "?" + enc
+	}
+	var rdr io.Reader
+	if body != nil {
+		rdr = strings.NewReader(string(body))
+	}
+	req, err := http.NewRequestWithContext(ctx, method, u, rdr)
+	if err != nil {
+		return iamEnvelope{}, err
+	}
+	req.Header.Set("Authorization", c.basicAuth())
+	req.Header.Set("Accept", "application/json")
+	if body != nil {
+		req.Header.Set("Content-Type", "application/json")
+	}
+	resp, err := c.http.Do(req)
+	if err != nil {
+		return iamEnvelope{}, fmt.Errorf("iam unreachable: %w", err)
+	}
+	defer resp.Body.Close()
+	raw, err := io.ReadAll(io.LimitReader(resp.Body, iamMaxBody))
+	if err != nil {
+		return iamEnvelope{}, err
+	}
+	if resp.StatusCode == http.StatusUnauthorized || resp.StatusCode == http.StatusForbidden {
+		return iamEnvelope{}, fmt.Errorf("iam denied (%d)", resp.StatusCode)
+	}
+	var env iamEnvelope
+	if err := json.Unmarshal(raw, &env); err != nil {
+		return iamEnvelope{}, fmt.Errorf("iam non-envelope response (%d)", resp.StatusCode)
+	}
+	if env.Status != "ok" {
+		msg := env.Msg
+		if msg == "" {
+			msg = fmt.Sprintf("iam status %d", resp.StatusCode)
+		}
+		return iamEnvelope{}, fmt.Errorf("iam: %s", msg)
+	}
+	return env, nil
+}
+
+// ── the `hk-` Cloud API key (per-user) ───────────────────────────────────────
+
+// userKey is the subset of an IAM user row the key surface reads: the `hk-` access
+// key and the last time the key row changed (updatedTime).
+type userKey struct {
+	AccessKey   string `json:"accessKey"`
+	UpdatedTime string `json:"updatedTime"`
+}
+
+// getUserKey reads a user's CURRENT `hk-` key AUTHORITATIVELY from IAM (get-user).
+// The session claim can lag a freshly-minted key (it returns ”) — so GET /keys
+// must read IAM, not the claim (the "key never listed" bug identity.ts documents).
+// `id` is the `<owner>/<name>` composite IAM parses.
+func (c *iamClient) getUserKey(ctx context.Context, id string) (userKey, error) {
+	env, err := c.do(ctx, http.MethodGet, "/v1/iam/get-user", url.Values{"id": {id}}, nil)
+	if err != nil {
+		return userKey{}, err
+	}
+	var u userKey
+	if err := json.Unmarshal(env.Data, &u); err != nil {
+		return userKey{}, fmt.Errorf("iam get-user: decode: %w", err)
+	}
+	return u, nil
+}
+
+// mintUserKey (re)generates the user's `hk-` key and returns the new secret — shown
+// ONCE to the caller (POST /keys), never echoed again. IAM binds the key to `id`,
+// so a caller can only ever mint their OWN.
+func (c *iamClient) mintUserKey(ctx context.Context, id string) (string, error) {
+	env, err := c.do(ctx, http.MethodPost, "/v1/iam/mint-user-keys", url.Values{"id": {id}}, nil)
+	if err != nil {
+		return "", err
+	}
+	var out struct {
+		AccessKey string `json:"accessKey"`
+	}
+	if err := json.Unmarshal(env.Data, &out); err != nil {
+		return "", fmt.Errorf("iam mint-user-keys: decode: %w", err)
+	}
+	if out.AccessKey == "" {
+		return "", fmt.Errorf("iam did not return an access key")
+	}
+	return out.AccessKey, nil
+}
+
+// revokeUserKey clears the user's `hk-` key (immediate revoke; the gateway key
+// cache lapses within ~5m).
+func (c *iamClient) revokeUserKey(ctx context.Context, id string) error {
+	_, err := c.do(ctx, http.MethodPost, "/v1/iam/revoke-user-keys", url.Values{"id": {id}}, nil)
+	return err
+}
+
+// ── organizations (onboarding) ───────────────────────────────────────────────
+
+// iamOrg is the subset of an IAM organization the onboarding surface reads/clones:
+// password + locale settings, so a created org is well-formed and a moved user's
+// login is unaffected.
+type iamOrg struct {
+	Owner                  string   `json:"owner"`
+	Name                   string   `json:"name"`
+	DisplayName            string   `json:"displayName"`
+	PasswordType           string   `json:"passwordType,omitempty"`
+	PasswordSalt           string   `json:"passwordSalt,omitempty"`
+	PasswordObfuscatorType string   `json:"passwordObfuscatorType,omitempty"`
+	PasswordObfuscatorKey  string   `json:"passwordObfuscatorKey,omitempty"`
+	PasswordOptions        []string `json:"passwordOptions,omitempty"`
+	CountryCodes           []string `json:"countryCodes,omitempty"`
+	Languages              []string `json:"languages,omitempty"`
+	DefaultAvatar          string   `json:"defaultAvatar,omitempty"`
+	IsPersonal             bool     `json:"isPersonal,omitempty"`
+	CreatedTime            string   `json:"createdTime,omitempty"`
+}
+
+// getOrganization reads an org (owned by the `admin` org) by slug; (nil,nil) when
+// absent so a caller can test availability. A transport error (unreachable IAM)
+// propagates so onboarding never mistakes "unreachable" for "available" and creates
+// a duplicate.
+func (c *iamClient) getOrganization(ctx context.Context, slug string) (*iamOrg, error) {
+	env, err := c.do(ctx, http.MethodGet, "/v1/iam/get-organization", url.Values{"id": {adminOrg + "/" + slug}}, nil)
+	if err != nil {
+		// IAM returns status!=ok / empty data for a missing org; do() maps a not-ok
+		// envelope to an "iam:" error — that means the org does not exist. A transport
+		// failure ("iam unreachable"/"iam denied") is a real error and propagates.
+		if strings.HasPrefix(err.Error(), "iam:") {
+			return nil, nil
+		}
+		return nil, err
+	}
+	if len(env.Data) == 0 || string(env.Data) == "null" {
+		return nil, nil
+	}
+	var o iamOrg
+	if err := json.Unmarshal(env.Data, &o); err != nil {
+		return nil, fmt.Errorf("iam get-organization: decode: %w", err)
+	}
+	return &o, nil
+}
+
+// createOrganization creates a customer org owned by the `admin` org, cloning
+// password + locale settings from the caller's current org (so the org is
+// well-formed and a moved user's login is unaffected). Mirrors identity.ts's
+// createOrganization.
+func (c *iamClient) createOrganization(ctx context.Context, o iamOrg) error {
+	body, err := json.Marshal(o)
+	if err != nil {
+		return err
+	}
+	_, err = c.do(ctx, http.MethodPost, "/v1/iam/add-organization", nil, body)
+	return err
+}
+
+// getUser reads a full user row (for the move: update-user re-submits it whole).
+func (c *iamClient) getUser(ctx context.Context, id string) (json.RawMessage, error) {
+	env, err := c.do(ctx, http.MethodGet, "/v1/iam/get-user", url.Values{"id": {id}}, nil)
+	if err != nil {
+		return nil, err
+	}
+	if len(env.Data) == 0 || string(env.Data) == "null" {
+		return nil, errNotFound
+	}
+	return env.Data, nil
+}
+
+// moveUserToOrg makes the zero-org user an admin of `slug`: it re-submits the user
+// row with owner=slug + isAdmin=true (update-user takes the whole row). The user's
+// password travels with the row (IAM verifies against user.PasswordType first), so
+// the move never locks them out. `id` is the caller's CURRENT `<owner>/<name>`.
+func (c *iamClient) moveUserToOrg(ctx context.Context, id, slug string) error {
+	rowRaw, err := c.getUser(ctx, id)
+	if err != nil {
+		return err
+	}
+	var row map[string]any
+	if err := json.Unmarshal(rowRaw, &row); err != nil {
+		return fmt.Errorf("iam get-user: decode: %w", err)
+	}
+	row["owner"] = slug
+	row["isAdmin"] = true
+	body, err := json.Marshal(row)
+	if err != nil {
+		return err
+	}
+	// update-user is keyed by the ORIGINAL id (the row's current owner/name).
+	_, err = c.do(ctx, http.MethodPost, "/v1/iam/update-user", url.Values{"id": {id}}, body)
+	return err
+}

clients/account/onboarding.go

@@ -0,0 +1,98 @@
+// onboarding.go — PURE org-naming + reserved-name policy, no transport/IAM. A
+// faithful Go port of console's src/lib/server/onboarding.ts, decomplected from
+// the handler so the naming rules are one testable thing (the route does the IAM
+// calls; this decides the slug). Two concerns:
+//
+//   - NAMING: turn a human org name (or a username) into a valid IAM org slug —
+//     lowercase, [a-z0-9-], collapsed, trimmed, bounded.
+//   - RESERVED: refuse names that must never become a customer org — IAM system
+//     owners (admin/built-in/app) and the brand/staff orgs (hanzo/lux/zoo/pars),
+//     which the OrgGate routes to the admin host. Creating one would collide with
+//     a staff tenant or a system principal.
+package account
+
+import "strings"
+
+// reservedOrgs are brand/staff orgs + IAM system owners — never a customer org.
+// Matches onboarding.ts RESERVED_ORGS exactly (kept as a set for O(1) lookup).
+var reservedOrgs = map[string]bool{
+	// IAM system owners
+	"admin":    true,
+	"built-in": true,
+	"app":      true,
+	// brand/staff orgs (the OrgGate sends these to the admin host)
+	"hanzo": true,
+	"lux":   true,
+	"zoo":   true,
+	"pars":  true,
+}
+
+const (
+	// maxOrgSlug bounds a slug (IAM org name is varchar(100); keep it short/readable).
+	maxOrgSlug = 60
+	// minOrgSlug is the minimum length after normalization.
+	minOrgSlug = 2
+)
+
+// slugifyOrg normalizes a human name to an IAM org slug: lowercase ASCII, runs of
+// non-alphanumerics → '-', collapse repeats, trim leading/trailing '-', cap at
+// maxOrgSlug (re-trimming a trailing '-' the slice may reveal). Returns "" when the
+// input has no usable characters. Mirrors onboarding.ts slugifyOrg (Go has no NFKD
+// normalize in std without golang.org/x/text; ASCII inputs — the real org-name
+// case — are handled identically, and any non-ASCII rune is treated as a separator,
+// which is the same net effect NFKD+[^a-z0-9] produces for the slug).
+func slugifyOrg(input string) string {
+	var b strings.Builder
+	prevDash := false
+	for _, r := range strings.ToLower(input) {
+		if (r >= 'a' && r <= 'z') || (r >= '0' && r <= '9') {
+			b.WriteRune(r)
+			prevDash = false
+		} else if !prevDash {
+			b.WriteByte('-')
+			prevDash = true
+		}
+	}
+	out := strings.Trim(b.String(), "-")
+	if len(out) > maxOrgSlug {
+		out = strings.TrimRight(out[:maxOrgSlug], "-")
+	}
+	return out
+}
+
+// personalOrgSlug is the default personal-org slug for a user. An email-like
+// username collapses to its local part (dave@x.com → dave) so a personal org reads
+// as the person, not their address; everything else is slugified as-is.
+func personalOrgSlug(username string) string {
+	base := username
+	if at := strings.IndexByte(username, '@'); at > 0 {
+		base = username[:at]
+	}
+	return slugifyOrg(base)
+}
+
+// isReservedOrg reports whether a slug is a brand/staff or system org — never
+// creatable.
+func isReservedOrg(slug string) bool { return reservedOrgs[slug] }
+
+// orgNameResult is the outcome of validating a requested org name: a creatable slug
+// or an honest client-facing error.
+type orgNameResult struct {
+	ok    bool
+	slug  string
+	error string
+}
+
+// validateOrgName validates + normalizes a requested org name into a creatable
+// slug, or an honest error. The ONE place the create rules live (handler + tests
+// share it). Mirrors onboarding.ts validateOrgName.
+func validateOrgName(input string) orgNameResult {
+	slug := slugifyOrg(input)
+	if len(slug) < minOrgSlug {
+		return orgNameResult{ok: false, error: "Use at least 2 letters or numbers."}
+	}
+	if isReservedOrg(slug) {
+		return orgNameResult{ok: false, error: "“" + slug + "” is reserved. Choose a different name."}
+	}
+	return orgNameResult{ok: true, slug: slug}
+}

clients/account/onboarding_test.go

@@ -0,0 +1,84 @@
+package account
+
+import "testing"
+
+func TestSlugifyOrg(t *testing.T) {
+	cases := map[string]string{
+		"Acme Rockets":      "acme-rockets",
+		"  Hello, World!  ": "hello-world",
+		"UPPER_case-123":    "upper-case-123",
+		"多 bytes 混":         "bytes", // non-ASCII runes act as separators (slug is ASCII)
+		"---":               "",
+		"":                  "",
+		"a.b.c":             "a-b-c",
+	}
+	for in, want := range cases {
+		if got := slugifyOrg(in); got != want {
+			t.Errorf("slugifyOrg(%q) = %q, want %q", in, got, want)
+		}
+	}
+	// A name longer than the cap is truncated and re-trimmed (no trailing dash).
+	long := "this-is-a-very-long-organization-name-that-exceeds-the-sixty-character-cap-easily"
+	got := slugifyOrg(long)
+	if len(got) > maxOrgSlug {
+		t.Errorf("slugifyOrg over-cap: len=%d > %d (%q)", len(got), maxOrgSlug, got)
+	}
+	if got != "" && got[len(got)-1] == '-' {
+		t.Errorf("slugifyOrg left a trailing dash after slice: %q", got)
+	}
+}
+
+func TestValidateOrgName(t *testing.T) {
+	if v := validateOrgName("a"); v.ok {
+		t.Errorf("single char should be rejected (min %d): %+v", minOrgSlug, v)
+	}
+	if v := validateOrgName("!!"); v.ok {
+		t.Errorf("no-usable-chars should be rejected: %+v", v)
+	}
+	for _, reserved := range []string{"admin", "Hanzo", "built-in", "lux", "zoo", "pars", "app"} {
+		if v := validateOrgName(reserved); v.ok {
+			t.Errorf("reserved %q should be rejected: %+v", reserved, v)
+		}
+	}
+	v := validateOrgName("Cool Team")
+	if !v.ok || v.slug != "cool-team" {
+		t.Errorf("valid name: want ok cool-team, got %+v", v)
+	}
+}
+
+func TestPersonalOrgSlug(t *testing.T) {
+	cases := map[string]string{
+		"dave@example.com": "dave",
+		"Alice.Smith":      "alice-smith",
+		"bob":              "bob",
+		"@leading":         "-leading"[1:], // slugified: "leading"
+	}
+	for in, want := range cases {
+		if got := personalOrgSlug(in); got != want {
+			t.Errorf("personalOrgSlug(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
+
+func TestHumanize(t *testing.T) {
+	cases := map[string]string{
+		"dave.smith@x.com": "Dave Smith",
+		"alice":            "Alice",
+		"bob_jones":        "Bob Jones",
+		"@":                "Personal",
+	}
+	for in, want := range cases {
+		if got := humanize(in); got != want {
+			t.Errorf("humanize(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
+
+func TestIsReservedOrg(t *testing.T) {
+	if !isReservedOrg("admin") || !isReservedOrg("hanzo") {
+		t.Fatal("admin/hanzo must be reserved")
+	}
+	if isReservedOrg("acme") {
+		t.Fatal("acme must not be reserved")
+	}
+}

clients/account/ratelimit.go

@@ -0,0 +1,115 @@
+package account
+
+// Per-IP rate limiting for the abuse-sensitive console write routes (hk- key
+// mint/rotate/revoke, HUSD wallet top-up). This is DISTINCT from commerce's spend-cap
+// (ScopeRateLimit): it caps request FREQUENCY per client IP to blunt brute-force /
+// enumeration / resource-exhaustion, restoring the edge protection cloud loses when a
+// caller reaches it DIRECTLY (bypassing the gateway/ingress limiter) on the money path.
+//
+// A token bucket per IP: `perMin` tokens refilled continuously, burst == perMin. In
+// memory (cloud is single-replica for this surface); multi-replica would be a per-
+// replica soft limit — acceptable defense-in-depth, not a hard global quota. Idle
+// buckets are evicted lazily so the map cannot grow without bound.
+
+import (
+	"net"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/hanzoai/cloud"
+	"github.com/zap-proto/zip"
+)
+
+type tokenBucket struct {
+	tokens float64
+	last   time.Time
+}
+
+type rateLimiter struct {
+	mu      sync.Mutex
+	buckets map[string]*tokenBucket
+	perSec  float64
+	burst   float64
+	ttl     time.Duration // evict buckets idle longer than this
+	lastGC  time.Time
+}
+
+// newRateLimiter builds a limiter allowing `perMin` requests/minute per IP (burst ==
+// perMin). perMin<=0 disables limiting (allow always).
+func newRateLimiter(perMin int) *rateLimiter {
+	return &rateLimiter{
+		buckets: map[string]*tokenBucket{},
+		perSec:  float64(perMin) / 60.0,
+		burst:   float64(perMin),
+		ttl:     10 * time.Minute,
+		lastGC:  time.Now(),
+	}
+}
+
+// allow reports whether a request from key (IP) may proceed, consuming one token.
+func (r *rateLimiter) allow(key string) bool {
+	if r.perSec <= 0 {
+		return true
+	}
+	now := time.Now()
+	r.mu.Lock()
+	defer r.mu.Unlock()
+
+	if now.Sub(r.lastGC) > r.ttl {
+		for k, b := range r.buckets {
+			if now.Sub(b.last) > r.ttl {
+				delete(r.buckets, k)
+			}
+		}
+		r.lastGC = now
+	}
+
+	b := r.buckets[key]
+	if b == nil {
+		b = &tokenBucket{tokens: r.burst, last: now}
+		r.buckets[key] = b
+	}
+	// Refill.
+	b.tokens += now.Sub(b.last).Seconds() * r.perSec
+	if b.tokens > r.burst {
+		b.tokens = r.burst
+	}
+	b.last = now
+	if b.tokens < 1 {
+		return false
+	}
+	b.tokens--
+	return true
+}
+
+// rateKey resolves the un-spoofable key to limit on. These are all POST-AUTH money-
+// write routes, so the primary key is the VALIDATED principal (X-Org-Id/X-User-Id,
+// minted by SanitizeIdentity from a verified JWT — a caller cannot forge it). This is
+// deliberately NOT X-Forwarded-For: the limiter exists for the OFF-GATEWAY path where
+// nothing trusted stamps XFF, so keying on a client-settable XFF would let an attacker
+// send a fresh value per request and reset the bucket at will (RED). An unauthenticated
+// request (which the handler 403s anyway) has no principal, so it falls back to the
+// SOCKET peer address (c.Fiber().IP() — the L4 RemoteAddr, the real attacker on the
+// direct-to-pod path), never a header.
+func rateKey(c *zip.Ctx) string {
+	if uid := strings.TrimSpace(c.User()); uid != "" {
+		return "p:" + strings.TrimSpace(c.Org()) + "/" + uid
+	}
+	ip := c.Fiber().IP()
+	if host, _, err := net.SplitHostPort(ip); err == nil {
+		ip = host
+	}
+	return "a:" + ip
+}
+
+// rateLimit wraps a handler, refusing 429 when the caller (validated principal, else
+// socket peer) exceeds rl.
+func rateLimit(s *cloud.Service[state], rl *rateLimiter, next zip.Handler) zip.Handler {
+	return func(c *zip.Ctx) error {
+		if !rl.allow(rateKey(c)) {
+			return zip.Errorf(429, "rate limit exceeded; retry shortly")
+		}
+		return next(c)
+	}
+}

clients/account/topup.go

@@ -0,0 +1,373 @@
+// topup.go ports console's app/billing/v1/topup/wallet/route.ts into the unified
+// binary at POST /v1/commerce/topup/wallet (task #41). It is the verify-and-record
+// seam for an HUSD wallet top-up: the browser sends an HUSD ERC-20 transfer to the
+// treasury and posts the tx hash here; this handler reads the receipt from the Hanzo
+// EVM, confirms it is a mined, successful HUSD Transfer(from → treasury, value),
+// derives USD cents from the (18-decimal, USD-pegged) on-chain value, records it to
+// commerce as an `husd` crypto payment, and returns the credited amount + balance.
+//
+// THE CREDITED AMOUNT IS THE ON-CHAIN VALUE, never a client number — which is exactly
+// why this MUST be a server handler and cannot collapse to a same-origin call. Two
+// hardenings over the Node route:
+//
+//   - IDOR-safe: the credit lands on the VALIDATED caller's own org/user (the
+//     gateway-verified X-Org-Id/X-User-Id), never a client-supplied `userId`.
+//   - S2S to commerce: recorded with the admin COMMERCE_SERVICE_TOKEN + the caller's
+//     X-Org-Id (the same service-to-service pattern clients/admin reads balances on),
+//     not by forwarding a browser cookie.
+//
+// The EVM receipt is read over plain JSON-RPC (eth_getTransactionReceipt) — one
+// well-known call + one well-known event, so the stdlib is sufficient and no EVM
+// client dependency is pulled in.
+//
+// Honest failure (no fabricated credit, ever): HUSD/treasury unconfigured
+// (greenfield — HUSD not yet deployed) → 501; a missing/failed/non-HUSD-to-treasury
+// tx → 400; the chain or commerce unreachable → 502.
+package account
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"math/big"
+	"net/http"
+	"net/url"
+	"os"
+	"regexp"
+	"strings"
+	"time"
+
+	"github.com/hanzoai/cloud"
+	"github.com/hanzoai/cloud/clients/commerceinproc"
+	"github.com/zap-proto/zip"
+)
+
+// httpClient is the shared outbound client for the account subsystem's plain-HTTP seams
+// (EVM JSON-RPC, commerce billing/store S2S). Small JSON envelopes, bounded reads; 15s
+// is generous for an in-cluster / same-region hop. (Owned here — the S2S transport home
+// — since the former waitlist.go was retired with the /v1/console namespace.)
+var httpClient = &http.Client{Timeout: 15 * time.Second}
+
+// commerceHTTP is the client for the commerce S2S seam ONLY (commerceDo). Separate
+// from httpClient (which also dials EVM JSON-RPC) so that — when commerce is folded
+// in-process (task #111) — commerce calls dispatch to the in-process handler via
+// commerceinproc's self-routing transport (no socket to the standalone), while the
+// HUSD chain RPC keeps going over the real network. Off the co-resident path it is a
+// plain HTTP client, exactly like before.
+var commerceHTTP = commerceinproc.Client(15 * time.Second)
+
+// transferTopic is keccak256("Transfer(address,address,uint256)") — the ERC-20
+// Transfer event signature, topics[0] of every transfer log. A universally-fixed
+// constant (no need to hash at runtime).
+const transferTopic = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
+
+// husdCentDivisor: HUSD is an 18-decimal, USD-pegged stablecoin, so 1e16 base units
+// = 1 cent. Mirrors route.ts's `value / 10n ** 16n`.
+var husdCentDivisor = new(big.Int).Exp(big.NewInt(10), big.NewInt(16), nil)
+
+var (
+	addrRe   = regexp.MustCompile(`^0x[0-9a-fA-F]{40}$`)
+	txHashRe = regexp.MustCompile(`^0x[0-9a-fA-F]{64}$`)
+)
+
+func isAddr(a string) bool { return addrRe.MatchString(a) }
+
+// topupConfig is the deployment's HUSD + commerce wiring, resolved from server-only
+// env (sourced from KMS by the deployment, never a browser value).
+type topupConfig struct {
+	husd     string // HUSD ERC-20 contract address
+	treasury string // the top-up treasury address
+	rpcURL   string // Hanzo EVM JSON-RPC endpoint
+	chainID  int64
+	commerce string // commerce base (e.g. http://commerce.hanzo.svc.cluster.local:8001)
+	token    string // admin S2S bearer for commerce (COMMERCE_SERVICE_TOKEN; never logged)
+}
+
+func loadTopupConfig() topupConfig {
+	chainID := int64(36963)
+	if v := strings.TrimSpace(os.Getenv("HANZO_CHAIN_ID")); v != "" {
+		if n, ok := new(big.Int).SetString(v, 10); ok {
+			chainID = n.Int64()
+		}
+	}
+	return topupConfig{
+		husd:     strings.TrimSpace(os.Getenv("HANZO_HUSD_ADDRESS")),
+		treasury: strings.TrimSpace(os.Getenv("HANZO_HUSD_TREASURY")),
+		rpcURL:   strings.TrimRight(getenv("HANZO_RPC_URL", "https://rpc.hanzo.network"), "/"),
+		chainID:  chainID,
+		commerce: strings.TrimRight(getenv("COMMERCE_URL", "https://api.hanzo.ai"), "/"),
+		token:    strings.TrimSpace(os.Getenv("COMMERCE_SERVICE_TOKEN")),
+	}
+}
+
+// configured reports whether the greenfield gate is satisfied — a valid HUSD contract
+// AND treasury. Until HUSD is deployed both are unset and the surface is honestly 501.
+func (t topupConfig) configured() bool { return isAddr(t.husd) && isAddr(t.treasury) }
+
+type walletTopupReq struct {
+	TxHash      string `json:"txHash"`
+	FromAddress string `json:"fromAddress"`
+	// A client-supplied `userId` is intentionally NOT read — the credit lands on the
+	// validated caller (no IDOR).
+}
+
+type walletTopupResp struct {
+	CreditedCents int64  `json:"creditedCents"`
+	Balance       int64  `json:"balance"`
+	TxHash        string `json:"txHash"`
+	Status        string `json:"status"`
+}
+
+// walletTopup verifies a sent HUSD transfer on-chain and credits the caller's org.
+// Mirrors POST app/billing/v1/topup/wallet/route.ts.
+func walletTopup(s *cloud.Service[state], c *zip.Ctx) error {
+	cfg := loadTopupConfig()
+	// Greenfield gate: no HUSD contract / treasury ⇒ honest "not configured yet".
+	if !cfg.configured() {
+		return zip.Errorf(http.StatusNotImplemented, "HUSD top-up is not configured yet (HUSD is not deployed on Hanzo Mainnet)")
+	}
+
+	// The credit lands on the VALIDATED caller's own org (X-Org-Id) — require it.
+	cr, ok := resolveCaller(c, true)
+	if !ok {
+		return zip.ErrForbidden("sign in to top up your balance")
+	}
+
+	var body walletTopupReq
+	if err := c.Bind(&body); err != nil {
+		return zip.ErrBadRequest("invalid JSON body")
+	}
+	txHash := strings.TrimSpace(body.TxHash)
+	if !txHashRe.MatchString(txHash) {
+		return zip.ErrBadRequest("a valid transaction hash is required")
+	}
+
+	// ── 1. Verify the HUSD transfer on-chain ─────────────────────────────────────
+	cents, verifiedFrom, herr := verifyHusdTransfer(c.Context(), cfg, txHash, strings.TrimSpace(body.FromAddress))
+	if herr != nil {
+		return herr
+	}
+
+	// ── 2. Record to commerce as an HUSD crypto payment (S2S) ────────────────────
+	status, herr := recordHusdPayment(c.Context(), cfg, cr, txHash, verifiedFrom, cents)
+	if herr != nil {
+		return herr
+	}
+
+	// New USD-ledger balance — best-effort; the credit already landed.
+	balance := commerceBalanceCents(c.Context(), cfg, cr)
+
+	return c.JSON(http.StatusOK, walletTopupResp{CreditedCents: cents, Balance: balance, TxHash: txHash, Status: status})
+}
+
+// ── on-chain verification (plain JSON-RPC) ───────────────────────────────────────
+
+// rpcReceipt is the subset of an eth_getTransactionReceipt result we read.
+type rpcReceipt struct {
+	Status string   `json:"status"` // "0x1" success, "0x0" failed
+	Logs   []rpcLog `json:"logs"`
+}
+
+type rpcLog struct {
+	Address string   `json:"address"`
+	Topics  []string `json:"topics"`
+	Data    string   `json:"data"`
+}
+
+// verifyHusdTransfer reads the receipt and confirms exactly one mined, successful
+// HUSD Transfer to the treasury, returning the credited cents and the sender. Any
+// non-conforming tx is an honest 400; an unreachable chain is a 502.
+func verifyHusdTransfer(ctx context.Context, cfg topupConfig, txHash, wantFrom string) (int64, string, error) {
+	rcpt, err := getReceipt(ctx, cfg.rpcURL, txHash)
+	if err != nil {
+		return 0, "", zip.Errorf(http.StatusBadGateway, "could not verify the transaction on Hanzo Mainnet: %v", err)
+	}
+	if rcpt == nil {
+		return 0, "", zip.ErrBadRequest("transaction not found or not yet mined")
+	}
+	if strings.ToLower(rcpt.Status) != "0x1" {
+		return 0, "", zip.ErrBadRequest("transaction failed on-chain")
+	}
+
+	husd := strings.ToLower(cfg.husd)
+	treasuryTopic := addrToTopic(cfg.treasury)
+	for _, lg := range rcpt.Logs {
+		if strings.ToLower(lg.Address) != husd {
+			continue
+		}
+		if len(lg.Topics) < 3 || strings.ToLower(lg.Topics[0]) != transferTopic {
+			continue
+		}
+		if strings.ToLower(lg.Topics[2]) != treasuryTopic { // indexed `to`
+			continue
+		}
+		value, ok := new(big.Int).SetString(strings.TrimPrefix(lg.Data, "0x"), 16)
+		if !ok {
+			continue
+		}
+		cents := new(big.Int).Div(value, husdCentDivisor)
+		if cents.Sign() <= 0 || !cents.IsInt64() {
+			return 0, "", zip.ErrBadRequest("transferred amount is below the minimum (1 cent)")
+		}
+		from := topicToAddr(lg.Topics[1]) // indexed `from`
+		if wantFrom != "" && isAddr(wantFrom) && !strings.EqualFold(from, wantFrom) {
+			return 0, "", zip.ErrBadRequest("transfer sender does not match the connected wallet")
+		}
+		return cents.Int64(), from, nil
+	}
+	return 0, "", zip.ErrBadRequest("no HUSD transfer to the treasury was found in this transaction")
+}
+
+// getReceipt calls eth_getTransactionReceipt over JSON-RPC. A null result (not mined)
+// returns (nil,nil); a transport / RPC error propagates.
+func getReceipt(ctx context.Context, rpcURL, txHash string) (*rpcReceipt, error) {
+	reqBody, _ := json.Marshal(map[string]any{
+		"jsonrpc": "2.0", "id": 1, "method": "eth_getTransactionReceipt", "params": []string{txHash},
+	})
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, rpcURL, bytes.NewReader(reqBody))
+	if err != nil {
+		return nil, err
+	}
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Accept", "application/json")
+	resp, err := httpClient.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("rpc unreachable: %w", err)
+	}
+	defer resp.Body.Close()
+	raw, err := io.ReadAll(io.LimitReader(resp.Body, 4<<20))
+	if err != nil {
+		return nil, err
+	}
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		return nil, fmt.Errorf("rpc status %d", resp.StatusCode)
+	}
+	var env struct {
+		Result *rpcReceipt `json:"result"`
+		Error  *struct {
+			Message string `json:"message"`
+		} `json:"error"`
+	}
+	if err := json.Unmarshal(raw, &env); err != nil {
+		return nil, fmt.Errorf("rpc decode: %w", err)
+	}
+	if env.Error != nil {
+		return nil, fmt.Errorf("rpc error: %s", env.Error.Message)
+	}
+	return env.Result, nil // Result==nil ⇒ not found / not yet mined
+}
+
+// addrToTopic left-pads a 20-byte address to a 32-byte indexed topic (lowercase).
+func addrToTopic(addr string) string {
+	h := strings.ToLower(strings.TrimPrefix(addr, "0x"))
+	return "0x" + strings.Repeat("0", 64-len(h)) + h
+}
+
+// topicToAddr extracts the 20-byte address from a 32-byte indexed topic (lowercase,
+// 0x-prefixed).
+func topicToAddr(topic string) string {
+	h := strings.TrimPrefix(topic, "0x")
+	if len(h) < 40 {
+		return "0x" + h
+	}
+	return "0x" + h[len(h)-40:]
+}
+
+// ── commerce (S2S) ───────────────────────────────────────────────────────────────
+
+// recordHusdPayment records the verified credit to commerce as an `husd` crypto
+// payment, scoped to the caller's org via the S2S service token + X-Org-Id.
+func recordHusdPayment(ctx context.Context, cfg topupConfig, cr caller, txHash, from string, cents int64) (string, error) {
+	payload, _ := json.Marshal(map[string]any{
+		"method":      "crypto",
+		"network":     "hanzo",
+		"chainId":     cfg.chainID,
+		"currency":    "husd",
+		"amount":      cents,
+		"txHash":      txHash,
+		"fromAddress": from,
+		"toAddress":   cfg.treasury,
+		"userId":      cr.id, // the VALIDATED caller — never a client-supplied id
+	})
+	raw, status, err := commerceDo(ctx, cfg.commerce, cfg.token, http.MethodPost, "/v1/billing/payment", nil, cr.owner, payload)
+	if err != nil {
+		return "", zip.Errorf(http.StatusBadGateway, "could not reach commerce to record the payment: %v", err)
+	}
+	if status < 200 || status >= 300 {
+		return "", zip.Errorf(http.StatusBadGateway, "commerce rejected the payment (HTTP %d): %s", status, strings.TrimSpace(string(raw)))
+	}
+	var out struct {
+		Status string `json:"status"`
+	}
+	_ = json.Unmarshal(raw, &out)
+	if out.Status == "" {
+		out.Status = "recorded"
+	}
+	return out.Status, nil
+}
+
+// commerceBalanceCents reads the caller's USD-ledger balance (cents). Best-effort:
+// the credit is already recorded, so a read error degrades to 0, not a failure.
+func commerceBalanceCents(ctx context.Context, cfg topupConfig, cr caller) int64 {
+	q := url.Values{"user": {cr.id}, "currency": {"usd"}}
+	raw, status, err := commerceDo(ctx, cfg.commerce, cfg.token, http.MethodGet, "/v1/billing/balance", q, cr.owner, nil)
+	if err != nil || status < 200 || status >= 300 {
+		return 0
+	}
+	var b struct {
+		Balance   int64 `json:"balance"`
+		Available int64 `json:"available"`
+	}
+	if err := json.Unmarshal(raw, &b); err != nil {
+		return 0
+	}
+	if b.Balance != 0 {
+		return b.Balance
+	}
+	return b.Available
+}
+
+// commerceDo performs one S2S commerce request: admin bearer + X-Org-Id (commerce's
+// EdgeAuth trusts the org header ONLY behind the service token). Returns the raw
+// body + status. Mirrors clients/admin/commerce.go's auth. Takes (base, token) rather
+// than the HUSD topupConfig so both the wallet top-up AND the /v1/billing/* data bridge
+// (billing.go) share this ONE S2S transport.
+func commerceDo(ctx context.Context, base, token, method, path string, q url.Values, org string, body []byte) ([]byte, int, error) {
+	if base == "" {
+		return nil, 0, fmt.Errorf("commerce not configured")
+	}
+	u := base + path
+	if enc := q.Encode(); enc != "" {
+		u += "?" + enc
+	}
+	var rdr io.Reader
+	if body != nil {
+		rdr = bytes.NewReader(body)
+	}
+	req, err := http.NewRequestWithContext(ctx, method, u, rdr)
+	if err != nil {
+		return nil, 0, err
+	}
+	req.Header.Set("Accept", "application/json")
+	if body != nil {
+		req.Header.Set("Content-Type", "application/json")
+	}
+	if token != "" {
+		req.Header.Set("Authorization", "Bearer "+token)
+	}
+	if org != "" {
+		req.Header.Set("X-Org-Id", org)
+	}
+	resp, err := commerceHTTP.Do(req)
+	if err != nil {
+		return nil, 0, fmt.Errorf("commerce unreachable: %w", err)
+	}
+	defer resp.Body.Close()
+	raw, err := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
+	if err != nil {
+		return nil, resp.StatusCode, err
+	}
+	return raw, resp.StatusCode, nil
+}

clients/account/topup_test.go

@@ -0,0 +1,241 @@
+package account
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"math/big"
+	"net/http"
+	"net/http/httptest"
+	"sync"
+	"testing"
+)
+
+const (
+	tHusd     = "0x1111111111111111111111111111111111111111"
+	tTreasury = "0x2222222222222222222222222222222222222222"
+	tSender   = "0x3333333333333333333333333333333333333333"
+	tOther    = "0x4444444444444444444444444444444444444444"
+	tTxHash   = "0xabc0000000000000000000000000000000000000000000000000000000000001"
+)
+
+// fakeRPC is a minimal eth JSON-RPC node: it returns a settable `result` for
+// eth_getTransactionReceipt (nil ⇒ null ⇒ not mined) and records the tx it was asked.
+type fakeRPC struct {
+	mu     sync.Mutex
+	result any
+	gotTx  string
+}
+
+func (f *fakeRPC) server(t *testing.T) *httptest.Server {
+	t.Helper()
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		var req struct {
+			Params []string `json:"params"`
+		}
+		raw, _ := io.ReadAll(r.Body)
+		_ = json.Unmarshal(raw, &req)
+		f.mu.Lock()
+		if len(req.Params) > 0 {
+			f.gotTx = req.Params[0]
+		}
+		res := f.result
+		f.mu.Unlock()
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(map[string]any{"jsonrpc": "2.0", "id": 1, "result": res})
+	}))
+	t.Cleanup(srv.Close)
+	return srv
+}
+
+// fakeCommerce records the S2S payment record + balance reads.
+type fakeCommerce struct {
+	mu      sync.Mutex
+	payment map[string]any
+	gotOrg  string
+	gotAuth string
+	balance int64
+}
+
+func (f *fakeCommerce) server(t *testing.T) *httptest.Server {
+	t.Helper()
+	mux := http.NewServeMux()
+	mux.HandleFunc("/v1/billing/payment", func(w http.ResponseWriter, r *http.Request) {
+		raw, _ := io.ReadAll(r.Body)
+		var p map[string]any
+		_ = json.Unmarshal(raw, &p)
+		f.mu.Lock()
+		f.payment, f.gotOrg, f.gotAuth = p, r.Header.Get("X-Org-Id"), r.Header.Get("Authorization")
+		f.mu.Unlock()
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = io.WriteString(w, `{"status":"paid"}`)
+	})
+	mux.HandleFunc("/v1/billing/balance", func(w http.ResponseWriter, r *http.Request) {
+		f.mu.Lock()
+		bal := f.balance
+		f.mu.Unlock()
+		_ = json.NewEncoder(w).Encode(map[string]any{"balance": bal})
+	})
+	srv := httptest.NewServer(mux)
+	t.Cleanup(srv.Close)
+	return srv
+}
+
+// husdReceipt builds a receipt carrying one HUSD Transfer(from→to, cents*1e16).
+func husdReceipt(status, husd, from, to string, cents int64) map[string]any {
+	value := new(big.Int).Mul(big.NewInt(cents), husdCentDivisor)
+	return map[string]any{
+		"status": status,
+		"logs": []any{map[string]any{
+			"address": husd,
+			"topics":  []any{transferTopic, addrToTopic(from), addrToTopic(to)},
+			"data":    "0x" + fmt.Sprintf("%064x", value),
+		}},
+	}
+}
+
+func setTopupEnv(t *testing.T, husd, treasury, rpcURL, commerceURL string) {
+	t.Helper()
+	t.Setenv("HANZO_HUSD_ADDRESS", husd)
+	t.Setenv("HANZO_HUSD_TREASURY", treasury)
+	t.Setenv("HANZO_RPC_URL", rpcURL)
+	t.Setenv("COMMERCE_URL", commerceURL)
+	t.Setenv("COMMERCE_SERVICE_TOKEN", "svc-token")
+}
+
+// principal for a signed-in caller in org acme.
+var alice = map[string]string{"X-User-Id": "alice", "X-Org-Id": "acme"}
+
+func TestTopup_NotConfigured_501(t *testing.T) {
+	setTopupEnv(t, "", "", "http://rpc.invalid", "http://commerce.invalid")
+	app := mountBrand(t, "hanzo")
+	code, _ := callH(t, app, http.MethodPost, "/v1/commerce/topup/wallet", alice, `{"txHash":"`+tTxHash+`"}`)
+	if code != http.StatusNotImplemented {
+		t.Fatalf("HUSD unconfigured: want 501, got %d", code)
+	}
+}
+
+func TestTopup_RequiresValidatedPrincipal(t *testing.T) {
+	rpc := &fakeRPC{}
+	com := &fakeCommerce{}
+	setTopupEnv(t, tHusd, tTreasury, rpc.server(t).URL, com.server(t).URL)
+	app := mountBrand(t, "hanzo")
+	code, _ := callH(t, app, http.MethodPost, "/v1/commerce/topup/wallet", nil, `{"txHash":"`+tTxHash+`"}`)
+	if code != http.StatusForbidden {
+		t.Fatalf("no principal: want 403, got %d", code)
+	}
+}
+
+func TestTopup_BadTxHash_400(t *testing.T) {
+	rpc := &fakeRPC{}
+	com := &fakeCommerce{}
+	setTopupEnv(t, tHusd, tTreasury, rpc.server(t).URL, com.server(t).URL)
+	app := mountBrand(t, "hanzo")
+	code, _ := callH(t, app, http.MethodPost, "/v1/commerce/topup/wallet", alice, `{"txHash":"0xnothex"}`)
+	if code != http.StatusBadRequest {
+		t.Fatalf("bad txHash: want 400, got %d", code)
+	}
+}
+
+func TestTopup_HappyPath_VerifiesAndCredits(t *testing.T) {
+	rpc := &fakeRPC{result: husdReceipt("0x1", tHusd, tSender, tTreasury, 500)}
+	com := &fakeCommerce{balance: 1200}
+	setTopupEnv(t, tHusd, tTreasury, rpc.server(t).URL, com.server(t).URL)
+	app := mountBrand(t, "hanzo")
+
+	code, body := callH(t, app, http.MethodPost, "/v1/commerce/topup/wallet", alice,
+		`{"txHash":"`+tTxHash+`","fromAddress":"`+tSender+`"}`)
+	if code != http.StatusOK {
+		t.Fatalf("topup: want 200, got %d (%s)", code, body)
+	}
+	var r walletTopupResp
+	mustJSON(t, body, &r)
+	if r.CreditedCents != 500 || r.Balance != 1200 || r.Status != "paid" || r.TxHash != tTxHash {
+		t.Fatalf("topup result wrong: %+v", r)
+	}
+	// Commerce recorded the on-chain amount (500), scoped S2S to the caller's org, on
+	// the caller's own subject, with the service bearer.
+	if com.gotOrg != "acme" || com.gotAuth != "Bearer svc-token" {
+		t.Fatalf("commerce S2S auth wrong: org=%q auth=%q", com.gotOrg, com.gotAuth)
+	}
+	if com.payment["userId"] != "acme/alice" {
+		t.Fatalf("credit must target the validated caller acme/alice, got %v", com.payment["userId"])
+	}
+	if amt, _ := com.payment["amount"].(float64); amt != 500 {
+		t.Fatalf("recorded amount must be the on-chain 500 cents, got %v", com.payment["amount"])
+	}
+	if com.payment["currency"] != "husd" {
+		t.Fatalf("currency must be husd, got %v", com.payment["currency"])
+	}
+	if rpc.gotTx != tTxHash {
+		t.Fatalf("rpc should have been asked for %s, got %s", tTxHash, rpc.gotTx)
+	}
+}
+
+func TestTopup_IDOR_CreditsCallerNotBodyUserId(t *testing.T) {
+	rpc := &fakeRPC{result: husdReceipt("0x1", tHusd, tSender, tTreasury, 100)}
+	com := &fakeCommerce{}
+	setTopupEnv(t, tHusd, tTreasury, rpc.server(t).URL, com.server(t).URL)
+	app := mountBrand(t, "hanzo")
+
+	// The body tries to credit "victim/root"; the handler MUST ignore it and credit
+	// the validated caller (acme/alice).
+	code, _ := callH(t, app, http.MethodPost, "/v1/commerce/topup/wallet", alice,
+		`{"txHash":"`+tTxHash+`","userId":"victim/root"}`)
+	if code != http.StatusOK {
+		t.Fatalf("topup: want 200, got %d", code)
+	}
+	if com.payment["userId"] != "acme/alice" || com.gotOrg != "acme" {
+		t.Fatalf("IDOR: credit must land on acme/alice, got userId=%v org=%q", com.payment["userId"], com.gotOrg)
+	}
+}
+
+func TestTopup_NotMined_400(t *testing.T) {
+	rpc := &fakeRPC{result: nil} // JSON-RPC null ⇒ not found / not mined
+	com := &fakeCommerce{}
+	setTopupEnv(t, tHusd, tTreasury, rpc.server(t).URL, com.server(t).URL)
+	app := mountBrand(t, "hanzo")
+	code, _ := callH(t, app, http.MethodPost, "/v1/commerce/topup/wallet", alice, `{"txHash":"`+tTxHash+`"}`)
+	if code != http.StatusBadRequest {
+		t.Fatalf("not mined: want 400, got %d", code)
+	}
+	if com.payment != nil {
+		t.Fatalf("commerce must not be called for an unmined tx")
+	}
+}
+
+func TestTopup_FailedTx_400(t *testing.T) {
+	rpc := &fakeRPC{result: husdReceipt("0x0", tHusd, tSender, tTreasury, 500)} // reverted
+	com := &fakeCommerce{}
+	setTopupEnv(t, tHusd, tTreasury, rpc.server(t).URL, com.server(t).URL)
+	app := mountBrand(t, "hanzo")
+	code, _ := callH(t, app, http.MethodPost, "/v1/commerce/topup/wallet", alice, `{"txHash":"`+tTxHash+`"}`)
+	if code != http.StatusBadRequest {
+		t.Fatalf("failed tx: want 400, got %d", code)
+	}
+}
+
+func TestTopup_NoTransferToTreasury_400(t *testing.T) {
+	// A valid HUSD transfer, but to some OTHER address (not the treasury) → rejected.
+	rpc := &fakeRPC{result: husdReceipt("0x1", tHusd, tSender, tOther, 500)}
+	com := &fakeCommerce{}
+	setTopupEnv(t, tHusd, tTreasury, rpc.server(t).URL, com.server(t).URL)
+	app := mountBrand(t, "hanzo")
+	code, _ := callH(t, app, http.MethodPost, "/v1/commerce/topup/wallet", alice, `{"txHash":"`+tTxHash+`"}`)
+	if code != http.StatusBadRequest {
+		t.Fatalf("non-treasury transfer: want 400, got %d", code)
+	}
+}
+
+func TestTopup_SenderMismatch_400(t *testing.T) {
+	rpc := &fakeRPC{result: husdReceipt("0x1", tHusd, tSender, tTreasury, 500)}
+	com := &fakeCommerce{}
+	setTopupEnv(t, tHusd, tTreasury, rpc.server(t).URL, com.server(t).URL)
+	app := mountBrand(t, "hanzo")
+	// Claims a different fromAddress than the on-chain sender → rejected.
+	code, _ := callH(t, app, http.MethodPost, "/v1/commerce/topup/wallet", alice,
+		`{"txHash":"`+tTxHash+`","fromAddress":"`+tOther+`"}`)
+	if code != http.StatusBadRequest {
+		t.Fatalf("sender mismatch: want 400, got %d", code)
+	}
+}

clients/admin/admin.go

@@ -0,0 +1,445 @@
+// Package admin mounts the god-mode admin surface (/v1/admin/*) the Hanzo Admin Console
+// (admin.hanzo.ai, apps/operator) calls, per the api.ts contract.
+//
+// It is an AGGREGATOR, not a new store: identity (orgs/users/roles/applications/audit/me)
+// is read from IAM, the money panels (spend/tokens/credits) from commerce, and System
+// Health from o11y — every one a real upstream. The facade fans out over HTTP, shaping
+// the reads into the /v1 envelope { status, msg, data, data2 } the operator's transport
+// decodes.
+//
+// The subsystem is decomposed into a shared kernel (clients/admin/core) plus one package
+// per handler domain (audit/customer/revenue/finance). This file is the Mount: it builds
+// the ONE core.State from Deps, then registers each domain's routes alongside the
+// top-level reads (me/overview/orgs/users/usage/roles/applications/products/compute/o11y/
+// analytics/bases + the flags/waitlist control plane).
+//
+// SECURITY — TWO tiers off ONE identity predicate, both fail-closed. PLATFORM routes are
+// SuperAdmin ONLY (core.Guard). ORG-SCOPED routes (me/overview/orgs/users/usage/analytics/
+// bases) are core.GuardScoped: a SuperAdmin sees EVERY tenant; any other validated admin
+// caller is HARD-limited to their OWN org subtree by core.ResolveScope/ScopedOrgs.
+package admin
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/url"
+	"os"
+	"sort"
+	"strings"
+	"time"
+
+	"github.com/hanzoai/cloud"
+	"github.com/hanzoai/cloud/clients/admin/audit"
+	"github.com/hanzoai/cloud/clients/admin/commerce"
+	"github.com/hanzoai/cloud/clients/admin/core"
+	"github.com/hanzoai/cloud/clients/admin/customer"
+	"github.com/hanzoai/cloud/clients/admin/digitalocean"
+	"github.com/hanzoai/cloud/clients/admin/finance"
+	"github.com/hanzoai/cloud/clients/admin/health"
+	"github.com/hanzoai/cloud/clients/admin/iam"
+	"github.com/hanzoai/cloud/clients/admin/revenue"
+	"github.com/hanzoai/cloud/clients/commerceinproc"
+	"github.com/hanzoai/cloud/clients/principal"
+	"github.com/zap-proto/zip"
+)
+
+// Mount registers the /v1/admin/* surface on app. Every handler gates on c.IsAdmin()
+// first (via core.Guard/GuardScoped), then aggregates real upstream data.
+//
+// The state is built from Deps fields NOT on cloud.Base (deps.Audit, deps.IAMIssuer), so
+// it constructs the cloud.Service value directly (cloud.NewBase + &cloud.Service[core.State]{…})
+// rather than via cloud.Mount.
+func Mount(app *zip.App, deps cloud.Deps) error {
+	if app == nil {
+		return fmt.Errorf("admin.Mount: nil zip.App")
+	}
+	if deps.Logger == nil {
+		return fmt.Errorf("admin.Mount: nil deps.Logger")
+	}
+	b := cloud.NewBase(deps, "admin")
+	s := &cloud.Service[core.State]{
+		Base: b,
+		State: core.State{
+			IAM:        iam.New(iamBase(deps)),
+			Commerce:   commerce.New(commerceinproc.BaseURL(os.Getenv("CLOUD_COMMERCE_HTTP_URL")), os.Getenv("COMMERCE_SERVICE_TOKEN")),
+			Health:     health.New(o11yHealthURL()),
+			DO:         digitalocean.New(doTokenFromEnv()),
+			AdminOrg:   adminOrgOf(deps),
+			AuditStore: deps.Audit,
+		},
+	}
+
+	routes(app, s)
+
+	b.Log.Info("admin surface mounted",
+		"prefix", "/v1/admin",
+		"iam", s.State.IAM.Ready(),
+		"commerce", s.State.Commerce.Ready(),
+		"digitalocean", s.State.DO.Ready(),
+		"adminOrg", s.State.AdminOrg,
+	)
+	return nil
+}
+
+// routes registers the /v1/admin/* surface on app, threading the ONE service value
+// through the two-tier gate: org-scoped panels behind core.GuardScoped, the platform
+// control plane behind core.Guard. Each carved-out domain (audit/customer/revenue/finance)
+// owns its own route registration.
+func routes(app *zip.App, s *cloud.Service[core.State]) {
+	// Org-scoped panels — GuardScoped. Cross-tenant reads are impossible for a non-super
+	// caller.
+	app.Get("/v1/admin/me", core.GuardScoped(s, me))
+	app.Get("/v1/admin/overview", core.GuardScoped(s, overview))
+	app.Get("/v1/admin/orgs", core.GuardScoped(s, orgs))
+	app.Get("/v1/admin/users", core.GuardScoped(s, users))
+	app.Get("/v1/admin/usage", core.GuardScoped(s, usage))
+	// Platform reads — SuperAdmin only (cross-tenant by nature).
+	app.Get("/v1/admin/roles", core.Guard(s, roles))
+	app.Get("/v1/admin/applications", core.Guard(s, applications))
+	app.Get("/v1/admin/products", core.Guard(s, products))
+	app.Get("/v1/admin/compute", core.Guard(s, compute))
+	app.Get("/v1/admin/o11y", core.Guard(s, o11y))
+	app.Post("/v1/admin/sync", core.Guard(s, syncNow))
+
+	// Product analytics — org-scoped (SuperAdmin: all-orgs; org admin: their own org).
+	app.Get("/v1/admin/analytics", core.GuardScoped(s, analytics))
+	// Bases — the tenant Base-instance panel, org-scoped (bases.go).
+	app.Get("/v1/admin/bases", core.GuardScoped(s, bases))
+
+	// ── Platform control plane — SuperAdmin ONLY (launch/release/flags + access). ──
+	app.Get("/v1/admin/flags", core.Guard(s, flags))
+	app.Get("/v1/admin/waitlist", core.Guard(s, waitlist))
+	app.Post("/v1/admin/waitlist/boost", core.Guard(s, waitlistBoost))
+
+	// ── Carved-out domains own their routes (audit/customer/revenue/finance). ──
+	audit.Routes(app, s)
+	customer.Routes(app, s)
+	revenue.Routes(app, s)
+	finance.Routes(app, s)
+}
+
+// ── /v1/admin/me — operator identity (AdminMe) ───────────────────────────────
+
+// me answers with the validated operator identity. The gate already proved this is an
+// admin, so the fields come from the sanitized identity headers — authoritative and never
+// client-forgeable.
+func me(s *cloud.Service[core.State], c *zip.Ctx) error {
+	sc := core.ResolveScope(s, c)
+	owner, _ := principal.Org(c)
+	if owner == "" && sc.Super {
+		owner = s.State.AdminOrg
+	}
+	name := strings.TrimSpace(c.User())
+	return core.OK(c, adminMe{
+		Owner:        owner,
+		Name:         name,
+		Email:        strings.TrimSpace(c.UserEmail()),
+		DisplayName:  name,
+		IsSuperAdmin: sc.Super,
+	})
+}
+
+// ── /v1/admin/orgs — tenant directory (OrgRow[]) ─────────────────────────────
+
+func orgs(s *cloud.Service[core.State], c *zip.Ctx) error {
+	ctx := c.Context()
+	cr := core.CallerCreds(c)
+	orgs, err := core.ScopedOrgs(s, ctx, c, cr)
+	if err != nil {
+		return core.Fail(c, err.Error())
+	}
+	rows := make([]orgRow, 0, len(orgs))
+	for _, o := range orgs {
+		users := orgUserCount(s, ctx, cr, o.Name)
+		// orgs is a per-ROW panel (OrgRow[] via OKList; it carries NO sources[] channel):
+		// a failed read degrades THAT org's row to an honest zero, never a fleet total that
+		// falsely reads healthy. The aggregate-freshness signal lives on /overview.
+		spend, credits, _ := core.OrgMoney(s, ctx, o.Name)
+		rows = append(rows, orgRow{
+			Org:          o.Name,
+			Display:      core.Display(o.DisplayName, o.Name),
+			Users:        users,
+			Products:     0, // workload registry feed pending (platform apps table)
+			SpendCents:   spend,
+			CreditsCents: credits,
+			Tokens:       0, // fleet token counters pending (insights/datastore)
+			Created:      o.CreatedTime,
+		})
+	}
+	sort.Slice(rows, func(i, j int) bool { return rows[i].Org < rows[j].Org })
+	return core.OKList(c, rows, len(rows))
+}
+
+// ── /v1/admin/users — cross-org directory (OperatorUser[]) ───────────────────
+
+func users(s *cloud.Service[core.State], c *zip.Ctx) error {
+	ctx := c.Context()
+	cr := core.CallerCreds(c)
+	sc := core.ResolveScope(s, c)
+	q := url.Values{}
+	if !sc.Super {
+		// A scoped caller lists ONLY their own org's users — the client ?org= is ignored,
+		// the owner hard-pinned to the sanitized org subtree.
+		if len(sc.Orgs) > 0 {
+			q.Set("owner", sc.Orgs[0])
+		}
+	} else if owner := strings.TrimSpace(c.Query("org")); owner != "" {
+		q.Set("owner", owner)
+	}
+	if p := strings.TrimSpace(c.Query("p")); p != "" {
+		q.Set("p", p)
+	}
+	if ps := strings.TrimSpace(c.Query("pageSize")); ps != "" {
+		q.Set("pageSize", ps)
+	}
+	if term := strings.TrimSpace(c.Query("q")); term != "" {
+		// IAM's list uses field/value contains-matching for the free-text filter.
+		q.Set("field", "name")
+		q.Set("value", term)
+	}
+	res, err := s.State.IAM.Users(ctx, cr, q)
+	if err != nil {
+		return core.Fail(c, err.Error())
+	}
+	var raw []iam.User
+	if len(res.Rows) > 0 {
+		if err := json.Unmarshal(res.Rows, &raw); err != nil {
+			return core.Fail(c, "users decode: "+err.Error())
+		}
+	}
+	rows := make([]operatorUser, 0, len(raw))
+	for _, u := range raw {
+		rows = append(rows, operatorUser{
+			Owner:        u.Owner,
+			Name:         u.Name,
+			Email:        u.Email,
+			DisplayName:  u.DisplayName,
+			IsAdmin:      u.IsAdmin,
+			IsSuperAdmin: u.Owner == s.State.AdminOrg,
+			Tag:          u.Tag,
+			Created:      u.CreatedTime,
+			LastSignin:   u.LastSigninTime,
+			Forbidden:    u.IsForbidden,
+		})
+	}
+	total := res.Total
+	if total < len(rows) {
+		total = len(rows)
+	}
+	return core.OKList(c, rows, total)
+}
+
+// ── /v1/admin/roles and /applications — verbatim IAM passthrough ─────────────
+
+func roles(s *cloud.Service[core.State], c *zip.Ctx) error {
+	return iamPassthrough(s, c, "/v1/iam/get-roles")
+}
+
+func applications(s *cloud.Service[core.State], c *zip.Ctx) error {
+	return iamPassthrough(s, c, "/v1/iam/get-applications")
+}
+
+// iamPassthrough forwards a paginated IAM read verbatim (the operator decodes Role /
+// Application as the raw IAM wire shape). `owner` defaults to the admin org, which owns
+// the platform applications.
+func iamPassthrough(s *cloud.Service[core.State], c *zip.Ctx, path string) error {
+	q := url.Values{}
+	owner := strings.TrimSpace(c.Query("owner"))
+	if owner == "" {
+		owner = s.State.AdminOrg
+	}
+	q.Set("owner", owner)
+	if p := strings.TrimSpace(c.Query("p")); p != "" {
+		q.Set("p", p)
+	}
+	if ps := strings.TrimSpace(c.Query("pageSize")); ps != "" {
+		q.Set("pageSize", ps)
+	}
+	res, err := s.State.IAM.List(c.Context(), core.CallerCreds(c), path, q)
+	if err != nil {
+		return core.Fail(c, err.Error())
+	}
+	return core.OKRaw(c, res.Rows, res.Total)
+}
+
+// ── /v1/admin/usage — fleet usage roll-up (UsageData) ────────────────────────
+
+// usage returns the real fleet money totals from commerce. The daily series and the
+// per-product breakdown are NOT derivable from the commerce billing API (they live in
+// insights/datastore); admin returns the honest empty series/byProduct rather than
+// fabricating a trend.
+func usage(s *cloud.Service[core.State], c *zip.Ctx) error {
+	ctx := c.Context()
+	cr := core.CallerCreds(c)
+	sc := core.ResolveScope(s, c)
+	org := strings.TrimSpace(c.Query("org"))
+	if !sc.Super {
+		// A scoped caller reads ONLY their own org's usage — the client ?org= is ignored,
+		// the org hard-pinned to the sanitized subtree.
+		org = ""
+		if len(sc.Orgs) > 0 {
+			org = sc.Orgs[0]
+		}
+	}
+
+	var spend int64
+	switch {
+	case org != "":
+		if sp, err := s.State.Commerce.Spend(ctx, org); err == nil {
+			spend = int64(sp.Consumed)
+		}
+	case sc.Super:
+		// Fleet: sum month-to-date consumption across every org.
+		orgs, err := core.ListOrgs(s, ctx, cr)
+		if err == nil {
+			for _, o := range orgs {
+				if sp, e := s.State.Commerce.Spend(ctx, o.Name); e == nil {
+					spend += int64(sp.Consumed)
+				}
+			}
+		}
+	}
+
+	return core.OK(c, usageData{
+		Totals:    usageTotals{SpendCents: spend, Tokens: 0, Requests: 0},
+		Series:    []usagePoint{},
+		ByProduct: []usageByProduct{},
+	})
+}
+
+// ── /v1/admin/products — workload registry (ProductRow[]) ────────────────────
+
+// products is the workload/drift registry. That inventory is the platform.hanzo.ai apps
+// table / operator reconcile state, NOT an in-binary source. admin exposes the gated
+// endpoint and returns the real empty registry until that feed is wired.
+func products(s *cloud.Service[core.State], c *zip.Ctx) error {
+	return core.OKList(c, []productRow{}, 0)
+}
+
+// ── /v1/admin/overview — Platform Overview tiles (OverviewData) ───────────────
+
+func overview(s *cloud.Service[core.State], c *zip.Ctx) error {
+	ctx := c.Context()
+	cr := core.CallerCreds(c)
+	now := time.Now().UTC().Format(time.RFC3339)
+
+	var sources []core.SourceStatus
+	orgCount, userCount, spend, credits := 0, 0, int64(0), int64(0)
+
+	orgs, orgErr := core.ScopedOrgs(s, ctx, c, cr)
+	sources = append(sources, core.SrcOf("iam", orgErr, len(orgs), now))
+	commercePartial := false
+	if orgErr == nil {
+		orgCount = len(orgs)
+		for _, o := range orgs {
+			userCount += orgUserCount(s, ctx, cr, o.Name)
+			sp, cr2, ok := core.OrgMoney(s, ctx, o.Name)
+			spend += sp
+			credits += cr2
+			if !ok {
+				// This org's money did not read — the fleet spend/credits totals are now
+				// an UNDERCOUNT, so the commerce source must report degraded, not healthy.
+				commercePartial = true
+			}
+		}
+	}
+
+	// Commerce freshness derives from the SAME per-org reads the totals fold — NOT a
+	// single probe org (which could read healthy while commerce was down for every other
+	// org, masking an undercount). Not-configured when unwired; degraded/partial (the ONE
+	// core.ErrPartialRevenue sentinel revenue/finance use) when ANY per-org read failed.
+	var commerceErr error
+	commerceRows := 0
+	switch {
+	case !s.State.Commerce.Ready():
+		commerceErr = fmt.Errorf("commerce endpoint not configured")
+	case commercePartial:
+		commerceErr = core.ErrPartialRevenue
+		commerceRows = orgCount
+	default:
+		commerceRows = orgCount
+	}
+	sources = append(sources, core.SrcOf("commerce", commerceErr, commerceRows, now))
+
+	// o11y System Health.
+	o11yRows := 0
+	oOK, oErr := s.State.Health.Up(ctx)
+	if oOK {
+		o11yRows = 1
+	}
+	sources = append(sources, core.SrcOf("o11y", oErr, o11yRows, now))
+
+	return core.OK(c, overviewData{
+		Orgs:           orgCount,
+		Users:          userCount,
+		Products:       0, // workload registry feed pending (platform apps table)
+		ActiveProducts: 0,
+		Drift:          0,
+		SpendCents30d:  spend,
+		Tokens30d:      0, // fleet token counters pending (insights/datastore)
+		CreditsCents:   credits,
+		LastSync:       now,
+		Sources:        sources,
+	})
+}
+
+// ── /v1/admin/sync — refresh trigger ─────────────────────────────────────────
+
+// syncNow answers the operator's "Sync now" button. admin aggregates LIVE on every read,
+// so there is no batch job to kick — the button simply re-reads. We acknowledge honestly
+// with { started: true }.
+func syncNow(s *cloud.Service[core.State], c *zip.Ctx) error {
+	return core.OK(c, map[string]bool{"started": true})
+}
+
+// ── aggregation helpers ──────────────────────────────────────────────────────
+
+// orgUserCount returns the member count for one org from the IAM list total (data2).
+// Best-effort: an error yields 0 rather than failing the whole row.
+func orgUserCount(s *cloud.Service[core.State], ctx context.Context, cr iam.Creds, org string) int {
+	q := url.Values{}
+	q.Set("owner", org)
+	q.Set("p", "1")
+	q.Set("pageSize", "1")
+	res, err := s.State.IAM.Users(ctx, cr, q)
+	if err != nil {
+		return 0
+	}
+	return res.Total
+}
+
+// ── config resolution ────────────────────────────────────────────────────────
+
+// iamBase resolves the IAM management HTTP base. CLOUD_IAM_HTTP_URL wins (the in-cluster
+// Service); otherwise the public issuer (deps.IAMIssuer) which also serves /v1/iam/*.
+func iamBase(deps cloud.Deps) string {
+	if v := strings.TrimSpace(os.Getenv("CLOUD_IAM_HTTP_URL")); v != "" {
+		return v
+	}
+	return strings.TrimSpace(deps.IAMIssuer)
+}
+
+// o11yHealthURL resolves the o11y health probe URL for the System Health source.
+// CLOUD_O11Y_HEALTH_URL wins; else the in-cluster o11y Service default.
+func o11yHealthURL() string {
+	if v := strings.TrimSpace(os.Getenv("CLOUD_O11Y_HEALTH_URL")); v != "" {
+		return v
+	}
+	return "http://o11y.hanzo.svc.cluster.local:80/v1/o11y/health"
+}
+
+// adminOrgOf resolves the admin org slug (IAM's IsSuperAdmin owner). IAM_ADMIN_ORG mirrors
+// config.go's default; "admin" is the fleet-wide default.
+func adminOrgOf(_ cloud.Deps) string {
+	if v := strings.TrimSpace(os.Getenv("IAM_ADMIN_ORG")); v != "" {
+		return v
+	}
+	return "admin"
+}
+
+// doTokenFromEnv reads the DigitalOcean token from the environment. Sourced from a
+// KMSSecret on the cloud deployment (DO_API_TOKEN) — never hard-coded.
+func doTokenFromEnv() string {
+	return strings.TrimSpace(os.Getenv("DO_API_TOKEN"))
+}

clients/admin/admin_test.go

@@ -0,0 +1,670 @@
+package admin
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/hanzoai/cloud"
+	"github.com/hanzoai/cloud/clients/admin/commerce"
+	"github.com/hanzoai/cloud/clients/admin/core"
+	"github.com/hanzoai/cloud/clients/admin/digitalocean"
+	"github.com/hanzoai/cloud/clients/admin/health"
+	"github.com/hanzoai/cloud/clients/admin/iam"
+	luxlog "github.com/luxfi/log"
+	fiber "github.com/zap-proto/fiber/v3"
+	"github.com/zap-proto/zip"
+)
+
+// mount builds a zip app with admin mounted against the given upstream bases,
+// and returns a `do` helper that issues test requests through the whole app.
+func mount(t *testing.T, iamURL, commerceURL, healthURL string) func(method, path string, hdr map[string]string) (*http.Response, []byte) {
+	do, _, _ := mountSvc(t, iamURL, commerceURL, healthURL)
+	return do
+}
+
+// mountSvc is mount but also returns the underlying cloud.Service[state] (so finance tests can swap
+// in a fake DigitalOcean client, and the cockpit tests can attach an audit store)
+// AND the raw fiber app (so tests that need a request BODY can drive it directly —
+// the returned `do` sends a nil body). The handlers read s.* live at request time,
+// so an override before issuing a request takes effect.
+func mountSvc(t *testing.T, iamURL, commerceURL, healthURL string) (func(method, path string, hdr map[string]string) (*http.Response, []byte), *cloud.Service[core.State], *fiber.App) {
+	t.Helper()
+	app := zip.New(zip.Config{Logger: luxlog.New("test")})
+	s := &cloud.Service[core.State]{State: core.State{
+		IAM:      iam.New(iamURL),
+		Commerce: commerce.New(commerceURL, "test-token"),
+		Health:   health.New(healthURL),
+		DO:       digitalocean.New(""), // no token → honest not-configured unless a test overrides s.State.DO
+		AdminOrg: "admin",
+	}}
+	// Mirror the REAL Mount EXACTLY by registering the same routes() the subsystem uses
+	// (org-scoped panels behind GuardScoped, the platform control plane behind Guard,
+	// each domain owning its own routes), so the harness stays authoritative for the
+	// two-tier gate + every surface.
+	routes(app, s)
+	fa := app.Fiber()
+
+	return func(method, path string, hdr map[string]string) (*http.Response, []byte) {
+		t.Helper()
+		req := httptest.NewRequest(method, path, nil)
+		for k, v := range hdr {
+			req.Header.Set(k, v)
+		}
+		resp, err := fa.Test(req, fiber.TestConfig{Timeout: 30 * time.Second})
+		if err != nil {
+			t.Fatalf("%s %s: %v", method, path, err)
+		}
+		b, _ := io.ReadAll(resp.Body)
+		return resp, b
+	}, s, fa
+}
+
+type adminRoute struct{ method, path string }
+
+// scopedAdminRoutes are the ORG-SCOPED panels (guardScoped): a SuperAdmin OR a validated
+// org admin is admitted, and the handler scopes the data. A caller with NO validated
+// principal (anonymous, or an org header but no X-User-Id) is still refused.
+var scopedAdminRoutes = []adminRoute{
+	{"GET", "/v1/admin/me"},
+	{"GET", "/v1/admin/overview"},
+	{"GET", "/v1/admin/orgs"},
+	{"GET", "/v1/admin/users"},
+	{"GET", "/v1/admin/usage"},
+	{"GET", "/v1/admin/analytics"},
+	{"GET", "/v1/admin/bases"},
+}
+
+// platformAdminRoutes are SuperAdmin ONLY (s.guard) — the cross-tenant platform reads +
+// the launch/release/flags/access control plane. A non-super caller is ALWAYS 403.
+var platformAdminRoutes = []adminRoute{
+	{"GET", "/v1/admin/roles"},
+	{"GET", "/v1/admin/applications"},
+	{"GET", "/v1/admin/audit"},
+	{"GET", "/v1/admin/audit/verify"},
+	{"GET", "/v1/admin/products"},
+	{"GET", "/v1/admin/finance"},
+	{"POST", "/v1/admin/sync"},
+	{"GET", "/v1/admin/customers"},
+	{"GET", "/v1/admin/customers/acme"},
+	{"POST", "/v1/admin/customers/acme/credit"},
+	{"POST", "/v1/admin/customers/acme/suspend"},
+	{"POST", "/v1/admin/customers/acme/reactivate"},
+	{"GET", "/v1/admin/revenue"},
+	{"GET", "/v1/admin/flags"},
+	{"GET", "/v1/admin/waitlist"},
+	{"POST", "/v1/admin/waitlist/boost"},
+}
+
+// adminRoutes is the full surface (both tiers) — the fail-closed gate test denies an
+// unauthenticated caller on EVERY one.
+var adminRoutes = append(append([]adminRoute{}, scopedAdminRoutes...), platformAdminRoutes...)
+
+// TestGate_DeniesEveryRoute proves the non-negotiable: EVERY /v1/admin/* route is
+// SuperAdmin only, fail-closed. An anonymous caller and a tenant-admin (whose
+// identity carries an org but NOT the sanitizer-minted X-User-IsAdmin) are BOTH
+// denied 403 on every route — no upstream is even reached. admin mirrors the
+// gateway's admin-guard: SanitizeIdentity sets X-User-IsAdmin only for a
+// validated principal whose owner == AdminOrg, so a forged header never survives
+// ingress and the c.IsAdmin() read here is authoritative.
+func TestGate_DeniesEveryRoute(t *testing.T) {
+	// Upstreams point nowhere reachable; the gate must reject BEFORE any call.
+	do := mount(t, "http://127.0.0.1:0", "http://127.0.0.1:0", "http://127.0.0.1:0")
+
+	// NO validated principal ⇒ denied on EVERY route (platform + scoped). guardScoped
+	// requires a sanitized X-User-Id, which an anonymous caller lacks — and a client
+	// that merely forges X-Org-Id (the documented Phase-1 residual) still has no
+	// X-User-Id, so it is refused here and can never reach a scoped read.
+	noPrincipal := []struct {
+		name string
+		hdr  map[string]string
+	}{
+		{"anonymous", nil},
+		{"forged X-Org-Id, no validated user", map[string]string{"X-Org-Id": "victim"}},
+	}
+	for _, tc := range noPrincipal {
+		for _, r := range adminRoutes {
+			resp, body := do(r.method, r.path, tc.hdr)
+			if resp.StatusCode != http.StatusForbidden {
+				t.Errorf("%s %s [%s]: got %d, want 403 (body=%s)", r.method, r.path, tc.name, resp.StatusCode, body)
+			}
+		}
+	}
+
+	// A VALIDATED org admin (X-User-Id + pinned X-Org-Id + the sanitizer-minted
+	// X-User-IsOrgAdmin, but NO GLOBAL X-User-IsAdmin) is denied on every PLATFORM route
+	// (super-only). The org-scoped routes admit them but hard-scope the data — proven in
+	// scope_test.go. (A validated NON-admin member, lacking the org-admin bit, is refused
+	// on the scoped panels too — TestScope_MemberWithoutOrgAdminDenied.)
+	orgAdmin := map[string]string{"X-Org-Id": "acme", "X-User-Id": "acme/bob", "X-User-Email": "bob@acme.test", "X-User-IsOrgAdmin": "true"}
+	for _, r := range platformAdminRoutes {
+		resp, body := do(r.method, r.path, orgAdmin)
+		if resp.StatusCode != http.StatusForbidden {
+			t.Errorf("%s %s [org-admin on platform route]: got %d, want 403 (body=%s)", r.method, r.path, resp.StatusCode, body)
+		}
+	}
+}
+
+// TestGate_AllowsSuperAdmin proves the flip side: a validated SuperAdmin
+// (X-User-IsAdmin=true, minted only for owner==AdminOrg) is admitted — the gate
+// is not vacuously closed. Reaches /v1/admin/me, which needs no upstream.
+func TestGate_AllowsSuperAdmin(t *testing.T) {
+	do := mount(t, "http://127.0.0.1:0", "http://127.0.0.1:0", "http://127.0.0.1:0")
+	admin := map[string]string{"X-User-IsAdmin": "true", "X-Org-Id": "admin", "X-User-Id": "admin/z", "X-User-Email": "z@hanzo.ai"}
+	resp, body := do("GET", "/v1/admin/me", admin)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("SuperAdmin GET /v1/admin/me: got %d, want 200 (body=%s)", resp.StatusCode, body)
+	}
+	var env struct {
+		Status string  `json:"status"`
+		Data   adminMe `json:"data"`
+	}
+	if err := json.Unmarshal(body, &env); err != nil {
+		t.Fatalf("decode me envelope: %v", err)
+	}
+	if env.Status != "ok" {
+		t.Fatalf("me status = %q, want ok", env.Status)
+	}
+	if env.Data.Owner != "admin" || env.Data.Email != "z@hanzo.ai" || !env.Data.IsSuperAdmin {
+		t.Errorf("me identity wrong: %+v", env.Data)
+	}
+	// SuperAdmin canonicalization: the isSuperAdmin key MUST be present and true
+	// for a platform SuperAdmin.
+	if !env.Data.IsSuperAdmin {
+		t.Errorf("me: isSuperAdmin must be true for a SuperAdmin: %+v", env.Data)
+	}
+}
+
+// fakeIAM stands in for the IAM management surface. It records whether the
+// caller's credential was replayed and returns /v1 envelopes.
+type fakeIAM struct {
+	server  *httptest.Server
+	gotAuth string
+	gotCook string
+}
+
+func newFakeIAM() *fakeIAM {
+	f := &fakeIAM{}
+	f.server = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		f.gotAuth = r.Header.Get("Authorization")
+		f.gotCook = r.Header.Get("Cookie")
+		w.Header().Set("Content-Type", "application/json")
+		switch {
+		case strings.HasSuffix(r.URL.Path, "/get-organizations"):
+			io.WriteString(w, `{"status":"ok","msg":"","data":[
+				{"owner":"admin","name":"hanzo","displayName":"Hanzo","createdTime":"2020-01-01T00:00:00Z"},
+				{"owner":"admin","name":"acme","displayName":"Acme Inc","createdTime":"2021-02-02T00:00:00Z"}
+			],"data2":2}`)
+		case strings.HasSuffix(r.URL.Path, "/get-users"):
+			// A single-page count probe (pageSize=1) still reports data2 total.
+			io.WriteString(w, `{"status":"ok","msg":"","data":[
+				{"owner":"hanzo","name":"alice","email":"alice@hanzo.ai","displayName":"Alice","tag":"staff","createdTime":"2020-03-01T00:00:00Z","lastSigninTime":"2026-06-01T00:00:00Z","isAdmin":true,"isForbidden":false}
+			],"data2":7}`)
+		case strings.HasSuffix(r.URL.Path, "/get-roles"):
+			io.WriteString(w, `{"status":"ok","msg":"","data":[{"owner":"admin","name":"ops","displayName":"Ops"}],"data2":1}`)
+		case strings.HasSuffix(r.URL.Path, "/get-applications"):
+			io.WriteString(w, `{"status":"ok","msg":"","data":[{"owner":"admin","name":"hanzo-cloud","clientId":"cid"}],"data2":1}`)
+		case strings.HasSuffix(r.URL.Path, "/get-records"):
+			io.WriteString(w, `{"status":"ok","msg":"","data":[{"createdTime":"2026-06-29T00:00:00Z","organization":"hanzo","user":"alice","clientIp":"1.2.3.4","method":"POST","action":"login","requestUri":"/v1/iam/login"}],"data2":1}`)
+		default:
+			w.WriteHeader(404)
+			io.WriteString(w, `{"status":"error","msg":"not found"}`)
+		}
+	}))
+	return f
+}
+
+// fakeCommerce mimics the LIVE commerce billing contract (commerce >=1.46.8, the
+// 2026-07 per-org durability rework): the per-org wallet is resolved from the
+// TRUSTED X-Org-Id header (set only with the service-token bearer) and keyed under
+// the BARE org slug as the `user` subject. A wrong header (X-IAM-Org-Id) or a wrong
+// subject ("org/org") resolves to an EMPTY wallet — so this fake is a regression
+// guard for the reconciliation bug that made every admin money panel read $0 while
+// real balances existed (lux $10,000, maxpower $20,498). Verified against live
+// commerce /v1/billing/{balance,usage-rollup}.
+type fakeCommerce struct {
+	server          *httptest.Server
+	balances        map[string]int64 // org slug -> availableCents (credits)
+	spend           map[string]int64 // org slug -> consumedCents (month-to-date)
+	sawIAMOrgHeader bool             // true if the stale X-IAM-Org-Id header was ever sent
+}
+
+func newFakeCommerce() *fakeCommerce {
+	f := &fakeCommerce{
+		balances: map[string]int64{"acme": 5000, "hanzo": 5000},
+		spend:    map[string]int64{"acme": 1500, "hanzo": 1500},
+	}
+	f.server = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		if r.Header.Get("X-IAM-Org-Id") != "" {
+			f.sawIAMOrgHeader = true
+		}
+		// Live commerce trusts ONLY X-Org-Id (with the service-token bearer) for the
+		// org namespace and keys the wallet under the bare org slug. Anything else
+		// (missing X-Org-Id, or user != org) resolves to an empty wallet.
+		org := r.Header.Get("X-Org-Id")
+		user := r.URL.Query().Get("user")
+		bal, spend := int64(0), int64(0)
+		if org != "" && user == org {
+			bal, spend = f.balances[org], f.spend[org]
+		}
+		switch {
+		case strings.HasSuffix(r.URL.Path, "/usage-rollup"):
+			fmt.Fprintf(w, `{"consumedCents":%d,"overageCents":0,"balance":{"balanceCents":%d,"availableCents":%d}}`, spend, bal, bal)
+		case strings.HasSuffix(r.URL.Path, "/balance"):
+			fmt.Fprintf(w, `{"user":%q,"currency":"usd","balance":%d,"holds":0,"available":%d}`, user, bal, bal)
+		case strings.HasSuffix(r.URL.Path, "/subscriptions"):
+			io.WriteString(w, `{"subscriptions":[]}`)
+		default:
+			w.WriteHeader(404)
+		}
+	}))
+	return f
+}
+
+// TestCommerce_ReconcilesWithXOrgIdBareSlug pins the exact live-commerce contract
+// the admin money aggregation depends on: the org selector is the TRUSTED X-Org-Id
+// header and the wallet subject is the BARE org slug (user=<org>) — NOT
+// X-IAM-Org-Id and NOT "org/org". This is the regression guard for the $0-fleet-
+// revenue bug (commerce.go had X-IAM-Org-Id; admin.go orgSubject had "org/org", so
+// every real balance read $0). /v1/admin/orgs must surface acme's real $50.00.
+func TestCommerce_ReconcilesWithXOrgIdBareSlug(t *testing.T) {
+	// The billing subject is the bare org slug for BOTH the X-Org-Id header and the
+	// `user` param — commerce.Client bakes that in (one subject, no "org/org"). This
+	// test proves it end to end: /v1/admin/orgs must surface acme's real $50.00.
+	iam := newFakeIAM()
+	defer iam.server.Close()
+	commerce := newFakeCommerce()
+	defer commerce.server.Close()
+
+	do := mount(t, iam.server.URL, commerce.server.URL, "")
+	admin := map[string]string{"X-User-IsAdmin": "true", "X-Org-Id": "admin"}
+	resp, body := do("GET", "/v1/admin/orgs", admin)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("orgs: got %d (body=%s)", resp.StatusCode, body)
+	}
+	var env struct {
+		Data []orgRow `json:"data"`
+	}
+	if err := json.Unmarshal(body, &env); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	// acme (sorted first) must show its REAL money, proving the header + subject key.
+	var acme *orgRow
+	for i := range env.Data {
+		if env.Data[i].Org == "acme" {
+			acme = &env.Data[i]
+		}
+	}
+	if acme == nil {
+		t.Fatalf("acme org missing from %+v", env.Data)
+	}
+	if acme.CreditsCents != 5000 || acme.SpendCents != 1500 {
+		t.Errorf("acme money = credits %d / spend %d, want 5000/1500 — the money did NOT reconcile (stale X-IAM-Org-Id or org/org subject reads $0)", acme.CreditsCents, acme.SpendCents)
+	}
+	// The stale header must NEVER be sent.
+	if commerce.sawIAMOrgHeader {
+		t.Error("admin sent the stale X-IAM-Org-Id header — commerce reads X-Org-Id only")
+	}
+}
+
+// TestOrgs_RealAggregation drives /v1/admin/orgs against fake IAM + commerce and
+// verifies the envelope, the field mapping, the per-org user count (from IAM
+// data2), the money (from commerce), and that the caller's credential is
+// replayed to IAM (admin never forges a service credential for the fan-out).
+func TestOrgs_RealAggregation(t *testing.T) {
+	iam := newFakeIAM()
+	defer iam.server.Close()
+	commerce := newFakeCommerce()
+	defer commerce.server.Close()
+
+	do := mount(t, iam.server.URL, commerce.server.URL, "")
+	admin := map[string]string{
+		"X-User-IsAdmin": "true", "X-Org-Id": "admin",
+		"Authorization": "Bearer operator-jwt", "Cookie": "iam_access_token=operator-jwt",
+	}
+	resp, body := do("GET", "/v1/admin/orgs", admin)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("orgs: got %d, want 200 (body=%s)", resp.StatusCode, body)
+	}
+	var env struct {
+		Status string   `json:"status"`
+		Data   []orgRow `json:"data"`
+		Data2  int      `json:"data2"`
+	}
+	if err := json.Unmarshal(body, &env); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if env.Status != "ok" || env.Data2 != 2 || len(env.Data) != 2 {
+		t.Fatalf("orgs envelope wrong: status=%q data2=%d rows=%d", env.Status, env.Data2, len(env.Data))
+	}
+	// Rows are sorted by org name: acme, hanzo.
+	acme := env.Data[0]
+	if acme.Org != "acme" || acme.Display != "Acme Inc" {
+		t.Errorf("org row[0] = %+v, want acme/Acme Inc", acme)
+	}
+	if acme.Users != 7 {
+		t.Errorf("org acme users = %d, want 7 (IAM data2)", acme.Users)
+	}
+	if acme.SpendCents != 1500 || acme.CreditsCents != 5000 {
+		t.Errorf("org acme money = spend %d credits %d, want 1500/5000", acme.SpendCents, acme.CreditsCents)
+	}
+	// The operator's own credential MUST have been replayed to IAM.
+	if iam.gotAuth != "Bearer operator-jwt" {
+		t.Errorf("IAM did not receive the caller's Authorization: got %q", iam.gotAuth)
+	}
+	if !strings.Contains(iam.gotCook, "operator-jwt") {
+		t.Errorf("IAM did not receive the caller's Cookie: got %q", iam.gotCook)
+	}
+}
+
+// TestUsers_MapsIAMToOperatorUser verifies the cross-org directory mapping,
+// including the derived isSuperAdmin (owner == adminOrg) and the data2 total.
+func TestUsers_MapsIAMToOperatorUser(t *testing.T) {
+	iam := newFakeIAM()
+	defer iam.server.Close()
+	do := mount(t, iam.server.URL, "", "")
+	admin := map[string]string{"X-User-IsAdmin": "true", "X-Org-Id": "admin"}
+
+	resp, body := do("GET", "/v1/admin/users?org=hanzo", admin)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("users: got %d (body=%s)", resp.StatusCode, body)
+	}
+	var env struct {
+		Data  []operatorUser `json:"data"`
+		Data2 int            `json:"data2"`
+	}
+	if err := json.Unmarshal(body, &env); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if env.Data2 != 7 || len(env.Data) != 1 {
+		t.Fatalf("users total=%d rows=%d, want 7/1", env.Data2, len(env.Data))
+	}
+	u := env.Data[0]
+	if u.Name != "alice" || u.Email != "alice@hanzo.ai" || !u.IsAdmin || u.LastSignin == "" {
+		t.Errorf("user mapping wrong: %+v", u)
+	}
+	// owner "hanzo" != adminOrg "admin" → not a SuperAdmin.
+	if u.IsSuperAdmin {
+		t.Errorf("user owner=hanzo must not be flagged SuperAdmin")
+	}
+}
+
+// TestRolesAndApplications_PassthroughShape verifies the verbatim IAM passthrough
+// keeps the exact wire fields (clientId on Application, etc.) the operator decodes.
+func TestRolesAndApplications_PassthroughShape(t *testing.T) {
+	iam := newFakeIAM()
+	defer iam.server.Close()
+	do := mount(t, iam.server.URL, "", "")
+	admin := map[string]string{"X-User-IsAdmin": "true", "X-Org-Id": "admin"}
+
+	_, appsBody := do("GET", "/v1/admin/applications", admin)
+	var appsEnv struct {
+		Data []struct {
+			Name     string `json:"name"`
+			ClientId string `json:"clientId"`
+		} `json:"data"`
+		Data2 int `json:"data2"`
+	}
+	if err := json.Unmarshal(appsBody, &appsEnv); err != nil {
+		t.Fatalf("apps decode: %v", err)
+	}
+	if len(appsEnv.Data) != 1 || appsEnv.Data[0].ClientId != "cid" {
+		t.Errorf("applications passthrough lost clientId: %+v", appsEnv.Data)
+	}
+
+	_, rolesBody := do("GET", "/v1/admin/roles", admin)
+	if !strings.Contains(string(rolesBody), `"ops"`) {
+		t.Errorf("roles passthrough missing role name: %s", rolesBody)
+	}
+}
+
+// TestAudit_MapsRecords verifies the audit directory returns the IAM Record wire
+// shape the operator's AuditRow decodes.
+func TestAudit_MapsRecords(t *testing.T) {
+	iam := newFakeIAM()
+	defer iam.server.Close()
+	do := mount(t, iam.server.URL, "", "")
+	admin := map[string]string{"X-User-IsAdmin": "true", "X-Org-Id": "admin"}
+
+	resp, body := do("GET", "/v1/admin/audit", admin)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("audit: got %d (body=%s)", resp.StatusCode, body)
+	}
+	var env struct {
+		Data []struct {
+			CreatedTime  string `json:"createdTime"`
+			Organization string `json:"organization"`
+			RequestUri   string `json:"requestUri"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(body, &env); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if len(env.Data) != 1 || env.Data[0].Organization != "hanzo" || env.Data[0].RequestUri != "/v1/iam/login" {
+		t.Errorf("audit record shape wrong: %+v", env.Data)
+	}
+}
+
+// TestOverview_RealTilesAndSources verifies the Platform Overview: real org/user
+// counts + money from the upstreams, and a per-source freshness row that reports
+// the honest state of each feed (iam ok, commerce ok, o11y not-configured here).
+func TestOverview_RealTilesAndSources(t *testing.T) {
+	iam := newFakeIAM()
+	defer iam.server.Close()
+	commerce := newFakeCommerce()
+	defer commerce.server.Close()
+
+	do := mount(t, iam.server.URL, commerce.server.URL, "") // no o11y health → source not-ok
+	admin := map[string]string{"X-User-IsAdmin": "true", "X-Org-Id": "admin"}
+
+	resp, body := do("GET", "/v1/admin/overview", admin)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("overview: got %d (body=%s)", resp.StatusCode, body)
+	}
+	var env struct {
+		Data overviewData `json:"data"`
+	}
+	if err := json.Unmarshal(body, &env); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	d := env.Data
+	if d.Orgs != 2 {
+		t.Errorf("overview orgs = %d, want 2", d.Orgs)
+	}
+	// 2 orgs × 7 users each (both count probes return data2=7).
+	if d.Users != 14 {
+		t.Errorf("overview users = %d, want 14", d.Users)
+	}
+	// 2 orgs × 1500 consumed cents.
+	if d.SpendCents30d != 3000 {
+		t.Errorf("overview spend = %d, want 3000", d.SpendCents30d)
+	}
+	if d.CreditsCents != 10000 {
+		t.Errorf("overview credits = %d, want 10000", d.CreditsCents)
+	}
+	if d.LastSync == "" {
+		t.Error("overview lastSync must be set")
+	}
+	// Source freshness: iam ok, commerce ok, o11y not-ok (unconfigured).
+	src := map[string]core.SourceStatus{}
+	for _, s := range d.Sources {
+		src[s.Name] = s
+	}
+	if !src["iam"].OK || src["iam"].Rows != 2 {
+		t.Errorf("iam source = %+v, want ok/2 rows", src["iam"])
+	}
+	if !src["commerce"].OK {
+		t.Errorf("commerce source = %+v, want ok", src["commerce"])
+	}
+	if src["o11y"].OK || src["o11y"].Error == "" {
+		t.Errorf("o11y source must be not-ok with an error when unconfigured: %+v", src["o11y"])
+	}
+}
+
+// TestOverview_CommercePartialOnPerOrgError proves the decomplected freshness rule: the
+// commerce source is DEGRADED when ANY per-org money read fails — the fleet total is then
+// an undercount and must NOT read healthy. Commerce succeeds for hanzo but 500s for acme;
+// the overview folds acme's failure into a not-ok commerce source (the SAME partial
+// pattern revenue/finance use) instead of the old single-probe that masked it.
+func TestOverview_CommercePartialOnPerOrgError(t *testing.T) {
+	iam := newFakeIAM()
+	defer iam.server.Close()
+	commerce := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		if r.Header.Get("X-Org-Id") == "acme" {
+			w.WriteHeader(500) // commerce down for THIS org only
+			io.WriteString(w, `{"status":"error","msg":"commerce down for acme"}`)
+			return
+		}
+		switch {
+		case strings.HasSuffix(r.URL.Path, "/usage-rollup"):
+			io.WriteString(w, `{"consumedCents":1500,"overageCents":0}`)
+		case strings.HasSuffix(r.URL.Path, "/balance"):
+			io.WriteString(w, `{"available":5000,"balance":5000}`)
+		default:
+			w.WriteHeader(404)
+		}
+	}))
+	defer commerce.Close()
+
+	do := mount(t, iam.server.URL, commerce.URL, "")
+	admin := map[string]string{"X-User-IsAdmin": "true", "X-Org-Id": "admin"}
+	resp, body := do("GET", "/v1/admin/overview", admin)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("overview: %d (%s)", resp.StatusCode, body)
+	}
+	var env struct {
+		Data overviewData `json:"data"`
+	}
+	if err := json.Unmarshal(body, &env); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	src := map[string]core.SourceStatus{}
+	for _, s := range env.Data.Sources {
+		src[s.Name] = s
+	}
+	c, ok := src["commerce"]
+	if !ok {
+		t.Fatal("overview must report a commerce source")
+	}
+	if c.OK {
+		t.Errorf("commerce source must be DEGRADED when a per-org read failed (undercount masked as healthy), got %+v", c)
+	}
+	if c.Error == "" {
+		t.Errorf("degraded commerce source must carry an error: %+v", c)
+	}
+	// The healthy org still contributes — an honest PARTIAL total, never a hard panel fail.
+	if env.Data.SpendCents30d != 1500 {
+		t.Errorf("spend = %d, want 1500 (only hanzo read; acme failed)", env.Data.SpendCents30d)
+	}
+}
+
+// TestUsage_RealTotalsHonestEmptySeries proves the usage roll-up returns the REAL
+// fleet spend from commerce but an HONEST empty series/byProduct — the timeseries
+// feed lives in insights/datastore, and admin must never fabricate a trend.
+func TestUsage_RealTotalsHonestEmptySeries(t *testing.T) {
+	iam := newFakeIAM()
+	defer iam.server.Close()
+	commerce := newFakeCommerce()
+	defer commerce.server.Close()
+
+	do := mount(t, iam.server.URL, commerce.server.URL, "")
+	admin := map[string]string{"X-User-IsAdmin": "true", "X-Org-Id": "admin"}
+
+	resp, body := do("GET", "/v1/admin/usage", admin)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("usage: got %d (body=%s)", resp.StatusCode, body)
+	}
+	var env struct {
+		Data usageData `json:"data"`
+	}
+	if err := json.Unmarshal(body, &env); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if env.Data.Totals.SpendCents != 3000 { // 2 orgs × 1500
+		t.Errorf("usage total spend = %d, want 3000", env.Data.Totals.SpendCents)
+	}
+	// Honest empty — NOT nil (the JSON must be [], which the operator renders as
+	// an empty chart), and NEVER a fabricated point.
+	if env.Data.Series == nil || len(env.Data.Series) != 0 {
+		t.Errorf("usage series must be an empty array (no fabricated trend), got %v", env.Data.Series)
+	}
+	if env.Data.ByProduct == nil || len(env.Data.ByProduct) != 0 {
+		t.Errorf("usage byProduct must be an empty array, got %v", env.Data.ByProduct)
+	}
+}
+
+// TestProductsAndSync_HonestShapes verifies products returns the real empty
+// registry (no fabricated workloads) and sync acknowledges with {started:true}.
+func TestProductsAndSync_HonestShapes(t *testing.T) {
+	do := mount(t, "", "", "")
+	admin := map[string]string{"X-User-IsAdmin": "true", "X-Org-Id": "admin"}
+
+	_, pBody := do("GET", "/v1/admin/products", admin)
+	var pEnv struct {
+		Data  []productRow `json:"data"`
+		Data2 int          `json:"data2"`
+	}
+	if err := json.Unmarshal(pBody, &pEnv); err != nil {
+		t.Fatalf("products decode: %v", err)
+	}
+	if pEnv.Data == nil || len(pEnv.Data) != 0 || pEnv.Data2 != 0 {
+		t.Errorf("products must be an empty registry (no fabricated rows): %+v", pEnv)
+	}
+
+	_, sBody := do("POST", "/v1/admin/sync", admin)
+	var sEnv struct {
+		Status string          `json:"status"`
+		Data   map[string]bool `json:"data"`
+	}
+	if err := json.Unmarshal(sBody, &sEnv); err != nil {
+		t.Fatalf("sync decode: %v", err)
+	}
+	if sEnv.Status != "ok" || !sEnv.Data["started"] {
+		t.Errorf("sync must ack {started:true}: %+v", sEnv)
+	}
+}
+
+// TestIAMError_SurfacedNotFabricated proves a failing upstream yields a real
+// error envelope (status:error), NOT a stubbed/zero success — the operator shows
+// the error state, honoring the api.ts "nothing here fabricates data" contract.
+func TestIAMError_SurfacedNotFabricated(t *testing.T) {
+	// IAM that always 500s.
+	bad := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(500)
+		io.WriteString(w, `{"status":"error","msg":"iam boom"}`)
+	}))
+	defer bad.Close()
+
+	do := mount(t, bad.URL, "", "")
+	admin := map[string]string{"X-User-IsAdmin": "true", "X-Org-Id": "admin"}
+
+	_, body := do("GET", "/v1/admin/orgs", admin)
+	var env struct {
+		Status string `json:"status"`
+		Msg    string `json:"msg"`
+	}
+	if err := json.Unmarshal(body, &env); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if env.Status != "error" || env.Msg == "" {
+		t.Errorf("failing IAM must surface an error envelope, got %+v", env)
+	}
+}
+
+// TestMount_NilGuards keeps the Mount contract honest (nil app / nil logger).
+func TestMount_NilGuards(t *testing.T) {
+	if err := Mount(nil, cloud.Deps{Logger: luxlog.New("test")}); err == nil {
+		t.Error("Mount(nil app) must error")
+	}
+	app := zip.New(zip.Config{Logger: luxlog.New("test")})
+	if err := Mount(app, cloud.Deps{}); err == nil {
+		t.Error("Mount(nil logger) must error")
+	}
+}

clients/admin/analytics.go

@@ -0,0 +1,532 @@
+package admin
+
+// Native SaaS business ANALYTICS (/v1/admin/analytics) — cohort retention, growth,
+// churn, active-customers (DAU/WAU/MAU), revenue (MRR/ARPU) and usage over time, derived
+// from REAL fleet data: IAM org `createdTime` (the signup cohort) + the commerce
+// transaction ledger (usage = `withdraw` rows). SuperAdmin/org-scoped via GuardScoped.
+//
+// The fleet activity model + the continuous spend series live in clients/admin/core
+// (core.FleetActivity / core.SpendSeries / core.CustActivity / core.SeriesPoint) because
+// the revenue board reuses them — one implementation, DRY. This file holds only the
+// analytics-specific derivation (growth/retention/churn/active/LTV) that folds over that
+// shared model.
+
+import (
+	"context"
+	"sort"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/hanzoai/cloud"
+	"github.com/hanzoai/cloud/clients/admin/core"
+	"github.com/hanzoai/cloud/clients/admin/iam"
+	"github.com/zap-proto/zip"
+)
+
+// ── wire shapes (operator contract) ──────────────────────────────────────────
+
+// retentionCohort is one row of the retention triangle: a signup cohort, its size, and
+// the % of it still ACTIVE at each subsequent period (values[0] = the signup period
+// itself). Percentages are 0..100.
+type retentionCohort struct {
+	Cohort string    `json:"cohort"`
+	Size   int       `json:"size"`
+	Values []float64 `json:"values"`
+}
+
+// retentionGrid is the classic cohort-retention heatmap (cohorts × periods).
+type retentionGrid struct {
+	Interval string            `json:"interval"` // "month"
+	Periods  int               `json:"periods"`
+	Cohorts  []retentionCohort `json:"cohorts"`
+}
+
+// analyticsData is the whole GET /v1/admin/analytics payload.
+type analyticsData struct {
+	Range       string `json:"range"`
+	Interval    string `json:"interval"`
+	GeneratedAt string `json:"generatedAt"`
+
+	// Growth — from IAM createdTime (always real).
+	Signups             []core.SeriesPoint `json:"signups"`
+	CumulativeCustomers []core.SeriesPoint `json:"cumulativeCustomers"`
+	TotalCustomers      int                `json:"totalCustomers"`
+	NewCustomers        int                `json:"newCustomers"`
+	GrowthRatePct       float64            `json:"growthRatePct"`
+
+	// Active customers — from the usage ledger.
+	ActiveCustomers []core.SeriesPoint `json:"activeCustomers"`
+	DAU             int                `json:"dau"`
+	WAU             int                `json:"wau"`
+	MAU             int                `json:"mau"`
+
+	// Retention triangle — signup cohort × active period.
+	Retention retentionGrid `json:"retention"`
+
+	// Churn — logo churn (count) + rate.
+	Churn        []core.SeriesPoint `json:"churn"`
+	ChurnRatePct float64            `json:"churnRatePct"`
+
+	// Revenue analytics.
+	MRRCents  int64              `json:"mrrCents"`
+	Revenue   []core.SeriesPoint `json:"revenue"`
+	ARPUCents int64              `json:"arpuCents"`
+	LTVCents  *int64             `json:"ltvCents"` // null until churn is observed
+	NRRPct    *float64           `json:"nrrPct"`   // null — needs MRR history
+
+	// Usage analytics.
+	Usage        []core.SeriesPoint `json:"usage"`
+	TopCustomers []analyticsSlice   `json:"topCustomers"`
+
+	// Transparency: which metrics are backed by real data vs honest-empty.
+	Computed map[string]bool     `json:"computed"`
+	Sources  []core.SourceStatus `json:"sources"`
+}
+
+// analyticsSlice is a labelled magnitude (top customers by usage cents).
+type analyticsSlice struct {
+	Label string `json:"label"`
+	Value int64  `json:"value"`
+	Hint  string `json:"hint,omitempty"`
+}
+
+// ── handler ──────────────────────────────────────────────────────────────────
+
+func analytics(s *cloud.Service[core.State], c *zip.Ctx) error {
+	ctx := c.Context()
+	cr := core.CallerCreds(c)
+	now := time.Now().UTC()
+	rangeStr := normalizeRange(c.Query("range"))
+	since, interval, _ := rangeWindow(rangeStr, now)
+
+	var sources []core.SourceStatus
+
+	// Scoped fan-in: a SuperAdmin gets every org (all-orgs SaaS analytics); an org admin
+	// gets ONLY their own subtree — the ONE tenant-scope predicate (core.ScopedOrgs).
+	orgs, err := core.ScopedOrgs(s, ctx, c, cr)
+	if err != nil {
+		return core.Fail(c, err.Error())
+	}
+	sources = append(sources, core.SrcOf("iam", nil, len(orgs), now.Format(time.RFC3339)))
+
+	acts, ledgerOK := core.FleetActivity(s, ctx, orgs)
+	ledgerRows := 0
+	for _, a := range acts {
+		ledgerRows += len(a.Usage)
+	}
+	var ledgerErr error
+	if !ledgerOK {
+		ledgerErr = core.ErrPartialRevenue // partial ledger read — mark degraded
+	}
+	sources = append(sources, core.SrcOf("commerce-ledger", ledgerErr, ledgerRows, now.Format(time.RFC3339)))
+
+	// MRR from subscriptions (point-in-time), fanned out like the money reads.
+	mrr := fleetMRR(s, ctx, orgs)
+
+	data := computeAnalytics(analyticsInput{
+		acts:     acts,
+		mrrCents: mrr,
+		now:      now,
+		since:    since,
+		interval: interval,
+		rangeStr: rangeStr,
+		ledgerOK: ledgerOK && ledgerRows > 0,
+	})
+	data.GeneratedAt = now.Format(time.RFC3339)
+	data.Sources = sources
+	return core.OK(c, data)
+}
+
+// analyticsInput is everything computeAnalytics needs — no I/O, so the whole SaaS
+// analytics derivation is unit-testable without a network.
+type analyticsInput struct {
+	acts     []core.CustActivity
+	mrrCents int64
+	now      time.Time
+	since    time.Time
+	interval string
+	rangeStr string
+	ledgerOK bool // the ledger read yielded real usage rows
+}
+
+// computeAnalytics is the PURE derivation of every analytics metric from the real
+// activity model. Growth is always computed (signup timestamps); the ledger-backed
+// metrics compute from real usage when present and degrade to honest empty/zero when the
+// fleet has no usage yet — never a fabricated curve. `computed` flags each.
+func computeAnalytics(in analyticsInput) analyticsData {
+	buckets := core.EnumerateBuckets(in.since, in.now, in.interval)
+
+	// ── Growth (IAM createdTime — always real) ──
+	signups := make([]core.SeriesPoint, len(buckets))
+	newCount := 0
+	total := 0
+	for i, b := range buckets {
+		signups[i] = core.SeriesPoint{T: b}
+	}
+	idx := core.IndexOf(buckets)
+	for _, a := range in.acts {
+		if !a.HasCreated {
+			continue
+		}
+		total++
+		if !a.Created.Before(in.since) {
+			newCount++
+		}
+		if i, ok := idx[core.BucketKeyOf(a.Created, in.interval)]; ok {
+			signups[i].Value++
+		}
+	}
+	// Cumulative customers across the SAME buckets (all-time count at each bucket end).
+	cumulative := make([]core.SeriesPoint, len(buckets))
+	for i, b := range buckets {
+		end := bucketEnd(b, in.interval)
+		n := 0
+		for _, a := range in.acts {
+			if a.HasCreated && !a.Created.After(end) {
+				n++
+			}
+		}
+		cumulative[i] = core.SeriesPoint{T: b, Value: int64(n)}
+	}
+	growthRate := priorWindowGrowth(in.acts, in.since, in.now)
+
+	// ── Active customers + usage (ledger-backed) ──
+	usage := core.SpendSeries(in.acts, in.since, in.now, in.interval)
+	active := make([]core.SeriesPoint, len(buckets))
+	for i, b := range buckets {
+		active[i] = core.SeriesPoint{T: b}
+	}
+	for _, a := range in.acts {
+		// active in a bucket = at least one usage event in it
+		seen := map[string]bool{}
+		for _, p := range a.Usage {
+			if p.T.Before(in.since) || p.T.After(in.now) {
+				continue
+			}
+			seen[core.BucketKeyOf(p.T, in.interval)] = true
+		}
+		for b := range seen {
+			if i, ok := idx[b]; ok {
+				active[i].Value++
+			}
+		}
+	}
+	dau := activeWithin(in.acts, in.now.AddDate(0, 0, -1))
+	wau := activeWithin(in.acts, in.now.AddDate(0, 0, -7))
+	mau := activeWithin(in.acts, in.now.AddDate(0, 0, -30))
+
+	// ── Retention triangle (monthly cohorts × active month) ──
+	retention := computeRetention(in.acts, in.now, 12)
+
+	// ── Churn (monthly logo churn from active months) + rate ──
+	churn, churnRate := computeChurn(in.acts, in.now, 6)
+
+	// ── Revenue analytics ──
+	var totalSpend int64
+	for _, a := range in.acts {
+		totalSpend += a.SpendCents
+	}
+	arpu := int64(0)
+	if mau > 0 {
+		arpu = totalSpend / int64(mau)
+	} else if total > 0 {
+		arpu = totalSpend / int64(total)
+	}
+	var ltv *int64
+	if churnRate > 0 && arpu > 0 {
+		// LTV ≈ ARPU / monthly churn rate — computed ONLY when real churn is observed.
+		v := int64(float64(arpu) / (churnRate / 100.0))
+		ltv = &v
+	}
+
+	// ── Top customers by usage ──
+	top := topCustomersByUsage(in.acts, 10)
+
+	// Revenue series = realized usage revenue per bucket (same as usage cents for a
+	// pay-as-you-go fleet; distinct field so the console can theme it as revenue).
+	revenue := make([]core.SeriesPoint, len(usage))
+	copy(revenue, usage)
+
+	return analyticsData{
+		Range:               in.rangeStr,
+		Interval:            in.interval,
+		Signups:             signups,
+		CumulativeCustomers: cumulative,
+		TotalCustomers:      total,
+		NewCustomers:        newCount,
+		GrowthRatePct:       growthRate,
+		ActiveCustomers:     active,
+		DAU:                 dau,
+		WAU:                 wau,
+		MAU:                 mau,
+		Retention:           retention,
+		Churn:               churn,
+		ChurnRatePct:        churnRate,
+		MRRCents:            in.mrrCents,
+		Revenue:             revenue,
+		ARPUCents:           arpu,
+		LTVCents:            ltv,
+		NRRPct:              nil, // honest null — needs MRR history commerce doesn't expose
+		Usage:               usage,
+		TopCustomers:        top,
+		Computed: map[string]bool{
+			"growth":    true, // signup timestamps are always present
+			"retention": in.ledgerOK,
+			"active":    in.ledgerOK,
+			"churn":     in.ledgerOK,
+			"usage":     in.ledgerOK,
+			"revenue":   in.ledgerOK,
+			"mrr":       true,
+			"arpu":      in.ledgerOK,
+			"ltv":       ltv != nil,
+			"nrr":       false,
+		},
+	}
+}
+
+// computeRetention builds the cohort × period retention triangle from real signup months
+// and usage months. retention[c][k] = fraction of cohort c ACTIVE in month c+k. Cohorts
+// are capped to the last `maxCohorts` months; a cohort with no signups is omitted. Values
+// are 0..100.
+func computeRetention(acts []core.CustActivity, now time.Time, maxCohorts int) retentionGrid {
+	// Group customers by signup month.
+	byCohort := map[string][]core.CustActivity{}
+	for _, a := range acts {
+		if !a.HasCreated {
+			continue
+		}
+		k := core.MonthKey(a.Created)
+		byCohort[k] = append(byCohort[k], a)
+	}
+
+	// Sorted cohort months, newest last, capped.
+	cohorts := make([]string, 0, len(byCohort))
+	for k := range byCohort {
+		cohorts = append(cohorts, k)
+	}
+	sort.Strings(cohorts)
+	if len(cohorts) > maxCohorts {
+		cohorts = cohorts[len(cohorts)-maxCohorts:]
+	}
+
+	nowMonth := core.MonthKey(now)
+	grid := retentionGrid{Interval: "month"}
+	maxPeriods := 0
+	for _, cohort := range cohorts {
+		members := byCohort[cohort]
+		periods := monthsBetween(cohort, nowMonth) + 1
+		if periods < 1 {
+			periods = 1
+		}
+		row := retentionCohort{Cohort: cohort, Size: len(members), Values: make([]float64, periods)}
+		for k := 0; k < periods; k++ {
+			month := addMonths(cohort, k)
+			activeN := 0
+			for _, m := range members {
+				if m.ActiveIn(month, "month") {
+					activeN++
+				}
+			}
+			if len(members) > 0 {
+				row.Values[k] = pct(activeN, len(members))
+			}
+		}
+		if periods > maxPeriods {
+			maxPeriods = periods
+		}
+		grid.Cohorts = append(grid.Cohorts, row)
+	}
+	grid.Periods = maxPeriods
+	return grid
+}
+
+// computeChurn derives monthly LOGO churn: a customer counts as churned in month M if
+// they were active in M-1 but NOT in M. The rate is the average monthly churn over the
+// observed window. Returns honest zeros when there is no usage history.
+func computeChurn(acts []core.CustActivity, now time.Time, months int) ([]core.SeriesPoint, float64) {
+	// Build the last `months` month keys ending at now.
+	keys := lastMonths(now, months)
+	series := make([]core.SeriesPoint, len(keys))
+	var churnedTotal, baseTotal int
+	for i, m := range keys {
+		series[i] = core.SeriesPoint{T: m}
+		if i == 0 {
+			continue // no prior month to compare
+		}
+		prev := keys[i-1]
+		churned := 0
+		base := 0
+		for _, a := range acts {
+			wasActive := a.ActiveIn(prev, "month")
+			if wasActive {
+				base++
+				if !a.ActiveIn(m, "month") {
+					churned++
+				}
+			}
+		}
+		series[i].Value = int64(churned)
+		churnedTotal += churned
+		baseTotal += base
+	}
+	rate := 0.0
+	if baseTotal > 0 {
+		rate = pct(churnedTotal, baseTotal)
+	}
+	return series, rate
+}
+
+// topCustomersByUsage returns the top-N customers by total usage cents (desc).
+func topCustomersByUsage(acts []core.CustActivity, n int) []analyticsSlice {
+	rows := make([]analyticsSlice, 0, len(acts))
+	for _, a := range acts {
+		if a.SpendCents <= 0 {
+			continue
+		}
+		rows = append(rows, analyticsSlice{Label: a.Display, Value: a.SpendCents, Hint: a.Org})
+	}
+	sort.Slice(rows, func(i, j int) bool { return rows[i].Value > rows[j].Value })
+	if len(rows) > n {
+		rows = rows[:n]
+	}
+	return rows
+}
+
+// priorWindowGrowth is the signup growth vs the immediately-preceding window: the %
+// change in new signups this window vs last. 0 when the prior window had none.
+func priorWindowGrowth(acts []core.CustActivity, since, now time.Time) float64 {
+	window := now.Sub(since)
+	priorStart := since.Add(-window)
+	cur, prev := 0, 0
+	for _, a := range acts {
+		if !a.HasCreated {
+			continue
+		}
+		if !a.Created.Before(since) && a.Created.Before(now) {
+			cur++
+		} else if !a.Created.Before(priorStart) && a.Created.Before(since) {
+			prev++
+		}
+	}
+	if prev == 0 {
+		return 0
+	}
+	return (float64(cur-prev) / float64(prev)) * 100
+}
+
+// activeWithin counts customers with at least one usage event since `cut`.
+func activeWithin(acts []core.CustActivity, cut time.Time) int {
+	n := 0
+	for _, a := range acts {
+		if a.ActiveSince(cut) {
+			n++
+		}
+	}
+	return n
+}
+
+// fleetMRR sums each org's active-subscription MRR concurrently.
+func fleetMRR(s *cloud.Service[core.State], ctx context.Context, orgs []iam.Org) int64 {
+	vals := make([]int64, len(orgs))
+	sem := make(chan struct{}, core.MaxCustomerConcurrency)
+	var wg sync.WaitGroup
+	for i, o := range orgs {
+		wg.Add(1)
+		sem <- struct{}{}
+		go func(i int, o iam.Org) {
+			defer wg.Done()
+			defer func() { <-sem }()
+			if pl, err := s.State.Commerce.Plan(ctx, o.Name); err == nil {
+				vals[i] = int64(pl.MRR)
+			}
+		}(i, o)
+	}
+	wg.Wait()
+	var total int64
+	for _, v := range vals {
+		total += v
+	}
+	return total
+}
+
+// ── analytics-specific month arithmetic (the shared bucket keys live in core) ──
+
+// bucketEnd returns the inclusive end instant of a bucket key (for the cumulative count).
+// A day/week/month key advances one unit; the end is one nanosecond before.
+func bucketEnd(key, interval string) time.Time {
+	switch interval {
+	case "month":
+		if t, err := time.Parse("2006-01", key); err == nil {
+			return t.AddDate(0, 1, 0).Add(-time.Nanosecond)
+		}
+	case "week":
+		if t, err := time.Parse("2006-01-02", key); err == nil {
+			return t.AddDate(0, 0, 7).Add(-time.Nanosecond)
+		}
+	default:
+		if t, err := time.Parse("2006-01-02", key); err == nil {
+			return t.AddDate(0, 0, 1).Add(-time.Nanosecond)
+		}
+	}
+	return time.Now().UTC()
+}
+
+// addMonths adds k months to a "2006-01" key.
+func addMonths(month string, k int) string {
+	t, err := time.Parse("2006-01", month)
+	if err != nil {
+		return month
+	}
+	return t.AddDate(0, k, 0).Format("2006-01")
+}
+
+// monthsBetween returns the whole-month distance from a..b ("2006-01" keys).
+func monthsBetween(a, b string) int {
+	ta, ea := time.Parse("2006-01", a)
+	tb, eb := time.Parse("2006-01", b)
+	if ea != nil || eb != nil {
+		return 0
+	}
+	return int(tb.Year()-ta.Year())*12 + int(tb.Month()-ta.Month())
+}
+
+// lastMonths returns the last n month keys ending at `now` (oldest first).
+func lastMonths(now time.Time, n int) []string {
+	out := make([]string, 0, n)
+	for i := n - 1; i >= 0; i-- {
+		out = append(out, core.MonthKey(now.AddDate(0, -i, 0)))
+	}
+	return out
+}
+
+func pct(part, whole int) float64 {
+	if whole <= 0 {
+		return 0
+	}
+	return (float64(part) / float64(whole)) * 100
+}
+
+// normalizeRange clamps the range param to the supported set (default 30d).
+func normalizeRange(r string) string {
+	switch strings.TrimSpace(r) {
+	case "7d", "30d", "90d", "all":
+		return strings.TrimSpace(r)
+	default:
+		return "30d"
+	}
+}
+
+// rangeWindow maps a range to (since, interval, approxBuckets).
+func rangeWindow(rangeStr string, now time.Time) (time.Time, string, int) {
+	switch rangeStr {
+	case "7d":
+		return now.AddDate(0, 0, -7), "day", 7
+	case "90d":
+		return now.AddDate(0, 0, -90), "week", 13
+	case "all":
+		return now.AddDate(-2, 0, 0), "month", 24
+	default: // 30d
+		return now.AddDate(0, 0, -30), "day", 30
+	}
+}

clients/admin/analytics_math_test.go

@@ -0,0 +1,261 @@
+package admin
+
+import (
+	"math"
+	"testing"
+	"time"
+
+	"github.com/hanzoai/cloud/clients/admin/core"
+)
+
+// mkTime is a test helper for an RFC3339-ish instant.
+func mkTime(s string) time.Time {
+	t, err := time.Parse("2006-01-02", s)
+	if err != nil {
+		panic(err)
+	}
+	return t.UTC()
+}
+
+// fleetFixture builds a deterministic 3-customer fleet with known signup cohorts
+// and usage events, so every analytics metric has a hand-computable expectation.
+//
+//	alpha: signup 2024-05-10; usage 2024-05-20 (100c), 2024-06-05 (200c)  [cohort 05, active 05+06]
+//	beta : signup 2024-05-25; usage 2024-05-28 (50c)                       [cohort 05, active 05 only]
+//	gamma: signup 2024-06-15; usage 2024-07-01 (400c)                      [cohort 06, active 07 only]
+func fleetFixture() []core.CustActivity {
+	return []core.CustActivity{
+		{Org: "alpha", Display: "Alpha", Created: mkTime("2024-05-10"), HasCreated: true,
+			Usage: []core.TxnPoint{{T: mkTime("2024-05-20"), Cents: 100}, {T: mkTime("2024-06-05"), Cents: 200}}, SpendCents: 300},
+		{Org: "beta", Display: "Beta", Created: mkTime("2024-05-25"), HasCreated: true,
+			Usage: []core.TxnPoint{{T: mkTime("2024-05-28"), Cents: 50}}, SpendCents: 50},
+		{Org: "gamma", Display: "Gamma", Created: mkTime("2024-06-15"), HasCreated: true,
+			Usage: []core.TxnPoint{{T: mkTime("2024-07-01"), Cents: 400}}, SpendCents: 400},
+	}
+}
+
+// TestComputeRetention_RealCohortTriangle is the headline: the cohort-retention
+// heatmap is REAL math over signup cohorts × active months — never a fabricated
+// curve. Every cell is hand-verified against the fixture.
+func TestComputeRetention_RealCohortTriangle(t *testing.T) {
+	now := mkTime("2024-07-15")
+	grid := computeRetention(fleetFixture(), now, 12)
+
+	if grid.Interval != "month" {
+		t.Fatalf("retention interval = %q, want month", grid.Interval)
+	}
+	byCohort := map[string]retentionCohort{}
+	for _, c := range grid.Cohorts {
+		byCohort[c.Cohort] = c
+	}
+
+	// Cohort 2024-05 (alpha, beta): period0=100% (both active in 05),
+	// period1=50% (only alpha active in 06), period2=0% (neither active in 07).
+	c05, ok := byCohort["2024-05"]
+	if !ok {
+		t.Fatalf("missing cohort 2024-05 in %+v", grid.Cohorts)
+	}
+	if c05.Size != 2 {
+		t.Errorf("cohort 2024-05 size = %d, want 2", c05.Size)
+	}
+	wantC05 := []float64{100, 50, 0}
+	if len(c05.Values) != len(wantC05) {
+		t.Fatalf("cohort 2024-05 periods = %d, want %d (%v)", len(c05.Values), len(wantC05), c05.Values)
+	}
+	for k, want := range wantC05 {
+		if math.Abs(c05.Values[k]-want) > 0.01 {
+			t.Errorf("retention[2024-05][%d] = %.1f, want %.1f", k, c05.Values[k], want)
+		}
+	}
+
+	// Cohort 2024-06 (gamma): period0=0% (no usage in 06), period1=100% (active in 07).
+	c06 := byCohort["2024-06"]
+	wantC06 := []float64{0, 100}
+	if len(c06.Values) != len(wantC06) {
+		t.Fatalf("cohort 2024-06 periods = %d, want %d (%v)", len(c06.Values), len(wantC06), c06.Values)
+	}
+	for k, want := range wantC06 {
+		if math.Abs(c06.Values[k]-want) > 0.01 {
+			t.Errorf("retention[2024-06][%d] = %.1f, want %.1f", k, c06.Values[k], want)
+		}
+	}
+}
+
+// TestComputeChurn_RealLogoChurn proves monthly logo churn + rate are real.
+//
+//	06 vs 05: base {alpha,beta}=2, churned {beta}=1
+//	07 vs 06: base {alpha}=1,      churned {alpha}=1
+//	rate = churned(2) / base(3) = 66.67%
+func TestComputeChurn_RealLogoChurn(t *testing.T) {
+	now := mkTime("2024-07-15")
+	series, rate := computeChurn(fleetFixture(), now, 6)
+
+	got := map[string]int64{}
+	for _, p := range series {
+		got[p.T] = p.Value
+	}
+	if got["2024-06"] != 1 {
+		t.Errorf("churn[2024-06] = %d, want 1 (beta churned)", got["2024-06"])
+	}
+	if got["2024-07"] != 1 {
+		t.Errorf("churn[2024-07] = %d, want 1 (alpha churned)", got["2024-07"])
+	}
+	if math.Abs(rate-66.666) > 0.1 {
+		t.Errorf("churn rate = %.2f, want ~66.67", rate)
+	}
+}
+
+// TestComputeAnalytics_RealFleet drives the whole pure derivation and asserts the
+// growth, active-customer, ARPU, top-customer, LTV, and computed-flag outputs.
+func TestComputeAnalytics_RealFleet(t *testing.T) {
+	now := mkTime("2024-07-15")
+	since, interval, _ := rangeWindow("30d", now) // since 2024-06-15, daily
+	d := computeAnalytics(analyticsInput{
+		acts: fleetFixture(), mrrCents: 0, now: now, since: since, interval: interval, rangeStr: "30d", ledgerOK: true,
+	})
+
+	if d.TotalCustomers != 3 {
+		t.Errorf("total customers = %d, want 3", d.TotalCustomers)
+	}
+	// New in the 30d window [06-15, 07-15]: gamma only (alpha/beta signed up in May).
+	if d.NewCustomers != 1 {
+		t.Errorf("new customers = %d, want 1 (gamma)", d.NewCustomers)
+	}
+	// MAU (30d): only gamma had usage in-window (07-01). DAU/WAU: none in last 1/7d.
+	if d.MAU != 1 {
+		t.Errorf("MAU = %d, want 1", d.MAU)
+	}
+	if d.DAU != 0 || d.WAU != 0 {
+		t.Errorf("DAU/WAU = %d/%d, want 0/0", d.DAU, d.WAU)
+	}
+	// ARPU = totalSpend(750) / MAU(1) = 750.
+	if d.ARPUCents != 750 {
+		t.Errorf("ARPU = %d, want 750", d.ARPUCents)
+	}
+	// Top customer by usage = gamma (400c) first.
+	if len(d.TopCustomers) != 3 || d.TopCustomers[0].Hint != "gamma" || d.TopCustomers[0].Value != 400 {
+		t.Errorf("top customers wrong: %+v", d.TopCustomers)
+	}
+	// LTV computed only because churn is observed (>0).
+	if d.LTVCents == nil {
+		t.Error("LTV must be computed when churn is observed")
+	}
+	// NRR is honest-null (no MRR history).
+	if d.NRRPct != nil {
+		t.Error("NRR must be honest-null (needs MRR history)")
+	}
+	// Computed transparency flags.
+	if !d.Computed["growth"] || !d.Computed["retention"] || !d.Computed["active"] || !d.Computed["churn"] {
+		t.Errorf("computed flags wrong for a real-ledger fleet: %+v", d.Computed)
+	}
+	if d.Computed["nrr"] {
+		t.Error("nrr computed flag must be false")
+	}
+	// The usage series is over a continuous daily axis (honest zeros, not gaps).
+	if len(d.Usage) == 0 {
+		t.Error("usage series must have buckets")
+	}
+	var usageTotal int64
+	for _, p := range d.Usage {
+		usageTotal += p.Value
+	}
+	if usageTotal != 400 { // only gamma's 07-01 400c falls in the 30d window
+		t.Errorf("in-window usage total = %d, want 400", usageTotal)
+	}
+}
+
+// TestComputeAnalytics_HonestEmptyNoLedger proves the no-fabrication contract: with
+// real signups but NO usage ledger, growth is still computed but retention/active/
+// churn/usage are honest-empty and flagged not-computed — NEVER an invented curve.
+func TestComputeAnalytics_HonestEmptyNoLedger(t *testing.T) {
+	now := mkTime("2024-07-15")
+	// Same signups, but strip all usage (ledger empty / unreachable).
+	acts := fleetFixture()
+	for i := range acts {
+		acts[i].Usage = nil
+		acts[i].SpendCents = 0
+	}
+	since, interval, _ := rangeWindow("30d", now)
+	d := computeAnalytics(analyticsInput{acts: acts, now: now, since: since, interval: interval, rangeStr: "30d", ledgerOK: false})
+
+	// Growth is real regardless of the ledger.
+	if d.TotalCustomers != 3 || !d.Computed["growth"] {
+		t.Errorf("growth must still be computed from signups: total=%d computed=%v", d.TotalCustomers, d.Computed["growth"])
+	}
+	// Ledger-backed metrics are flagged NOT computed.
+	for _, k := range []string{"retention", "active", "churn", "usage", "revenue"} {
+		if d.Computed[k] {
+			t.Errorf("computed[%q] must be false with no ledger", k)
+		}
+	}
+	// And the actual values are honest zero — no fabricated activity.
+	if d.MAU != 0 || d.WAU != 0 || d.DAU != 0 {
+		t.Errorf("active must be 0 with no usage: dau=%d wau=%d mau=%d", d.DAU, d.WAU, d.MAU)
+	}
+	var usageTotal int64
+	for _, p := range d.Usage {
+		usageTotal += p.Value
+	}
+	if usageTotal != 0 {
+		t.Errorf("usage must be all-zero with no ledger, got %d", usageTotal)
+	}
+	if d.LTVCents != nil {
+		t.Error("LTV must be null with no churn observed")
+	}
+	// Retention cohorts still exist (from signups) but every cell is 0% (no activity).
+	for _, c := range d.Retention.Cohorts {
+		for k, v := range c.Values {
+			if v != 0 {
+				t.Errorf("retention[%s][%d] = %.1f, want 0 (no usage → no fabricated retention)", c.Cohort, k, v)
+			}
+		}
+	}
+}
+
+// TestSpendSeries_ContinuousHonestBuckets proves the shared spend series buckets
+// real usage onto a continuous axis with honest zeros.
+func TestSpendSeries_ContinuousHonestBuckets(t *testing.T) {
+	now := mkTime("2024-07-05")
+	since := mkTime("2024-07-01")
+	acts := []core.CustActivity{
+		{Usage: []core.TxnPoint{{T: mkTime("2024-07-01"), Cents: 100}, {T: mkTime("2024-07-03"), Cents: 300}}},
+	}
+	series := core.SpendSeries(acts, since, now, "day")
+	// 5 daily buckets 07-01..07-05.
+	if len(series) != 5 {
+		t.Fatalf("series buckets = %d, want 5 (%+v)", len(series), series)
+	}
+	got := map[string]int64{}
+	for _, p := range series {
+		got[p.T] = p.Value
+	}
+	if got["2024-07-01"] != 100 || got["2024-07-03"] != 300 {
+		t.Errorf("spend buckets wrong: %+v", got)
+	}
+	// 07-02, 07-04, 07-05 are honest zeros (present, not missing).
+	if got["2024-07-02"] != 0 || got["2024-07-04"] != 0 {
+		t.Errorf("empty days must be honest 0, got %+v", got)
+	}
+}
+
+// TestBucketHelpers pins the month arithmetic the retention triangle relies on.
+func TestBucketHelpers(t *testing.T) {
+	if addMonths("2024-05", 2) != "2024-07" {
+		t.Errorf("addMonths(2024-05,2) = %q, want 2024-07", addMonths("2024-05", 2))
+	}
+	if addMonths("2024-11", 3) != "2025-02" {
+		t.Errorf("addMonths(2024-11,3) = %q, want 2025-02", addMonths("2024-11", 3))
+	}
+	if monthsBetween("2024-05", "2024-07") != 2 {
+		t.Errorf("monthsBetween(05,07) = %d, want 2", monthsBetween("2024-05", "2024-07"))
+	}
+	if monthsBetween("2024-11", "2025-02") != 3 {
+		t.Errorf("monthsBetween cross-year = %d, want 3", monthsBetween("2024-11", "2025-02"))
+	}
+	if normalizeRange("bogus") != "30d" {
+		t.Errorf("normalizeRange must default to 30d")
+	}
+	if normalizeRange("90d") != "90d" {
+		t.Errorf("normalizeRange must keep 90d")
+	}
+}

clients/admin/audit/audit.go

@@ -0,0 +1,151 @@
+// Package audit is the /v1/admin/audit query surface, wired to cloud's REAL
+// tamper-evident audit store (the audit.Recorder Serve builds and hands over via
+// deps.Audit).
+//
+// cloud keeps its OWN append-only, hash-chained trail of every security-relevant
+// request against this binary, and that is what a compliance auditor queries here. IAM's
+// own login/session records remain a DIFFERENT trail; admin still federates them as a
+// fallback when cloud's local store is not configured, so no capability is lost.
+//
+// SECURITY. Both handlers are registered behind core.Guard (SuperAdmin only,
+// fail-closed). They are READ-ONLY (Query and Verify issue SELECT only), so exposing
+// them cannot weaken the append-only property.
+package audit
+
+import (
+	"net/url"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/hanzoai/cloud"
+	auditstore "github.com/hanzoai/cloud/audit"
+	"github.com/hanzoai/cloud/clients/admin/core"
+	"github.com/zap-proto/zip"
+)
+
+// Routes registers the /v1/admin/audit* surface (SuperAdmin only).
+func Routes(app *zip.App, s *cloud.Service[core.State]) {
+	app.Get("/v1/admin/audit", core.Guard(s, Records))
+	app.Get("/v1/admin/audit/verify", core.Guard(s, Verify))
+}
+
+// Records answers GET /v1/admin/audit from cloud's local tamper-evident store when
+// configured, else falls back to the IAM get-records proxy (federated view). Filters:
+// org, sub, action, resource, result, since, until, pageSize, p (page). The response is
+// the /v1 list envelope { data:[rows], data2:total } with the current chain integrity
+// summary attached.
+func Records(s *cloud.Service[core.State], c *zip.Ctx) error {
+	// No local store configured → preserve the legacy federated IAM view so the endpoint
+	// never regresses to empty.
+	if s.State.AuditStore == nil {
+		return fromIAM(s, c)
+	}
+
+	f := auditFilterFromQuery(c)
+	rows, total, err := s.State.AuditStore.Query(c.Context(), f)
+	if err != nil {
+		return core.Fail(c, err.Error())
+	}
+
+	out := make([]auditstore.Wire, 0, len(rows))
+	for _, r := range rows {
+		out = append(out, r.ToWire())
+	}
+
+	// Attach the live integrity summary so the console can badge the trail as verified.
+	// Best-effort: a verify error must not fail the listing.
+	integrity, ivErr := s.State.AuditStore.Verify(c.Context())
+	var integrityPayload any
+	if ivErr == nil {
+		integrityPayload = integrity
+	}
+
+	return c.JSON(200, map[string]any{
+		"status":    "ok",
+		"msg":       "",
+		"data":      out,
+		"data2":     total,
+		"integrity": integrityPayload,
+	})
+}
+
+// Verify answers GET /v1/admin/audit/verify — the tamper-evidence check. It walks the
+// whole hash chain and returns the integrity result (ok, count, head, and the seq where
+// the chain first breaks if tampered).
+func Verify(s *cloud.Service[core.State], c *zip.Ctx) error {
+	if s.State.AuditStore == nil {
+		return core.Fail(c, "audit store not configured")
+	}
+	integrity, err := s.State.AuditStore.Verify(c.Context())
+	if err != nil {
+		return core.Fail(c, err.Error())
+	}
+	return core.OK(c, integrity)
+}
+
+// auditFilterFromQuery builds an audit.Filter from the request query params. Time bounds
+// accept RFC3339. pageSize (default 100) and p (1-based page) drive Limit/Offset.
+// Unknown/blank params are simply not applied.
+func auditFilterFromQuery(c *zip.Ctx) auditstore.Filter {
+	f := auditstore.Filter{
+		Org:        strings.TrimSpace(c.Query("org")),
+		Sub:        strings.TrimSpace(c.Query("sub")),
+		Action:     strings.TrimSpace(c.Query("action")),
+		Resource:   strings.TrimSpace(c.Query("resource")),
+		ResourceID: strings.TrimSpace(c.Query("resourceId")),
+		Result:     strings.TrimSpace(c.Query("result")),
+	}
+	if v := strings.TrimSpace(c.Query("since")); v != "" {
+		if t, err := time.Parse(time.RFC3339, v); err == nil {
+			f.Since = t
+		}
+	}
+	if v := strings.TrimSpace(c.Query("until")); v != "" {
+		if t, err := time.Parse(time.RFC3339, v); err == nil {
+			f.Until = t
+		}
+	}
+	pageSize := 100
+	if v := strings.TrimSpace(c.Query("pageSize")); v != "" {
+		if n, err := strconv.Atoi(v); err == nil && n > 0 {
+			pageSize = n
+		}
+	}
+	f.Limit = pageSize
+	if v := strings.TrimSpace(c.Query("p")); v != "" {
+		if page, err := strconv.Atoi(v); err == nil && page > 1 {
+			f.Offset = (page - 1) * pageSize
+		}
+	}
+	return f
+}
+
+// fromIAM is the legacy federated view: when cloud has no local audit store, forward the
+// IAM get-records read verbatim (the prior behavior), so the endpoint still surfaces
+// IAM's own audit trail rather than an empty list.
+func fromIAM(s *cloud.Service[core.State], c *zip.Ctx) error {
+	q := iamAuditQuery(c)
+	res, err := s.State.IAM.List(c.Context(), core.CallerCreds(c), "/v1/iam/get-records", q)
+	if err != nil {
+		return core.Fail(c, err.Error())
+	}
+	return core.OKRaw(c, res.Rows, res.Total)
+}
+
+// iamAuditQuery builds the IAM get-records query for the federated fallback.
+func iamAuditQuery(c *zip.Ctx) url.Values {
+	q := url.Values{}
+	if org := strings.TrimSpace(c.Query("org")); org != "" {
+		q.Set("organizationName", org)
+	}
+	q.Set("p", "1")
+	ps := strings.TrimSpace(c.Query("pageSize"))
+	if ps == "" {
+		ps = "100"
+	}
+	q.Set("pageSize", ps)
+	q.Set("sortField", "createdTime")
+	q.Set("sortOrder", "descend")
+	return q
+}

clients/admin/audit/audit_test.go

@@ -0,0 +1,232 @@
+package audit
+
+// Tests for the store-backed /v1/admin/audit + /v1/admin/audit/verify surface. They wire
+// the audit domain against a REAL audit.Recorder (on-disk SQLite) seeded with records,
+// drive requests through the whole zip app, and assert the query results, the integrity
+// summary, and the SuperAdmin gate.
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/hanzoai/cloud"
+	auditstore "github.com/hanzoai/cloud/audit"
+	"github.com/hanzoai/cloud/clients/admin/core"
+	luxlog "github.com/luxfi/log"
+	fiber "github.com/zap-proto/fiber/v3"
+	"github.com/zap-proto/zip"
+)
+
+// mountWithStore builds a zip app with the audit routes wired to a real audit store, and
+// returns the store + a request helper. Only the audit routes are mounted here.
+func mountWithStore(t *testing.T) (*auditstore.Recorder, func(method, path string, hdr map[string]string) (*http.Response, []byte)) {
+	t.Helper()
+	path := filepath.Join(t.TempDir(), "audit.db")
+	rec, err := auditstore.Open(path, nil)
+	if err != nil {
+		t.Fatalf("audit.Open: %v", err)
+	}
+	t.Cleanup(func() { _ = rec.Close() })
+
+	app := zip.New(zip.Config{Logger: luxlog.New("test")})
+	s := &cloud.Service[core.State]{State: core.State{AdminOrg: "admin", AuditStore: rec}}
+	app.Get("/v1/admin/audit", core.Guard(s, Records))
+	app.Get("/v1/admin/audit/verify", core.Guard(s, Verify))
+	fa := app.Fiber()
+
+	do := func(method, p string, hdr map[string]string) (*http.Response, []byte) {
+		t.Helper()
+		req := httptest.NewRequest(method, p, nil)
+		for k, v := range hdr {
+			req.Header.Set(k, v)
+		}
+		resp, err := fa.Test(req, fiber.TestConfig{Timeout: 30 * time.Second})
+		if err != nil {
+			t.Fatalf("%s %s: %v", method, p, err)
+		}
+		b, _ := io.ReadAll(resp.Body)
+		return resp, b
+	}
+	return rec, do
+}
+
+func seedAudit(t *testing.T, rec *auditstore.Recorder, n int) {
+	t.Helper()
+	ctx := context.Background()
+	for i := 0; i < n; i++ {
+		_, err := rec.Append(ctx, auditstore.Record{
+			Time:     time.Now().UTC(),
+			Actor:    auditstore.Actor{Org: "admin", Sub: "z@hanzo.ai"},
+			Action:   "DELETE /v1/admin/orgs",
+			Resource: auditstore.Resource{Type: "org", ID: "acme"},
+			Auth:     auditstore.AuthContext{Method: "jwt", IsAdmin: true},
+			Outcome:  auditstore.Outcome{Result: "success", Status: 200},
+			Method:   "DELETE",
+			Path:     "/v1/admin/orgs/acme",
+		})
+		if err != nil {
+			t.Fatalf("seed %d: %v", i, err)
+		}
+	}
+}
+
+var superAdmin = map[string]string{"X-User-IsAdmin": "true", "X-Org-Id": "admin", "X-User-Id": "z@hanzo.ai"}
+
+// TestAdminAudit_ReturnsRealRecords proves GET /v1/admin/audit returns the store's
+// records (newest-first) with an accurate total and an integrity summary.
+func TestAdminAudit_ReturnsRealRecords(t *testing.T) {
+	rec, do := mountWithStore(t)
+	seedAudit(t, rec, 5)
+
+	resp, body := do("GET", "/v1/admin/audit", superAdmin)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("audit: got %d (body=%s)", resp.StatusCode, body)
+	}
+	var env struct {
+		Data []struct {
+			Seq    uint64 `json:"seq"`
+			Action string `json:"action"`
+			Hash   string `json:"hash"`
+			Result string `json:"result"`
+		} `json:"data"`
+		Data2     int `json:"data2"`
+		Integrity struct {
+			OK    bool   `json:"ok"`
+			Count uint64 `json:"count"`
+		} `json:"integrity"`
+	}
+	if err := json.Unmarshal(body, &env); err != nil {
+		t.Fatalf("decode: %v (body=%s)", err, body)
+	}
+	if env.Data2 != 5 || len(env.Data) != 5 {
+		t.Fatalf("got %d rows / total %d, want 5/5", len(env.Data), env.Data2)
+	}
+	if env.Data[0].Seq < env.Data[len(env.Data)-1].Seq {
+		t.Errorf("not newest-first: %d..%d", env.Data[0].Seq, env.Data[len(env.Data)-1].Seq)
+	}
+	if env.Data[0].Hash == "" {
+		t.Error("row has no hash — chain linkage not surfaced")
+	}
+	if !env.Integrity.OK || env.Integrity.Count != 5 {
+		t.Errorf("integrity summary = %+v, want ok/count=5", env.Integrity)
+	}
+}
+
+// TestAdminAudit_Filters proves the query filters (result) reach the store.
+func TestAdminAudit_Filters(t *testing.T) {
+	rec, do := mountWithStore(t)
+	ctx := context.Background()
+	// One deny among successes.
+	_, _ = rec.Append(ctx, auditstore.Record{Action: "POST /v1/admin/roles", Actor: auditstore.Actor{Org: "admin"}, Outcome: auditstore.Outcome{Result: "deny", Status: 403}})
+	seedAudit(t, rec, 3)
+
+	resp, body := do("GET", "/v1/admin/audit?result=deny", superAdmin)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("got %d (body=%s)", resp.StatusCode, body)
+	}
+	var env struct {
+		Data  []map[string]any `json:"data"`
+		Data2 int              `json:"data2"`
+	}
+	_ = json.Unmarshal(body, &env)
+	if env.Data2 != 1 || len(env.Data) != 1 {
+		t.Fatalf("result=deny returned %d/%d, want 1/1", len(env.Data), env.Data2)
+	}
+	if env.Data[0]["result"] != "deny" {
+		t.Errorf("filtered row result = %v, want deny", env.Data[0]["result"])
+	}
+}
+
+// TestAdminAudit_VerifyEndpoint proves GET /v1/admin/audit/verify returns the integrity
+// result for the chain.
+func TestAdminAudit_VerifyEndpoint(t *testing.T) {
+	rec, do := mountWithStore(t)
+	seedAudit(t, rec, 8)
+
+	resp, body := do("GET", "/v1/admin/audit/verify", superAdmin)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("verify: got %d (body=%s)", resp.StatusCode, body)
+	}
+	var env struct {
+		Data struct {
+			OK       bool   `json:"ok"`
+			Count    uint64 `json:"count"`
+			BrokenAt int64  `json:"brokenAt"`
+			HeadHash string `json:"headHash"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(body, &env); err != nil {
+		t.Fatalf("decode: %v (body=%s)", err, body)
+	}
+	if !env.Data.OK || env.Data.Count != 8 || env.Data.BrokenAt != -1 {
+		t.Errorf("verify result = %+v, want ok/count=8/brokenAt=-1", env.Data)
+	}
+	if env.Data.HeadHash == "" {
+		t.Error("verify returned no head hash")
+	}
+}
+
+// TestAdminAudit_DeniedWithoutSuperAdmin proves BOTH audit endpoints fail-closed 403 for
+// a non-SuperAdmin, and — critically — the store is NEVER read on a denied request.
+func TestAdminAudit_DeniedWithoutSuperAdmin(t *testing.T) {
+	rec, do := mountWithStore(t)
+	seedAudit(t, rec, 3)
+
+	cases := []struct {
+		name string
+		hdr  map[string]string
+	}{
+		{"no identity", map[string]string{}},
+		{"tenant admin (org != adminOrg, no minted IsAdmin)", map[string]string{"X-Org-Id": "acme", "X-User-Id": "mallory"}},
+		{"forged-looking but non-admin", map[string]string{"X-Org-Id": "acme"}},
+	}
+	for _, ep := range []string{"/v1/admin/audit", "/v1/admin/audit/verify"} {
+		for _, tc := range cases {
+			resp, body := do("GET", ep, tc.hdr)
+			if resp.StatusCode != http.StatusForbidden {
+				t.Errorf("%s [%s]: got %d, want 403 (body=%s)", ep, tc.name, resp.StatusCode, body)
+			}
+			// No record content must appear in a denied response.
+			if len(body) > 0 && (contains(body, "DELETE /v1/admin/orgs") || contains(body, `"hash"`)) {
+				t.Errorf("%s [%s]: denied response leaked audit data: %s", ep, tc.name, body)
+			}
+		}
+	}
+}
+
+// TestAdminAudit_VerifyWithoutStore proves the nil-store verify endpoint reports "not
+// configured" rather than panicking.
+func TestAdminAudit_VerifyWithoutStore(t *testing.T) {
+	app := zip.New(zip.Config{Logger: luxlog.New("test")})
+	s := &cloud.Service[core.State]{State: core.State{AdminOrg: "admin"}} // no auditStore
+	app.Get("/v1/admin/audit/verify", core.Guard(s, Verify))
+	req := httptest.NewRequest("GET", "/v1/admin/audit/verify", nil)
+	for k, v := range superAdmin {
+		req.Header.Set(k, v)
+	}
+	resp, err := app.Fiber().Test(req, fiber.TestConfig{Timeout: 30 * time.Second})
+	if err != nil {
+		t.Fatalf("verify: %v", err)
+	}
+	body, _ := io.ReadAll(resp.Body)
+	// A well-formed error envelope, not a 500/panic.
+	if resp.StatusCode != http.StatusOK || !contains(body, "not configured") {
+		t.Errorf("nil-store verify = %d %s, want an ok-envelope 'not configured' error", resp.StatusCode, body)
+	}
+}
+
+func contains(b []byte, sub string) bool {
+	s := string(b)
+	for i := 0; i+len(sub) <= len(s); i++ {
+		if s[i:i+len(sub)] == sub {
+			return true
+		}
+	}
+	return false
+}

clients/admin/bases.go

@@ -0,0 +1,140 @@
+package admin
+
+// The BASES panel (/v1/admin/bases) — the tenant Base-instance surface, scoped by the ONE
+// tenant predicate: a SuperAdmin sees EVERY tenant's Base instance; any other admin caller
+// sees ONLY their own subtree's. "Base" is Hanzo's multi-tenant app engine (hanzoai/base —
+// a per-tenant DB store); an instance is one tenant's Base.
+//
+// SEAM (honest gap). The Base engine is being EMBEDDED into cloud (a /v1/base subsystem);
+// until it lands, this panel proxies a server-authed Base admin surface at BASE_ADMIN_URL
+// (secret from KMS via BASE_ADMIN_TOKEN — never a client claim, the SAME pattern
+// waitlist.go uses) and returns the HONEST empty state when unconfigured — never
+// fabricated instances. When /v1/base is embedded, point BASE_ADMIN_URL at the in-process
+// handler; the scope filter below is unchanged.
+//
+// SCOPE SAFETY (defense in depth). A non-super caller's read is filtered to their subtree
+// in TWO places: the upstream is asked for their org (?org=), AND every returned row is
+// re-checked against the scope here — so a mis-filtering or unparseable upstream can NEVER
+// leak another tenant's instance to a scoped caller (it degrades to empty, not to raw
+// passthrough).
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"os"
+	"strings"
+	"time"
+
+	"github.com/hanzoai/cloud"
+	"github.com/hanzoai/cloud/clients/admin/core"
+	"github.com/zap-proto/zip"
+)
+
+const (
+	baseAdminURLEnv   = "BASE_ADMIN_URL"
+	baseAdminTokenEnv = "BASE_ADMIN_TOKEN"
+)
+
+var baseHTTP = &http.Client{Timeout: 15 * time.Second}
+
+// baseInstance is one tenant's Base instance as the cockpit renders it. `Org` is the
+// tenant slug the scope filter keys on — it MUST be present for a row to be visible to a
+// scoped (non-super) caller.
+type baseInstance struct {
+	Name    string `json:"name"`
+	Org     string `json:"org"`
+	URL     string `json:"url"`
+	Status  string `json:"status"`
+	Plan    string `json:"plan"`
+	Region  string `json:"region"`
+	Created string `json:"created"`
+}
+
+func baseAdminConfig() (base, token string, ok bool) {
+	base = strings.TrimRight(strings.TrimSpace(os.Getenv(baseAdminURLEnv)), "/")
+	token = strings.TrimSpace(os.Getenv(baseAdminTokenEnv))
+	return base, token, base != ""
+}
+
+// baseProxy issues a server-authed GET to the Base admin surface and returns its raw JSON
+// body + status. Bounded read; Bearer token only when configured; never forwards a client
+// header.
+func baseProxy(s *cloud.Service[core.State], ctx context.Context, target, token string) (json.RawMessage, int, error) {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, target, nil)
+	if err != nil {
+		return nil, 0, fmt.Errorf("base request: %w", err)
+	}
+	req.Header.Set("Accept", "application/json")
+	if token != "" {
+		req.Header.Set("Authorization", "Bearer "+token)
+	}
+	resp, err := baseHTTP.Do(req)
+	if err != nil {
+		return nil, 0, fmt.Errorf("could not reach the Base engine: %w", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+	raw, err := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
+	if err != nil {
+		return nil, resp.StatusCode, fmt.Errorf("base read: %w", err)
+	}
+	return json.RawMessage(raw), resp.StatusCode, nil
+}
+
+// bases answers GET /v1/admin/bases — the scoped Base-instance list. Honest empty when the
+// engine is unconfigured; scope-filtered for a non-super caller.
+func bases(s *cloud.Service[core.State], c *zip.Ctx) error {
+	sc := core.ResolveScope(s, c)
+	base, token, ok := baseAdminConfig()
+	if !ok {
+		return c.JSON(200, map[string]any{
+			"status": "ok",
+			"msg":    "the Base engine is not yet embedded on this deployment",
+			"data":   []baseInstance{},
+			"data2":  0,
+		})
+	}
+	q := url.Values{}
+	if !sc.Super && len(sc.Orgs) > 0 {
+		q.Set("org", sc.Orgs[0]) // defense 1: server-side narrowing to the caller's org
+	}
+	target := base + "/v1/base/instances"
+	if enc := q.Encode(); enc != "" {
+		target += "?" + enc
+	}
+	raw, code, err := baseProxy(s, c.Context(), target, token)
+	if err != nil {
+		return core.Fail(c, err.Error())
+	}
+	if code/100 != 2 {
+		return core.Fail(c, fmt.Sprintf("base engine returned http %d", code))
+	}
+	// Defense 2: re-check every row against the resolved scope. A scoped caller NEVER
+	// sees a row outside their subtree even if the upstream ignored ?org=.
+	out := make([]baseInstance, 0)
+	for _, r := range decodeInstances(raw) {
+		if sc.ScopedToOrg(r.Org) {
+			out = append(out, r)
+		}
+	}
+	return core.OKList(c, out, len(out))
+}
+
+// decodeInstances tolerates BOTH a bare JSON array and a { data: [...] } envelope (the two
+// shapes a Base admin surface might return), so the panel is robust to the engine's exact
+// wire form.
+func decodeInstances(raw json.RawMessage) []baseInstance {
+	body := raw
+	var env struct {
+		Data json.RawMessage `json:"data"`
+	}
+	if json.Unmarshal(raw, &env) == nil && len(env.Data) > 0 {
+		body = env.Data
+	}
+	var rows []baseInstance
+	_ = json.Unmarshal(body, &rows)
+	return rows
+}

clients/admin/cockpit_test.go

@@ -0,0 +1,594 @@
+package admin
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/hanzoai/cloud"
+	"github.com/hanzoai/cloud/audit"
+	fiber "github.com/zap-proto/fiber/v3"
+
+	"github.com/hanzoai/cloud/clients/admin/commerce"
+	"github.com/hanzoai/cloud/clients/admin/core"
+	"github.com/hanzoai/cloud/clients/admin/customer"
+	"github.com/hanzoai/cloud/clients/admin/revenue"
+)
+
+// ── rich stateful fakes for the customer-management surfaces ──────────────────
+
+// cockpitFakes bundles a stateful IAM + commerce fake and the mounted `do` helper,
+// exposing the recorded state (forbidden flips, deposits) tests assert on.
+type cockpitFakes struct {
+	iam      *httptest.Server
+	commerce *httptest.Server
+	service  *cloud.Service[core.State]
+	do       func(method, path string, hdr map[string]string, body string) (*http.Response, []byte)
+
+	mu          sync.Mutex
+	forbidden   map[string]bool  // "owner/name" -> forbidden (mutated by update-user)
+	updateCalls []string         // ids passed to update-user
+	deposits    []depositCapture // deposits commerce received
+	balances    map[string]int64 // org -> availableCents (mutated by deposit)
+}
+
+type depositCapture struct {
+	org    string
+	user   string
+	amount int64
+	idem   string // X-Idempotency-Key commerce received (empty when none forwarded)
+}
+
+// adminHdr is a validated SuperAdmin identity (what SanitizeIdentity mints for
+// owner==AdminOrg) plus a replayable credential.
+func adminHdr() map[string]string {
+	return map[string]string{
+		"X-User-IsAdmin": "true", "X-Org-Id": "admin", "X-User-Id": "admin/z", "X-User-Email": "z@hanzo.ai",
+		"Authorization": "Bearer operator-jwt", "Cookie": "iam_access_token=operator-jwt",
+	}
+}
+
+// newCockpitFakes builds the stateful fleet: orgs acme + globex (owned by admin),
+// with users, balances, subscriptions, and a dated usage ledger — all relative to
+// `now` so the analytics windows are stable whenever the test runs.
+func newCockpitFakes(t *testing.T) *cockpitFakes {
+	t.Helper()
+	now := time.Now().UTC()
+	f := &cockpitFakes{
+		forbidden: map[string]bool{},
+		balances:  map[string]int64{"acme": 20000, "globex": 5000},
+	}
+	spend := map[string]int64{"acme": 1500, "globex": 300}
+
+	// Signup + usage dates relative to now so analytics windows include them.
+	acmeCreated := now.AddDate(0, 0, -45).Format(time.RFC3339)
+	globexCreated := now.AddDate(0, 0, -20).Format(time.RFC3339)
+	usage := map[string][]commerce.Entry{
+		"acme": {
+			{ID: "t1", Kind: "withdraw", Amount: 100, Currency: "usd", At: now.AddDate(0, 0, -40).Format(time.RFC3339)},
+			{ID: "t2", Kind: "withdraw", Amount: 200, Currency: "usd", At: now.AddDate(0, 0, -5).Format(time.RFC3339)},
+			{ID: "t3", Kind: "deposit", Amount: 20000, Currency: "usd", At: now.AddDate(0, 0, -46).Format(time.RFC3339)},
+		},
+		"globex": {
+			{ID: "t4", Kind: "withdraw", Amount: 400, Currency: "usd", At: now.AddDate(0, 0, -3).Format(time.RFC3339)},
+		},
+	}
+	// users per org (owner/name): forbidden read live from f.forbidden.
+	type u struct {
+		owner, name, email, key string
+		admin                   bool
+	}
+	users := map[string][]u{
+		"acme":   {{"acme", "anna", "anna@acme.test", "hk-anna-secret", true}, {"acme", "bob", "bob@acme.test", "", false}},
+		"globex": {{"globex", "gwen", "gwen@globex.test", "hk-gwen-secret", true}},
+	}
+
+	f.iam = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		q := r.URL.Query()
+		switch {
+		case strings.HasSuffix(r.URL.Path, "/get-organizations"):
+			fmt.Fprintf(w, `{"status":"ok","msg":"","data":[
+				{"owner":"admin","name":"acme","displayName":"Acme Inc","createdTime":%q},
+				{"owner":"admin","name":"globex","displayName":"Globex","createdTime":%q}
+			],"data2":2}`, acmeCreated, globexCreated)
+		case strings.HasSuffix(r.URL.Path, "/get-users"):
+			owner := q.Get("owner")
+			rows := []string{}
+			for _, us := range users[owner] {
+				f.mu.Lock()
+				forb := f.forbidden[us.owner+"/"+us.name]
+				f.mu.Unlock()
+				created := acmeCreated
+				if owner == "globex" {
+					created = globexCreated
+				}
+				rows = append(rows, fmt.Sprintf(`{"owner":%q,"name":%q,"email":%q,"isAdmin":%v,"isForbidden":%v,"accessKey":%q,"createdTime":%q,"lastSigninTime":%q}`,
+					us.owner, us.name, us.email, us.admin, forb, us.key, created, now.AddDate(0, 0, -2).Format(time.RFC3339)))
+			}
+			fmt.Fprintf(w, `{"status":"ok","msg":"","data":[%s],"data2":%d}`, strings.Join(rows, ","), len(rows))
+		case strings.HasSuffix(r.URL.Path, "/get-user"):
+			id := q.Get("id")
+			parts := strings.SplitN(id, "/", 2)
+			owner := ""
+			if len(parts) == 2 {
+				owner = parts[0]
+			}
+			for _, us := range users[owner] {
+				if us.owner+"/"+us.name == id {
+					f.mu.Lock()
+					forb := f.forbidden[id]
+					f.mu.Unlock()
+					// Full object incl. fields update-user must preserve.
+					fmt.Fprintf(w, `{"status":"ok","msg":"","data":{"owner":%q,"name":%q,"email":%q,"isAdmin":%v,"isForbidden":%v,"accessKey":%q,"displayName":"X","phone":"","type":"normal-user"}}`,
+						us.owner, us.name, us.email, us.admin, forb, us.key)
+					return
+				}
+			}
+			w.WriteHeader(404)
+			io.WriteString(w, `{"status":"error","msg":"not found"}`)
+		case strings.HasSuffix(r.URL.Path, "/update-user"):
+			id := q.Get("id")
+			body, _ := io.ReadAll(r.Body)
+			var obj map[string]any
+			_ = json.Unmarshal(body, &obj)
+			forb, _ := obj["isForbidden"].(bool)
+			f.mu.Lock()
+			f.forbidden[id] = forb
+			f.updateCalls = append(f.updateCalls, id)
+			f.mu.Unlock()
+			io.WriteString(w, `{"status":"ok","msg":"","data":"Affected"}`)
+		default:
+			w.WriteHeader(404)
+			io.WriteString(w, `{"status":"error","msg":"not found"}`)
+		}
+	}))
+
+	f.commerce = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		org := r.Header.Get("X-Org-Id")
+		q := r.URL.Query()
+		user := q.Get("user")
+		f.mu.Lock()
+		bal := f.balances[org]
+		f.mu.Unlock()
+		sp := int64(0)
+		if org != "" && user == org {
+			sp = spend[org]
+		} else {
+			bal = 0 // wrong subject/namespace → empty wallet (the live contract)
+		}
+		switch {
+		case r.Method == http.MethodPost && strings.HasSuffix(r.URL.Path, "/deposit"):
+			var req struct {
+				User     string `json:"user"`
+				Amount   int64  `json:"amount"`
+				Currency string `json:"currency"`
+			}
+			body, _ := io.ReadAll(r.Body)
+			_ = json.Unmarshal(body, &req)
+			f.mu.Lock()
+			f.balances[org] += req.Amount
+			f.deposits = append(f.deposits, depositCapture{org: org, user: req.User, amount: req.Amount, idem: r.Header.Get("X-Idempotency-Key")})
+			f.mu.Unlock()
+			w.WriteHeader(201)
+			fmt.Fprintf(w, `{"transactionId":"dep-%d","user":%q,"amount":%d,"currency":%q,"type":"deposit"}`, req.Amount, req.User, req.Amount, req.Currency)
+		case strings.HasSuffix(r.URL.Path, "/usage-rollup"):
+			fmt.Fprintf(w, `{"consumedCents":%d,"overageCents":0,"balance":{"balanceCents":%d,"availableCents":%d}}`, sp, bal, bal)
+		case strings.HasSuffix(r.URL.Path, "/balance"):
+			fmt.Fprintf(w, `{"user":%q,"currency":"usd","available":%d,"balance":%d}`, user, bal, bal)
+		case strings.HasSuffix(r.URL.Path, "/subscriptions"):
+			if org == "acme" && user == "acme" {
+				io.WriteString(w, `{"subscriptions":[{"status":"active","plan":{"name":"Pro","price":5000,"currency":"usd","interval":"month"}}]}`)
+			} else {
+				io.WriteString(w, `{"subscriptions":[]}`)
+			}
+		case strings.HasSuffix(r.URL.Path, "/transactions"):
+			// Commerce serves the ledger WRAPPED as { count, transactions:[...] }
+			// (the live contract) — the fake mirrors it so the decode is guarded
+			// against the real shape, not a bare array a mock would let pass.
+			rows := usage[org]
+			b, _ := json.Marshal(map[string]any{"count": len(rows), "transactions": rows})
+			w.Write(b)
+		default:
+			w.WriteHeader(404)
+			io.WriteString(w, `{"status":"error","msg":"not found"}`)
+		}
+	}))
+
+	_, s, fa := mountSvc(t, f.iam.URL, f.commerce.URL, "")
+	f.service = s
+	f.do = func(method, path string, hdr map[string]string, body string) (*http.Response, []byte) {
+		t.Helper()
+		var rdr io.Reader
+		if body != "" {
+			rdr = strings.NewReader(body)
+		}
+		req := httptest.NewRequest(method, path, rdr)
+		if body != "" {
+			req.Header.Set("Content-Type", "application/json")
+		}
+		for k, v := range hdr {
+			req.Header.Set(k, v)
+		}
+		resp, err := fa.Test(req, fiber.TestConfig{Timeout: 30 * time.Second})
+		if err != nil {
+			t.Fatalf("%s %s: %v", method, path, err)
+		}
+		bb, _ := io.ReadAll(resp.Body)
+		return resp, bb
+	}
+	t.Cleanup(func() { f.iam.Close(); f.commerce.Close() })
+	return f
+}
+
+// TestCustomers_ListRealFleet proves the fleet customer list is real: every field
+// (owner email, plan, balance, spend, MRR, status, user count) comes from the live
+// IAM + commerce upstreams.
+func TestCustomers_ListRealFleet(t *testing.T) {
+	f := newCockpitFakes(t)
+	resp, body := f.do("GET", "/v1/admin/customers", adminHdr(), "")
+	if resp.StatusCode != 200 {
+		t.Fatalf("customers: %d (%s)", resp.StatusCode, body)
+	}
+	var env struct {
+		Data  []customer.CustomerRow `json:"data"`
+		Data2 int                    `json:"data2"`
+	}
+	if err := json.Unmarshal(body, &env); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if env.Data2 != 2 || len(env.Data) != 2 {
+		t.Fatalf("want 2 customers, got %d (%+v)", len(env.Data), env.Data)
+	}
+	acme := env.Data[0] // sorted: acme, globex
+	if acme.Org != "acme" || acme.OwnerEmail != "anna@acme.test" || acme.Plan != "Pro" {
+		t.Errorf("acme identity wrong: %+v", acme)
+	}
+	if acme.BalanceCents != 20000 || acme.SpendCents != 1500 || acme.MRRCents != 5000 {
+		t.Errorf("acme money wrong: bal=%d spend=%d mrr=%d", acme.BalanceCents, acme.SpendCents, acme.MRRCents)
+	}
+	if acme.Users != 2 || acme.Status != "active" {
+		t.Errorf("acme users/status wrong: users=%d status=%s", acme.Users, acme.Status)
+	}
+}
+
+// TestCustomerDetail_RealAndNoSecretLeak proves the detail is real AND that the
+// hk- access key VALUE never appears in the response (presence only).
+func TestCustomerDetail_RealAndNoSecretLeak(t *testing.T) {
+	f := newCockpitFakes(t)
+	resp, body := f.do("GET", "/v1/admin/customers/acme", adminHdr(), "")
+	if resp.StatusCode != 200 {
+		t.Fatalf("detail: %d (%s)", resp.StatusCode, body)
+	}
+	if strings.Contains(string(body), "hk-anna-secret") {
+		t.Fatalf("SECRET LEAK: the access key value appears in the customer detail response")
+	}
+	var env struct {
+		Data customer.CustomerDetailData `json:"data"`
+	}
+	if err := json.Unmarshal(body, &env); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	d := env.Data
+	if d.Org != "acme" || d.Plan != "Pro" || d.BalanceCents != 20000 || d.MRRCents != 5000 {
+		t.Errorf("detail money/plan wrong: %+v", d)
+	}
+	// anna has a key, bob does not → apiKeys count = 1.
+	if d.APIKeys != 1 {
+		t.Errorf("apiKeys = %d, want 1", d.APIKeys)
+	}
+	if len(d.Users) != 2 {
+		t.Fatalf("want 2 users, got %d", len(d.Users))
+	}
+	// The users carry hasApiKey (presence) but NO key value field exists in the type.
+	var anna *customer.CustomerUser
+	for i := range d.Users {
+		if d.Users[i].Name == "anna" {
+			anna = &d.Users[i]
+		}
+	}
+	if anna == nil || !anna.HasAPIKey || !anna.IsAdmin {
+		t.Errorf("anna mapping wrong: %+v", anna)
+	}
+	if len(d.Transactions) == 0 {
+		t.Error("detail must include the real ledger transactions")
+	}
+}
+
+// TestGrantCredit_DepositLandsAndAudited proves grant credit is a REAL commerce
+// deposit (right org/subject) reflected in the balance AND recorded to the
+// tamper-evident audit trail with a before/after.
+func TestGrantCredit_DepositLandsAndAudited(t *testing.T) {
+	f := newCockpitFakes(t)
+	rec, err := audit.Open(":memory:", nil)
+	if err != nil {
+		t.Fatalf("audit open: %v", err)
+	}
+	defer rec.Close()
+	f.service.State.AuditStore = rec
+
+	resp, body := f.do("POST", "/v1/admin/customers/acme/credit", adminHdr(), `{"amountCents":5000,"reason":"support comp"}`)
+	if resp.StatusCode != 200 {
+		t.Fatalf("credit: %d (%s)", resp.StatusCode, body)
+	}
+	var env struct {
+		Status string `json:"status"`
+		Data   struct {
+			GrantedCents  int64  `json:"grantedCents"`
+			BalanceCents  int64  `json:"balanceCents"`
+			TransactionID string `json:"transactionId"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(body, &env); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if env.Status != "ok" || env.Data.GrantedCents != 5000 {
+		t.Fatalf("grant envelope wrong: %+v", env)
+	}
+	// The balance reflects the grant (20000 + 5000).
+	if env.Data.BalanceCents != 25000 {
+		t.Errorf("balance after grant = %d, want 25000", env.Data.BalanceCents)
+	}
+	// Commerce received a deposit for the RIGHT org + subject (X-Org-Id=acme, user=acme).
+	f.mu.Lock()
+	deps := append([]depositCapture(nil), f.deposits...)
+	f.mu.Unlock()
+	if len(deps) != 1 || deps[0].org != "acme" || deps[0].user != "acme" || deps[0].amount != 5000 {
+		t.Fatalf("deposit not landed on the right subject: %+v", deps)
+	}
+	// The action is on the tamper-evident trail with a before/after balance.
+	rows, total, err := rec.Query(context.Background(), audit.Filter{Action: "admin.customer.credit"})
+	if err != nil || total < 1 || len(rows) < 1 {
+		t.Fatalf("credit not audited: total=%d err=%v", total, err)
+	}
+	r := rows[0]
+	if r.Actor.Org != "admin" || r.Outcome.Result != "success" || r.Resource.ID != "acme" {
+		t.Errorf("audit record wrong: %+v", r)
+	}
+	if !strings.Contains(string(r.Before), "balanceCents") || !strings.Contains(string(r.After), "grantedCents") {
+		t.Errorf("audit before/after missing: before=%s after=%s", r.Before, r.After)
+	}
+}
+
+// TestGrantCredit_Validation proves the guardrails (positive amount, cap, real org).
+func TestGrantCredit_Validation(t *testing.T) {
+	f := newCockpitFakes(t)
+	cases := []struct {
+		name, org, body string
+		wantStatus      int
+		wantErr         bool
+	}{
+		{"zero amount", "acme", `{"amountCents":0}`, 200, true},
+		{"negative", "acme", `{"amountCents":-100}`, 200, true},
+		{"over cap", "acme", `{"amountCents":999999999}`, 200, true},
+		{"unknown org", "nope", `{"amountCents":100}`, 404, true},
+	}
+	for _, tc := range cases {
+		resp, body := f.do("POST", "/v1/admin/customers/"+tc.org+"/credit", adminHdr(), tc.body)
+		if resp.StatusCode != tc.wantStatus {
+			t.Errorf("%s: status %d, want %d (%s)", tc.name, resp.StatusCode, tc.wantStatus, body)
+		}
+		if tc.wantErr && !strings.Contains(string(body), `"error"`) {
+			t.Errorf("%s: expected error envelope, got %s", tc.name, body)
+		}
+	}
+	// No deposit should have landed for any invalid grant.
+	f.mu.Lock()
+	n := len(f.deposits)
+	f.mu.Unlock()
+	if n != 0 {
+		t.Errorf("invalid grants must NOT deposit, but %d landed", n)
+	}
+}
+
+// TestGrantCredit_NilAuditStoreFailsClosed proves the SOC2 durability guarantee: a
+// credit grant is REFUSED (503) — with NO money moved — on a deployment that has no
+// durable audit store to record it into. newCockpitFakes attaches no AuditStore, so a
+// valid grant must fail closed rather than silently move money with no cloud-side record.
+func TestGrantCredit_NilAuditStoreFailsClosed(t *testing.T) {
+	f := newCockpitFakes(t)
+	if f.service.State.AuditStore != nil {
+		t.Fatal("precondition: cockpit fakes must start with a nil AuditStore")
+	}
+
+	resp, body := f.do("POST", "/v1/admin/customers/acme/credit", adminHdr(), `{"amountCents":5000,"reason":"support comp"}`)
+	if resp.StatusCode != 503 {
+		t.Fatalf("nil-audit-store grant: status %d, want 503 (fail-closed) — body=%s", resp.StatusCode, body)
+	}
+	if !strings.Contains(string(body), `"error"`) {
+		t.Errorf("expected error envelope, got %s", body)
+	}
+	// The money must NOT have moved — no deposit reached commerce.
+	f.mu.Lock()
+	n := len(f.deposits)
+	bal := f.balances["acme"]
+	f.mu.Unlock()
+	if n != 0 {
+		t.Errorf("unaudited grant must NOT deposit, but %d landed", n)
+	}
+	if bal != 20000 {
+		t.Errorf("acme balance = %d after refused grant, want unchanged 20000", bal)
+	}
+}
+
+// TestGrantCredit_IdempotencyKeyForwarded proves the double-credit guard: when the
+// operator supplies an Idempotency-Key, cloud forwards a DETERMINISTIC X-Idempotency-Key
+// to commerce (so a commit-then-timeout retry dedupes there), the SAME nonce yields the
+// SAME key (a retry lands nothing new), a DIFFERENT nonce yields a DIFFERENT key, and NO
+// nonce forwards no key (the additive default).
+func TestGrantCredit_IdempotencyKeyForwarded(t *testing.T) {
+	f := newCockpitFakes(t)
+	rec, err := audit.Open(":memory:", nil)
+	if err != nil {
+		t.Fatalf("audit open: %v", err)
+	}
+	defer rec.Close()
+	f.service.State.AuditStore = rec
+
+	grant := func(hdr map[string]string) string {
+		resp, body := f.do("POST", "/v1/admin/customers/acme/credit", hdr, `{"amountCents":5000,"reason":"support comp"}`)
+		if resp.StatusCode != 200 {
+			t.Fatalf("credit: %d (%s)", resp.StatusCode, body)
+		}
+		f.mu.Lock()
+		defer f.mu.Unlock()
+		if len(f.deposits) == 0 {
+			t.Fatal("no deposit captured")
+		}
+		return f.deposits[len(f.deposits)-1].idem
+	}
+
+	withKey := func(k string) map[string]string {
+		h := adminHdr()
+		h["Idempotency-Key"] = k
+		return h
+	}
+
+	// A supplied nonce is forwarded as a non-empty, deterministic X-Idempotency-Key.
+	k1 := grant(withKey("op-nonce-1"))
+	if k1 == "" {
+		t.Fatal("Idempotency-Key supplied but commerce received no X-Idempotency-Key")
+	}
+	// The SAME nonce (a retry) → the SAME key, so commerce dedupes and lands nothing new.
+	if k1b := grant(withKey("op-nonce-1")); k1b != k1 {
+		t.Errorf("same nonce must yield same key: %q vs %q", k1, k1b)
+	}
+	// A DIFFERENT nonce → a DIFFERENT key (a genuinely new grant is never dropped).
+	if k2 := grant(withKey("op-nonce-2")); k2 == k1 {
+		t.Errorf("distinct nonce must yield distinct key, both = %q", k1)
+	}
+	// No nonce → no key forwarded (additive default preserved).
+	if k0 := grant(adminHdr()); k0 != "" {
+		t.Errorf("no nonce must forward no key, got %q", k0)
+	}
+}
+
+// TestSuspendReactivate_ForbidsUsersAndAudits proves suspend flips IAM isForbidden
+// on every org user (the real access lever) and is audited, and reactivate reverses
+// it — the customer's status reflects the change on a re-list.
+func TestSuspendReactivate_ForbidsUsersAndAudits(t *testing.T) {
+	f := newCockpitFakes(t)
+	rec, _ := audit.Open(":memory:", nil)
+	defer rec.Close()
+	f.service.State.AuditStore = rec
+
+	// Suspend acme.
+	resp, body := f.do("POST", "/v1/admin/customers/acme/suspend", adminHdr(), "")
+	if resp.StatusCode != 200 {
+		t.Fatalf("suspend: %d (%s)", resp.StatusCode, body)
+	}
+	// Both acme users were update-user'd to forbidden.
+	f.mu.Lock()
+	if !f.forbidden["acme/anna"] || !f.forbidden["acme/bob"] {
+		t.Errorf("suspend did not forbid both users: %+v", f.forbidden)
+	}
+	f.mu.Unlock()
+
+	// A re-list shows acme suspended (all users forbidden).
+	_, lb := f.do("GET", "/v1/admin/customers", adminHdr(), "")
+	var env struct {
+		Data []customer.CustomerRow `json:"data"`
+	}
+	_ = json.Unmarshal(lb, &env)
+	for _, c := range env.Data {
+		if c.Org == "acme" && c.Status != "suspended" {
+			t.Errorf("acme status = %q after suspend, want suspended", c.Status)
+		}
+	}
+	// Audited.
+	if _, total, _ := rec.Query(context.Background(), audit.Filter{Action: "admin.customer.suspend"}); total < 1 {
+		t.Errorf("suspend not audited")
+	}
+
+	// Reactivate reverses it.
+	if _, rb := f.do("POST", "/v1/admin/customers/acme/reactivate", adminHdr(), ""); !strings.Contains(string(rb), `"suspended":false`) {
+		t.Errorf("reactivate response wrong: %s", rb)
+	}
+	f.mu.Lock()
+	if f.forbidden["acme/anna"] || f.forbidden["acme/bob"] {
+		t.Errorf("reactivate did not clear forbidden: %+v", f.forbidden)
+	}
+	f.mu.Unlock()
+}
+
+// TestRevenue_RealAggregate proves the fleet revenue board: totals, paying-customer
+// count, ARPU, and the per-customer table are real commerce aggregates.
+func TestRevenue_RealAggregate(t *testing.T) {
+	f := newCockpitFakes(t)
+	resp, body := f.do("GET", "/v1/admin/revenue", adminHdr(), "")
+	if resp.StatusCode != 200 {
+		t.Fatalf("revenue: %d (%s)", resp.StatusCode, body)
+	}
+	var env struct {
+		Data revenue.RevenueData `json:"data"`
+	}
+	if err := json.Unmarshal(body, &env); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	d := env.Data
+	if d.TotalBalancesCents != 25000 { // acme 20000 + globex 5000
+		t.Errorf("total balances = %d, want 25000", d.TotalBalancesCents)
+	}
+	if d.TotalSpendCents != 1800 { // 1500 + 300
+		t.Errorf("total spend = %d, want 1800", d.TotalSpendCents)
+	}
+	if d.MRRCents != 5000 {
+		t.Errorf("MRR = %d, want 5000", d.MRRCents)
+	}
+	if d.PayingCustomers != 2 {
+		t.Errorf("paying customers = %d, want 2", d.PayingCustomers)
+	}
+	if d.ARPUCents != 900 { // 1800 / 2
+		t.Errorf("ARPU = %d, want 900", d.ARPUCents)
+	}
+	if len(d.PerCustomer) != 2 || d.PerCustomer[0].Org != "acme" { // sorted by spend desc
+		t.Errorf("per-customer table wrong: %+v", d.PerCustomer)
+	}
+	if len(d.SpendTrend) == 0 {
+		t.Error("revenue must include a real spend trend")
+	}
+}
+
+// TestAnalytics_HandlerRealWiring proves the analytics handler wires IAM signups +
+// commerce ledger into a REAL cohort/active/growth board, and flags computed=true.
+func TestAnalytics_HandlerRealWiring(t *testing.T) {
+	f := newCockpitFakes(t)
+	resp, body := f.do("GET", "/v1/admin/analytics?range=all", adminHdr(), "")
+	if resp.StatusCode != 200 {
+		t.Fatalf("analytics: %d (%s)", resp.StatusCode, body)
+	}
+	var env struct {
+		Data analyticsData `json:"data"`
+	}
+	if err := json.Unmarshal(body, &env); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	d := env.Data
+	if d.TotalCustomers != 2 {
+		t.Errorf("total customers = %d, want 2", d.TotalCustomers)
+	}
+	// Real ledger present → retention/active/usage computed, growth always.
+	if !d.Computed["growth"] || !d.Computed["retention"] || !d.Computed["active"] {
+		t.Errorf("computed flags must be true with a real ledger: %+v", d.Computed)
+	}
+	// Both customers had recent usage → MAU covers them.
+	if d.MAU < 1 {
+		t.Errorf("MAU = %d, want >=1 (recent usage)", d.MAU)
+	}
+	// Retention grid has cohorts from the two signups.
+	if len(d.Retention.Cohorts) == 0 {
+		t.Error("retention grid must have cohorts from real signups")
+	}
+	// Top customer by usage present (acme 300c > globex 400c? globex 400 wins).
+	if len(d.TopCustomers) == 0 {
+		t.Error("top customers must be populated from real usage")
+	}
+}

clients/admin/commerce/commerce.go

@@ -0,0 +1,367 @@
+// Package commerce is the admin cockpit's typed reader for the commerce billing
+// plane. It models the domain, not the endpoints: a billing subject (an org's
+// slug) has orthogonal, independently-readable facets —
+//
+//	Spend    — what it consumed this month
+//	Credits  — what prepaid balance it holds
+//	Plan     — its subscription tier + monthly-recurring revenue
+//	Ledger   — its transaction history
+//
+// plus one fleet god-view (Costs, our vendor COGS) and one write (Deposit, the
+// grant-credit primitive). Each read is total: an unwired or unreachable commerce
+// degrades to an honest zero, never a fabricated number.
+//
+// Commerce runs as its own deployment; these are HTTP calls authenticated with the
+// admin-scoped COMMERCE_SERVICE_TOKEN (a KMS-sourced secret already on the cloud
+// env — never hard-coded). A per-subject read resolves the org's billing namespace
+// from the TRUSTED X-Org-Id header (commerce's EdgeAuth trusts it only when the
+// bearer is the service token) AND keys the wallet under the bare slug — one value,
+// the subject, is both. The fleet Costs god-view is org-independent and sends no
+// subject.
+package commerce
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"strings"
+	"time"
+
+	"github.com/hanzoai/cloud/clients/admin/money"
+)
+
+// errUnconfigured marks a write (Deposit) attempted against an unwired commerce.
+var errUnconfigured = errors.New("commerce not configured")
+
+// Client reads the commerce billing plane.
+type Client struct {
+	base  string // e.g. http://commerce.hanzo.svc.cluster.local:8001
+	token string // admin S2S bearer (secret; never logged)
+	http  *http.Client
+}
+
+// New builds a commerce client for base + admin S2S token.
+func New(base, token string) *Client {
+	return &Client{
+		base:  strings.TrimRight(strings.TrimSpace(base), "/"),
+		token: strings.TrimSpace(token),
+		http:  &http.Client{Timeout: 15 * time.Second},
+	}
+}
+
+// Ready reports whether a commerce endpoint is wired on this deployment.
+func (c *Client) Ready() bool { return c != nil && c.base != "" }
+
+// Spend is a subject's month-to-date consumption.
+type Spend struct {
+	Consumed money.Cents `json:"consumedCents"`
+	Overage  money.Cents `json:"overageCents"`
+}
+
+// Spend reads a subject's month-to-date consumption (GET /v1/billing/usage-rollup).
+// Zero (not an error) when commerce is unwired, so a partial deploy degrades to
+// honest zeros.
+func (c *Client) Spend(ctx context.Context, subject string) (Spend, error) {
+	var out Spend
+	if !c.Ready() {
+		return out, nil
+	}
+	body, err := c.get(ctx, "/v1/billing/usage-rollup", url.Values{"user": {subject}}, subject)
+	if err != nil {
+		return out, err
+	}
+	if err := json.Unmarshal(body, &out); err != nil {
+		return out, fmt.Errorf("commerce spend decode: %w", err)
+	}
+	return out, nil
+}
+
+// Credits reads a subject's available prepaid credit (GET /v1/billing/balance).
+// Zero (not an error) when commerce is unwired.
+func (c *Client) Credits(ctx context.Context, subject string) (money.Cents, error) {
+	if !c.Ready() {
+		return 0, nil
+	}
+	q := url.Values{"user": {subject}, "currency": {"usd"}}
+	body, err := c.get(ctx, "/v1/billing/balance", q, subject)
+	if err != nil {
+		return 0, err
+	}
+	var b struct {
+		Available money.Cents `json:"available"`
+	}
+	if err := json.Unmarshal(body, &b); err != nil {
+		return 0, fmt.Errorf("commerce credits decode: %w", err)
+	}
+	return b.Available, nil
+}
+
+// Plan is a subject's subscription: the active tier, the monthly-normalized
+// recurring revenue, and whether any subscription is active. Name is
+// "pay-as-you-go" for a metered subject with no active subscription (the honest
+// default, never a fabricated tier).
+type Plan struct {
+	Name   string
+	MRR    money.Cents
+	Active bool
+}
+
+// subscriptionsWire is the /v1/billing/subscriptions list shape Plan folds over.
+type subscriptionsWire struct {
+	Subscriptions []struct {
+		Status string `json:"status"`
+		Plan   struct {
+			Name     string      `json:"name"`
+			Price    money.Cents `json:"price"`
+			Interval string      `json:"interval"`
+		} `json:"plan"`
+	} `json:"subscriptions"`
+}
+
+// Plan reads a subject's subscription tier + MRR in ONE decode (GET
+// /v1/billing/subscriptions), so the customer + revenue surfaces share a single
+// upstream read. Only "active"/"trialing" subscriptions count. Honest
+// zero/"pay-as-you-go" (not an error) when commerce is unwired.
+func (c *Client) Plan(ctx context.Context, subject string) (Plan, error) {
+	out := Plan{Name: "pay-as-you-go"}
+	if !c.Ready() {
+		return out, nil
+	}
+	body, err := c.get(ctx, "/v1/billing/subscriptions", url.Values{"user": {subject}}, subject)
+	if err != nil {
+		return out, err
+	}
+	var w subscriptionsWire
+	if err := json.Unmarshal(body, &w); err != nil {
+		return out, fmt.Errorf("commerce plan decode: %w", err)
+	}
+	for _, s := range w.Subscriptions {
+		switch strings.ToLower(strings.TrimSpace(s.Status)) {
+		case "active", "trialing":
+			out.MRR += monthlyNormalized(s.Plan.Price, s.Plan.Interval)
+			out.Active = true
+			if name := strings.TrimSpace(s.Plan.Name); name != "" && out.Name == "pay-as-you-go" {
+				out.Name = name
+			}
+		}
+	}
+	return out, nil
+}
+
+// monthlyNormalized normalizes a plan price to a monthly figure by its billing
+// interval so annual and monthly plans are comparable in one MRR sum.
+func monthlyNormalized(price money.Cents, interval string) money.Cents {
+	switch strings.ToLower(strings.TrimSpace(interval)) {
+	case "year", "yearly", "annual", "annually":
+		return price / 12
+	case "week", "weekly":
+		return price * 52 / 12
+	case "day", "daily":
+		return price * 365 / 12
+	default: // month/monthly and anything unrecognized → treat as monthly
+		return price
+	}
+}
+
+// Entry is one ledger row. Kind is "deposit" (credit) or "withdraw" (usage). At is
+// the RFC3339 event time analytics buckets on.
+type Entry struct {
+	ID       string      `json:"id"`
+	Kind     string      `json:"type"`
+	Amount   money.Cents `json:"amount"`
+	Currency string      `json:"currency"`
+	Tags     string      `json:"tags,omitempty"`
+	Notes    string      `json:"notes,omitempty"`
+	At       string      `json:"createdAt"`
+}
+
+// Ledger reads a subject's transaction history (GET /v1/billing/transactions),
+// newest-first, bounded by limit. Empty (not an error) when commerce is unwired.
+func (c *Client) Ledger(ctx context.Context, subject string, limit int) ([]Entry, error) {
+	if !c.Ready() {
+		return nil, nil
+	}
+	q := url.Values{"user": {subject}}
+	if limit > 0 {
+		q.Set("limit", fmt.Sprintf("%d", limit))
+	}
+	body, err := c.get(ctx, "/v1/billing/transactions", q, subject)
+	if err != nil {
+		return nil, err
+	}
+	// Commerce serves the ledger WRAPPED as { count, transactions:[...] }; tolerate a
+	// bare array too so a contract change in either direction degrades gracefully.
+	var wrap struct {
+		Transactions []Entry `json:"transactions"`
+	}
+	if err := json.Unmarshal(body, &wrap); err == nil && wrap.Transactions != nil {
+		return wrap.Transactions, nil
+	}
+	var rows []Entry
+	if err := json.Unmarshal(body, &rows); err != nil {
+		return nil, fmt.Errorf("commerce ledger decode: %w", err)
+	}
+	return rows, nil
+}
+
+// Vendor is one line of what WE pay a vendor for a service in a period (COGS).
+type Vendor struct {
+	Name    string      `json:"vendor"`
+	Service string      `json:"service"`
+	Amount  money.Cents `json:"amountCents"`
+	Source  string      `json:"source"` // "actual" | "estimated"
+	Note    string      `json:"note,omitempty"`
+}
+
+// Costs is the fleet COGS god-view: every vendor line for a period plus the total.
+type Costs struct {
+	Period   string      `json:"period"`
+	Vendors  []Vendor    `json:"vendors"`
+	Total    money.Cents `json:"totalCents"`
+	Currency string      `json:"currency"`
+}
+
+// Costs reads commerce's vendor-COGS god-view (GET /v1/costs) for a period — the
+// SINGLE source of truth for what we pay every vendor. It authenticates with the
+// admin S2S service token (no IAM user identity) and is org-INDEPENDENT, so it
+// sends no subject. Zero (not an error) when commerce is unwired.
+func (c *Client) Costs(ctx context.Context, period string) (Costs, error) {
+	var out Costs
+	if !c.Ready() {
+		return out, nil
+	}
+	q := url.Values{}
+	if period != "" {
+		q.Set("period", period)
+	}
+	body, err := c.get(ctx, "/v1/costs", q, "")
+	if err != nil {
+		return out, err
+	}
+	if err := json.Unmarshal(body, &out); err != nil {
+		return out, fmt.Errorf("commerce costs decode: %w", err)
+	}
+	return out, nil
+}
+
+// Receipt is the result of a Deposit — the transaction id of the credit that landed.
+type Receipt struct {
+	TxID     string      `json:"transactionId"`
+	Amount   money.Cents `json:"amount"`
+	Currency string      `json:"currency"`
+}
+
+// Deposit grants credit to a subject's wallet (POST /v1/billing/deposit) — the ONE
+// money-in primitive. Symmetric with Credits: the same X-Org-Id namespace + `user`
+// subject the reads resolve. amount must be positive (the handler validates + caps).
+//
+// idempotencyKey, when non-empty, is sent as X-Idempotency-Key so commerce dedupes a
+// retried deposit AT MOST ONCE (a completed key REPLAYS the stored receipt, an in-flight
+// key 409s; scoped billing-deposit:<subject>). This closes the commit-then-timeout double
+// -credit: cloud's 15s client can time out AFTER commerce committed, and a retry carrying
+// the SAME key lands nothing new. An EMPTY key preserves the additive default (distinct
+// deposits to the same subject are legitimately cumulative) — commerce never dedupes by
+// amount. See commerce api/billing/deposit.go.
+func (c *Client) Deposit(ctx context.Context, subject string, amount money.Cents, currency, notes, tags, idempotencyKey string) (Receipt, error) {
+	var out Receipt
+	if !c.Ready() {
+		return out, errUnconfigured
+	}
+	if currency == "" {
+		currency = "usd"
+	}
+	body, err := json.Marshal(map[string]any{
+		"user":     subject,
+		"currency": currency,
+		"amount":   amount,
+		"notes":    notes,
+		"tags":     tags,
+	})
+	if err != nil {
+		return out, err
+	}
+	respBody, err := c.post(ctx, "/v1/billing/deposit", subject, body, idempotencyKey)
+	if err != nil {
+		return out, err
+	}
+	if err := json.Unmarshal(respBody, &out); err != nil {
+		return out, fmt.Errorf("commerce deposit decode: %w", err)
+	}
+	return out, nil
+}
+
+// post performs one admin-authenticated commerce POST (JSON body) and returns the
+// raw response. The admin S2S service token is the bearer and X-Org-Id=<subject>
+// the per-org namespace selector commerce's EdgeAuth trusts only after verifying
+// the service token. idempotencyKey, when non-empty, is sent as X-Idempotency-Key so a
+// retried write dedupes at commerce. A non-2xx is an error the caller surfaces + audits
+// honestly.
+func (c *Client) post(ctx context.Context, path, subject string, body []byte, idempotencyKey string) ([]byte, error) {
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, c.base+path, bytes.NewReader(body))
+	if err != nil {
+		return nil, err
+	}
+	req.Header.Set("Accept", "application/json")
+	req.Header.Set("Content-Type", "application/json")
+	if c.token != "" {
+		req.Header.Set("Authorization", "Bearer "+c.token)
+	}
+	if subject != "" {
+		req.Header.Set("X-Org-Id", subject)
+	}
+	if idempotencyKey != "" {
+		req.Header.Set("X-Idempotency-Key", idempotencyKey)
+	}
+	resp, err := c.http.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("commerce unreachable: %w", err)
+	}
+	defer resp.Body.Close()
+	respBody, err := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
+	if err != nil {
+		return nil, err
+	}
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		return nil, fmt.Errorf("commerce status %d", resp.StatusCode)
+	}
+	return respBody, nil
+}
+
+// get performs one admin-authenticated commerce GET and returns the raw body.
+func (c *Client) get(ctx context.Context, path string, q url.Values, subject string) ([]byte, error) {
+	u := c.base + path
+	if enc := q.Encode(); enc != "" {
+		u += "?" + enc
+	}
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, u, nil)
+	if err != nil {
+		return nil, err
+	}
+	req.Header.Set("Accept", "application/json")
+	if c.token != "" {
+		req.Header.Set("Authorization", "Bearer "+c.token)
+	}
+	if subject != "" {
+		// Commerce's EdgeAuth trusts X-Org-Id ONLY after it verifies the bearer is the
+		// COMMERCE_SERVICE_TOKEN, then resolves the per-org billing namespace from it.
+		req.Header.Set("X-Org-Id", subject)
+	}
+	resp, err := c.http.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("commerce unreachable: %w", err)
+	}
+	defer resp.Body.Close()
+	body, err := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
+	if err != nil {
+		return nil, err
+	}
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		return nil, fmt.Errorf("commerce status %d", resp.StatusCode)
+	}
+	return body, nil
+}

clients/admin/commerce/commerce_test.go

@@ -0,0 +1,16 @@
+package commerce
+
+import "testing"
+
+// TestMonthlyNormalizedCents proves annual/monthly normalization for MRR.
+func TestMonthlyNormalizedCents(t *testing.T) {
+	if got := monthlyNormalized(12_000, "year"); got != 1_000 {
+		t.Errorf("yearly $120 → monthly = %d, want 1000", got)
+	}
+	if got := monthlyNormalized(2_000, "month"); got != 2_000 {
+		t.Errorf("monthly must pass through, got %d", got)
+	}
+	if got := monthlyNormalized(2_000, ""); got != 2_000 {
+		t.Errorf("unknown interval must be treated as monthly, got %d", got)
+	}
+}

clients/admin/compute.go

@@ -0,0 +1,234 @@
+// Copyright 2023-2026 Hanzo AI Inc. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package admin
+
+// compute — GET /v1/admin/compute, the cross-tenant compute-analytics read the
+// operator's Bots and Machines boards (admin.hanzo.ai) group into an
+// org → app → project tree. It aggregates the operator-owned usage table
+// hanzo.compute_usage(org, app, project, kind, event, machine_id, size,
+// price_cents, ts) — the same warehouse (`datastore`, datastore) the analytics
+// subsystem reads, over the SAME shared client (aiobject.DatastoreQuery), no
+// second connection. `kind` is an OPEN LowCardinality spectrum (bot | machine |
+// cluster | nodepool | container | function | …) — a bot is a machine running the
+// @hanzo/bot agent, a machine is raw compute visor opens — and each console lens
+// reuses this one endpoint with a different `?kind=` (Bots=bot, Machines=machine).
+//
+// SUPERADMIN ONLY (the s.guard wrap in admin.go), all-orgs by default; this is
+// an AGGREGATOR — admin holds no compute state, it only reads. Honest by
+// construction, exactly like the analytics events lens: no datastore connected, or
+// the events table not provisioned yet (the emitter is still being wired) → the
+// real empty list, NEVER a fabricated fleet. admin creates NO table (the datastore
+// stream owns hanzo.compute_usage). Money is USD cents end to end.
+
+import (
+	"context"
+	"strings"
+	"time"
+
+	aiobject "github.com/hanzoai/ai/object"
+	"github.com/hanzoai/cloud"
+	"github.com/hanzoai/cloud/clients/admin/core"
+	"github.com/zap-proto/zip"
+)
+
+// computeTable is the operator-owned compute-usage warehouse table (named to match
+// the existing hanzo.cloud_usage convention; the visor/commerce emitter writes it).
+// admin only READS it (never creates it — mirrors how analytics treats hanzo.events).
+const computeTable = "hanzo.compute_usage"
+
+// terminalComputeEvents are the lifecycle events whose LATEST occurrence means a
+// machine is no longer running (mirrors the console foldEvents terminal set). A
+// CLOSED server-side constant — never user input — so rendering it into the argMax
+// check is injection-safe.
+var terminalComputeEvents = []string{
+	"stop", "stopped", "destroy", "destroyed", "terminate", "terminated",
+	"delete", "deleted", "off", "shutdown", "expire", "expired",
+}
+
+// computeLeaf is one (org, app, project, kind) rollup: distinct machines of that
+// kind, how many are currently active (latest event non-terminal), the billed
+// spend over the window, and the most recent event. The console folds these into
+// the org → app → project tree.
+type computeLeaf struct {
+	Org        string `json:"org"`
+	App        string `json:"app"`
+	Project    string `json:"project"`
+	Kind       string `json:"kind"`
+	Machines   int64  `json:"machines"`
+	Active     int64  `json:"active"`
+	SpendCents int64  `json:"spendCents"`
+	LastTs     string `json:"lastTs"`
+}
+
+// compute answers GET /v1/admin/compute. ?kind=<kind> and ?org= narrow the
+// aggregate; ?range=24h|7d|30d bounds it (default 30d). SuperAdmin only.
+func compute(s *cloud.Service[core.State], c *zip.Ctx) error {
+	ctx := c.Context()
+	// Honest-empty when the warehouse is not connected or the usage table is not
+	// provisioned yet (the visor/commerce emitter is still being wired).
+	if !aiobject.DatastoreEnabled() || !computeTableExists(ctx) {
+		return core.OKList(c, []computeLeaf{}, 0)
+	}
+
+	// `kind` is an OPEN LowCardinality spectrum (bot | machine | cluster | nodepool |
+	// container | function | …), matched as a PLAIN STRING — no enum assumption. Each
+	// console lens passes its own kind; empty = all kinds. Case-normalized to the
+	// warehouse's lower-case convention.
+	kind := strings.ToLower(strings.TrimSpace(c.Query("kind")))
+	sql, args := buildComputeQuery(c.Query("range"), kind, strings.TrimSpace(c.Query("org")))
+	rows, err := aiobject.DatastoreQuery(ctx, sql, args...)
+	if err != nil {
+		return core.Fail(c, "compute query: "+err.Error())
+	}
+	leaves := computeLeavesFromRows(rows)
+	return core.OKList(c, leaves, len(leaves))
+}
+
+// buildComputeQuery assembles the two-level roll-up (pure, so it is unit-tested).
+// The inner query resolves each machine's LATEST lifecycle state (argMax event by
+// ts) + its billed spend; the outer counts machines, counts the still-active ones,
+// and sums spend per (org, app, project, kind). `kind` is a PLAIN STRING over an
+// open LowCardinality spectrum (no enum assumption; any non-empty value filters) and
+// the terminal set is a constant, so nothing user-derived is interpolated — org,
+// kind, and the time bound are all POSITIONAL parameters.
+func buildComputeQuery(rangeLabel, kind, org string) (string, []any) {
+	where := "ts >= ?"
+	args := []any{chTS(computeSince(rangeLabel))}
+	if kind != "" {
+		where += " AND kind = ?"
+		args = append(args, kind)
+	}
+	if org != "" {
+		where += " AND org = ?"
+		args = append(args, org)
+	}
+	sql := "SELECT org, app, project, kind, " +
+		"count() AS machines, countIf(active) AS active, sum(spend) AS spend_cents, max(last_ts) AS last_ts " +
+		"FROM (SELECT org, app, project, kind, machine_id, " +
+		"sum(price_cents) AS spend, max(ts) AS last_ts, " +
+		"argMax(event, ts) NOT IN (" + terminalComputeSQL() + ") AS active " +
+		"FROM " + computeTable + " WHERE " + where + " " +
+		"GROUP BY org, app, project, kind, machine_id) " +
+		"GROUP BY org, app, project, kind ORDER BY spend_cents DESC"
+	return sql, args
+}
+
+// computeLeavesFromRows maps the DatastoreQuery rows onto []computeLeaf (pure).
+func computeLeavesFromRows(rows []map[string]any) []computeLeaf {
+	leaves := make([]computeLeaf, 0, len(rows))
+	for _, r := range rows {
+		leaves = append(leaves, computeLeaf{
+			Org:        chStr(r["org"]),
+			App:        chStr(r["app"]),
+			Project:    chStr(r["project"]),
+			Kind:       chStr(r["kind"]),
+			Machines:   chInt64(r["machines"]),
+			Active:     chInt64(r["active"]),
+			SpendCents: chInt64(r["spend_cents"]),
+			LastTs:     chTime(r["last_ts"]),
+		})
+	}
+	return leaves
+}
+
+// computeTableExists probes for the operator-owned events table. Any error → false
+// (honest "not available yet"), mirroring analytics.tableExists.
+func computeTableExists(ctx context.Context) bool {
+	rows, err := aiobject.DatastoreQuery(ctx, "EXISTS TABLE "+computeTable)
+	if err != nil || len(rows) == 0 {
+		return false
+	}
+	for _, v := range rows[0] {
+		return chInt64(v) == 1
+	}
+	return false
+}
+
+// computeSince maps the ?range enum to a lower time bound (default 30d).
+func computeSince(rangeLabel string) time.Time {
+	now := time.Now().UTC()
+	switch strings.TrimSpace(rangeLabel) {
+	case "24h":
+		return now.Add(-24 * time.Hour)
+	case "7d":
+		return now.Add(-7 * 24 * time.Hour)
+	default:
+		return now.Add(-30 * 24 * time.Hour)
+	}
+}
+
+// terminalComputeSQL renders the terminal-event set as a datastore string list.
+func terminalComputeSQL() string {
+	quoted := make([]string, len(terminalComputeEvents))
+	for i, e := range terminalComputeEvents {
+		quoted[i] = "'" + e + "'"
+	}
+	return strings.Join(quoted, ",")
+}
+
+// chTS formats a time as a datastore DateTime literal (UTC), bound as a string arg.
+func chTS(t time.Time) string { return t.UTC().Format("2006-01-02 15:04:05") }
+
+// ── map[string]any coercers (the DatastoreQuery row shape) ───────────────────
+//
+// The datastore driver decodes each column to its native Go type (uint64 for
+// count()/sum(UInt*), time.Time for DateTime, string for String); these accept
+// those natives so a driver/transport change can't crash a read.
+
+func chInt64(v any) int64 {
+	switch n := v.(type) {
+	case int:
+		return int64(n)
+	case int64:
+		return n
+	case int32:
+		return int64(n)
+	case uint:
+		return int64(n)
+	case uint64:
+		return int64(n)
+	case uint32:
+		return int64(n)
+	case uint16:
+		return int64(n)
+	case uint8:
+		return int64(n)
+	case float64:
+		return int64(n)
+	case float32:
+		return int64(n)
+	default:
+		return 0
+	}
+}
+
+func chStr(v any) string {
+	if s, ok := v.(string); ok {
+		return s
+	}
+	return ""
+}
+
+// chTime coerces a datastore DateTime (time.Time) to an RFC3339 UTC string.
+func chTime(v any) string {
+	switch t := v.(type) {
+	case time.Time:
+		return t.UTC().Format(time.RFC3339)
+	case string:
+		return t
+	default:
+		return ""
+	}
+}

clients/admin/compute_test.go

@@ -0,0 +1,143 @@
+// Copyright 2023-2026 Hanzo AI Inc. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package admin
+
+import (
+	"strings"
+	"testing"
+	"time"
+)
+
+// TestBuildComputeQuery_Filters proves the WHERE clause binds the range, and adds
+// kind + org as POSITIONAL params only when supplied — never interpolated.
+func TestBuildComputeQuery_Filters(t *testing.T) {
+	// Unfiltered: time bound only.
+	sql, args := buildComputeQuery("30d", "", "")
+	if len(args) != 1 {
+		t.Fatalf("unfiltered args = %d, want 1 (time bound)", len(args))
+	}
+	// Reads the real table the datastore stream + visor emitter write.
+	if !strings.Contains(sql, "FROM hanzo.compute_usage") {
+		t.Errorf("query must read hanzo.compute_usage; got %q", sql)
+	}
+	if !strings.Contains(sql, "GROUP BY org, app, project, kind") {
+		t.Errorf("query must group by (org, app, project, kind); got %q", sql)
+	}
+	if strings.Contains(sql, "AND kind = ?") || strings.Contains(sql, "AND org = ?") {
+		t.Errorf("unfiltered query must not add kind/org predicates; got %q", sql)
+	}
+
+	// kind=bot + org: two extra bound params, in order.
+	sql, args = buildComputeQuery("7d", "bot", "acme")
+	if len(args) != 3 {
+		t.Fatalf("kind+org args = %d, want 3", len(args))
+	}
+	if args[1] != "bot" || args[2] != "acme" {
+		t.Errorf("args = %v, want [<ts> bot acme]", args)
+	}
+	if !strings.Contains(sql, "AND kind = ?") || !strings.Contains(sql, "AND org = ?") {
+		t.Errorf("filtered query must bind kind + org; got %q", sql)
+	}
+
+	// OPEN SPECTRUM: an arbitrary kind (not bot/machine) filters too — no enum
+	// whitelist. Future Clusters/Functions lenses reuse this endpoint unchanged.
+	sql, args = buildComputeQuery("30d", "cluster", "")
+	if len(args) != 2 || args[1] != "cluster" {
+		t.Fatalf("kind=cluster args = %v, want [<ts> cluster]", args)
+	}
+	if !strings.Contains(sql, "AND kind = ?") {
+		t.Errorf("an arbitrary kind must still bind the kind predicate; got %q", sql)
+	}
+}
+
+// TestComputeSince maps the range enum to a lower time bound (default 30d).
+func TestComputeSince(t *testing.T) {
+	now := time.Now().UTC()
+	cases := map[string]time.Duration{
+		"24h": 24 * time.Hour,
+		"7d":  7 * 24 * time.Hour,
+		"30d": 30 * 24 * time.Hour,
+		"":    30 * 24 * time.Hour, // default
+		"xyz": 30 * 24 * time.Hour, // unknown → default
+	}
+	for label, want := range cases {
+		got := now.Sub(computeSince(label))
+		if d := got - want; d < -2*time.Second || d > 2*time.Second {
+			t.Errorf("computeSince(%q) lookback = %v, want ≈%v", label, got, want)
+		}
+	}
+}
+
+// TestTerminalComputeSQL renders the terminal set as a quoted CH list.
+func TestTerminalComputeSQL(t *testing.T) {
+	got := terminalComputeSQL()
+	for _, e := range []string{"'stop'", "'destroy'", "'terminated'", "'shutdown'"} {
+		if !strings.Contains(got, e) {
+			t.Errorf("terminal list missing %s; got %q", e, got)
+		}
+	}
+	if strings.Contains(got, "'start'") || strings.Contains(got, "'provision'") {
+		t.Errorf("terminal list must NOT include running states; got %q", got)
+	}
+}
+
+// TestComputeLeavesFromRows maps the driver's native row types (uint64 counts,
+// time.Time DateTime, string dims) onto typed leaves — the honest-empty and the
+// real-row paths both.
+func TestComputeLeavesFromRows(t *testing.T) {
+	if got := computeLeavesFromRows(nil); len(got) != 0 {
+		t.Fatalf("nil rows → %d leaves, want 0", len(got))
+	}
+	ts := time.Date(2026, 7, 1, 12, 0, 0, 0, time.UTC)
+	rows := []map[string]any{
+		{
+			"org": "acme", "app": "web", "project": "prod", "kind": "machine",
+			"machines": uint64(4), "active": uint64(3), "spend_cents": uint64(1200), "last_ts": ts,
+		},
+	}
+	got := computeLeavesFromRows(rows)
+	if len(got) != 1 {
+		t.Fatalf("rows → %d leaves, want 1", len(got))
+	}
+	l := got[0]
+	if l.Org != "acme" || l.App != "web" || l.Project != "prod" || l.Kind != "machine" {
+		t.Errorf("dims wrong: %+v", l)
+	}
+	if l.Machines != 4 || l.Active != 3 || l.SpendCents != 1200 {
+		t.Errorf("counts wrong: %+v", l)
+	}
+	if l.LastTs != "2026-07-01T12:00:00Z" {
+		t.Errorf("lastTs = %q, want 2026-07-01T12:00:00Z", l.LastTs)
+	}
+}
+
+// TestComputeCoercers proves the map coercers accept the driver natives + degrade.
+func TestComputeCoercers(t *testing.T) {
+	if chInt64(uint64(7)) != 7 || chInt64(int64(7)) != 7 || chInt64(float64(7)) != 7 {
+		t.Error("chInt64 must accept uint64/int64/float64")
+	}
+	if chInt64("nope") != 0 || chInt64(nil) != 0 {
+		t.Error("chInt64 must degrade non-numerics to 0")
+	}
+	if chStr("x") != "x" || chStr(42) != "" {
+		t.Error("chStr must pass strings, degrade others to empty")
+	}
+	if chTime(time.Date(2026, 1, 2, 3, 4, 5, 0, time.UTC)) != "2026-01-02T03:04:05Z" {
+		t.Error("chTime must format time.Time as RFC3339 UTC")
+	}
+	if chTime(123) != "" {
+		t.Error("chTime must degrade non-time to empty")
+	}
+}

clients/admin/core/activity.go

@@ -0,0 +1,215 @@
+package core
+
+// The fleet ACTIVITY + TIME-SERIES model, shared by the analytics board and the revenue
+// board (one implementation, DRY): real per-customer signup + usage folded into a pure
+// activity value, and the continuous bucketed spend series both boards render.
+
+import (
+	"context"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/hanzoai/cloud"
+	"github.com/hanzoai/cloud/clients/admin/iam"
+)
+
+// SeriesPoint is one bucketed point (count OR cents, per the series). T is the bucket
+// key (RFC3339 date / "2006-01" month).
+type SeriesPoint struct {
+	T     string `json:"t"`
+	Value int64  `json:"value"`
+}
+
+// TxnPoint is one dated usage event (a commerce `withdraw`, in cents).
+type TxnPoint struct {
+	T     time.Time
+	Cents int64
+}
+
+// CustActivity is one customer's real analytics input: when they signed up (IAM
+// createdTime) and their consumption events (commerce withdraws). Deposits are NOT
+// activity (a credit grant is not the customer using the product), so only withdraws
+// feed active/retention/churn/usage — the honest "used it" signal.
+type CustActivity struct {
+	Org        string
+	Display    string
+	Created    time.Time
+	HasCreated bool
+	Usage      []TxnPoint
+	SpendCents int64
+}
+
+// ActiveIn reports whether the customer had a usage event in the given bucket.
+func (ca CustActivity) ActiveIn(bucket string, interval string) bool {
+	for _, p := range ca.Usage {
+		if BucketKeyOf(p.T, interval) == bucket {
+			return true
+		}
+	}
+	return false
+}
+
+// ActiveSince reports whether the customer had a usage event at or after cut.
+func (ca CustActivity) ActiveSince(cut time.Time) bool {
+	for _, p := range ca.Usage {
+		if !p.T.Before(cut) {
+			return true
+		}
+	}
+	return false
+}
+
+// FleetActivity reads every org's signup time (already on the org row) + usage ledger,
+// folded into the pure activity model. Returns (acts, ok) where ok is false if ANY org's
+// ledger read failed (the caller marks the source degraded and flags the ledger-backed
+// metrics as not-fully-computed). Fanned out concurrently with a bound.
+func FleetActivity(s *cloud.Service[State], ctx context.Context, orgs []iam.Org) ([]CustActivity, bool) {
+	acts := make([]CustActivity, len(orgs))
+	oks := make([]bool, len(orgs))
+	sem := make(chan struct{}, MaxCustomerConcurrency)
+	var wg sync.WaitGroup
+	for i, o := range orgs {
+		wg.Add(1)
+		sem <- struct{}{}
+		go func(i int, o iam.Org) {
+			defer wg.Done()
+			defer func() { <-sem }()
+			ca := CustActivity{Org: o.Name, Display: Display(o.DisplayName, o.Name)}
+			if t, err := time.Parse(time.RFC3339, o.CreatedTime); err == nil {
+				ca.Created = t.UTC()
+				ca.HasCreated = true
+			}
+			rows, err := s.State.Commerce.Ledger(ctx, o.Name, 2000)
+			oks[i] = err == nil
+			for _, r := range rows {
+				if strings.ToLower(r.Kind) != "withdraw" {
+					continue // only consumption is "activity"; deposits are credits
+				}
+				t, perr := ParseTxnTime(r.At)
+				if perr != nil {
+					continue
+				}
+				amt := int64(r.Amount)
+				if amt < 0 {
+					amt = -amt
+				}
+				ca.Usage = append(ca.Usage, TxnPoint{T: t, Cents: amt})
+				ca.SpendCents += amt
+			}
+			acts[i] = ca
+		}(i, o)
+	}
+	wg.Wait()
+	allOK := true
+	for _, ok := range oks {
+		if !ok {
+			allOK = false
+			break
+		}
+	}
+	return acts, allOK
+}
+
+// SpendSeries buckets fleet usage cents into a continuous series over since..now. Shared
+// by the analytics usage/revenue trend and the revenue board's spend trend (one
+// implementation, DRY). A bucket with no usage is an honest 0, not a gap.
+func SpendSeries(acts []CustActivity, since, now time.Time, interval string) []SeriesPoint {
+	buckets := EnumerateBuckets(since, now, interval)
+	idx := IndexOf(buckets)
+	out := make([]SeriesPoint, len(buckets))
+	for i, b := range buckets {
+		out[i] = SeriesPoint{T: b}
+	}
+	for _, a := range acts {
+		for _, p := range a.Usage {
+			if p.T.Before(since) || p.T.After(now) {
+				continue
+			}
+			if i, ok := idx[BucketKeyOf(p.T, interval)]; ok {
+				out[i].Value += p.Cents
+			}
+		}
+	}
+	return out
+}
+
+// ── pure time-bucket helpers ─────────────────────────────────────────────────
+
+func MonthKey(t time.Time) string { return t.UTC().Format("2006-01") }
+func DayKey(t time.Time) string   { return t.UTC().Format("2006-01-02") }
+
+// WeekKey buckets to the ISO week's Monday (a stable weekly key).
+func WeekKey(t time.Time) string {
+	u := t.UTC()
+	// back up to Monday
+	wd := int(u.Weekday())
+	if wd == 0 {
+		wd = 7
+	}
+	monday := u.AddDate(0, 0, -(wd - 1))
+	return monday.Format("2006-01-02")
+}
+
+func BucketKeyOf(t time.Time, interval string) string {
+	switch interval {
+	case "month":
+		return MonthKey(t)
+	case "week":
+		return WeekKey(t)
+	default:
+		return DayKey(t)
+	}
+}
+
+// EnumerateBuckets lists every bucket key from since..now inclusive so a series has a
+// continuous axis (a zero-usage bucket is an honest 0, not a gap).
+func EnumerateBuckets(since, now time.Time, interval string) []string {
+	if since.After(now) {
+		return nil
+	}
+	var out []string
+	seen := map[string]bool{}
+	step := func(t time.Time) time.Time {
+		switch interval {
+		case "month":
+			return t.AddDate(0, 1, 0)
+		case "week":
+			return t.AddDate(0, 0, 7)
+		default:
+			return t.AddDate(0, 0, 1)
+		}
+	}
+	// cap iterations so a bad range can never spin unbounded
+	for t, n := since, 0; !t.After(now) && n < 800; t, n = step(t), n+1 {
+		k := BucketKeyOf(t, interval)
+		if !seen[k] {
+			seen[k] = true
+			out = append(out, k)
+		}
+	}
+	// ensure the final bucket (now) is present
+	last := BucketKeyOf(now, interval)
+	if !seen[last] {
+		out = append(out, last)
+	}
+	return out
+}
+
+// IndexOf maps each bucket key to its position for O(1) fold-in.
+func IndexOf(buckets []string) map[string]int {
+	m := make(map[string]int, len(buckets))
+	for i, b := range buckets {
+		m[b] = i
+	}
+	return m
+}
+
+// ParseTxnTime accepts the commerce ledger's RFC3339 forms.
+func ParseTxnTime(s string) (time.Time, error) {
+	s = strings.TrimSpace(s)
+	if t, err := time.Parse(time.RFC3339, s); err == nil {
+		return t.UTC(), nil
+	}
+	return time.Parse("2006-01-02T15:04:05Z", s)
+}

clients/admin/core/envelope.go

@@ -0,0 +1,36 @@
+package core
+
+import (
+	"encoding/json"
+
+	"github.com/zap-proto/zip"
+)
+
+// The /v1 envelope writers { status, msg, data, data2 } the operator's transport
+// decodes (get<T> reads data; getList<T> reads data + data2 total).
+
+// OK writes a { status:"ok", data } envelope (the get<T> shape).
+func OK(c *zip.Ctx, data any) error {
+	return c.JSON(200, map[string]any{"status": "ok", "msg": "", "data": data})
+}
+
+// OKList writes a { status:"ok", data:[...], data2:total } envelope (getList<T>).
+func OKList(c *zip.Ctx, rows any, total int) error {
+	return c.JSON(200, map[string]any{"status": "ok", "msg": "", "data": rows, "data2": total})
+}
+
+// OKRaw writes a { status:"ok", data:<raw>, data2:total } envelope, forwarding an
+// IAM payload verbatim so its exact wire shape (Role, Application, Record, User)
+// reaches the operator field-for-field.
+func OKRaw(c *zip.Ctx, rows json.RawMessage, total int) error {
+	if len(rows) == 0 {
+		rows = json.RawMessage("[]")
+	}
+	return c.JSON(200, map[string]any{"status": "ok", "msg": "", "data": rows, "data2": total})
+}
+
+// Fail writes a { status:"error", msg } envelope. The operator's transport maps a
+// non-ok envelope to a surfaced error (never a fabricated value).
+func Fail(c *zip.Ctx, msg string) error {
+	return c.JSON(200, map[string]any{"status": "error", "msg": msg, "data": nil})
+}

clients/admin/core/fanin.go

@@ -0,0 +1,80 @@
+package core
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/url"
+	"strings"
+
+	"github.com/hanzoai/cloud"
+	"github.com/hanzoai/cloud/clients/admin/iam"
+)
+
+// MaxCustomerConcurrency bounds the per-org enrichment fan-out so a large fleet does
+// not open one upstream connection per org at once. Admin is low-QPS; 8 keeps latency
+// low without hammering IAM/commerce.
+const MaxCustomerConcurrency = 8
+
+// ListOrgs reads the org directory (owner = admin org) as the typed shape the
+// overview/orgs/usage/customer/revenue/finance aggregators fold over.
+func ListOrgs(s *cloud.Service[State], ctx context.Context, cr iam.Creds) ([]iam.Org, error) {
+	q := url.Values{}
+	q.Set("owner", s.State.AdminOrg)
+	res, err := s.State.IAM.Orgs(ctx, cr, q)
+	if err != nil {
+		return nil, err
+	}
+	var orgs []iam.Org
+	if len(res.Rows) > 0 {
+		if err := json.Unmarshal(res.Rows, &orgs); err != nil {
+			return nil, fmt.Errorf("orgs decode: %w", err)
+		}
+	}
+	return orgs, nil
+}
+
+// OrgMoney returns (spendCents, creditsCents, ok) for one org from commerce. ok is
+// false when the spend OR credits read FAILED — so a fleet aggregator can fold the
+// per-org failure into a PARTIAL/degraded source rather than presenting the resulting
+// undercount as authoritative (the SAME (row, ok) contract revenue.revenueOf uses). An
+// unwired commerce is NOT a failure: Spend/Credits return (0, nil) when unconfigured, so
+// ok stays true and the caller distinguishes "not configured" via Commerce.Ready().
+func OrgMoney(s *cloud.Service[State], ctx context.Context, org string) (spend, credits int64, ok bool) {
+	ok = true
+	if sp, err := s.State.Commerce.Spend(ctx, org); err == nil {
+		spend = int64(sp.Consumed)
+	} else {
+		ok = false
+	}
+	if c, err := s.State.Commerce.Credits(ctx, org); err == nil {
+		credits = int64(c)
+	} else {
+		ok = false
+	}
+	return spend, credits, ok
+}
+
+// FindOrg returns the IAM org by slug (nil, nil when it does not exist) so a management
+// action can validate its target before acting — never credit or suspend an org that
+// isn't real.
+func FindOrg(s *cloud.Service[State], ctx context.Context, cr iam.Creds, org string) (*iam.Org, error) {
+	orgs, err := ListOrgs(s, ctx, cr)
+	if err != nil {
+		return nil, err
+	}
+	for i := range orgs {
+		if orgs[i].Name == org {
+			return &orgs[i], nil
+		}
+	}
+	return nil, nil
+}
+
+// Display returns displayName when non-blank, else the fallback.
+func Display(displayName, fallback string) string {
+	if strings.TrimSpace(displayName) != "" {
+		return displayName
+	}
+	return fallback
+}

clients/admin/core/gate.go

@@ -0,0 +1,62 @@
+package core
+
+import (
+	"github.com/hanzoai/cloud"
+	"github.com/hanzoai/cloud/clients/admin/iam"
+	"github.com/hanzoai/cloud/clients/principal"
+	"github.com/zap-proto/zip"
+)
+
+// Handler is the admin handler shape: a free function over the shared kernel. Every
+// domain handler is `func h(s *cloud.Service[core.State], c *zip.Ctx) error`.
+type Handler = func(*cloud.Service[State], *zip.Ctx) error
+
+// Guard wraps a handler with the SuperAdmin gate. Fail-closed: any request whose
+// validated identity is not a SuperAdmin (X-User-IsAdmin != "true", which
+// SanitizeIdentity sets only for owner == AdminOrg) is refused 403 before the handler
+// — no upstream is touched, no data leaks.
+func Guard(s *cloud.Service[State], h Handler) zip.Handler {
+	return func(c *zip.Ctx) error {
+		if !c.IsAdmin() {
+			return zip.ErrForbidden("SuperAdmin required")
+		}
+		return h(s, c)
+	}
+}
+
+// GuardScoped is the gate for the ORG-SCOPED panels (me/overview/orgs/users/usage/
+// analytics/bases). It admits a SuperAdmin (principal.IsSuperAdmin) OR an ORG admin
+// (an admin of their OWN org — principal.IsOrgAdmin) pinned to a validated org, and the
+// handler then scopes every read to ResolveScope(c) — so a non-super caller passes the
+// gate but the DATA layer hard-limits them to their own org subtree. Cross-tenant reads
+// are impossible for a non-super caller regardless of input.
+//
+// The non-super admission requires BOTH the sanitizer-minted X-User-IsOrgAdmin
+// (principal.IsOrgAdmin — the "admin of my own org" bit, unforgeable because the boundary
+// strips it on ingress) AND a validated principal pinned to its own org (principal.Org,
+// the ONE org accessor: validated X-User-Id + non-empty in-bounds X-Org-Id). So a
+// validated but NON-admin MEMBER of an org is
+// REFUSED here — the same denial an anonymous caller who forged X-Org-Id gets — closing
+// the same-tenant over-visibility gap where any org member could read their org's admin
+// panels. A validated non-super principal's X-Org-Id is PINNED by the boundary to their
+// own owner, never client-chosen.
+func GuardScoped(s *cloud.Service[State], h Handler) zip.Handler {
+	return func(c *zip.Ctx) error {
+		if principal.IsSuperAdmin(c) {
+			return h(s, c) // SuperAdmin: cross-tenant, admitted regardless of org pin.
+		}
+		if _, ok := principal.Org(c); ok && principal.IsOrgAdmin(c) {
+			return h(s, c)
+		}
+		return zip.ErrForbidden("admin required")
+	}
+}
+
+// CallerCreds captures the caller's replayed authorization context for the IAM
+// fan-out: the raw Cookie header (session model) and the Authorization bearer.
+func CallerCreds(c *zip.Ctx) iam.Creds {
+	return iam.Creds{
+		Cookie: string(c.Fiber().Request().Header.Peek("Cookie")),
+		Auth:   c.Header("Authorization"),
+	}
+}

clients/admin/core/grant.go

@@ -0,0 +1,211 @@
+package core
+
+// The ONE credit-write path + the ONE tamper-evident audit emit. ApplyGrant is the
+// single core shared by POST /v1/admin/customers/:org/credit (org from the path) and
+// POST /v1/admin/grants (org from the body): validate the amount + target org, deposit
+// into the org's commerce ledger (trial vs prepaid by source), and record the audit
+// row. One path, one way to grant.
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"strconv"
+	"strings"
+
+	"github.com/hanzoai/cloud"
+	"github.com/hanzoai/cloud/audit"
+	"github.com/hanzoai/cloud/clients/admin/money"
+	"github.com/hanzoai/cloud/clients/principal"
+	"github.com/zap-proto/zip"
+)
+
+// CreditRequest is the grant body. AmountCents is the credit to add (positive only — a
+// grant, never a silent debit). Reason is the operator's justification, recorded in the
+// audit trail's before/after (refund / comp / support).
+type CreditRequest struct {
+	AmountCents int64  `json:"amountCents"`
+	Currency    string `json:"currency"`
+	Reason      string `json:"reason"`
+	// Source splits the grant into the commerce ledger's two money buckets:
+	//   - "trial"   (default) — a non-cash promo/comp credit: spendable on non-premium
+	//                metered usage only, NEVER refundable cash and NEVER paid out.
+	//   - "prepaid" — real money added to the customer's cash balance. Refundable,
+	//                GPU-eligible.
+	// Unknown/empty → trial (fail-closed to non-cash).
+	Source string `json:"source"`
+}
+
+// maxGrantCents caps a single grant at $100,000 — a guardrail against a fat-finger
+// operator credit, not a policy limit. The cap keeps a typo from minting a fortune.
+const maxGrantCents int64 = 100 * 100 * 1000
+
+// grantTag maps a grant source to the commerce deposit Tags that billing/bucket
+// DepositKind classifies into Credit (trial) vs Prepaid (real money). Default
+// (empty/unknown/"trial") is the non-cash Credit bucket — a staff comp is never
+// silently minted as payout-able real money.
+func grantTag(source string) (tag, normalized string) {
+	if strings.ToLower(strings.TrimSpace(source)) == "prepaid" {
+		return "admin-grant", "prepaid" // DepositKind: bare → Prepaid (real money)
+	}
+	return "grant:admin", "trial" // DepositKind: grant:* → Credit (non-cash trial)
+}
+
+// grantNote composes the deposit note from the operator's reason (bounded), so the
+// commerce ledger row itself carries the justification alongside the audit trail.
+func grantNote(c *zip.Ctx, reason string) string {
+	r := strings.TrimSpace(reason)
+	if len(r) > 200 {
+		r = r[:200]
+	}
+	by := strings.TrimSpace(c.UserEmail())
+	if by == "" {
+		by = strings.TrimSpace(c.User())
+	}
+	if r == "" {
+		r = "operator credit"
+	}
+	if by != "" {
+		return fmt.Sprintf("Admin grant by %s: %s", by, r)
+	}
+	return "Admin grant: " + r
+}
+
+// grantIdempotencyKey derives the DETERMINISTIC commerce idempotency key for a grant from
+// its (org, amount, currency, source) BOUND to the operator-supplied Idempotency-Key nonce
+// — so a retried grant (a commit-then-timeout re-submit carrying the SAME nonce) dedupes at
+// commerce (X-Idempotency-Key, at-most-once), while two DISTINCT grants — even same org +
+// amount — never collide. Binding the amount/currency/source into the hash means a nonce
+// accidentally reused for a DIFFERENT grant still lands (a different key), so dedup can
+// never silently DROP a legitimate distinct grant.
+//
+// Empty when the operator supplied no nonce: without a stable per-attempt id there is no
+// value that is both retry-stable AND grant-unique, so we do NOT fabricate one (a content
+// -only hash would wrongly dedupe two legitimate identical comps). The deposit is then
+// additive — the pre-existing behavior. Effective end-to-end once the operator console
+// sends an Idempotency-Key per grant attempt (reused verbatim on retry); commerce already
+// enforces the dedup (api/billing/deposit.go).
+func grantIdempotencyKey(c *zip.Ctx, org, currency, source string, amountCents int64) string {
+	nonce := strings.TrimSpace(c.Header("Idempotency-Key"))
+	if nonce == "" {
+		nonce = strings.TrimSpace(c.Header("X-Idempotency-Key"))
+	}
+	if nonce == "" {
+		return ""
+	}
+	sum := sha256.Sum256([]byte(strings.Join([]string{
+		org, strconv.FormatInt(amountCents, 10), currency, source, nonce,
+	}, "|")))
+	return "grant-" + hex.EncodeToString(sum[:])
+}
+
+// ApplyGrant validates the amount + target org, deposits into the org's commerce ledger
+// (trial vs prepaid by source), and records the tamper-evident audit row. One path, one
+// way to grant.
+func ApplyGrant(s *cloud.Service[State], c *zip.Ctx, org string, req CreditRequest) error {
+	ctx := c.Context()
+	cr := CallerCreds(c)
+	if req.AmountCents <= 0 {
+		return Fail(c, "amountCents must be positive")
+	}
+	if req.AmountCents > maxGrantCents {
+		return Fail(c, fmt.Sprintf("amountCents exceeds the %d-cent per-grant cap", maxGrantCents))
+	}
+	currency := strings.ToLower(strings.TrimSpace(req.Currency))
+	if currency == "" {
+		currency = "usd"
+	}
+
+	// Validate the target is a REAL org (never mint an orphan wallet on a typo).
+	o, err := FindOrg(s, ctx, cr, org)
+	if err != nil {
+		return Fail(c, err.Error())
+	}
+	if o == nil {
+		return c.JSON(404, map[string]any{"status": "error", "msg": "customer not found", "data": nil})
+	}
+
+	// FAIL-CLOSED durability (SOC2 AU-2/AU-5): a credit grant moves REAL money and MUST
+	// leave a durable, tamper-evident record. If this deployment has no audit store to
+	// record into, REFUSE the grant BEFORE any money moves — never an unaudited money
+	// move. A nil store is not a production state: cloud requires a persistent data dir
+	// for the trail (audit_serve.go), and nil arises only from the explicit
+	// CLOUD_AUDIT_DISABLED dev opt-out, on which moving money is not a supported op.
+	if s.State.AuditStore == nil {
+		return c.JSON(503, map[string]any{"status": "error", "msg": "grant refused: no durable audit store is configured on this deployment; a credit grant must be recorded before money moves", "data": nil})
+	}
+
+	before, _ := s.State.Commerce.Credits(ctx, org)
+
+	tag, source := grantTag(req.Source)
+	notes := grantNote(c, req.Reason)
+	idem := grantIdempotencyKey(c, org, currency, source, req.AmountCents)
+	res, derr := s.State.Commerce.Deposit(ctx, org, money.Cents(req.AmountCents), currency, notes, tag, idem)
+	if derr != nil {
+		// The grant did not land — record the FAILED attempt (accountability), then
+		// surface the error. Never report a grant that failed as success.
+		EmitAudit(s, c, "admin.customer.credit", "credit", org,
+			map[string]any{"balanceCents": before},
+			map[string]any{"amountCents": req.AmountCents, "currency": currency, "reason": req.Reason, "source": source, "error": derr.Error()},
+			audit.Outcome{Result: "error", Status: 200, Reason: "grant failed"})
+		return Fail(c, "grant failed: "+derr.Error())
+	}
+
+	after, _ := s.State.Commerce.Credits(ctx, org)
+	EmitAudit(s, c, "admin.customer.credit", "credit", org,
+		map[string]any{"balanceCents": before},
+		map[string]any{"balanceCents": after, "grantedCents": req.AmountCents, "currency": currency, "reason": req.Reason, "source": source, "transactionId": res.TxID},
+		audit.Outcome{Result: "success", Status: 200})
+
+	return OK(c, map[string]any{
+		"org":           org,
+		"grantedCents":  req.AmountCents,
+		"currency":      currency,
+		"source":        source,
+		"balanceCents":  after,
+		"transactionId": res.TxID,
+	})
+}
+
+// EmitAudit writes ONE compliance record for a management action to cloud's
+// tamper-evident trail: who (the validated SuperAdmin from the sanitized identity —
+// the gate already proved it), what (action + resource), the redacted before/after, and
+// the outcome. This is the "before/after on a config-affecting change" the request-level
+// middleware record cannot carry (it never reads bodies). Best-effort: a failure here is
+// logged loud, never silent, and never double-fails the response. A nil store
+// (unconfigured deployment) is a no-op, like the middleware.
+func EmitAudit(s *cloud.Service[State], c *zip.Ctx, action, resType, resID string, before, after any, outcome audit.Outcome) {
+	if s.State.AuditStore == nil {
+		return
+	}
+	org, _ := principal.Org(c)
+	rec := audit.Record{
+		Actor:     audit.Actor{Org: org, Sub: strings.TrimSpace(c.User()), Email: strings.TrimSpace(c.UserEmail())},
+		Action:    action,
+		Resource:  audit.Resource{Type: resType, ID: resID},
+		Auth:      audit.AuthContext{Method: "jwt", IsAdmin: c.IsAdmin()},
+		Outcome:   outcome,
+		UserAgent: c.Header("User-Agent"),
+		RequestID: c.RequestID(),
+		Method:    c.Method(),
+		Path:      c.Path(),
+		Before:    audit.Redact(mustJSON(before)),
+		After:     audit.Redact(mustJSON(after)),
+	}
+	if _, err := s.State.AuditStore.Append(c.Context(), rec); err != nil {
+		c.Log().Error("admin: audit emit failed (request-level record still applies)",
+			"action", action, "resource", resType, "id", resID, "err", err)
+	}
+}
+
+// mustJSON marshals v to raw JSON for the audit before/after, returning an empty object
+// on the (unexpected) marshal error rather than panicking — a metadata diff must never
+// crash a money/access action.
+func mustJSON(v any) json.RawMessage {
+	b, err := json.Marshal(v)
+	if err != nil {
+		return json.RawMessage("{}")
+	}
+	return b
+}

clients/admin/core/grant_test.go

@@ -0,0 +1,29 @@
+package core
+
+import "testing"
+
+// TestGrantTag pins the money-bucket mapping: a staff comp defaults to the non-cash
+// TRIAL (Credit) bucket, and ONLY an explicit "prepaid" mints real money. A tagging slip
+// must never silently create payout-able cash.
+func TestGrantTag(t *testing.T) {
+	cases := []struct {
+		source   string
+		wantTag  string
+		wantNorm string
+	}{
+		{"", "grant:admin", "trial"},          // default → trial (fail-closed non-cash)
+		{"trial", "grant:admin", "trial"},     // explicit trial
+		{"TRIAL", "grant:admin", "trial"},     // case-insensitive
+		{"  trial ", "grant:admin", "trial"},  // trimmed
+		{"comp", "grant:admin", "trial"},      // unknown → trial (never real money by accident)
+		{"prepaid", "admin-grant", "prepaid"}, // explicit real money
+		{"PREPAID", "admin-grant", "prepaid"}, // case-insensitive
+		{" prepaid", "admin-grant", "prepaid"},
+	}
+	for _, tc := range cases {
+		tag, norm := grantTag(tc.source)
+		if tag != tc.wantTag || norm != tc.wantNorm {
+			t.Errorf("grantTag(%q) = (%q,%q), want (%q,%q)", tc.source, tag, norm, tc.wantTag, tc.wantNorm)
+		}
+	}
+}

clients/admin/core/scope.go

@@ -0,0 +1,99 @@
+package core
+
+// The TENANT-SCOPE predicate — the ONE rule the whole cockpit obeys so admin.hanzo.ai
+// is a single pane for BOTH tiers off ONE identity primitive:
+//
+//	owner == the admin org  (SuperAdmin, c.IsAdmin())  ⇒ CROSS-TENANT: every org.
+//	any other validated admin caller                   ⇒ OWN SUBTREE: their org
+//	                                                      (+ the sub-orgs they own).
+//
+// Decomplected into exactly one place (ResolveScope + ScopedOrgs + Descendants) so no
+// handler re-derives it and the escalation line — a non-super caller reaching ANOTHER
+// tenant — cannot be crossed by any single panel.
+//
+// RECURSION SEAM (honest gap). The subtree is TODAY the singleton {org}: IAM's
+// Organization has NO parent-org / hierarchy field yet, so no tenant subtree exists to
+// walk. `Descendants` is the ONE function that becomes a parent-index BFS once IAM adds
+// the ParentOrg link — every scoped read composes over it, so recursion lands there and
+// nowhere else, with zero change to the callers.
+
+import (
+	"context"
+	"strings"
+
+	"github.com/hanzoai/cloud"
+	"github.com/hanzoai/cloud/clients/admin/iam"
+	"github.com/hanzoai/cloud/clients/principal"
+	"github.com/zap-proto/zip"
+)
+
+// TenantScope is a request's resolved visibility window. Super and Orgs are the two
+// mutually exclusive views: a SuperAdmin sees all tenants (Orgs ignored); anyone else
+// sees exactly Orgs (their own subtree).
+type TenantScope struct {
+	Super bool
+	Orgs  []string
+}
+
+// ScopedToOrg reports whether the scope admits reads for org o. Super admits every org;
+// a scoped caller admits only orgs in their subtree. Used by panels that filter an
+// upstream list (e.g. bases) rather than fanning out per-org.
+func (t TenantScope) ScopedToOrg(o string) bool {
+	if t.Super {
+		return true
+	}
+	o = strings.TrimSpace(o)
+	for _, s := range t.Orgs {
+		if s == o {
+			return true
+		}
+	}
+	return false
+}
+
+// ResolveScope derives the request's tenant window from the SANITIZED identity only —
+// never a client-forgeable field. A SuperAdmin (c.IsAdmin(), owner == admin org) is
+// cross-tenant; any other caller is pinned to the subtree of their own (sanitized) org.
+func ResolveScope(s *cloud.Service[State], c *zip.Ctx) TenantScope {
+	if c.IsAdmin() {
+		return TenantScope{Super: true}
+	}
+	org, ok := principal.Org(c)
+	if !ok {
+		return TenantScope{} // no validated principal/org ⇒ empty window ⇒ sees nothing
+	}
+	return TenantScope{Orgs: Descendants(s, org)}
+}
+
+// Descendants returns org + every sub-org it owns — the subtree the caller administers.
+// See the RECURSION SEAM note above: today the singleton {org}; the ONE place a future
+// IAM parent-org index is walked.
+func Descendants(s *cloud.Service[State], org string) []string {
+	org = strings.TrimSpace(org)
+	if org == "" {
+		return nil
+	}
+	return []string{org}
+}
+
+// ScopedOrgs is the ONE fan-in the org-scoped read panels (overview, orgs, usage,
+// analytics) fold over — enforcing the two-scope predicate in a single place. A
+// SuperAdmin gets EVERY org (the cross-tenant list); any other caller gets ONLY their
+// own subtree, each row read from IAM so the display name / createdTime are the REAL
+// values. An org row that can't be read best-effort degrades to a name-only row rather
+// than failing the panel — the scope is unaffected.
+func ScopedOrgs(s *cloud.Service[State], ctx context.Context, c *zip.Ctx, cr iam.Creds) ([]iam.Org, error) {
+	sc := ResolveScope(s, c)
+	if sc.Super {
+		return ListOrgs(s, ctx, cr)
+	}
+	rows := make([]iam.Org, 0, len(sc.Orgs))
+	for _, name := range sc.Orgs {
+		row := iam.Org{Owner: s.State.AdminOrg, Name: name, DisplayName: name}
+		if full, err := s.State.IAM.Org(ctx, cr, s.State.AdminOrg+"/"+name); err == nil && full.Name != "" {
+			row = full
+		}
+		rows = append(rows, row)
+	}
+	return rows, nil
+}

clients/admin/core/source.go

@@ -0,0 +1,28 @@
+package core
+
+import "errors"
+
+// ErrPartialRevenue marks a revenue read that succeeded at the org-list level but had
+// one or more per-org failures — the fleet total is real but PARTIAL. SrcOf reports it
+// as a not-ok source so the console shows a degraded state rather than presenting an
+// under-count as authoritative.
+var ErrPartialRevenue = errors.New("partial: one or more org revenue reads failed")
+
+// SourceStatus is the freshness of one upstream the aggregator pulls from
+// (overview.sources[] / revenue.sources[] / finance.sources[] / analytics.sources[]).
+type SourceStatus struct {
+	Name  string `json:"name"`
+	OK    bool   `json:"ok"`
+	Rows  int    `json:"rows"`
+	Error string `json:"error"`
+	At    string `json:"at"`
+}
+
+// SrcOf builds a SourceStatus freshness row for an aggregator.
+func SrcOf(name string, err error, rows int, at string) SourceStatus {
+	s := SourceStatus{Name: name, OK: err == nil, Rows: rows, At: at}
+	if err != nil {
+		s.Error = err.Error()
+	}
+	return s
+}