Merge pull request #48 from InstaNode-dev/feat/admin-path-prefix-ui-fresh

mastermanas805 · web-flow · commit 59e1d1f7a000 · 2026-05-13T08:36:17.000+05:30
admin: read admin_path_prefix from /auth/me + build admin URLs from it
diff --git a/src/api/index.test.ts b/src/api/index.test.ts
@@ -1259,3 +1259,117 @@ describe('reportExperimentConverted()', () => {
     })
   })
 })
+
+// ─── Admin URL prefix wiring (Track A — unguessable path) ──────────────
+//
+// The admin URL builders must read the prefix the API serves on /auth/me
+// and stitch it into the request path. Empty prefix → throw a clear
+// error (programmer error: UI should have gated on getAdminPathPrefix
+// first). logout() clears the stash so a re-login by a different user
+// can't inherit the previous user's admin path.
+
+describe('Admin URL prefix wiring', () => {
+  it('fetchMe stashes admin_path_prefix when the API serves it', async () => {
+    const m = installFetch()
+    m.mockResolvedValueOnce(jsonResponse({
+      ok: true,
+      user_id: 'u_admin',
+      team_id: 't_admin',
+      email: 'founder@instanode.dev',
+      tier: 'team',
+      trial_ends_at: null,
+      is_platform_admin: true,
+      admin_path_prefix: 'abcdefghijklmnopqrstuvwxyz012345',
+    }))
+    // Imported lazily so we get the freshly-mocked module instance.
+    const { fetchMe, getAdminPathPrefix } = await import('./index')
+    const me = await fetchMe()
+    expect(me.admin_path_prefix).toBe('abcdefghijklmnopqrstuvwxyz012345')
+    expect(getAdminPathPrefix()).toBe('abcdefghijklmnopqrstuvwxyz012345')
+  })
+
+  it('fetchMe leaves the prefix empty when the API omits the field', async () => {
+    const m = installFetch()
+    m.mockResolvedValueOnce(jsonResponse({
+      ok: true,
+      user_id: 'u_user',
+      team_id: 't_user',
+      email: 'alice@example.com',
+      tier: 'hobby',
+      trial_ends_at: null,
+      // is_platform_admin and admin_path_prefix both absent
+    }))
+    const { fetchMe, getAdminPathPrefix, setAdminPathPrefix } = await import('./index')
+    // Pre-seed a stale prefix to prove fetchMe resets it.
+    setAdminPathPrefix('stale_should_be_cleared_xxxxxxxx')
+    const me = await fetchMe()
+    expect(me.admin_path_prefix).toBeUndefined()
+    expect(getAdminPathPrefix()).toBe('')
+  })
+
+  it('logout clears the stashed admin prefix', async () => {
+    const { setAdminPathPrefix, getAdminPathPrefix } = await import('./index')
+    setAdminPathPrefix('prefix_set_by_prior_admin_session_abc')
+    expect(getAdminPathPrefix()).not.toBe('')
+    await logout()
+    expect(getAdminPathPrefix()).toBe('')
+  })
+
+  it('admin builders mint /api/v1/<prefix>/customers when the prefix is set', async () => {
+    const { setAdminPathPrefix, listAdminCustomers } = await import('./index')
+    setAdminPathPrefix('abcdefghijklmnopqrstuvwxyz012345')
+    const m = installFetch()
+    m.mockResolvedValueOnce(jsonResponse({ ok: true, customers: [], total: 0 }))
+    await listAdminCustomers()
+    const url = String(m.mock.calls[0][0])
+    expect(url).toContain('/api/v1/abcdefghijklmnopqrstuvwxyz012345/customers')
+    // The legacy guessable path must NOT appear in the request URL.
+    expect(url).not.toContain('/api/v1/admin/customers')
+  })
+
+  it('admin builders throw admin_endpoints_unavailable when the prefix is empty', async () => {
+    const { setAdminPathPrefix, listAdminCustomers, getAdminCustomer, setAdminCustomerTier, issueAdminCustomerPromo } =
+      await import('./index')
+    setAdminPathPrefix('') // closed-by-default
+    installFetch() // not actually called — every builder throws before fetch.
+
+    await expect(listAdminCustomers()).rejects.toMatchObject({
+      status: 403,
+      code: 'admin_endpoints_unavailable',
+    })
+    await expect(getAdminCustomer('t_x')).rejects.toMatchObject({
+      status: 403,
+      code: 'admin_endpoints_unavailable',
+    })
+    await expect(
+      setAdminCustomerTier('t_x', { tier: 'pro', reason: 'comp' } as any),
+    ).rejects.toMatchObject({ status: 403, code: 'admin_endpoints_unavailable' })
+    await expect(
+      issueAdminCustomerPromo('t_x', {
+        kind: 'percent_off',
+        value: 10,
+        valid_for_days: 30,
+      } as any),
+    ).rejects.toMatchObject({ status: 403, code: 'admin_endpoints_unavailable' })
+  })
+
+  it('admin builders never include /admin/ in the request URL', async () => {
+    // Belt-and-braces — even if the prefix happens to contain the
+    // substring "admin", the LEGACY path /api/v1/admin/customers must
+    // not appear in any request. Concretely: we set a prefix that
+    // contains "admin" and check the URL is built around the prefix
+    // verbatim, not the literal /api/v1/admin/.
+    const { setAdminPathPrefix, listAdminCustomers } = await import('./index')
+    const prefixWithAdminSubstring = 'preadminxxxxxxxxxxxxxxxxxxxxxxxx' // 32 chars, contains "admin"
+    setAdminPathPrefix(prefixWithAdminSubstring)
+    const m = installFetch()
+    m.mockResolvedValueOnce(jsonResponse({ ok: true, customers: [], total: 0 }))
+    await listAdminCustomers()
+    const url = String(m.mock.calls[0][0])
+    expect(url).toContain(`/api/v1/${prefixWithAdminSubstring}/customers`)
+    // The exact legacy path is /api/v1/admin/customers — i.e. /admin/
+    // bounded by slashes. A prefix containing "admin" as substring must
+    // NOT produce that exact path.
+    expect(url).not.toContain('/api/v1/admin/customers')
+  })
+})
diff --git a/src/api/index.ts b/src/api/index.ts
@@ -166,6 +166,12 @@ export async function fetchMe(): Promise<AuthMeResponse> {
      *  dashboard surfaces the `/app/admin/customers` console only when
      *  this is `true`. Absent on older API builds → treat as `false`. */
     is_platform_admin?: boolean
+    /** Unguessable URL prefix for the admin customer-management surface.
+     *  Sent by the API only when (a) the caller is on the ADMIN_EMAILS
+     *  allowlist AND (b) the deploy has ADMIN_PATH_PREFIX configured.
+     *  Absent for every other caller / configuration. Treat as "no admin
+     *  surface available" when undefined or empty. */
+    admin_path_prefix?: string
   }
   // No try/catch — errors propagate. The previous fixture fallback masked
   // backend outages by serving the `aanya@acme.dev` mock identity, which
@@ -179,6 +185,11 @@ export async function fetchMe(): Promise<AuthMeResponse> {
   // human-readable identity we have until a real team table exposes a slug.
   const localPart = me.email?.split('@')[0] ?? ''
   const slug = localPart.toLowerCase().replace(/[^a-z0-9-]/g, '-') || me.team_id.slice(0, 8)
+  // Stash the admin path prefix in a module-local var so the admin URL
+  // builders below can mint `/api/v1/${prefix}/customers/...` requests
+  // without forcing every caller to plumb it through manually. The prefix
+  // is a secret — see setAdminPathPrefix() — never log, never echo to UI.
+  setAdminPathPrefix(me.admin_path_prefix ?? '')
   return {
     user: {
       id: me.user_id,
@@ -198,6 +209,7 @@ export async function fetchMe(): Promise<AuthMeResponse> {
     },
     experiments: me.experiments,
     is_platform_admin: me.is_platform_admin === true,
+    admin_path_prefix: me.admin_path_prefix,
   }
 }
 
@@ -229,6 +241,12 @@ export async function reportExperimentConverted(input: {
 
 export async function logout(): Promise<{ ok: true }> {
   clearToken()
+  // Drop the admin URL prefix on logout. A stale prefix in module-local
+  // state would survive across a re-login by a different user (admin →
+  // non-admin same tab), and the non-admin's first /auth/me would race
+  // with their first admin-page render. Belt-and-braces: also clears it
+  // in tests that mock fetchMe but exercise logout afterwards.
+  setAdminPathPrefix('')
   return { ok: true }
 }
 
@@ -1230,16 +1248,78 @@ export async function fetchQuotaWall(): Promise<QuotaWallResponse> {
 
 // ─── Admin Customers (Track A — founder console) ────────────────────────
 //
-// Four endpoints back the /app/admin/customers page:
-//   listAdminCustomers       — GET  /api/v1/admin/customers
-//   getAdminCustomer         — GET  /api/v1/admin/customers/:team_id
-//   setAdminCustomerTier     — POST /api/v1/admin/customers/:team_id/tier
-//   issueAdminCustomerPromo  — POST /api/v1/admin/customers/:team_id/promo
+// Four endpoints back the /app/admin/customers page. They register on the
+// API under an UNGUESSABLE PATH PREFIX (env var ADMIN_PATH_PREFIX), not
+// the legacy /api/v1/admin/customers path. The prefix is delivered to
+// admin clients in the /auth/me response (`admin_path_prefix` field) and
+// stashed module-locally by fetchMe().
+//
+//   listAdminCustomers       — GET  /api/v1/<prefix>/customers
+//   getAdminCustomer         — GET  /api/v1/<prefix>/customers/:team_id
+//   setAdminCustomerTier     — POST /api/v1/<prefix>/customers/:team_id/tier
+//   issueAdminCustomerPromo  — POST /api/v1/<prefix>/customers/:team_id/promo
 //
 // Track A returns 403 with `agent_action` for non-admin callers; the
 // dashboard's route guard turns the page into a 404 for those users so
 // the route's existence isn't leaked. Other errors propagate so the
 // page renders a real banner instead of silently failing.
+//
+// SECURITY: the prefix is a credential with the same blast radius as a
+// session token. NEVER log it. NEVER echo it into rendered UI text. NEVER
+// hand it to a third-party analytics tool. The module-local var is the
+// canonical store; treat reads through getAdminPathPrefix() as "I am
+// about to build an admin URL right now."
+
+/** Module-local cache of the admin URL prefix. Populated by fetchMe()
+ *  from the /auth/me response (`admin_path_prefix`) and reset to '' by
+ *  logout(). The two reader entry-points are:
+ *
+ *  - getAdminPathPrefix() — used by tests + the route gate to check
+ *    "is the admin surface available to this session?"
+ *  - buildAdminURL(...)    — used by every admin API function to mint
+ *    a request URL; throws if the prefix is empty.
+ *
+ *  Stored at module scope so the four admin builders below stay free of
+ *  per-call arguments. Bundle-scoped, not module-scoped-per-bundle: the
+ *  Vite build leaves one instance of this module per build, so all four
+ *  builders + the route guard see the same cache. */
+let _adminPathPrefix = ''
+
+/** setAdminPathPrefix is called by fetchMe() with the value from the
+ *  /auth/me response. Idempotent; safe to call on every fetchMe(). */
+export function setAdminPathPrefix(prefix: string): void {
+  _adminPathPrefix = prefix
+}
+
+/** getAdminPathPrefix returns the currently stashed admin URL prefix, or
+ *  the empty string if /auth/me has not yet loaded or returned no value.
+ *  Components use this to decide "should I render the admin route?" — an
+ *  empty result means "no", regardless of why (no prefix configured on
+ *  the server, the caller isn't on ADMIN_EMAILS, fetchMe hasn't run yet,
+ *  or the session was just logged out). */
+export function getAdminPathPrefix(): string {
+  return _adminPathPrefix
+}
+
+/** buildAdminURL is the only place that turns the stashed prefix into an
+ *  HTTP path. Throws with a clear, copy-and-paste-able error message when
+ *  the prefix is empty — admin functions should never be called from UI
+ *  that hasn't already gated on getAdminPathPrefix(), so an empty here
+ *  is a programmer error, not a user-visible state.
+ *
+ *  Note: we deliberately omit the prefix from the error message to avoid
+ *  the case where the empty-state error gets logged with a non-empty
+ *  prefix value next to it. */
+function buildAdminURL(suffix: string): string {
+  if (_adminPathPrefix === '') {
+    throw new APIError(
+      403,
+      'admin_endpoints_unavailable',
+      'admin endpoints unavailable: not authorized or session not loaded',
+    )
+  }
+  return `/api/v1/${_adminPathPrefix}${suffix}`
+}
 
 /** Filter / sort options accepted by GET /api/v1/admin/customers. The
  *  query string is built up only for the fields the caller actually sets
@@ -1267,7 +1347,8 @@ export async function listAdminCustomers(
   if (input.limit !== undefined) params.set('limit', String(input.limit))
   if (input.offset !== undefined) params.set('offset', String(input.offset))
   const qs = params.toString()
-  const path = qs ? `/api/v1/admin/customers?${qs}` : '/api/v1/admin/customers'
+  const base = buildAdminURL('/customers')
+  const path = qs ? `${base}?${qs}` : base
   const r = await call<{
     ok: boolean
     customers?: AdminCustomerListResponse['customers']
@@ -1288,7 +1369,7 @@ export async function getAdminCustomer(
     deploys?: AdminCustomerDetailResponse['deploys']
     subscription?: AdminCustomerDetailResponse['subscription']
     promos?: AdminCustomerDetailResponse['promos']
-  }>(`/api/v1/admin/customers/${encodeURIComponent(teamID)}`)
+  }>(buildAdminURL(`/customers/${encodeURIComponent(teamID)}`))
   return {
     ok: true,
     team: r.team ?? ({ id: teamID } as AdminCustomerDetailResponse['team']),
@@ -1306,7 +1387,7 @@ export async function setAdminCustomerTier(
   input: AdminSetTierInput,
 ): Promise<AdminSetTierResponse> {
   const r = await call<{ ok: boolean; team: DashboardTeam }>(
-    `/api/v1/admin/customers/${encodeURIComponent(teamID)}/tier`,
+    buildAdminURL(`/customers/${encodeURIComponent(teamID)}/tier`),
     { method: 'POST', body: JSON.stringify(input) },
   )
   return { ok: true, team: r.team }
@@ -1317,7 +1398,7 @@ export async function issueAdminCustomerPromo(
   input: AdminIssuePromoInput,
 ): Promise<AdminIssuePromoResponse> {
   const r = await call<{ ok: boolean; code: string; expires_at: string | null }>(
-    `/api/v1/admin/customers/${encodeURIComponent(teamID)}/promo`,
+    buildAdminURL(`/customers/${encodeURIComponent(teamID)}/promo`),
     { method: 'POST', body: JSON.stringify(input) },
   )
   return { ok: true, code: r.code, expires_at: r.expires_at ?? null }
diff --git a/src/api/types.ts b/src/api/types.ts
@@ -260,6 +260,18 @@ export interface AuthMeResponse {
    *  as a regular user (404 on the admin route, link hidden). The flag
    *  is server-authoritative; the dashboard never elevates by itself. */
   is_platform_admin?: boolean
+  /** Unguessable URL segment under which the founder-only customer-management
+   *  endpoints register on the API. The agent API serves this field ONLY
+   *  for callers on the ADMIN_EMAILS allowlist AND when the operator has
+   *  configured ADMIN_PATH_PREFIX. For every non-admin caller and every
+   *  deploy without an admin path, the field is absent (not empty — absent;
+   *  the field's mere presence would leak the surface's existence).
+   *
+   *  The admin API URL builders in src/api/index.ts read this value at
+   *  fetchMe-time and stash it in a module-local var. URLs are built as
+   *  `/api/v1/${prefix}/customers/...`. With no prefix loaded, the
+   *  builders throw a clear error and the admin route hides itself. */
+  admin_path_prefix?: string
 }
 
 // ---------- Admin customers (Track A — founder console) ----------
diff --git a/src/layout/AppShell.tsx b/src/layout/AppShell.tsx
@@ -223,22 +223,29 @@ export function AppShell() {
             <NavRow to="/app/billing" icon={icons.billing}>Billing</NavRow>
             <NavRow to="/app/settings" icon={icons.settings}>Settings</NavRow>
 
-            {/* Admin-only — only rendered when /auth/me sets
-                is_platform_admin: true. Non-admin users never see the
-                link, and the underlying page 404-redirects too, so the
-                route's existence isn't leaked. */}
-            {ctx.me?.is_platform_admin && (
-              <>
-                <div className="nav-section">platform admin</div>
-                <NavRow
-                  to="/app/admin/customers"
-                  icon={icons.team}
-                  testId="nav-admin-customers"
-                >
-                  Customers
-                </NavRow>
-              </>
-            )}
+            {/* Admin-only — rendered when BOTH server-authoritative
+                signals fire: is_platform_admin (caller is on
+                ADMIN_EMAILS) AND admin_path_prefix (the API has an
+                unguessable admin URL prefix configured; without it, the
+                admin URL builder can't construct a request and the page
+                would be useless). Non-admin users + admin users on a
+                deploy without an admin path both see no link, and the
+                page 404-redirects, so the route's existence isn't
+                leaked either way. */}
+            {ctx.me?.is_platform_admin &&
+              typeof ctx.me?.admin_path_prefix === 'string' &&
+              ctx.me.admin_path_prefix.length > 0 && (
+                <>
+                  <div className="nav-section">platform admin</div>
+                  <NavRow
+                    to="/app/admin/customers"
+                    icon={icons.team}
+                    testId="nav-admin-customers"
+                  >
+                    Customers
+                  </NavRow>
+                </>
+              )}
 
             <div className="nav-section">design ref</div>
             {/* §10.21: removed the "11 gaps" badge — the contracts page is a
diff --git a/src/pages/AdminCustomersPage.test.tsx b/src/pages/AdminCustomersPage.test.tsx
@@ -42,14 +42,21 @@ vi.mock('../api', async () => {
 })
 
 // Stub useDashboardCtx so we control is_platform_admin per test.
+// We also surface admin_path_prefix because the page's gate is the
+// intersection of the two signals — both must be present for the
+// admin route to render. The fixture prefix is a 32-char alphanumeric
+// blob so it matches what the API would actually serve. Tests that
+// flip mockIsAdmin to false unset both signals at the same time.
 let mockIsAdmin = true
 let mockMeLoading = false
+const TEST_ADMIN_PATH_PREFIX = 'testfixturepathprefix0123456789ab'
 vi.mock('../hooks/useDashboardCtx', () => ({
   useDashboardCtx: () => ({
     me: {
       user: { id: 'u_admin', email: 'manas@instanode.dev', tier: 'team' },
       team: { id: 't_admin', slug: 'instanode', name: 'instanode', tier: 'team' },
       is_platform_admin: mockIsAdmin,
+      admin_path_prefix: mockIsAdmin ? TEST_ADMIN_PATH_PREFIX : undefined,
     },
     meErr: null,
     meLoading: mockMeLoading,
diff --git a/src/pages/AdminCustomersPage.tsx b/src/pages/AdminCustomersPage.tsx
@@ -119,13 +119,22 @@ export function AdminCustomersPage() {
     writeStoredCurrency(next)
   }
 
-  // Gate the entire page on the admin flag. We render Navigate(*) which
-  // matches the dashboard's catch-all and redirects to "/" — i.e., the
-  // route 404-equivalents instead of 403-ing. Non-admin users never
-  // learn the URL exists.
+  // Gate the entire page on TWO server-authoritative signals:
+  //   1. is_platform_admin — caller is on the ADMIN_EMAILS allowlist.
+  //   2. admin_path_prefix — present-and-non-empty means the operator
+  //      has configured ADMIN_PATH_PREFIX on the API. Without a prefix,
+  //      the admin URL builder in src/api/index.ts can't construct a
+  //      request anyway, so the page would be useless.
+  //
+  // We render Navigate(*) which matches the dashboard's catch-all and
+  // redirects to "/" — the route 404-equivalents instead of 403-ing.
+  // Non-admin users never learn the URL exists. Belt-and-braces: even if
+  // is_platform_admin somehow flips true without a prefix, the route
+  // still hides itself.
   const me = ctx.me
   const meLoading = ctx.meLoading
-  const isAdmin = me?.is_platform_admin === true
+  const hasAdminPrefix = typeof me?.admin_path_prefix === 'string' && me.admin_path_prefix.length > 0
+  const isAdmin = me?.is_platform_admin === true && hasAdminPrefix
 
   useEffect(() => {
     if (!isAdmin) return
