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

PRD: Appliance registration → download → install flow

• Slug: appliance-registration-install-flow
• Date: 2026-06-05
• Status: Draft
• Source spec: docs/superpowers/specs/2026-06-05-appliance-registration-install-flow-design.md

1. Problem statement & user value

A customer who wants on-prem (appliance) AlgaPSA must be able to register, download a generic ISO, install it, and have the appliance come up already bound to a tenant identity that was minted upstream at registration. Today the appliance generates its own tenant UUID at first boot and only optionally connects a license afterward, so: (a) a license issued before install can't be bound to the right tenant, and (b) free (essentials) installs leave no record in the global registry. The value: licenses are bound from first boot, essentials installs get a real tenant_registry row, and a wipe-and-reinstall recovers the same tenant.

The organizing idea: the appliance image is generic — we do not build a per-customer ISO — so per-tenant identity travels separately from the download, carried by a short, one-time install code the appliance redeems at setup. The code is the per-customer artifact; the ISO is not.

2. Goals

• Mint tenant_id upstream at registration (in the tenant_registry) and carry it to the appliance via a one-time install code.
• Reuse the existing /register claim-code machinery for the redeem (one code format, one redeem path) — see §5.
• Support essentials (free, no entitlement) and paid (entitlement + bound license) through the same flow.
• Adopt the minted tenant_id at install via a new INITIAL_TENANT_ID seam (vs. today's DB-generated UUID), additive and safe when unset.
• Presigned-for-all downloads (registration-gated, not public).
• Re-issue / recovery in scope now: re-fetch a fresh code for the same tenant.

3. Non-goals

• No per-customer ISO builds; the ISO stays generic.
• No migration/backfill of existing hosted tenants into the registry (forward-only).
• No CRM/relationship modeling — registry holds identity + entitlement state only.
• No new license-binding mechanism — binding (aud) already shipped; this flow only changes where aud is sourced (registry vs. appliance input).
• No observability/metrics/admin-tooling beyond what the flow needs to function.

4. Personas & primary flows

• Prospect/customer (nm-store): fills the registration form → gets an install code + download link (confirmation page + email).
• Installer/admin (appliance setup UI): downloads the ISO, boots it, enters the install code + sets the admin password → appliance comes up under the minted tenant.
• Returning admin (reinstall/recovery): uses the portal "re-issue install code" to get a fresh code for the same tenant, then reinstalls.

Primary flow (happy path):

register (nm-store) → /register-tenant mints tenant_id + install code + presigned URL
  → download generic ISO → setup UI: enter install code + admin password
  → /register returns tenant_id + edition (+ license if paid)
  → create-tenant with INITIAL_TENANT_ID → seed license_state → registry=installed

5. Resolved design decisions

1. Install code redeemed via /register — reuse the existing claim-code → /register machinery for the short, friendly code (no separate redeem path).
2. Extend claim_codes — make entitlement_id nullable and add a tenant_id FK to tenant_registry. One code type serves essentials (no entitlement) and paid (with entitlement). (Chosen over a new install_tokens table.)
3. Presigned for all downloads, essentials included — gated by registration, not public; the ISO itself is not a secret, the code is the gate.
4. Re-issue in scope now — a portal "re-issue install code" action resolves an existing registry tenant and mints a fresh code for the same tenant_id (folded out of a later phase into this build).

6. Architecture: the four surfaces

1. nm-store (DB-less Next.js): registration form + confirmation/email + portal re-issue. Calls alga-license; never writes the registry directly.
2. alga-license (C4): registry writes, install-code mint/redeem, presigned-URL mint, license signing. Routes live in src/routes/.
3. Object store (MinIO): holds the current generic appliance ISO at a known key; alga-license presigns time-boxed GET URLs.
4. Appliance (alga-psa): setup UI install-code step, install-time redeem consumer, INITIAL_TENANT_ID tenant adoption, license_state seeding.

The spine is a direction inversion: today tenant_id flows appliance→service (/register accepts it as input); the new flow mints it upstream and flows it service→appliance (the code carries it, /register returns it, the appliance adopts it).

7. Data model changes (alga-license)

One migration extending claim_codes (current: alga-license/migrations/03_claim_codes.cjs, entitlement_id NOT NULL):

• entitlement_id → NULLABLE (essentials codes carry no entitlement).
• add tenant_id uuid NULLABLE FK → tenant_registry(tenant_id) (ON DELETE CASCADE), indexed. Nullable (not NOT NULL as first drafted): the legacy /claim-codes path and any existing rows carry no registry tenant, and /register falls back to the appliance-supplied body tenant_id for those. Implemented as migrations/05_claim_codes_registry.cjs.

No change to tenant_registry (already has edition, company_name, contact_email, status, stripe_customer_id) beyond writing status='installed' + installed_at at install.

DB accessors (alga-license/src/db/db.ts): createRegistryTenant, getRegistryTenant, getRegistryTenantByEmail, getClaimCode, consumeClaimCode, upsertAppliance (already takes tenantId) exist. Changes: insertClaimCode accepts tenant_id + optional entitlement_id; getClaimCode/ClaimCodeRow expose tenant_id; new revokeClaimCodesForTenant (reissue for essentials has no entitlement to key on).

8. API changes (alga-license)

/register (extend src/routes/register.ts):

• Source tenant_id from the code row (row.tenant_id), not the request body (the registry-minted identity). Keep accepting body tenant_id only as a legacy fallback for pre-registry appliances.
• If row.entitlement_id is null → essentials: skip license minting; still upsertAppliance (credential + tenant_id, no token).
• Look up tenant_registry by tenant_id for edition + company_name + contact_email.
• Response gains tenant_id, edition, company_name, contact_email; appliance_credential / first_jwt / check_in_url become optional (present only for paid).
• On success, set registry status='installed' + installed_at.

POST /register-tenant (new, service-authed): body = company/contact, edition, deployment_type, optional Stripe linkage → createRegistryTenant (status='registered'); paid → create/link entitlement; mint install code carrying tenant_id (+ entitlement_id if paid); presign ISO; return { tenant_id, install_code, download_url }.

POST /install-codes/reissue (new, service-authed): body = { contact_email | tenant_id } → resolve registry tenant → revokeClaimCodesForTenant → mint fresh code (same tenant_id, current entitlement) → fresh presigned download_url. Returns { install_code, download_url }.

9. Appliance changes (alga-psa)

INITIAL_TENANT_ID seam (the UUID is born in ee/server/src/lib/testing/tenant-creation.ts createTenant, line ~80, which inserts into tenants without a tenant value → DB default):

• createTenant gains optional tenantId; when set, tenantInsert.tenant = input.tenantId. Thread through createTenantComplete.
• server/scripts/create-tenant.ts reads INITIAL_TENANT_ID (env, next to the existing INITIAL_ADMIN_PASSWORD already wired in the licval WIP) and passes it down.
• Appliance bootstrap (configmap/script running create-tenant at first boot) sets INITIAL_TENANT_ID from the redeem result.
• Unset INITIAL_TENANT_ID = unchanged DB-generated behavior (additive/safe).

Install-time redeem consumer (generalize server/src/lib/actions/licenseManagementActions.ts connectAppliance):

• Setup UI collects install code + admin password (password set at install only, never in registration/email — the licval WIP already threads INITIAL_ADMIN_PASSWORD).
• Host-service POSTs { claim_code, appliance_id } to /register; receives tenant_id + edition (+ license bits if paid).
• Run create-tenant with INITIAL_TENANT_ID = tenant_id.
• Seed license_state: edition always; for paid also license_token (first_jwt), appliance_credential, check_in_url (the existing connectAppliance write, minus the assumption a token is always present).
• Essentials: license_state row, no token; appliance reads edition from license_state (consistent with "always seed license_state").

10. nm-store changes

• Registration form (company, contact, edition) → POST /register-tenant.
• Email the install code + presigned download link to the contact after registration/purchase (primary delivery); the confirmation page may also show the install code.
• Paid: Stripe checkout ordering — create registry row at submit (status='registered'), attach entitlement + mint code on checkout.session.completed (§16.2).
• Portal "re-issue install code" action (behind portal auth) → /install-codes/reissue.

11. Presigned download & ISO publishing

• alga-license mints time-boxed presigned GET URLs; the object-store (MinIO) credentials are supplied to the service as env vars (§16.1).
• The presigned download_url is delivered by email to the contact after registration/purchase, alongside the install code — registration-gated, not a public link. (/register-tenant returns it; the post-registration/checkout email step carries it to the user.)
• The appliance release process publishes the current generic ISO to a known object-store key; download_url points there (impl detail under F041).
• Presigning provides registration gating + link expiry, not ISO confidentiality.

12. Security / permissions

• Install code is single-use (consumeClaimCode is atomic under concurrency) and short-lived (claimCodeTtlSeconds); re-issue is the only way to get another and is behind portal auth.
• Per-tenant binding preserved end-to-end: registry mints tenant_id → code carries it → /register stamps aud → /check-in preserves aud across re-signs. A leaked license still can't activate on another tenant.
• /register-tenant and /install-codes/reissue require service auth (makeServiceAuthHook), same as /claim-codes.
• Admin password set at install, never transmitted via registration/email.

13. Error handling

• Invalid / expired / consumed code → existing /register codes (invalid_claim_code / expired_claim_code / consumed_claim_code); setup UI surfaces them and points to portal re-issue.
• Consumed code on reinstall is expected → re-issue (revokes stragglers, newest code wins).
• Expired presigned URL → re-issue mints a fresh one (code + link travel together).
• License service unreachable at install → setup blocks with a clear error (the appliance can't self-mint a registry identity, by design).
• Idempotent install: rerun with the same INITIAL_TENANT_ID must no-op rather than duplicate (admin-user create already guards on (email, tenant)).

14. Testing approach (smoke-first)

Per the project convention and explicit direction: light on automated tests, mostly smoke. A small automated set covers only the highest-risk seams (migration up/down, /register essentials vs. paid branch, reissue revoke+reuse, INITIAL_TENANT_ID honor + idempotency). Everything else is validated live on the appliance VM end-to-end (register → download → install → reinstall-via-reissue). See tests.json (smoke-weighted, not the usual tests-longer-than-features).

15. Rollout / phasing

One coherent build (re-issue folded in). Build order, each independently verifiable:

1. alga-license schema + /register extension (essentials path + tenant_id from the code + richer response) — the seam everything hangs off.
2. INITIAL_TENANT_ID in createTenant / create-tenant.ts / bootstrap.
3. /register-tenant + /install-codes/reissue + presigned-URL minting.
4. Setup-UI install-code step + install-time redeem/seed consumer.
5. nm-store registration + confirmation/email + portal re-issue.

16. Resolved decisions (was open — settled 2026-06-05)

1. Presign owner / delivery. alga-license mints the time-boxed presigned GET URL, with the object-store (MinIO) credentials provided as env vars. The presigned URL is delivered by email to the contact after registration/purchase (carried alongside the install code), not handed out publicly. (Remaining implementation detail: which object-store key holds the "current" generic ISO and how the appliance release process publishes it — an impl task under F041, not a design fork.)
2. Stripe vs. registration ordering (paid). Create the tenant_registry row at form submit (status='registered'); attach the entitlement + mint the install code on checkout.session.completed.
3. Edition source for essentials at /register. From tenant_registry.edition via code → tenant_id → registry lookup; no edition stored on the code.
4. Code format. Reuse generateClaimCode() (existing 8-char unambiguous format) for install codes — one machinery, essentials and paid alike.

17. Acceptance criteria (Definition of Done)

• A free registration on nm-store yields an install code + presigned download link; installing the generic ISO with that code brings the appliance up under the registry-minted tenant_id at edition=essentials, with a license_state row and no token; registry status='installed'.
• A paid registration additionally yields a license bound to that tenant_id (aud), seeded into license_state, and the appliance shows licensed at the purchased tier; /check-in keeps the binding on refresh.
• A wipe-and-reinstall using a re-issued code recovers the same tenant_id.
• INITIAL_TENANT_ID unset → appliance behavior unchanged (DB-generated UUID).
• Smoke loop passes on the VM; the small automated set is green.