PSA/docs/superpowers/specs/2026-06-05-appliance-registration-install-flow-design.md

# Appliance registration → download → install flow

**Status:** Design • **Date:** 2026-06-05

## Goal

Let a customer register for an on-prem (appliance) AlgaPSA install, download a
generic ISO, and have the installed appliance come up already bound to a
**tenant identity that was minted upstream at registration** — so licenses are
bound from first boot and even free (essentials) installs get a real
`tenant_registry` record.

The single organizing idea: the appliance image is **generic** (we don't build a
per-customer ISO), so per-tenant identity travels separately from the download,
carried by a short, one-time **install code** that the appliance redeems at
setup. The code is the per-customer artifact; the ISO is not.

## What exists today (grounded)

The pieces this flow reuses already exist:

- **`tenant_registry`** (`alga-license/migrations/01_tenant_registry.cjs`) — the
  global directory: `tenant_id uuid` (minted here, `gen_random_uuid()`),
  `edition`, `deployment_type`, `status` (`registered → installed → active …`),
  `company_name`/`contact_email`, `stripe_customer_id`. This is the source of
  truth for "a tenant exists, who owns it, what edition."
- **`/register`** (`alga-license/src/routes/register.ts`) — redeems a
  `claim_code`, mints a per-appliance license JWT bound to a tenant via the `aud`
  claim (`signLicense({ …, aud })`), issues an appliance credential, returns
  `{ appliance_credential, first_jwt, check_in_url }`. Today it **requires an
  entitlement** (`getEntitlementById(row.entitlement_id)` → 500 if none) and
  takes `tenant_id` as **caller-supplied input**.
- **`/claim-codes`** (`alga-license/src/routes/claimCodes.ts`) — mints a code for
  an entitlement, keyed by `stripe_sub_id` (paid only). Revokes prior unclaimed
  codes for that entitlement first (rebind path).
- **`/check-in`** (`alga-license/src/routes/checkIn.ts`) — refreshes the bound
  license daily, **preserving `appliance.tenant_id` as `aud`** across re-signs.
  No change needed.
- **`claim_codes`** (`alga-license/migrations/03_claim_codes.cjs`) —
  `entitlement_id` is `NOT NULL` with an FK to `entitlements`.
- **Appliance tenant creation** (`ee/server/src/lib/testing/tenant-creation.ts`,
  used by `server/scripts/create-tenant.ts`) — `createTenant` inserts into
  `tenants` **without** a `tenant` value, so the DB generates the UUID
  (`gen_random_uuid()`) and returns it (`.returning('tenant')`, line 80–84).
- **Appliance consumer** (`server/src/lib/actions/licenseManagementActions.ts`) —
  `connectAppliance` POSTs `{ claim_code, appliance_id }` to `/register` and
  seeds `license_state` with `first_jwt` / `appliance_credential` /
  `check_in_url`. Runs **after** the tenant already exists.

### The gap

Today the appliance **generates its own tenant UUID** at setup, then *optionally*
connects a license later. The tenant identity is never known upstream, so a
license issued before install can't be bound, and essentials installs leave no
registry record. The flow below inverts the direction: **mint `tenant_id`
upstream at registration; the install code carries it downstream; the appliance
adopts it.**

## The four surfaces

```
 nm-store              alga-license (C4)            object store        appliance
 ────────              ─────────────────            ────────────        ─────────
 register  ──POST───►  /register-tenant
   form                  • tenant_registry row (tenant_id)
                         • (paid) entitlement
                         • mint install code  ──carries──► tenant_id
                         • presign ISO URL  ◄──────────────┐
           ◄──{code, tenant_id, download_url}              │
 confirm page                                              │
   + email                                                 │
                                                           │
 download  ──────────────────────presigned GET────────────┘──────────►  ISO
                                                                         │
 install: setup UI "enter install code"                                  ▼
           ──POST {claim_code, appliance_id}──►  /register
                                                  • look up code → tenant_id (registry-minted)
                                                  • (paid) mint license bound aud=tenant_id
           ◄──{ tenant_id, edition, first_jwt?, credential?, check_in_url? }
                                                                         │
           create-tenant  INITIAL_TENANT_ID=tenant_id ◄─────────────────┘
           seed license_state (edition; + token/credential if paid)
           registry status → installed
```

1. **Registration (nm-store → alga-license).** A new service-authed endpoint
   `POST /register-tenant` on alga-license creates the `tenant_registry` row
   (`deployment_type=appliance`, `status=registered`), and for **paid** tiers
   creates the entitlement (Stripe checkout drives this, as the hosted flow does
   today). It mints an **install code** carrying that `tenant_id` (and the
   `entitlement_id` for paid), and returns `{ tenant_id, install_code,
   download_url }`. nm-store shows the code on the confirmation page and emails
   it. nm-store stays DB-less — alga-license owns the registry write, the code,
   and the presigned URL.

2. **Download (presigned, all tiers).** `download_url` is a time-boxed presigned
   URL to the **current generic appliance ISO** in the in-cluster object store
   (MinIO). Presigned for everyone — essentials included — so downloads are
   gated by registration, not public. The ISO carries no identity.

3. **Install (appliance redeems the code).** The first-boot setup UI gains an
   **"enter install code"** step. The host-service redeems it via the existing
   `/register`, which now returns the registry-minted `tenant_id` and `edition`
   (plus, for paid, `first_jwt` / `appliance_credential` / `check_in_url`).
   Bootstrap then runs `create-tenant` with a new **`INITIAL_TENANT_ID`** so the
   local `tenants` row is created under the pre-minted UUID, and seeds
   `license_state` (edition always; license token + credential + check-in URL for
   paid). alga-license flips the registry row to `status=installed`.

4. **Re-issue / recovery (in scope).** Install codes are one-time. A new
   service-authed `POST /install-codes/reissue` on alga-license resolves an
   existing registry tenant (by `contact_email`, or `tenant_id`), revokes any
   unconsumed codes for it, and mints a **fresh install code for the same
   `tenant_id`** (+ current entitlement) with a fresh presigned `download_url`.
   nm-store exposes this as a portal "re-issue install code" action. This is what
   makes a wipe-and-reinstall recover the *same* tenant identity rather than
   stranding it.

## Data model changes (alga-license)

A single migration extending `claim_codes` so one code type serves both paid and
essentials, carrying the registry tenant:

```
ALTER claim_codes:
  entitlement_id  → NULLABLE        -- essentials codes carry no entitlement
  + tenant_id     uuid NOT NULL FK → tenant_registry(tenant_id)
  + index on tenant_id
```

- **Paid code:** `entitlement_id` set (license path unchanged) **and** `tenant_id`
  set (so `aud` comes from the registry, not appliance input).
- **Essentials code:** `entitlement_id` null, `tenant_id` set. No license minted.

`tenant_registry` already has everything else needed (`edition`, `company_name`,
`contact_email`, `status`); no change there beyond writing `status=installed` at
install.

## API changes (alga-license)

**`/register` (extend, don't replace).** Today it 500s when the code has no
entitlement and binds `aud` from caller-supplied `tenant_id`. New behavior:

- Resolve `tenant_id` from **the code** (`row.tenant_id`), not the request body —
  this is the registry-minted identity. (Keep accepting a body `tenant_id` only
  as a legacy fallback for pre-registry appliances; the registry path ignores
  it.)
- If `row.entitlement_id` is null → **essentials**: skip license minting; still
  upsert the appliance row (credential, `tenant_id`, no token).
- Look up `tenant_registry` by `tenant_id` for `edition` + `company_name` /
  `contact_email`.
- **Response gains** `tenant_id`, `edition`, and (for essentials) omits
  `first_jwt`. So `RegisterResponse` becomes:
  `{ tenant_id, edition, company_name, contact_email, appliance_credential?,
  first_jwt?, check_in_url? }` — credential/token/url present only when there's a
  license (paid).

**`POST /register-tenant` (new, service-authed).** Body: company/contact,
edition, deployment_type, optional Stripe linkage. Creates the registry row,
(paid) entitlement, mints the install code carrying `tenant_id`, presigns the
ISO, returns `{ tenant_id, install_code, download_url }`. Reuses
`createRegistryTenant` + the claim-code minting (generalized to accept a
`tenant_id` and optional `entitlement_id`).

**`POST /install-codes/reissue` (new, service-authed).** Body:
`{ contact_email | tenant_id }`. Resolves the registry tenant, revokes its
unconsumed codes, mints a fresh code + presigned `download_url`. Returns
`{ install_code, download_url }`.

## The `INITIAL_TENANT_ID` seam (appliance)

The change is small and localized at the one place the UUID is born:

- `createTenant` (`tenant-creation.ts`) gains an optional `tenantId` on its input;
  when present, set `tenantInsert.tenant = input.tenantId` instead of letting the
  DB default it. Thread the option through `createTenantComplete`.
- `server/scripts/create-tenant.ts` reads `INITIAL_TENANT_ID` (env, alongside the
  existing `INITIAL_ADMIN_PASSWORD`) and passes it down.
- The appliance bootstrap (the configmap/script that runs `create-tenant` at
  first boot) sets `INITIAL_TENANT_ID` to the `tenant_id` the redeem returned.

When `INITIAL_TENANT_ID` is unset, behavior is unchanged (DB-generated UUID) — so
this is additive and safe for non-registry installs.

## The install-time redeem consumer (appliance)

`connectAppliance` already knows how to call `/register` and seed `license_state`.
The install path generalizes it:

1. Setup UI collects the install code + admin password (the password is set here,
   at install — it never travels through registration or email).
2. Host-service POSTs `{ claim_code, appliance_id }` to `/register`, receives
   `tenant_id` + `edition` (+ license bits if paid).
3. Bootstrap runs `create-tenant` with `INITIAL_TENANT_ID = tenant_id`.
4. Seed `license_state`: `edition` always; for paid also `license_token`
   (`first_jwt`), `appliance_credential`, `check_in_url` (the existing
   `connectAppliance` write, minus the assumption that a token is always present).

Essentials installs simply run at `edition=essentials` with a `license_state` row
and no token — consistent with "always seed `license_state`" (the appliance reads
edition from `license_state`, not from the presence of a token).

## Error handling

- **Code invalid / expired / already consumed** — `/register` already returns
  `invalid_claim_code` / `expired_claim_code` / `consumed_claim_code`; the setup
  UI surfaces these and points the user to portal **re-issue**.
- **Consumed code on reinstall** — expected; the user re-issues. Re-issue revokes
  stragglers so only the newest code is live.
- **Presigned URL expired** — re-issue mints a fresh one; the download link and
  the code travel together.
- **Registry/license-service unreachable at install** — setup blocks with a clear
  "can't reach license service" error (the appliance can't self-mint a registry
  identity; that's by design).
- **Idempotent install** — if `create-tenant` reruns with the same
  `INITIAL_TENANT_ID`, it must no-op/short-circuit rather than duplicate
  (the existing admin-user create already guards on `(email, tenant)`).

## Security considerations

- The install code is **single-use** (`consumeClaimCode` is atomic under
  concurrency) and short-lived (`claimCodeTtlSeconds`); re-issue is the only way
  to get another, and it's behind portal auth on nm-store.
- Per-tenant binding is preserved end-to-end: the registry mints `tenant_id`,
  the code carries it, `/register` stamps it as `aud`, `/check-in` keeps it across
  refreshes — so a leaked license still can't activate on another tenant
  (the binding work already shipped; this flow just sources `aud` from the
  registry instead of appliance input).
- Presigned-for-all means the ISO isn't a public URL, but note the ISO itself is
  **not** a secret — the install code is the gate. Presigning is registration
  gating + link expiry, not ISO confidentiality.
- The admin password is set at install, never in registration/email.

## Testing

Following the repo's light-automated-then-smoke convention:

- **Automated (alga-license):** the `claim_codes` extension + `/register`
  essentials path + `/register-tenant` + `/install-codes/reissue` get db-layer
  and route tests against a throwaway Postgres (the existing pattern: gated on
  `DB_HOST`, `DELETE` not `TRUNCATE` for the least-priv role). Cover: essentials
  code (no entitlement) redeems and returns `tenant_id`/`edition` with no token;
  paid code returns a license bound to the registry `tenant_id`; reissue revokes
  prior codes and reuses the same `tenant_id`.
- **Automated (appliance):** `createTenant` honors `INITIAL_TENANT_ID`
  (creates the `tenants` row under the supplied UUID; unchanged when unset).
- **Smoke (live, on the VM):** full loop — register on nm-store → download →
  enter code in setup UI → confirm the appliance comes up under the minted
  `tenant_id`, `license_state` seeded, paid tier licensed/bound, then a
  wipe-and-reinstall via **re-issue** recovers the same tenant.

## Phasing

The four decisions collapsed the original two-phase split: re-issue is **in
scope now**, so this is one coherent build rather than essentials-first then
paid. Suggested 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.

## Open questions (for spec review)

1. **Presigned URL owner.** Lean: alga-license mints the presigned URL (holds the
   MinIO creds; nm-store stays DB-less and just relays). Confirm MinIO is the ISO
   store and the appliance release process publishes the "current" ISO to a known
   key. Current appliance release metadata is published by the `~/nm-kube-config`
   Argo workflow to OCI, not from local files in `alga-psa`.
2. **`/register-tenant` vs Stripe ordering for paid.** Does nm-store call
   `/register-tenant` before or after Stripe checkout completes? Lean: create the
   registry row at form submit (`status=registered`), attach the entitlement on
   `checkout.session.completed`, mint the code at that point.
3. **Edition source for essentials at `/register`.** Confirmed via
   `tenant_registry.edition` (the code → tenant_id → registry lookup); no edition
   on the code itself. OK?
4. **Code format.** Reuse `generateClaimCode()` as-is (same friendly format), or a
   distinct visual format for install codes? Lean: reuse — one machinery.
```