@startsimpli/auth 0.4.22 → 0.4.24

package/package.json

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

package/src/__tests__/sso-exchange.test.ts

@@ -0,0 +1,128 @@
+/**
+ * Tests for the cross-domain SSO one-time-code client helpers (startsim-001y.2).
+ *
+ * mintSsoCode(): authenticated POST to /auth/sso/code/ → returns the code.
+ * redeemSsoCode(code): POST to /auth/sso/exchange/ → stores the returned access
+ * token (first-party) via setAccessToken and returns the auth result.
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import {
+  mintSsoCode,
+  redeemSsoCode,
+  redeemSsoCodeFromUrl,
+  SSO_CODE_PARAM,
+  setAccessToken,
+  getAccessToken,
+} from '../client/functions';
+
+const VALID_TOKEN =
+  'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwiZXhwIjo5OTk5OTk5OTk5fQ.sig';
+
+beforeEach(() => {
+  vi.restoreAllMocks();
+  localStorage.clear();
+  sessionStorage.clear();
+  setAccessToken(null);
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+function stubFetch(body: unknown, ok = true, status = 200) {
+  const fn = vi.fn(async () => ({
+    ok,
+    status,
+    json: async () => body,
+  }));
+  vi.stubGlobal('fetch', fn);
+  return fn;
+}
+
+describe('mintSsoCode', () => {
+  it('POSTs to the sso/code endpoint with the current access token and returns the code', async () => {
+    setAccessToken(VALID_TOKEN);
+    const fetchFn = stubFetch({ code: 'one-time-abc' });
+
+    const code = await mintSsoCode();
+
+    expect(code).toBe('one-time-abc');
+    expect(fetchFn).toHaveBeenCalledTimes(1);
+    const [url, init] = fetchFn.mock.calls[0] as [string, RequestInit];
+    expect(url).toContain('/api/v1/auth/sso/code/');
+    expect(init.method).toBe('POST');
+    expect((init.headers as Record<string, string>).Authorization).toBe(
+      `Bearer ${VALID_TOKEN}`,
+    );
+  });
+
+  it('throws when the request fails', async () => {
+    setAccessToken(VALID_TOKEN);
+    stubFetch({ detail: 'nope' }, false, 401);
+    await expect(mintSsoCode()).rejects.toThrow();
+  });
+});
+
+describe('redeemSsoCode', () => {
+  it('POSTs the code to the exchange endpoint and stores the returned access token', async () => {
+    const fetchFn = stubFetch({
+      access: VALID_TOKEN,
+      user: { id: '1', email: 'foo@bar.com' },
+    });
+
+    const result = await redeemSsoCode('one-time-abc');
+
+    expect(result.user?.email).toBe('foo@bar.com');
+    // The whole point: a first-party session token is now stored on this origin.
+    expect(getAccessToken()).toBe(VALID_TOKEN);
+
+    const [url, init] = fetchFn.mock.calls[0] as [string, RequestInit];
+    expect(url).toContain('/api/v1/auth/sso/exchange/');
+    expect(init.method).toBe('POST');
+    expect(init.credentials).toBe('include');
+    expect(JSON.parse(init.body as string)).toEqual({ code: 'one-time-abc' });
+  });
+
+  it('throws and stores nothing on a rejected code', async () => {
+    stubFetch({ detail: 'Invalid or expired code.' }, false, 400);
+    await expect(redeemSsoCode('bad')).rejects.toThrow();
+    expect(getAccessToken()).toBeNull();
+  });
+});
+
+describe('redeemSsoCodeFromUrl — app-init bootstrap', () => {
+  beforeEach(() => {
+    window.history.replaceState(null, '', '/');
+  });
+
+  it('redeems an ss_code from the URL, stores the session, and strips the param', async () => {
+    window.history.replaceState(null, '', `/dashboard?${SSO_CODE_PARAM}=abc&ref=x`);
+    stubFetch({ access: VALID_TOKEN, user: { id: '1', email: 'a@b.com' } });
+
+    const result = await redeemSsoCodeFromUrl();
+
+    expect(result?.user?.email).toBe('a@b.com');
+    expect(getAccessToken()).toBe(VALID_TOKEN);
+    // single-use: the code must not survive a reload
+    expect(window.location.search).not.toContain(SSO_CODE_PARAM);
+    expect(window.location.search).toContain('ref=x');
+  });
+
+  it('is a no-op (returns null) when there is no ss_code', async () => {
+    const fetchFn = stubFetch({});
+    const result = await redeemSsoCodeFromUrl();
+    expect(result).toBeNull();
+    expect(fetchFn).not.toHaveBeenCalled();
+  });
+
+  it('swallows a bad code (returns null) but still strips the param', async () => {
+    window.history.replaceState(null, '', `/?${SSO_CODE_PARAM}=bad`);
+    stubFetch({ detail: 'Invalid or expired code.' }, false, 400);
+
+    const result = await redeemSsoCodeFromUrl();
+
+    expect(result).toBeNull();
+    expect(getAccessToken()).toBeNull();
+    expect(window.location.search).not.toContain(SSO_CODE_PARAM);
+  });
+});

package/src/client/auth-context.tsx

@@ -14,7 +14,7 @@ import {
   type ReactNode,
 } from 'react';
 import { AuthClient } from './auth-client';
-import { setOnSessionExpired, hydrateSharedSession } from './functions';
+import { setOnSessionExpired, hydrateSharedSession, redeemSsoCodeFromUrl } from './functions';
 import type { AuthBackend } from './backend';
 import type { AuthConfig, AuthState, Session, AuthUser } from '../types';
 
@@ -88,46 +88,54 @@ export function AuthProvider({
   useEffect(() => {
     let cancelled = false;
 
-    // Cross-subdomain SSO fast-path: if we arrived from a central-auth login on
-    // another *.startsimpli.com host, seed this origin's empty token store from
-    // the shared `auth_session` cookie so restoreSession() finds a session
-    // immediately. Guarded no-op when a local session already exists.
-    hydrateSharedSession();
-
-    if (initialSession) {
-      authClient.setSession(initialSession);
-      setState({
-        session: initialSession,
-        isLoading: false,
-        isAuthenticated: true,
-      });
-      return;
-    }
+    const init = async () => {
+      // Foreign-apex SSO hand-off (startsim-001y): if central auth returned us
+      // with a one-time ?ss_code=, redeem it into a first-party session before
+      // anything else. No-op when absent (subdomain apps use the shared cookie).
+      await redeemSsoCodeFromUrl();
+      if (cancelled) return;
+
+      // Cross-subdomain SSO fast-path: if we arrived from a central-auth login on
+      // another *.startsimpli.com host, seed this origin's empty token store from
+      // the shared `auth_session` cookie so restoreSession() finds a session
+      // immediately. Guarded no-op when a local session already exists.
+      hydrateSharedSession();
+
+      if (initialSession) {
+        authClient.setSession(initialSession);
+        setState({
+          session: initialSession,
+          isLoading: false,
+          isAuthenticated: true,
+        });
+        return;
+      }
 
-    const existing = authClient.getSession();
-    if (existing) {
-      setState({
-        session: existing,
-        isLoading: false,
-        isAuthenticated: true,
-      });
-      return;
-    }
+      const existing = authClient.getSession();
+      if (existing) {
+        setState({
+          session: existing,
+          isLoading: false,
+          isAuthenticated: true,
+        });
+        return;
+      }
 
-    authClient
-      .restoreSession()
-      .then((session) => {
+      try {
+        const session = await authClient.restoreSession();
         if (cancelled) return;
         setState({
           session,
           isLoading: false,
           isAuthenticated: !!session,
         });
-      })
-      .catch(() => {
+      } catch {
         if (cancelled) return;
         setState({ session: null, isLoading: false, isAuthenticated: false });
-      });
+      }
+    };
+
+    void init();
 
     return () => {
       cancelled = true;

package/src/client/functions.ts

@@ -503,6 +503,94 @@ export async function completeMicrosoftOAuth(code: string, state: string) {
   return _completeOAuthCallback(AUTH_PATHS.OAUTH_MICROSOFT_CALLBACK, code, state);
 }
 
+/** Query param the one-time SSO code rides on. Distinct from OAuth `code`. */
+export const SSO_CODE_PARAM = 'ss_code';
+
+const AUTH_SSO_CODE_PATH = '/api/v1/auth/sso/code/';
+const AUTH_SSO_EXCHANGE_PATH = '/api/v1/auth/sso/exchange/';
+
+/**
+ * Mint a single-use SSO code for the currently-authenticated session
+ * (startsim-001y). Used by central auth (auth.startsimpli.com) to hand a
+ * session to a foreign-apex app (crochets.site, app.raisesimpli.com) that
+ * cannot receive the `.startsimpli.com` cookie. The returned code — not a JWT —
+ * is appended to the app's return URL; the app redeems it via redeemSsoCode().
+ */
+export async function mintSsoCode(): Promise<string> {
+  const token = getAccessToken();
+  const response = await fetchWithTimeout(resolveAuthUrl(AUTH_SSO_CODE_PATH), {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      ...(token ? { Authorization: `Bearer ${token}` } : {}),
+    },
+    credentials: 'include',
+    body: JSON.stringify({}),
+  });
+
+  const data = await response.json().catch(() => ({}));
+  if (!response.ok) {
+    throw new Error(extractApiError(data as Record<string, unknown>, 'Failed to mint SSO code'));
+  }
+  const code = (data as { code?: string }).code;
+  if (!code) {
+    throw new Error('SSO mint response did not contain a code');
+  }
+  return code;
+}
+
+/**
+ * Redeem a single-use SSO code for a real JWT session on THIS origin
+ * (startsim-001y). Called by a foreign-apex app when it sees an `?ss_code=`.
+ * On success the access token is stored first-party (via setAccessToken →
+ * host-only `auth_session` cookie on the foreign origin), which is exactly what
+ * the app's middleware / SessionProvider then reads.
+ */
+export async function redeemSsoCode(code: string): Promise<{ access?: string; user?: AuthUser }> {
+  const response = await fetchWithTimeout(resolveAuthUrl(AUTH_SSO_EXCHANGE_PATH), {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    credentials: 'include',
+    body: JSON.stringify({ code }),
+  });
+
+  const data = await response.json().catch(() => ({}));
+  if (!response.ok) {
+    throw new Error(extractApiError(data as Record<string, unknown>, 'Failed to redeem SSO code'));
+  }
+
+  const parsed = parseAuthResponse(data);
+  if (parsed.access) {
+    setAccessToken(parsed.access);
+  }
+  return parsed;
+}
+
+/**
+ * App-init bootstrap for foreign-apex apps (startsim-001y): if the current URL
+ * carries an `?ss_code=`, redeem it for a first-party session and strip the
+ * param so a reload never re-submits the single-use code. Returns the auth
+ * result on success, or null when there is no code / redemption failed (the
+ * app then proceeds with its normal unauthenticated flow). Safe to call on
+ * every mount; a no-op server-side or when no code is present.
+ */
+export async function redeemSsoCodeFromUrl(): Promise<{ access?: string; user?: AuthUser } | null> {
+  if (typeof window === 'undefined') return null;
+  const url = new URL(window.location.href);
+  const code = url.searchParams.get(SSO_CODE_PARAM);
+  if (!code) return null;
+
+  // Strip the param up-front so a reload never re-submits a consumed code.
+  url.searchParams.delete(SSO_CODE_PARAM);
+  window.history.replaceState(null, '', `${url.pathname}${url.search}${url.hash}`);
+
+  try {
+    return await redeemSsoCode(code);
+  } catch {
+    return null;
+  }
+}
+
 async function _completeOAuthCallback(callbackPath: string, code: string, state: string) {
   const response = await fetchWithTimeout(
     resolveAuthUrl(

package/src/index.ts

@@ -32,6 +32,11 @@ export {
   resendVerification,
   initiateGoogleOAuth,
   completeGoogleOAuth,
+  // cross-domain SSO one-time-code (startsim-001y)
+  mintSsoCode,
+  redeemSsoCode,
+  redeemSsoCodeFromUrl,
+  SSO_CODE_PARAM,
   refreshAccessToken,
   getMe,
   signOut,