@startsimpli/auth 0.4.15 → 0.4.17

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@startsimpli/auth",
-  "version": "0.4.15",
+  "version": "0.4.17",
   "description": "Shared authentication package for StartSimpli Next.js apps",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts",
     "./client": "./src/client/index.ts",
+    "./token": "./src/client/token.ts",
     "./components": "./src/components/index.ts",
     "./server": "./src/server/index.ts",
     "./types": "./src/types/index.ts",
@@ -19,25 +20,28 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "type-check": "tsc --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "clean": "rm -rf dist"
-  },
   "peerDependencies": {
+    "expo-secure-store": ">=12.0.0",
     "next": "^14.0.0 || ^15.0.0 || ^16.0.0",
     "react": "^18.0.0 || ^19.0.0"
   },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    },
+    "expo-secure-store": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@testing-library/react": "^16.3.2",
+    "@types/jsdom": "^21.1.7",
     "@types/node": "^20.19.39",
     "@types/react": "^19.2.14",
     "@vitest/ui": "^4.1.5",
     "jsdom": "^29.0.2",
-    "@types/jsdom": "^21.1.7",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.5"
@@ -51,5 +55,14 @@
   ],
   "dependencies": {
     "zod": "^4.3.6"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "clean": "rm -rf dist"
   }
-}
+}

package/src/__tests__/auth-backend-contract.test.ts

@@ -0,0 +1,84 @@
+/**
+ * AuthBackend decoupling contract (bead mcr-ios-app-dp4.1).
+ *
+ * AuthProvider now drives its state from any object satisfying AuthBackend,
+ * not just the Django AuthClient. This file pins:
+ *   1. AuthClient structurally implements AuthBackend (compile-time).
+ *   2. A minimal non-Django object satisfies AuthBackend (compile-time) — this
+ *      is the shape backendless apps inject.
+ *   3. restoreSession() delegates to the cookie bootstrap on AuthClient
+ *      (behavioral) so renaming the provider's call didn't change semantics.
+ *
+ * The end-to-end "provider renders off a mock backend" proof lives in the MCR
+ * app's Playwright e2e (the actual consumer); this package stays dependency-free.
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { AuthClient } from '../client/auth-client';
+import type { AuthBackend } from '../client/backend';
+import type { Session } from '../types';
+
+// (1) AuthClient must satisfy the interface. The `implements` clause in
+// auth-client.ts enforces this under type-check; this binding documents it.
+const _clientIsBackend: AuthBackend = new AuthClient({ apiBaseUrl: 'http://localhost' });
+
+// (2) A minimal, network-free object also satisfies the interface.
+const _minimalBackend: AuthBackend = {
+  async login() {
+    return null as unknown as Session;
+  },
+  async logout() {},
+  async register() {
+    return null as unknown as Session;
+  },
+  async getCurrentUser() {
+    return null as never;
+  },
+  async getAccessToken() {
+    return null;
+  },
+  getSession() {
+    return null;
+  },
+  setSession() {},
+  async restoreSession() {
+    return null;
+  },
+  async signInWithGoogle() {
+    return '';
+  },
+  async completeGoogleCallback() {
+    return null as unknown as Session;
+  },
+  destroy() {},
+};
+
+describe('AuthBackend contract', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('AuthClient and a minimal object both satisfy AuthBackend', () => {
+    expect(_clientIsBackend).toBeInstanceOf(AuthClient);
+    expect(typeof _minimalBackend.restoreSession).toBe('function');
+  });
+
+  it('restoreSession() delegates to bootstrapFromCookies()', async () => {
+    const client = new AuthClient({ apiBaseUrl: 'http://localhost:8001' });
+    const sentinel: Session | null = null;
+    const spy = vi
+      .spyOn(client, 'bootstrapFromCookies')
+      .mockResolvedValue(sentinel);
+
+    const result = await client.restoreSession();
+
+    expect(spy).toHaveBeenCalledTimes(1);
+    expect(result).toBe(sentinel);
+  });
+
+  it('setOnSessionExpired is optional on the contract', () => {
+    // AuthClient routes expiry through AuthConfig.onSessionExpired, so it does
+    // not implement the optional method — the provider must null-guard it.
+    expect((_clientIsBackend as AuthBackend).setOnSessionExpired).toBeUndefined();
+  });
+});

package/src/__tests__/auth-client-oauth-register.test.ts

@@ -5,7 +5,7 @@
  * swap (bead q6vf). They are written to fail until the implementation lands.
  *
  * Scope of this file:
- *  - AuthClient.register({ email, password, passwordConfirm, name? })
+ *  - AuthClient.register({ email, password, name? })
  *  - AuthClient.signInWithGoogle(redirectTo?)
  *  - AuthClient.completeGoogleCallback(code, state)
  *
@@ -46,7 +46,7 @@ describe('AuthClient.register (contract)', () => {
     vi.restoreAllMocks()
   })
 
-  it('POSTs { email, password, password_confirm, name } to /api/v1/auth/register/ and returns a Session', async () => {
+  it('POSTs { email, password, name } to /api/v1/auth/register/ and returns a Session', async () => {
     const client = new AuthClient(makeConfig())
     const mockFetch = vi.fn()
       .mockResolvedValueOnce({
@@ -62,7 +62,6 @@ describe('AuthClient.register (contract)', () => {
     const session = await client.register({
       email: 'new@example.com',
       password: 'SecurePass1!',
-      passwordConfirm: 'SecurePass1!',
       name: 'New User',
     })
 
@@ -74,7 +73,6 @@ describe('AuthClient.register (contract)', () => {
     expect(body.email).toBe('new@example.com')
     expect(body.password).toBe('SecurePass1!')
     // Backend expects snake_case for confirmation field
-    expect(body.password_confirm).toBe('SecurePass1!')
     expect(body.name).toBe('New User')
 
     // Return shape
@@ -97,7 +95,7 @@ describe('AuthClient.register (contract)', () => {
     }))
 
     await expect(
-      client.register({ email: 'taken@example.com', password: 'x', passwordConfirm: 'x' })
+      client.register({ email: 'taken@example.com', password: 'x' })
     ).rejects.toThrow(/already exists/i)
   })
 
@@ -120,7 +118,6 @@ describe('AuthClient.register (contract)', () => {
     const session = await client.register({
       email: 'fetched@example.com',
       password: 'SecurePass1!',
-      passwordConfirm: 'SecurePass1!',
     })
 
     expect(session.user.email).toBe('fetched@example.com')
@@ -134,7 +131,7 @@ describe('AuthClient.register (contract)', () => {
       json: async () => ({ access: VALID_TOKEN, user: userPayload() }),
     }))
 
-    await client.register({ email: 'new@example.com', password: 'x', passwordConfirm: 'x' })
+    await client.register({ email: 'new@example.com', password: 'x' })
 
     // The refresh timer is a private member — asserting via internal state
     // is brittle, but the behavior we care about is observable: getSession
@@ -154,7 +151,7 @@ describe('AuthClient.register (contract)', () => {
     const { getAccessToken, setAccessToken } = await import('../client/functions')
     setAccessToken(null) // start clean
 
-    await client.register({ email: 'new@example.com', password: 'x', passwordConfirm: 'x' })
+    await client.register({ email: 'new@example.com', password: 'x' })
 
     // @startsimpli/api's FetchWrapper reads via this module-level getter.
     // Without the mirror, useAuth().session would have a token but API calls

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

@@ -131,7 +131,6 @@ describe('CSRF not required for signin/register (endpoints are @csrf_exempt)', (
     await registerAccount({
       email: 'new@test.com',
       password: 'securepassword',
-      passwordConfirm: 'securepassword',
     });
 
     // Should NOT call the CSRF endpoint

package/src/__tests__/session-user-groups.test.ts

@@ -0,0 +1,45 @@
+/**
+ * The session AuthUser (types/index.ts) now carries `groups`/`permissions` so
+ * a signed-in user from useAuth() works directly with the role helpers — no
+ * separate fetch of the functional-API user shape (bead mcr-ios-app-dp4.4).
+ */
+import { describe, it, expect } from 'vitest';
+import { hasGroup, hasPermission } from '../client';
+import type { AuthUser } from '../types';
+
+const staff: AuthUser = {
+  id: 'u1',
+  email: 'staff@x.test',
+  firstName: 'MCR',
+  lastName: 'Admin',
+  isEmailVerified: true,
+  createdAt: '',
+  updatedAt: '',
+  groups: ['mcr-staff'],
+  permissions: ['artist:view-all'],
+};
+
+describe('session AuthUser role membership', () => {
+  it('resolves group membership via hasGroup', () => {
+    expect(hasGroup(staff, 'mcr-staff')).toBe(true);
+    expect(hasGroup(staff, 'artist')).toBe(false);
+  });
+
+  it('resolves permissions via hasPermission', () => {
+    expect(hasPermission(staff, 'artist:view-all')).toBe(true);
+    expect(hasPermission(staff, 'nope')).toBe(false);
+  });
+
+  it('treats a user with no groups as a member of nothing', () => {
+    const bare: AuthUser = {
+      id: 'u2',
+      email: 'a@x.test',
+      firstName: '',
+      lastName: '',
+      isEmailVerified: false,
+      createdAt: '',
+      updatedAt: '',
+    };
+    expect(hasGroup(bare, 'mcr-staff')).toBe(false);
+  });
+});

package/src/__tests__/useauth-shape-contract.test.ts

@@ -31,7 +31,6 @@ describe('useAuth() shape contract (target API)', () => {
     const _: (payload: {
       email: string
       password: string
-      passwordConfirm: string
       name?: string
       firstName?: string
       lastName?: string

package/src/client/__tests__/mock-backend.test.ts

@@ -0,0 +1,141 @@
+import { describe, it, expect } from 'vitest';
+import { createMockAuthBackend } from '../mock-backend';
+import { createMemorySessionStorage } from '../session-storage';
+import type { AuthUser } from '../../types';
+
+function user(email: string, over: Partial<AuthUser> = {}): AuthUser {
+  return {
+    id: `u-${email}`,
+    email,
+    firstName: 'A',
+    lastName: 'B',
+    isEmailVerified: true,
+    createdAt: '',
+    updatedAt: '',
+    ...over,
+  };
+}
+
+const seed = (over: Partial<{ password: string; user: AuthUser }> = {}) => [
+  { email: 'a@x.test', password: 'pw', user: user('a@x.test'), ...over },
+];
+
+describe('createMockAuthBackend', () => {
+  it('logs in with valid credentials', async () => {
+    const b = createMockAuthBackend({ accounts: seed() });
+    const s = await b.login('a@x.test', 'pw');
+    expect(s.user.email).toBe('a@x.test');
+    expect(s.accessToken).toMatch(/^mock-access\./);
+    expect(b.getSession()?.user.email).toBe('a@x.test');
+    expect(await b.getAccessToken()).toBe(s.accessToken);
+  });
+
+  it('rejects wrong password and unknown email identically', async () => {
+    const b = createMockAuthBackend({ accounts: seed() });
+    await expect(b.login('a@x.test', 'nope')).rejects.toThrow(/invalid email or password/i);
+    await expect(b.login('ghost@x.test', 'pw')).rejects.toThrow(/invalid email or password/i);
+  });
+
+  it('matches email case-insensitively', async () => {
+    const b = createMockAuthBackend({ accounts: [{ email: 'A@X.test', password: 'pw', user: user('A@X.test') }] });
+    const s = await b.login('a@x.TEST', 'pw');
+    expect(s.user.email).toBe('A@X.test');
+  });
+
+  it('registers a new account (unverified) and can sign in after', async () => {
+    const b = createMockAuthBackend();
+    const s = await b.register({ email: 'new@x.test', password: 'pw', name: 'New Artist' });
+    expect(s.user.email).toBe('new@x.test');
+    expect(s.user.isEmailVerified).toBe(false);
+    expect(s.user.name).toBe('New Artist');
+    await b.logout();
+    expect((await b.login('new@x.test', 'pw')).user.email).toBe('new@x.test');
+  });
+
+  it('rejects duplicate registration', async () => {
+    const b = createMockAuthBackend({ accounts: seed() });
+    await expect(
+      b.register({ email: 'a@x.test', password: 'pw' })
+    ).rejects.toThrow(/already exists/i);
+  });
+
+  it('persists across a "restart" via shared storage', async () => {
+    const storage = createMemorySessionStorage();
+    const b1 = createMockAuthBackend({ accounts: seed(), storage });
+    await b1.login('a@x.test', 'pw');
+
+    const b2 = createMockAuthBackend({ accounts: seed(), storage });
+    const restored = await b2.restoreSession();
+    expect(restored?.user.email).toBe('a@x.test');
+    expect(b2.getSession()?.user.email).toBe('a@x.test');
+  });
+
+  it('logout clears the persisted session', async () => {
+    const storage = createMemorySessionStorage();
+    const b = createMockAuthBackend({ accounts: seed(), storage });
+    await b.login('a@x.test', 'pw');
+    await b.logout();
+    expect(await b.restoreSession()).toBeNull();
+  });
+
+  it('expires the session and fires onSessionExpired', async () => {
+    let t = 1000;
+    const b = createMockAuthBackend({ accounts: seed(), sessionTtlMs: 100, now: () => t });
+    let expired = false;
+    b.setOnSessionExpired?.(() => {
+      expired = true;
+    });
+    await b.login('a@x.test', 'pw');
+    expect(b.getSession()).not.toBeNull();
+    t = 2000;
+    expect(b.getSession()).toBeNull();
+    expect(expired).toBe(true);
+  });
+
+  it('restoreSession drops an expired persisted session', async () => {
+    let t = 1000;
+    const storage = createMemorySessionStorage();
+    const b1 = createMockAuthBackend({ accounts: seed(), storage, sessionTtlMs: 100, now: () => t });
+    await b1.login('a@x.test', 'pw');
+    t = 5000;
+    const b2 = createMockAuthBackend({ accounts: seed(), storage, sessionTtlMs: 100, now: () => t });
+    expect(await b2.restoreSession()).toBeNull();
+  });
+
+  it('password reset flow swaps the password', async () => {
+    const b = createMockAuthBackend({ accounts: seed() });
+    const { token } = await b.requestPasswordReset('a@x.test');
+    await b.resetPassword(token, 'newpw');
+    await expect(b.login('a@x.test', 'pw')).rejects.toThrow();
+    expect((await b.login('a@x.test', 'newpw')).user.email).toBe('a@x.test');
+  });
+
+  it('rejects reset for unknown email and bogus token', async () => {
+    const b = createMockAuthBackend({ accounts: seed() });
+    await expect(b.requestPasswordReset('ghost@x.test')).rejects.toThrow(/no account/i);
+    await expect(b.resetPassword('bogus', 'x')).rejects.toThrow(/invalid or expired/i);
+  });
+
+  it('email verification flips the flag on the live session', async () => {
+    const b = createMockAuthBackend({
+      accounts: [{ email: 'a@x.test', password: 'pw', user: user('a@x.test', { isEmailVerified: false }) }],
+    });
+    await b.login('a@x.test', 'pw');
+    expect(b.getSession()?.user.isEmailVerified).toBe(false);
+    const { token } = await b.requestEmailVerification('a@x.test');
+    await b.verifyEmail(token);
+    expect(b.getSession()?.user.isEmailVerified).toBe(true);
+  });
+
+  it('upsertAccount adds a runtime account that can sign in', async () => {
+    const b = createMockAuthBackend();
+    b.upsertAccount({ email: 'late@x.test', password: 'pw', user: user('late@x.test') });
+    expect((await b.login('late@x.test', 'pw')).user.email).toBe('late@x.test');
+  });
+
+  it('oauth methods throw not-supported', async () => {
+    const b = createMockAuthBackend();
+    await expect(b.signInWithGoogle()).rejects.toThrow(/not supported/i);
+    await expect(b.completeGoogleCallback('c', 's')).rejects.toThrow(/not supported/i);
+  });
+});

package/src/client/__tests__/secure-session-storage.test.ts

@@ -0,0 +1,75 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+
+// expo-secure-store is loaded through the guarded loader; mock that seam so the
+// test controls whether the (optional) native module is "present".
+const store = vi.hoisted(() => new Map<string, string>());
+const mocked = vi.hoisted(() => ({
+  getItemAsync: vi.fn(async (k: string) => (store.has(k) ? store.get(k)! : null)),
+  setItemAsync: vi.fn(async (k: string, v: string) => void store.set(k, v)),
+  deleteItemAsync: vi.fn(async (k: string) => void store.delete(k)),
+}));
+const loadSecureStore = vi.hoisted(() => vi.fn());
+vi.mock('../optional-secure-store', () => ({ loadSecureStore }));
+
+import { createSecureSessionStorage } from '../secure-session-storage.native';
+import { SESSION_STORAGE_KEY } from '../session-storage';
+import type { Session } from '../../types';
+
+const session: Session = {
+  user: {
+    id: 'u1',
+    email: 'a@x.test',
+    firstName: 'A',
+    lastName: 'B',
+    isEmailVerified: true,
+    createdAt: '',
+    updatedAt: '',
+  },
+  accessToken: 'tok',
+  expiresAt: Date.now() + 1e6,
+};
+
+describe('createSecureSessionStorage (native module present)', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    store.clear();
+    loadSecureStore.mockReturnValue(mocked);
+  });
+
+  it('round-trips a session through SecureStore under the default key', async () => {
+    const s = createSecureSessionStorage();
+    await s.save(session);
+    expect(mocked.setItemAsync).toHaveBeenCalledWith(
+      SESSION_STORAGE_KEY,
+      expect.stringContaining('a@x.test')
+    );
+    const loaded = await s.load();
+    expect(loaded?.user.email).toBe('a@x.test');
+  });
+
+  it('returns null when nothing is stored', async () => {
+    const s = createSecureSessionStorage('empty.key');
+    expect(await s.load()).toBeNull();
+  });
+
+  it('clears by deleting the key', async () => {
+    const s = createSecureSessionStorage();
+    await s.clear();
+    expect(mocked.deleteItemAsync).toHaveBeenCalledWith(SESSION_STORAGE_KEY);
+  });
+});
+
+describe('createSecureSessionStorage (native module absent — graceful fallback)', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    loadSecureStore.mockReturnValue(null);
+  });
+
+  it('falls back to in-memory and never touches SecureStore', async () => {
+    const s = createSecureSessionStorage();
+    expect(await s.load()).toBeNull();
+    await s.save(session);
+    expect((await s.load())?.user.email).toBe('a@x.test'); // in-memory round-trip
+    expect(mocked.setItemAsync).not.toHaveBeenCalled();
+  });
+});

package/src/client/__tests__/secure-token-storage.test.ts

@@ -0,0 +1,69 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+
+// expo-secure-store is loaded through the guarded loader; mock that seam so the
+// test controls whether the (optional) native module is "present".
+const mocked = vi.hoisted(() => ({
+  getItemAsync: vi.fn(),
+  setItemAsync: vi.fn(),
+  deleteItemAsync: vi.fn(),
+}));
+const loadSecureStore = vi.hoisted(() => vi.fn());
+vi.mock('../optional-secure-store', () => ({ loadSecureStore }));
+
+import { SecureTokenStorage, REFRESH_TOKEN_KEY } from '../secure-token-storage.native';
+
+describe('SecureTokenStorage (native module present)', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    loadSecureStore.mockReturnValue(mocked);
+  });
+
+  it('reads the refresh token from SecureStore under a stable key', async () => {
+    mocked.getItemAsync.mockResolvedValueOnce('rt');
+    const storage = new SecureTokenStorage();
+    expect(await storage.getRefreshToken()).toBe('rt');
+    expect(mocked.getItemAsync).toHaveBeenCalledWith(REFRESH_TOKEN_KEY);
+  });
+
+  it('returns null when nothing is stored', async () => {
+    mocked.getItemAsync.mockResolvedValueOnce(null);
+    const storage = new SecureTokenStorage();
+    expect(await storage.getRefreshToken()).toBeNull();
+  });
+
+  it('writes the refresh token under the same key', async () => {
+    const storage = new SecureTokenStorage();
+    await storage.setRefreshToken('rt2');
+    expect(mocked.setItemAsync).toHaveBeenCalledWith(REFRESH_TOKEN_KEY, 'rt2');
+  });
+
+  it('clears by deleting the key', async () => {
+    const storage = new SecureTokenStorage();
+    await storage.clear();
+    expect(mocked.deleteItemAsync).toHaveBeenCalledWith(REFRESH_TOKEN_KEY);
+  });
+
+  it('honors a custom key', async () => {
+    const storage = new SecureTokenStorage('custom.refresh');
+    await storage.setRefreshToken('x');
+    expect(mocked.setItemAsync).toHaveBeenCalledWith('custom.refresh', 'x');
+  });
+});
+
+describe('SecureTokenStorage (native module absent — graceful fallback)', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    loadSecureStore.mockReturnValue(null);
+  });
+
+  it('falls back to in-memory and never touches SecureStore', async () => {
+    const storage = new SecureTokenStorage();
+    expect(await storage.getRefreshToken()).toBeNull();
+    await storage.setRefreshToken('rt');
+    expect(await storage.getRefreshToken()).toBe('rt');
+    await storage.clear();
+    expect(await storage.getRefreshToken()).toBeNull();
+    expect(mocked.getItemAsync).not.toHaveBeenCalled();
+    expect(mocked.setItemAsync).not.toHaveBeenCalled();
+  });
+});