@startsimpli/auth 0.4.24 → 0.4.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/auth",
-  "version": "0.4.24",
+  "version": "0.4.25",
   "description": "Shared authentication package for StartSimpli Next.js apps",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/__tests__/auth-resolve-user.test.ts

@@ -0,0 +1,237 @@
+/**
+ * Tests for the configurable user resolver on AuthClient.
+ *
+ * Background (startsim-cotv): a relying-party tenant app signs in via central
+ * auth and receives a TENANT-scoped token (aud=tenant:<slug>). The shared
+ * AuthProvider restores the session by calling central GET /api/v1/auth/me/,
+ * which validates aud=startsimpli-firstparty and 401s the tenant token — so
+ * useAuth().user never resolves and the dashboard hangs on "Loading…".
+ *
+ * Fix: AuthConfig gains an optional `mePath` (default `/api/v1/auth/me/`, the
+ * current central behavior) and an optional `resolveUser(token)` resolver. A
+ * tenant app points `mePath` at its OWN backend (`/api/v1/whoami/`, JWKS-verified
+ * offline) and/or supplies `resolveUser` to map the whoami response shape
+ * `{sub,email,company_id,org_id,role}` to the auth `User`.
+ *
+ * The DEFAULT must be byte-for-byte the existing behavior so first-party apps
+ * (foundry control plane, vault, etc.) are unchanged.
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { AuthClient } from '../client/auth-client';
+import type { AuthUser } from '../types';
+
+function makeToken(exp: number): string {
+  const header = btoa(JSON.stringify({ alg: 'HS256', typ: 'JWT' }));
+  const body = btoa(
+    JSON.stringify({ tokenType: 'access', exp, iat: exp - 3600, jti: 'test', userId: '123' })
+  );
+  return `${header}.${body}.signature`;
+}
+
+const VALID_TOKEN = makeToken(Math.floor(Date.now() / 1000) + 3600);
+
+function seedSession(client: AuthClient) {
+  (client as any).session = {
+    user: {
+      id: '',
+      email: '',
+      firstName: '',
+      lastName: '',
+      isEmailVerified: false,
+      createdAt: '',
+      updatedAt: '',
+    },
+    accessToken: VALID_TOKEN,
+    expiresAt: Date.now() + 3600000,
+  };
+}
+
+describe('AuthClient.getCurrentUser — default mePath (unchanged behavior)', () => {
+  beforeEach(() => vi.restoreAllMocks());
+
+  it('hits central /api/v1/auth/me/ when no mePath is configured', async () => {
+    const client = new AuthClient({ apiBaseUrl: 'http://localhost:8001' });
+    seedSession(client);
+
+    const fetchMock = vi.fn().mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({
+        user: {
+          id: 'abc-123',
+          email: 'first@party.test',
+          first_name: 'First',
+          last_name: 'Party',
+          is_email_verified: true,
+          created_at: '2026-01-01T00:00:00Z',
+          updated_at: '2026-01-02T00:00:00Z',
+        },
+      }),
+    });
+    vi.stubGlobal('fetch', fetchMock);
+
+    const user = await client.getCurrentUser();
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      'http://localhost:8001/api/v1/auth/me/',
+      expect.anything()
+    );
+    expect(user.id).toBe('abc-123');
+    expect(user.email).toBe('first@party.test');
+    expect(user.firstName).toBe('First');
+    expect(user.isEmailVerified).toBe(true);
+  });
+});
+
+describe('AuthClient.getCurrentUser — configured mePath', () => {
+  beforeEach(() => vi.restoreAllMocks());
+
+  it('hits the configured mePath instead of central /auth/me/', async () => {
+    const client = new AuthClient({
+      apiBaseUrl: 'http://localhost:8465',
+      mePath: '/api/v1/whoami/',
+    });
+    seedSession(client);
+
+    const fetchMock = vi.fn().mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({
+        sub: '296eab8d-c55c-407b-82d9-e5586ff4b9c6',
+        email: 'qa-mcr@local.test',
+        company_id: 'mcr',
+        org_id: 'mcr',
+        role: 'owner',
+      }),
+    });
+    vi.stubGlobal('fetch', fetchMock);
+
+    const user = await client.getCurrentUser();
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      'http://localhost:8465/api/v1/whoami/',
+      expect.anything()
+    );
+    // The whoami shape uses `sub` as the identity; with no resolveUser the
+    // default normalizer still maps it to a usable user (id from sub).
+    expect(user.email).toBe('qa-mcr@local.test');
+    expect(user.id).toBe('296eab8d-c55c-407b-82d9-e5586ff4b9c6');
+  });
+});
+
+describe('AuthClient.getCurrentUser — configured resolveUser', () => {
+  beforeEach(() => vi.restoreAllMocks());
+
+  it('uses resolveUser to map the tenant /whoami/ shape to AuthUser', async () => {
+    const resolveUser = vi.fn(
+      async (token: string): Promise<AuthUser> => {
+        const res = await fetch('http://localhost:8465/api/v1/whoami/', {
+          headers: { Authorization: `Bearer ${token}` },
+        });
+        const w = (await res.json()) as Record<string, unknown>;
+        return {
+          id: String(w.sub),
+          email: String(w.email),
+          firstName: '',
+          lastName: '',
+          isEmailVerified: true,
+          createdAt: '',
+          updatedAt: '',
+          groups: [String(w.role)],
+          currentCompanyId: String(w.company_id),
+        };
+      }
+    );
+
+    const client = new AuthClient({
+      apiBaseUrl: 'http://localhost:8465',
+      resolveUser,
+    });
+    seedSession(client);
+
+    vi.stubGlobal(
+      'fetch',
+      vi.fn().mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          sub: 'tenant-sub-1',
+          email: 'qa-mcr@local.test',
+          company_id: 'mcr',
+          org_id: 'mcr',
+          role: 'owner',
+        }),
+      })
+    );
+
+    const user = await client.getCurrentUser();
+
+    expect(resolveUser).toHaveBeenCalledWith(VALID_TOKEN);
+    expect(user.email).toBe('qa-mcr@local.test');
+    expect(user.id).toBe('tenant-sub-1');
+    expect(user.currentCompanyId).toBe('mcr');
+    expect(user.groups).toEqual(['owner']);
+  });
+
+  it('resolveUser takes precedence over mePath', async () => {
+    const resolveUser = vi.fn(
+      async (): Promise<AuthUser> => ({
+        id: 'resolved',
+        email: 'resolved@tenant.test',
+        firstName: '',
+        lastName: '',
+        isEmailVerified: true,
+        createdAt: '',
+        updatedAt: '',
+      })
+    );
+    const fetchMock = vi.fn();
+    vi.stubGlobal('fetch', fetchMock);
+
+    const client = new AuthClient({
+      apiBaseUrl: 'http://localhost:8465',
+      mePath: '/api/v1/whoami/',
+      resolveUser,
+    });
+    seedSession(client);
+
+    const user = await client.getCurrentUser();
+
+    expect(user.id).toBe('resolved');
+    // resolveUser owns the network call; getCurrentUser must NOT also fetch mePath.
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+});
+
+describe('AuthClient.restoreSession (bootstrap) — honors mePath', () => {
+  beforeEach(() => vi.restoreAllMocks());
+
+  it('bootstrapFromCookies resolves the user via the configured mePath', async () => {
+    const client = new AuthClient({
+      apiBaseUrl: 'http://localhost:8465',
+      mePath: '/api/v1/whoami/',
+    });
+
+    const fetchMock = vi
+      .fn()
+      // 1) token/refresh
+      .mockResolvedValueOnce({ ok: true, status: 200, json: async () => ({ access: VALID_TOKEN }) })
+      // 2) whoami
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: async () => ({
+          sub: 'boot-sub',
+          email: 'boot@tenant.test',
+          company_id: 'mcr',
+          org_id: 'mcr',
+          role: 'owner',
+        }),
+      });
+    vi.stubGlobal('fetch', fetchMock);
+
+    const session = await client.restoreSession();
+
+    expect(session).not.toBeNull();
+    expect(session!.user.email).toBe('boot@tenant.test');
+    // Second fetch must target the configured whoami endpoint, not central /me/.
+    expect(fetchMock.mock.calls[1][0]).toBe('http://localhost:8465/api/v1/whoami/');
+  });
+});

package/src/__tests__/central-auth.test.ts

@@ -1,5 +1,9 @@
 import { describe, it, expect } from 'vitest';
-import { resolveAppHomeUrl, buildCentralAuthUrl } from '../utils/central-auth';
+import {
+  resolveAppHomeUrl,
+  buildCentralAuthUrl,
+  resolveCentralAuthHost,
+} from '../utils/central-auth';
 
 describe('resolveAppHomeUrl', () => {
   it('maps known app slugs to their home URL', () => {
@@ -22,4 +26,71 @@ describe('resolveAppHomeUrl', () => {
     expect(u).toContain('app=present');
     expect(u).toContain('return_to=');
   });
+  it('buildCentralAuthUrl preserves a base-path on the host (single-origin gateway)', () => {
+    // startsim-jmuw.2.7: a path-host like http://localhost:4011/auth must keep
+    // the /auth prefix, not get clobbered to http://localhost:4011/signin.
+    expect(buildCentralAuthUrl('signin', { app: 'foundry', host: 'http://localhost:4011/auth' }))
+      .toBe('http://localhost:4011/auth/signin?app=foundry');
+    expect(buildCentralAuthUrl('signin', { app: 'foundry', host: 'http://localhost:4011/auth/' }))
+      .toBe('http://localhost:4011/auth/signin?app=foundry');
+  });
+  it('buildCentralAuthUrl leaves a no-path host unchanged', () => {
+    expect(buildCentralAuthUrl('signin', { app: 'vault', host: 'https://auth.startsimpli.com' }))
+      .toBe('https://auth.startsimpli.com/signin?app=vault');
+  });
+});
+
+describe('buildCentralAuthUrl — relative (same-origin) host (startsim-jmuw.2.8 / lr8)', () => {
+  it('emits a RELATIVE, scheme/host-less URL when the host is relative', () => {
+    // A relative host like "/auth" must yield a path-only URL so the redirect
+    // stays on whatever origin the browser is currently on (works behind a
+    // DebuggAI tunnel hostname AND on real deploys).
+    expect(buildCentralAuthUrl('signin', { app: 'foundry', host: '/auth' }))
+      .toBe('/auth/signin?app=foundry');
+  });
+
+  it('preserves a trailing slash on the relative host (no double slash)', () => {
+    expect(buildCentralAuthUrl('signin', { app: 'foundry', host: '/auth/' }))
+      .toBe('/auth/signin?app=foundry');
+  });
+
+  it('supports a bare-root relative host', () => {
+    expect(buildCentralAuthUrl('signin', { app: 'foundry', host: '/' }))
+      .toBe('/signin?app=foundry');
+  });
+
+  it('keeps the return_to RELATIVE when the host is relative', () => {
+    expect(
+      buildCentralAuthUrl('signin', {
+        app: 'foundry',
+        host: '/auth',
+        returnTo: '/new?slug=acme',
+      }),
+    ).toBe('/auth/signin?app=foundry&return_to=%2Fnew%3Fslug%3Dacme');
+  });
+
+  it('still preserves app + return_to + extra params on a relative host', () => {
+    const u = buildCentralAuthUrl('signin', {
+      app: 'foundry',
+      host: '/auth',
+      returnTo: '/dashboard',
+      extraParams: { foo: 'bar' },
+    });
+    expect(u.startsWith('/auth/signin?')).toBe(true);
+    const params = new URLSearchParams(u.slice(u.indexOf('?') + 1));
+    expect(params.get('app')).toBe('foundry');
+    expect(params.get('return_to')).toBe('/dashboard');
+    expect(params.get('foo')).toBe('bar');
+  });
+
+  it('resolveCentralAuthHost returns a relative host verbatim from env', () => {
+    const prev = process.env.NEXT_PUBLIC_AUTH_HOST;
+    process.env.NEXT_PUBLIC_AUTH_HOST = '/auth';
+    try {
+      expect(resolveCentralAuthHost()).toBe('/auth');
+    } finally {
+      if (prev === undefined) delete process.env.NEXT_PUBLIC_AUTH_HOST;
+      else process.env.NEXT_PUBLIC_AUTH_HOST = prev;
+    }
+  });
 });

package/src/client/auth-client.ts

@@ -56,6 +56,10 @@ export class AuthClient implements AuthBackend {
       onUnauthorized: () => {},
       loginPath: '',
       callbackParam: 'callbackUrl',
+      // Default to the central IdP /me/ endpoint — unchanged first-party behavior.
+      // Tenant forks override this to their own /whoami/ (see AuthConfig.mePath).
+      mePath: '/api/v1/auth/me/',
+      resolveUser: undefined as unknown as Required<AuthConfig>['resolveUser'],
       ...config,
     };
   }
@@ -435,10 +439,31 @@ export class AuthClient implements AuthBackend {
   }
 
   /**
-   * Get current user data from backend
+   * Get current user data from backend.
+   *
+   * Resolution order (startsim-cotv):
+   *   1. `config.resolveUser(token)` if supplied — fully owns the resolution
+   *      (including its own network call). Used by tenant forks that map a
+   *      non-default response shape.
+   *   2. Otherwise GET `config.mePath` (default `/api/v1/auth/me/`, central IdP).
+   *      Tenant forks point mePath at their own `/api/v1/whoami/`, whose
+   *      `{sub,email,company_id,org_id,role}` shape the normalizer below maps
+   *      to AuthUser (sub→id).
    */
   async getCurrentUser(): Promise<AuthUser> {
-    const response = await fetch(`${this.config.apiBaseUrl}/api/v1/auth/me/`, {
+    if (this.config.resolveUser) {
+      const token = this.session?.accessToken;
+      if (!token) {
+        throw new Error('No access token available to resolve user');
+      }
+      const user = await this.config.resolveUser(token);
+      if (this.session) {
+        this.session.user = user;
+      }
+      return user;
+    }
+
+    const response = await fetch(`${this.config.apiBaseUrl}${this.config.mePath}`, {
       headers: this.getAuthHeaders(),
       credentials: 'include',
     });
@@ -453,7 +478,8 @@ export class AuthClient implements AuthBackend {
     const data = await response.json();
     const raw = data.user || data;
     const user: AuthUser = {
-      id: raw.id,
+      // Tenant /whoami/ returns the identity under `sub`; central /me/ uses `id`.
+      id: raw.id ?? raw.sub,
       email: raw.email,
       firstName: raw.first_name || raw.firstName || '',
       lastName: raw.last_name || raw.lastName || '',
@@ -463,6 +489,10 @@ export class AuthClient implements AuthBackend {
       isStaff: raw.is_staff ?? raw.isStaff,
       isActive: raw.is_active ?? raw.isActive,
       name: raw.full_name ?? raw.name ?? null,
+      // Tenant whoami carries role + company context; surface them so guards
+      // and company-scoped UI work without a second call. Harmless for /me/.
+      groups: raw.role ? [raw.role] : raw.groups,
+      currentCompanyId: raw.company_id ?? raw.currentCompanyId,
     };
 
     if (this.session) {

package/src/types/index.ts

@@ -131,6 +131,28 @@ export interface AuthConfig {
    * Defaults to `callbackUrl` to match the shared server middleware.
    */
   callbackParam?: string;
+  /**
+   * Path (relative to `apiBaseUrl`) the client GETs to resolve the current
+   * user. Defaults to `/api/v1/auth/me/` — the central IdP endpoint, which
+   * validates a first-party (aud=startsimpli-firstparty) token.
+   *
+   * Relying-party tenant apps (foundry forks) receive a TENANT-scoped token
+   * (aud=tenant:<slug>) that central's /auth/me/ rejects (401). Such an app
+   * MUST resolve identity from its OWN side — point this at the tenant
+   * backend's `/api/v1/whoami/` (JWKS-verified offline), which returns
+   * `{sub,email,company_id,org_id,role}`. The default normalizer maps that
+   * shape to AuthUser (sub→id); supply `resolveUser` for full control.
+   * (startsim-cotv)
+   */
+  mePath?: string;
+  /**
+   * Fully custom user resolver. When provided it OWNS resolving the current
+   * user (including any network call) and takes precedence over `mePath`.
+   * Receives the current access token. Use this to map a non-default backend
+   * response shape (e.g. the tenant `/whoami/` `{sub,email,company_id,org_id,
+   * role}`) to the auth `User`. Throw to signal an unresolvable session.
+   */
+  resolveUser?: (accessToken: string) => Promise<AuthUser>;
 }
 
 /**

package/src/utils/central-auth.ts

@@ -31,6 +31,10 @@ export type CentralAuthFlow =
 /**
  * Resolve the central auth host. Reads `NEXT_PUBLIC_AUTH_HOST` when present
  * so apps can point at a staging deploy without rebuilding the package.
+ *
+ * The value may be ABSOLUTE (`https://auth.startsimpli.com`) or RELATIVE
+ * (`/auth`, `/`). A relative value means "auth lives at this path on the SAME
+ * origin as the app" — used behind a single-origin gateway / tunnel.
  */
 export function resolveCentralAuthHost(): string {
   if (typeof process !== 'undefined' && process.env?.NEXT_PUBLIC_AUTH_HOST) {
@@ -39,6 +43,15 @@ export function resolveCentralAuthHost(): string {
   return DEFAULT_CENTRAL_AUTH_HOST;
 }
 
+/**
+ * True when the configured auth host is a relative, same-origin path (starts
+ * with `/`) rather than an absolute URL. Relative hosts produce relative
+ * redirects so they never leave the current origin.
+ */
+export function isRelativeHost(host: string): boolean {
+  return host.startsWith('/');
+}
+
 /**
  * Known app slug → production home URL. Most apps live at
  * `<slug>.startsimpli.com`; the exceptions (different registrable domains) are
@@ -93,7 +106,35 @@ export function buildCentralAuthUrl(
   options: BuildCentralAuthUrlOptions,
 ): string {
   const host = options.host ?? resolveCentralAuthHost();
-  const url = new URL(`/${flow}`, host);
+
+  // Relative host (e.g. "/auth", "/") — emit a same-origin, scheme/host-less
+  // URL (path + query only). This keeps the sign-in redirect on whatever origin
+  // the browser is currently on, which is essential behind a DebuggAI tunnel
+  // hostname (an absolute http://localhost:4011 redirect escapes the tunnel and
+  // hits the remote browser's own empty localhost → ERR_CONNECTION_REFUSED) and
+  // is equally correct on a real single-origin deploy. startsim-jmuw.2.8 (lr8).
+  if (isRelativeHost(host)) {
+    const prefix = host.replace(/\/+$/, '');
+    const params = new URLSearchParams();
+    params.set('app', options.app);
+    if (options.returnTo) {
+      params.set('return_to', options.returnTo);
+    }
+    if (options.extraParams) {
+      for (const [key, value] of Object.entries(options.extraParams)) {
+        params.set(key, value);
+      }
+    }
+    return `${prefix}/${flow}?${params.toString()}`;
+  }
+
+  // The host may carry a base-path prefix (e.g. a single-origin local gateway
+  // running auth-web under `http://localhost:4011/auth`). `new URL('/signin',
+  // host)` would discard that prefix because a leading-slash path is absolute,
+  // so we splice the flow onto the host's existing pathname instead.
+  const base = new URL(host);
+  const prefix = base.pathname.replace(/\/+$/, '');
+  const url = new URL(`${prefix}/${flow}`, base);
   url.searchParams.set('app', options.app);
   if (options.returnTo) {
     url.searchParams.set('return_to', options.returnTo);
@@ -112,9 +153,14 @@ export function buildCentralAuthUrl(
  */
 export function redirectToCentralSignin(app: string): void {
   if (typeof window === 'undefined') return;
-  const url = buildCentralAuthUrl('signin', {
-    app,
-    returnTo: window.location.href,
-  });
+  const host = resolveCentralAuthHost();
+  // For a relative (same-origin) host, prefer a RELATIVE return_to
+  // (pathname + search) so the round-trip stays on the current origin — an
+  // absolute window.location.href would re-introduce the localhost/tunnel
+  // hostname mismatch the relative redirect exists to avoid. startsim-jmuw.2.8.
+  const returnTo = isRelativeHost(host)
+    ? `${window.location.pathname}${window.location.search}`
+    : window.location.href;
+  const url = buildCentralAuthUrl('signin', { app, host, returnTo });
   window.location.href = url;
 }