fix(install): set the homepage without a login only on unclaimed environments

[nicknisi]

Follow-up to #244.

Problem

Without a dashboard session, Next.js setup registers the callback with the API key, then writes the default homepage only if none is set (preserveExisting). To check, it reads GET /user_management/app_homepage_url. That route doesn't exist: it returns the same 404 as a made-up path.

GET /user_management/app_homepage_url       → 404 {"message":"The requested resource was not found","error":"Not Found"}
GET /user_management/definitely_not_a_route → 404 {"message":"The requested resource was not found","error":"Not Found"}

The read never succeeds, so every install without a login (including every freshly provisioned unclaimed environment) ends with:

Application setup is incomplete: Callback registered using the API key, but homepage setup failed.

It also leaves no homepage set. Seen in a real workos integrate run.

Fix

With only an API key, the current homepage can't be known. So the installer writes it only where nothing can be overwritten:

• --homepage-url given: written, as before.
• Unclaimed environment (the stored environment is unclaimed and its key is the one in use): written. Nobody can open its dashboard until it's claimed. This covers every fresh install, whose sign-out then has a homepage to fall back to.
• Otherwise: left alone, and listed with the Sign-out URI and Initiate login URI for the dashboard.

The unused preserveExisting read path in setHomepageUrl is removed. The path with a dashboard session is unchanged: it reads appHomepageUrl over GraphQL, which works.

Tests

The API-key tests mocked a homepage read ({ url: null }) that the API never returns. They now mock the real 404 and cover:

• an unclaimed environment;
• a claimed environment, another environment's key, and no stored environment;
• a keyring error;
• an explicit --homepage-url;
• PUT failures.

bun run test, typecheck, lint, format, build and scripts/command-smoke.sh all pass.

[greptile-apps]

Confidence Score: 4/5

This PR should not merge until an externally claimed environment cannot have its dashboard homepage overwritten by a stale local profile.

Findings

1.  Stale profile overwrites homepage ▶

Fix with agent prompt

### Issue 1
src/lib/authkit-application-setup.ts:42-43
If an environment is claimed in the dashboard but its local profile still says `unclaimed`, a later API-key-only install treats the matching key as permission to write the default homepage. Install does not refresh the claim status first, and the REST homepage read returns 404, so the PUT can silently replace a homepage set after the claim. Check the current claim status before allowing this write.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

The PR replaces an unavailable REST homepage read with a conditional write during API-key-only AuthKit setup.

• It writes an explicit homepage or a default for a locally unclaimed environment, and leaves other homepages for dashboard setup.
• It updates API-key tests to reflect the REST endpoint’s 404 response.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Callback registered with API key] --> B{Explicit homepage?}
  B -- Yes --> D[PUT homepage]
  B -- No --> C{Local active profile unclaimed and key matches?}
  C -- Yes --> D
  C -- No --> E[Leave homepage for dashboard setup]
  D --> F[Return pending dashboard steps]
  E --> F

Loading

_{Reviews (1) · Last reviewed commit: "fix(install): set the homepage without a..."}

[greptile-apps]

Stale profile overwrites homepage

If an environment is claimed in the dashboard but its local profile still says unclaimed, a later API-key-only install treats the matching key as permission to write the default homepage. Install does not refresh the claim status first, and the REST homepage read returns 404, so the PUT can silently replace a homepage set after the claim. Check the current claim status before allowing this write.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/lib/authkit-application-setup.ts
Line: 42-43

Comment:
**Stale profile overwrites homepage**

If an environment is claimed in the dashboard but its local profile still says `unclaimed`, a later API-key-only install treats the matching key as permission to write the default homepage. Install does not refresh the claim status first, and the REST homepage read returns 404, so the PUT can silently replace a homepage set after the claim. Check the current claim status before allowing this write.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

[nicknisi]

Addressed on main by merged #252 (60578d0), following #250. The shared isUnclaimedEnvironmentKey helper now confirms live claim status via createClaimNonce after matching the stored key and, when available, the expected client ID. Both implicit-homepage write paths await it; claimed or unavailable status leaves the homepage unchanged, while explicit --homepage-url remains supported.

Regression coverage includes an externally claimed environment, HTTP 409, invalid tokens, missing environments, rate limits, server/network failures, malformed responses, and client-ID mismatches. Rechecked the main-equivalent files today: 105 relevant tests pass. This is a best-effort preflight, not an atomic claim/write guarantee.

Closing this older PR as superseded rather than merging its stale duplicate implementation. The unused preserveExisting option cleanup is the only non-behavioral remainder and is not needed for this fix.

[nicknisi]

Superseded by merged #250 and #252. The homepage policy and live-claim safeguard are already on main, including regression tests for the review finding. No additional behavior needs to merge from this conflicted branch; retaining the branch/history for reference.