@startsimpli/auth 0.4.14 → 0.4.16

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@startsimpli/auth",
-  "version": "0.4.14",
+  "version": "0.4.16",
   "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",
@@ -30,7 +31,16 @@
   },
   "peerDependencies": {
     "next": "^14.0.0 || ^15.0.0 || ^16.0.0",
-    "react": "^18.0.0 || ^19.0.0"
+    "react": "^18.0.0 || ^19.0.0",
+    "expo-secure-store": ">=12.0.0"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    },
+    "expo-secure-store": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@types/node": "^20.19.39",

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__/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/client/__tests__/mock-backend.test.ts

@@ -0,0 +1,144 @@
+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', passwordConfirm: '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 and mismatched passwords', async () => {
+    const b = createMockAuthBackend({ accounts: seed() });
+    await expect(
+      b.register({ email: 'a@x.test', password: 'pw', passwordConfirm: 'pw' })
+    ).rejects.toThrow(/already exists/i);
+    await expect(
+      b.register({ email: 'b@x.test', password: 'pw', passwordConfirm: 'nope' })
+    ).rejects.toThrow(/do not match/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();
+  });
+});

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

@@ -0,0 +1,118 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import {
+  createMemorySessionStorage,
+  createWebSessionStorage,
+  createRememberAwareSessionStorage,
+  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('createMemorySessionStorage', () => {
+  it('round-trips and clears', async () => {
+    const s = createMemorySessionStorage();
+    expect(await s.load()).toBeNull();
+    await s.save(session);
+    expect((await s.load())?.user.email).toBe('a@x.test');
+    await s.clear();
+    expect(await s.load()).toBeNull();
+  });
+});
+
+describe('createWebSessionStorage', () => {
+  beforeEach(() => localStorage.clear());
+
+  it('persists to localStorage and reads it back', async () => {
+    const s = createWebSessionStorage();
+    await s.save(session);
+    expect(localStorage.getItem(SESSION_STORAGE_KEY)).toBeTruthy();
+    expect((await s.load())?.accessToken).toBe('tok');
+  });
+
+  it('honors a custom key and an injected Storage', async () => {
+    const backing = createMemoryStorage();
+    const s = createWebSessionStorage({ key: 'k2', storage: backing });
+    await s.save(session);
+    expect(backing.getItem('k2')).toBeTruthy();
+    expect((await s.load())?.user.id).toBe('u1');
+    await s.clear();
+    expect(backing.getItem('k2')).toBeNull();
+  });
+
+  it('returns null on malformed JSON rather than throwing', async () => {
+    localStorage.setItem(SESSION_STORAGE_KEY, '{not json');
+    const s = createWebSessionStorage();
+    expect(await s.load()).toBeNull();
+  });
+
+  it('returns null when the stored value is not a Session shape', async () => {
+    localStorage.setItem(SESSION_STORAGE_KEY, JSON.stringify({ nope: true }));
+    const s = createWebSessionStorage();
+    expect(await s.load()).toBeNull();
+  });
+});
+
+describe('createRememberAwareSessionStorage', () => {
+  it('persists to the persistent store when remembering', async () => {
+    const persistent = createMemorySessionStorage();
+    const s = createRememberAwareSessionStorage(persistent, () => true);
+    await s.save(session);
+    expect((await persistent.load())?.accessToken).toBe('tok');
+    expect((await s.load())?.accessToken).toBe('tok');
+  });
+
+  it('does NOT persist (and clears) when not remembering', async () => {
+    const persistent = createMemorySessionStorage();
+    const s = createRememberAwareSessionStorage(persistent, () => false);
+    await s.save(session);
+    expect(await persistent.load()).toBeNull();
+    expect(await s.load()).toBeNull();
+  });
+
+  it('clears the persistent store when switching from remember to not', async () => {
+    const persistent = createMemorySessionStorage();
+    let remember = true;
+    const s = createRememberAwareSessionStorage(persistent, () => remember);
+    await s.save(session);
+    expect(await s.load()).not.toBeNull();
+    remember = false;
+    await s.save(session);
+    expect(await persistent.load()).toBeNull();
+  });
+
+  it('clear() wipes both stores', async () => {
+    const persistent = createMemorySessionStorage();
+    const s = createRememberAwareSessionStorage(persistent, () => true);
+    await s.save(session);
+    await s.clear();
+    expect(await s.load()).toBeNull();
+  });
+});
+
+// Minimal Storage impl for the injected-storage test.
+function createMemoryStorage(): Storage {
+  const map = new Map<string, string>();
+  return {
+    get length() {
+      return map.size;
+    },
+    clear: () => map.clear(),
+    getItem: (k: string) => (map.has(k) ? map.get(k)! : null),
+    key: (i: number) => Array.from(map.keys())[i] ?? null,
+    removeItem: (k: string) => void map.delete(k),
+    setItem: (k: string, v: string) => void map.set(k, String(v)),
+  } as Storage;
+}