rebrand: preserve existing user data across the domain migration

[liuchao-001]

Part of the OpenTag rebranding migration decided by @liuchao-001 on 2026-08-11. Durable decisions/constraints are recorded in the Context Tree (system/opentag-migration.md, tree PR agent-team-foundation/first-tree-context#915). Related brand decisions: customer/marketing/rebranding.md.

Scope

Existing users must be able to sign in on opentag.build and regain all of their data: accounts, organizations, agents, workspaces, chats, Context Tree bindings, tokens/credits.

• Sessions and cookies are domain-scoped and will not carry over — define the re-login path and make sure account identity matching is by provider identity, not domain-scoped artifacts.
• Audit anything keyed by domain (localStorage user-scoped keys, OAuth subject mappings, webhook endpoints, invite links).

Acceptance

• A pre-migration account signs in on opentag.build and sees all prior data.
• No data loss or duplicate-account creation during the cutover; rollback plan documented.

[liuchao-001]

Full data-continuity audit done on a fresh worktree off origin/main (19e6603), covering auth/identity matching, web client-side storage, DB-persisted URLs, and installed CLI/daemon state.

TL;DR

Account continuity holds by construction — no duplicate-account risk from the domain change. The single hard prerequisite is that opentag.build serves the same backend, same database, same FIRST_TREE_JWT_SECRET. The dominant migration risk is not in the DB at all: it's the fleet of already-installed CLI daemons that have cloud.first-tree.ai persisted on disk — that host must remain a transparent reverse proxy (incl. WebSocket Upgrade), not a 301.

Identity & re-login path

• Matching is keyed exclusively on (provider, subject) — findOrCreateUserFromExternalAccount (packages/server/src/services/auth/identity.ts:78), unique index on (provider, identifier). GitHub uses the numeric user id, Google the id_token sub — both stable across domains, redirect URIs, and even a new OAuth client ID. No email-based matching exists. A returning user on opentag.build re-runs OAuth once and lands on the same users.id (created: false).
• Access/refresh JWTs carry no iss/aud and are verified against the secret only — old tokens validate on the new domain. But web tokens live in localStorage["first-tree:tokens"] (origin-scoped, no cookies), so every web user is logged out once on the new origin. Re-login path needs zero code changes: deep link → /login → OAuth → same account.
• Cutover metric: oauth.account_reused vs oauth.account_created — account_created for existing users should be ≈0; any spike is the duplicate-account alarm.
• OIDC self-host identities are keyed by the IdP's issuer — untouched by this migration.

What users actually lose (browser-local only)

Unrecoverable: unsent chat drafts (first-tree:chat-drafts:v1) and per-chat read-state/scroll anchors (IndexedDB) — every chat renders as first-visit once. Everything else is preference resets (theme, selected org, sidebar widths) or re-warmable caches (messages, images). All server-side data — accounts, orgs, agents, workspaces, chats, tree bindings — is unaffected since the DB doesn't move.

DB audit: one column, nothing else

• connect_codes.issuer is the only column persisting our own origin. 10-min TTL, single-use → self-healing; optionally one UPDATE at cutover.
• Invite links store a 43-char token only (7-day TTL); URLs are built at render time from FIRST_TREE_PUBLIC_URL. A path-preserving redirect first-tree.ai/invite/* → opentag.build/invite/* keeps old links working.
• Attachments/avatars are bytea in Postgres — no URL columns. No billing/credits tables. Historical messages.content contains report.first-tree.ai links (findings expire ~30 days) — keep the host resolving, don't rewrite history.
• One-off scan: agent_configs.payload may contain a manually set FIRST_TREE_SERVER_URL.

The hard constraint: installed daemons

Three copies of the old origin persist on user machines: credentials.json.serverUrl (drives /auth/refresh), client.yaml server.url (drives WS + HTTP), and the compiled-in channel default (packages/shared/src/channel/index.ts:84, routes short connect codes). There is no remote re-pointing mechanism, and:

• The WS client (ws@8, followRedirects unset) does not follow redirects → a 301 puts every daemon into a permanent 30s reconnect loop.
• Cross-origin HTTP redirects strip the Authorization header (WHATWG fetch), and 301/302 downgrades POST → GET → /auth/refresh fails → daemon enters auth_refresh_failed paused mode; recovery is a manual login <code>.

⇒ cloud.first-tree.ai must stay a transparent alias/proxy to the new backend until clients.last_seen_at/paused_reason telemetry shows the fleet has rolled over. The static rebranding page + 30s redirect (#2282) applies to the marketing domain only; the API subdomain cannot redirect. download.first-tree.ai can 301 but must stay alive indefinitely (published manifests embed absolute URLs).

Inputs to sibling issues

• rebrand: migrate cloud service to opentag.build; first-tree.ai becomes a static rebranding page with 30s redirect #2282: hostname equality gates silently kill GA/Clarity (packages/web/src/analytics.tsx:24, index.html:28,:57) and mistag Sentry (sentry.ts:165) on the new domain; plus channel/index.ts defaults, PARENT_URL ×4, reportBaseUrl ×2, FIRST_TREE_PUBLIC_URL/FIRST_TREE_CORS_ORIGIN.
• rebrand: keep Google OAuth and GitHub OAuth working through the migration #2285: register old + new redirect URIs side by side during the window (providers allow multiple) for a zero-downtime OAuth cut; Google grants survive (sub is client-independent).
• rebrand: investigate whether the First Tree GitHub App can be renamed #2286: keep the same GitHub App and only update Homepage/Callback/Webhook URLs — installations and stored user tokens all survive. A new App would keep account matching intact (numeric id is App-independent) but orphan every installation. GitLab webhooks are pasted on the customer's side — each org must re-paste the origin (bearer unchanged); gitlab_connections staleness columns give a ready-made "who stopped delivering" dashboard.

Cutover runbook (data/identity scope)

1. Rehearse on staging (dev.cloud.first-tree.ai → staging opentag host) with an existing account; verify oauth.account_reused + all data visible.
2. Flip FIRST_TREE_PUBLIC_URL + FIRST_TREE_CORS_ORIGIN; provider redirect URIs already dual-registered.
3. Old API host → transparent proxy; /invite/* path-preserving redirect; download host stays alive.
4. Optional: UPDATE connect_codes SET issuer='https://<new-origin>' WHERE consumed_at IS NULL AND expires_at > now(); (else accept a ≤10-min window of failed CLI connects).
5. Scan agent_configs.payload for hardcoded server URLs.
6. Watch: oauth.account_created spike (dup-account alarm), clients.paused_reason/last_seen_at (fleet rollover), GitLab delivery staleness, state-expired blips (in-flight OAuth crossing the cut — self-healing on retry).

Rollback

Same DB, no schema migration, no data rewrite (the connect_codes UPDATE is reversible) → rollback = revert DNS/FIRST_TREE_PUBLIC_URL/CORS/redirect URIs. Zero data loss in either direction, and since the old origin stays transparently alive throughout, installed clients never notice a rollback.