PSA/docs/plans/2026-06-05-appliance-registration-install-flow/SCRATCHPAD.md

Scratchpad — Appliance registration → download → install flow

• Plan slug: appliance-registration-install-flow
• Created: 2026-06-05
• Source spec: docs/superpowers/specs/2026-06-05-appliance-registration-install-flow-design.md

What This Is

Working memory for the register → download → install (+ re-issue) flow. The spine is a direction inversion: today the appliance generates its own tenant UUID and sends it up at /register; the new flow mints tenant_id upstream at registration, carries it down via a one-time install code, and the appliance adopts it via a new INITIAL_TENANT_ID.

Decisions

• (2026-06-05) Reuse /register for the friendly install code (decision 1) — one redeem path, reuse the claim-code machinery.
• (2026-06-05) Extend claim_codes (decision 2): entitlement_id → nullable, add tenant_id FK → tenant_registry. One code type for essentials (no entitlement) and paid. Chosen over a separate install_tokens table.
• (2026-06-05) Presigned for all downloads (decision 3) — registration-gated, not public; ISO isn't a secret, the code is the gate.
• (2026-06-05) Re-issue in scope now (decision 4) — portal action resolves an existing registry tenant and mints a fresh code for the same tenant_id.
• (2026-06-05) Test weighting is smoke-first (user directive): small automated set for the riskiest seams, everything else validated live on the VM. This deliberately inverts the software-planner default (tests longer than features) — tests.json is shorter and smoke-weighted on purpose.
• (2026-06-05) The short code is the identity carrier for BOTH tiers (not just paid). Essentials installs get a short code too and never type a raw tenant_id; the code's tenant_id is set for everyone, entitlement_id is null for essentials. One-liner framing: "a short code always resolves a tenant; for paid it additionally mints a bound license."
• (2026-06-05) §16 open questions all resolved: (1) alga-license presigns with object-store creds via env vars; the presigned URL is emailed to the user after registration/purchase (alongside the code) — not a public link. (2) Paid ordering: registry row at form submit, entitlement + code on checkout.session.completed. (3) Essentials edition from tenant_registry.edition (no edition on the code). (4) Reuse generateClaimCode() for install codes. Remaining impl detail (not a fork): which object-store key holds the current generic ISO + how the release process publishes it (F041).

Discoveries / Constraints

• (2026-06-05) claim_codes baseline is entitlement_id NOT NULL (alga-license/migrations/03_claim_codes.cjs). Needs a new migration to relax it and add tenant_id.
• (2026-06-05) alga-license accessors that already exist (src/db/db.ts): createRegistryTenant, getRegistryTenant, getRegistryTenantByEmail, insertClaimCode, getClaimCode, consumeClaimCode, revokeClaimCodesForEntitlement, upsertAppliance (already takes tenantId), setEntitlementLicenseSub, getEntitlementById. Signing helpers exist: signLicense (takes aud), generateClaimCode, generateApplianceCredential, generateLicenseId.
• (2026-06-05) New alga-license work: the migration, insertClaimCode + getClaimCode/ClaimCodeRow for tenant_id/nullable entitlement, a new revokeClaimCodesForTenant (essentials reissue has no entitlement to key on), a setRegistryTenantInstalled, the /register essentials+response changes, the /register-tenant and /install-codes/reissue routes, and a MinIO presign helper.
• (2026-06-05) /register today (src/routes/register.ts): requires an entitlement (getEntitlementById → 500 if none), binds aud from the request body tenant_id, returns { appliance_credential, first_jwt, check_in_url }. The new flow sources tenant_id from the code row and returns it (+ edition) to the appliance.
• (2026-06-05) /check-in (src/routes/checkIn.ts) already preserves appliance.tenant_id as aud across re-signs — no change needed.
• (2026-06-05) The appliance tenant UUID is born in ee/server/src/lib/testing/tenant-creation.ts createTenant (~line 80): it inserts into tenants without a tenant value, so the DB default (gen_random_uuid()) generates it and it's returned via .returning('tenant'). That insert is the exact INITIAL_TENANT_ID seam.
• (2026-06-05) connectAppliance (server/src/lib/actions/licenseManagementActions.ts, ~line 125) already POSTs { claim_code, appliance_id } to /register and seeds license_state with first_jwt/appliance_credential/check_in_url — but AFTER the tenant exists. The install-time consumer generalizes this to run before create-tenant and adopt the returned tenant_id.
• (2026-06-05) Licval WIP already in the working tree (uncommitted, NOT part of this plan's deltas — treat as precondition F001): create-tenant.ts + tenant-creation.ts thread INITIAL_ADMIN_PASSWORD/args.password through to createAdminUser (uses input.password ?? generateSecurePassword()), initialize tenant_settings (onboarding pending), and honor DB_HOST/DB_PORT/DB_USER_ADMIN. INITIAL_TENANT_ID lands in the same two files. Do not revert this WIP.

Build-step 1 — alga-license schema + /register (DONE on branch feat/registration-install-flow)

• (2026-06-05) Two refinements discovered while implementing (both fed back into the PRD/features):
  • claim_codes.tenant_id is NULLABLE, not NOT NULL. Migration alters entitlement_id NULLABLE via knex.raw('ALTER TABLE … DROP NOT NULL') (knex .alter() would try to rebuild the FK) and adds tenant_id uuid nullable FK + index (migrations/05_claim_codes_registry.cjs). /register resolves tenant = row.tenant_id ?? body.tenant_id — the body path is the clean legacy fallback, which only works because tenant_id is nullable.
  • Essentials /register creates NO appliance row. appliances.entitlement_id is NOT NULL (FK), and essentials has nothing to refresh (no license → no check-in), so the essentials branch returns { tenant_id, edition } and does not call upsertAppliance or issue a credential. (Original F012 said "still upsertAppliance" — corrected.)
• (2026-06-05) createRegistryTenant already accepted a pinned tenantId and returns the row — /register-tenant (build step 3) is mostly wiring.
• (2026-06-05) RegisterResponse now returns tenant_id + edition + company_name/contact_email; appliance_credential/first_jwt/check_in_url are optional (paid only). The existing alga-psa connectAppliance destructures the three paid fields and ignores the rest, so paid back-compat holds.
• (2026-06-05) Validated: tsc --noEmit clean; migration applies + rolls back + re-applies on a throwaway postgres:16 (5433); jest 28/28 incl. 3 new seam tests (claim_codes tenant_id round-trip, revokeClaimCodesForTenant, setRegistryTenantInstalled). The repo's signing.test.ts IS the gated-on-DB_HOST pg integration suite — extend that block, don't add a parallel harness.
• (2026-06-05) Test weighting note: /register HTTP behavior (T003/T004) is smoke, not Fastify route tests — validated in the build-step-4 live loop, per the light-automated directive.

Build-step 2 — INITIAL_TENANT_ID seam (code in working tree, alga-psa; UNCOMMITTED w/ licval WIP)

• (2026-06-05) Implemented F050/F051/F052/F054/F055: createTenant (ee/server/src/lib/testing/tenant-creation.ts) takes optional tenantId → sets tenantInsert.tenant when present (else DB gen_random_uuid() default, unchanged); idempotency guard returns the existing tenant (+ its client) if the id already exists so a re-run doesn't error/duplicate. Threaded through TenantCreationInput → createTenantComplete. create-tenant.ts reads INITIAL_TENANT_ID (env or --tenantId) and passes it down.
• (2026-06-05) Three tenant-creation.ts copies — only ee/server/src/lib/testing/tenant-creation.ts is the live path (what server/scripts/create-tenant.ts imports). packages/ee/src/lib/testing/… is the CE stub (throws). No parallel edit needed.
• (2026-06-05) No caller breakage: the change is additive-optional; tenant-test-factory.ts (the only other createTenantComplete consumer) is unaffected. Other createTenant( matches are unrelated functions (temporal activities, server test-utils).
• (2026-06-05) Not committed — these two files also carry the user's licval WIP (password seam). Left uncommitted in the working tree to avoid committing in-flight work; appliance changes (steps 2+4) commit together when the user is ready. F053 (bootstrap passes the redeemed id) + full typecheck land in step 4.
• (2026-06-05) T007/T008 reclassified AUTO→SMOKE: exercising createTenant's id adoption needs the full alga-psa tenants/clients schema (heavy), so it's validated in the live install loop, not a unit DB.

Build-step 3 — /register-tenant + /install-codes/reissue + presign (DONE, alga-license branch)

• (2026-06-05) Dependency-free SigV4 presigner (src/storage/presign.ts) — the service had no AWS SDK and is intentionally lean (fastify/knex/pg only), so the S3/MinIO presigned-GET URL is hand-rolled with node:crypto (path-style, UNSIGNED-PAYLOAD, query-auth). now is injectable for deterministic tests.
• (2026-06-05) Object-store config is env-driven and OPTIONAL: OBJECT_STORE_ENDPOINT/REGION/BUCKET/ACCESS_KEY/SECRET_KEY + APPLIANCE_ISO_KEY (default appliance/current/alga-appliance.iso). getPresignConfigFromEnv() returns null when unset so existing deploys (and /sign /register /check-in) boot without it; only register-tenant/reissue need it, and they emit download_url:'' if it's missing. TTL = claimCodeTtlSeconds (link expiry aligned to the code).
• (2026-06-05) New routes: /register-tenant (service-authed) creates the registry row, (paid) upserts the entitlement bound to the new tenant, mints the install code carrying tenant_id (+ entitlement), presigns. /install-codes/reissue resolves by tenant_id|email, revokeClaimCodesForTenant, re-attaches the active entitlement via new getActiveEntitlementByTenant, mints a fresh code + link.
• (2026-06-05) Validated: tsc clean; jest 31/31 (added presign structural test ×2 + getActiveEntitlementByTenant). Route HTTP behavior (T010/T018) is smoke.
• (2026-06-05) DEPLOY FOLLOW-UP (relates to F041): the alga-license Deployment (service k8s/deployment.yaml + nm-kube-config) must get the OBJECT_STORE_* env + APPLIANCE_ISO_KEY, and the appliance release process must publish the current ISO to that key. Not wired here (ops); register-tenant returns an empty download_url until it is.

Build-step 4 — appliance setup integration (MAPPED; needs coordination, NOT yet built)

• (2026-06-05) The redeem belongs in the host-service setup-engine.mjs (has the form inputs + network egress; mints the in-cluster secrets), not the in-app connectAppliance (which runs post-tenant). Seam: after normalizeInitialTenant, if an install code is present, POST it to ALGA_LICENSE_SERVICE_URL/register → capture tenant_id + edition (+ paid first_jwt/appliance_credential/ check_in_url), then:
  • add INITIAL_TENANT_ID to the appliance-initial-tenant Secret (initialTenantSecretYaml, ~line 429) → create-tenant adopts it (build-step 2);
  • feed the appliance-license-seed Secret (licenseSeedCmd, ~line 1014: EDITION_CHOICE + optional LICENSE_TOKEN).
• (2026-06-05) THREE reconciliation decisions block a clean edit (all inside the user's ACTIVE licval license-setup rework):
  1. UX: the setup UI (status-ui/app/setup/page.tsx) already has editionChoice (ee/ce) + a pasted licenseKey. Does the install code become the primary path (overriding those), an added third option, or replace them?
  2. Taxonomy: registry edition = essentials|pro|premium vs appliance editionChoice = ee|ce + license tier pro|premium. Need a mapping (essentials→ce? pro/premium→ee+token?).
  3. Connected seed: appliance_credential/check_in_url are written today only by in-app connectAppliance, not the seed Secret — install-time connected licensing needs new seed plumbing in packages/licensing/src/lib/license-state.ts.
• (2026-06-05) setup-engine.mjs + status-ui/ are NOT in the uncommitted WIP (safe to edit git-wise) but are conceptually the licval subsystem. F053/F060–F068 pend on the three decisions above.

Build-step 4 — appliance setup integration (BUILT in working tree, alga-psa)

• (2026-06-05) Redeem lives in the host-service. New install-code.mjs (redeemInstallCode / deriveApplianceId / licenseSeedFromRedeem) is pure + unit-tested (7 tests, mock fetch). setup-engine.mjs validateSetupInputs takes installCode; applyRuntimeValuesAndReleaseSelection redeems it (injectable via options.redeemInstallCode for tests) BEFORE building the two Secrets, threading tenant_id → initialTenantSecretYaml(initialTenant, tenantId) (INITIAL_TENANT_ID line) and the license fields → the appliance-license-seed literals (licenseSeedFromRedeem). Redeem failure → preflightFailure blocks the install (F067/F068). 2 new workflow tests; 8/8 pass.
• (2026-06-05) appliance-bootstrap-configmap.yaml: create-tenant gets INITIAL_TENANT_ID="${INITIAL_TENANT_ID:-}" (create-tenant.ts reads it; empty => DB-generated). License-seed SQL extended: a sql_value() helper + new columns appliance_id/check_in_url/appliance_credential (connected refresh), and the trial is suppressed when INSTALL_EDITION=essentials (essentials resolves to the essentials tier, not an auto premium trial).
• (2026-06-05) status-ui setup/page.tsx: an Install code field (primary, recommended) above the manual Edition/license fallback; included in the POST. Typechecks clean.
• (2026-06-05) DEFAULTS I PICKED — confirm during smoke (you authorized sensible defaults + flag):
  1. Taxonomy: the appliance always runs EE (EDITION_CHOICE=ee); essentials = EE-unlicensed (no token, no auto-trial), pro/premium = EE + minted token. The ce choice stays only for a manual community install (no install code).
  2. Connected seed: appliance_id/check_in_url/appliance_credential are seeded straight into license_state by the bootstrap SQL (vs. the in-app connectAppliance plaintext write) so daily check-in works from first boot.
• (2026-06-05) Two caveats: (a) the install code is single-use and consumed at apply time — a failed install past that point needs a re-issued code (the reissue endpoint exists; consider persisting the redeem to skip re-redeem on retry). (b) ee/appliance/ubuntu-iso/overlay/.../host-service/ is a build-synced COPY — the ISO build must pick up the new install-code.mjs + setup-engine edits (overlay sync, not a manual edit).

Build-step 5 — nm-store (separate repo /home/robert/nm-store; outward-facing)

• (2026-05-31/06-06) nm-store is local. Its existing order flow is hosted-only (checkout → Temporal OrderInstallWorkflow → hosted tenant; no appliance/ deploymentType concept). Appliance registration is a new outward-facing product surface there.
• (2026-06-06) BUILT (branch feat/appliance-registration-client, commit 6ab0a427): src/lib/algaLicenseClient.ts — typed registerTenant() + reissueInstallCode() calling /register-tenant + /install-codes/reissue (Bearer ALGA_LICENSE_SERVICE_SECRET, ALGA_LICENSE_SERVICE_URL). This is the transport F071/F075 build on. Logic validated via a tsx harness (the repo's vitest can't run here — missing strip-literal in node_modules under Node 24; the .test.ts is correct and runs once that dep gap is fixed).
• (2026-06-06) BUILT — commerce surface (decisions: SEPARATE route + essentials+paid), branch feat/appliance-registration-client commit ee53d0b0, tsc clean:
  • /order/appliance registration form (client): essentials → direct register → show code; paid (pro/premium) → embedded Stripe checkout. /order/appliance/reissue.
  • lib/appliance/applianceRegistration.ts: registerApplianceAndEmail, reissueApplianceAndEmail, sendInstallCodeEmail (Resend, reuses the newsletter pattern), and idempotent provisionApplianceFromCheckoutSession — nm-store has no DB, so it writes the minted tenant_id/install_code back onto the Stripe subscription metadata and reuses them on thank-you refresh (so a refresh never re-mints).
  • lib/appliance/applianceCheckout.ts: embedded subscription checkout stamping deploymentType=appliance + edition/contact into metadata, dedicated return_url=/order/appliance/thank-you. Hosted OrderForm/checkout/thank-you untouched (the separate-route choice).
  • Checkout-complete is handled by the thank-you page (Stripe return_url), not a webhook — so the appliance thank-you provisions on render.
  • Email is best-effort (Resend): logs + returns emailSent:false if RESEND_API_KEY unset; the code is always shown on-page too.
• (2026-06-06) nm-store env to set for PAID: STRIPE_PRICE_ID_APPLIANCE_{PRO,PREMIUM}_{MONTHLY,YEARLY} (+ optional ..._USER_MONTHLY/YEARLY per-user), ALGA_LICENSE_SERVICE_URL, ALGA_LICENSE_SERVICE_SECRET, RESEND_API_KEY/APPLIANCE_FROM_EMAIL. Essentials needs no Stripe price. Tests can't run here (repo vitest strip-literal gap + server-only blocks tsx) — validated by tsc + the tsx client harness + smoke.
• (2026-06-06) F076 operator doc written: ee/appliance/docs/registration-install-flow.md.
• (2026-06-06) F041 remains ops: publish the current generic ISO to the object-store key the presigner targets (APPLIANCE_ISO_KEY), and wire the OBJECT_STORE_* env onto the alga-license Deployment (service k8s/deployment.yaml
  • nm-kube-config).

Commands / Runbooks

• (2026-06-05) alga-license migration/db tests: run against a throwaway docker run postgres:16 (snap docker can't reach /tmp; docker run is fine — prior runs used port 5433). The least-priv app role can't TRUNCATE (by design) — tests DELETE. DB-layer tests are gated on DB_HOST (skip without a DB).
• (2026-06-05) Build gotcha: the shell has NODE_ENV=production, so npm install omits devDeps (breaks tsc/@types) — use npm install --include=dev.
• (2026-06-05) alga-license validation one-liner (throwaway pg): docker run -d --name algalic-pg -e POSTGRES_PASSWORD=test -e POSTGRES_DB=alga_license -p 5433:5432 postgres:16 then DB_HOST=localhost DB_PORT=5433 DB_NAME=alga_license DB_USER_ADMIN=postgres DB_PASSWORD_ADMIN=test npm run migrate and DB_HOST=localhost DB_PORT=5433 DB_NAME=alga_license DB_USER_APP=postgres DB_PASSWORD_APP=test npm test. The signLicense tests need the alga-psa fixture key at packages/licensing/src/lib/__test-fixtures__/v1-test.private.pem (present).
• (2026-06-05) Appliance VM smoke: the full register→download→install loop is validated live on the libvirt appliance VM (see the appliance teardown/reinstall
  • VM ISO-test memories for driving setup via the browser / virsh).

Links / References

• Design spec: docs/superpowers/specs/2026-06-05-appliance-registration-install-flow-design.md
• Registry foundation (already shipped): alga-license PR #3/#4, nm-kube-config PR #50/#51.
• alga-license routes: src/routes/{register,claimCodes,checkIn,sign,revoke}.ts; db: src/db/db.ts; migrations: migrations/0{1..4}_*.cjs; types: src/api-types.ts.
• Appliance: ee/server/src/lib/testing/tenant-creation.ts, server/scripts/create-tenant.ts, server/src/lib/actions/licenseManagementActions.ts.

Open Questions

• (2026-06-05) All four §16 design questions resolved — see the Decisions section. No open design forks remain. Only impl detail left: the object-store key for the current generic ISO + the release-process publish step (F041).