@ateam-ai-mobile/core 0.1.6 → 0.1.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ateam-ai-mobile/core",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Headless ADAS SDK core — auth bridge, API client, chat/job streaming, MCP calls, theme tokens. No UI, no Expo dependencies.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/acs/ws.ts

@@ -39,6 +39,19 @@ const TOPIC = 'acs.artifacts';
 const TOPIC_HOME = 'acs.home-actions';
 const MAX_BACKOFF_MS = 30_000;
 
+// Application close codes the SERVER means as PERMANENT — reconnecting with the
+// same credentials will just be refused again, so we stop the retry loop instead
+// of hammering the socket every 30s forever (silently, on the user's mobile
+// data). We do NOT interpret what the code MEANS for the UI — that is the
+// server's job via GET /api/session; here we only decide "retrying is pointless."
+// Extend as the backend documents more terminal codes.
+//   4003 = invalid/inactive tenant (e.g. an expired trial workspace).
+const TERMINAL_CLOSE_CODES = new Set<number>([4003]);
+
+// Set when a terminal close arrives; suppresses BOTH the backoff loop and the
+// foreground re-poke until an explicit connectAcsWs() (new creds / reactivation).
+let _terminated = false;
+
 function backoffMs(attempt: number): number {
   // 0.5s, 1s, 2s, 4s, ... capped at 30s. Tiny jitter to avoid thundering herd.
   const base = Math.min(MAX_BACKOFF_MS, 500 * Math.pow(2, attempt));
@@ -125,12 +138,23 @@ function openSocket() {
   const ws = new WebSocket(url);
   _ws = ws;
 
+  // IDENTITY GUARD. `connectAcsWs()` (tenant switch / re-auth) and reconnects
+  // replace `_ws` while an OLD socket may still be mid-teardown. A late callback
+  // from that old socket must NOT touch the singleton state of the CURRENT one:
+  // its `onclose` could null out the live `_ws`, schedule a spurious reconnect,
+  // or poison `_terminated` for a connection that is perfectly healthy. Every
+  // callback proves it is still the current socket before doing anything — the
+  // captured `ws` vs the live `_ws`. A superseded socket's events are inert.
+  const isCurrent = () => ws === _ws;
+
   ws.onopen = () => {
+    if (!isCurrent()) return;
     _retryAttempt = 0;
     send({ type: 'subscribe', topic: TOPIC });
     send({ type: 'subscribe', topic: TOPIC_HOME });
   };
   ws.onmessage = (e) => {
+    if (!isCurrent()) return;
     try {
       const msg = JSON.parse(typeof e.data === 'string' ? e.data : '');
       handleEvent(msg);
@@ -140,13 +164,28 @@ function openSocket() {
     }
   };
   ws.onerror = (e: any) => {
+    if (!isCurrent()) return;
     console.warn('[acsWs] error', e?.message || e);
   };
-  ws.onclose = () => {
+  ws.onclose = (ev: any) => {
+    // A superseded socket closing is expected and inert — do not clear the live
+    // `_ws`, schedule a retry, or set `_terminated`. Only the CURRENT socket's
+    // close drives the reconnect/terminate state machine.
+    if (!isCurrent()) return;
     _ws = null;
     if (!_wantOpen) return;
+    const code = typeof ev?.code === 'number' ? ev.code : 0;
+    if (TERMINAL_CLOSE_CODES.has(code)) {
+      // Permanent refusal — stop. Only an explicit connectAcsWs() (re-auth or
+      // tenant change) clears this; the automatic loop and foreground re-poke
+      // both stay off so we never loop against a socket that will keep refusing.
+      _terminated = true;
+      if (_retryTimer) { clearTimeout(_retryTimer); _retryTimer = null; }
+      console.warn(`[acsWs] server refused permanently (close ${code}); stopping reconnects until re-auth/tenant change`);
+      return;
+    }
     const delay = backoffMs(_retryAttempt++);
-    console.log(`[acsWs] closed; reconnecting in ${Math.round(delay)}ms (attempt ${_retryAttempt})`);
+    console.log(`[acsWs] closed (${code}); reconnecting in ${Math.round(delay)}ms (attempt ${_retryAttempt})`);
     if (_retryTimer) clearTimeout(_retryTimer);
     _retryTimer = setTimeout(openSocket, delay);
   };
@@ -158,6 +197,7 @@ function openSocket() {
  * immediately rather than waiting out the backoff timer.
  */
 export function notifyAcsWsForeground() {
+  if (_terminated) return; // permanent refusal — don't re-poke a socket that keeps refusing
   if (_wantOpen && !_ws) {
     if (_retryTimer) { clearTimeout(_retryTimer); _retryTimer = null; }
     _retryAttempt = 0;
@@ -171,6 +211,9 @@ export function notifyAcsWsForeground() {
  * (JWT available).
  */
 export function connectAcsWs(token: string, tenant: string) {
+  // Explicit connect (sign-in, tenant switch, reactivation) always gets a fresh
+  // chance — clear any terminal state a prior refusal left behind.
+  _terminated = false;
   if (_ws && _wantOpen && _token === token && _tenant === tenant) return;
   // Token or tenant changed → tear down + reopen.
   if (_ws) {
@@ -188,6 +231,7 @@ export function connectAcsWs(token: string, tenant: string) {
  */
 export function disconnectAcsWs() {
   _wantOpen = false;
+  _terminated = false;
   _token = null;
   _tenant = null;
   if (_retryTimer) { clearTimeout(_retryTimer); _retryTimer = null; }

package/src/api/tenants.ts

@@ -8,12 +8,26 @@ export interface TenantMembership {
 }
 
 /**
- * List the tenants the CURRENT user belongs to (GET /api/tenants/list).
+ * List the tenants the CURRENT user belongs to.
  *
  * The list is membership-scoped: for consumer JWTs the backend returns ONLY
  * tenants where the user's login identity (google/apple oauth or embed id)
  * has an active actor; builder JWTs get their user-doc memberships. It never
  * leaks the full tenant list. Returns [] when signed out or unknown.
+ *
+ * IT CALLS CONSUMER-AUTH, NOT CORE. This used to be
+ * `apiFetch('/api/tenants/list')` against the Core API, which is the wrong
+ * service: the membership a consumer JWT proves is held by consumer-auth, so
+ * Core could not answer it for the case that matters — a signed-in consumer
+ * asking which teams they are in. Hence the explicit fetch with the bearer
+ * token rather than the shared `apiFetch` helper, which is Core-scoped.
+ *
+ * EVERY FAILURE PATH RETURNS [] deliberately: no token, non-OK response,
+ * unparseable body, or a thrown fetch. "I could not find out" and "you belong
+ * to nothing" are genuinely different, but this signature has no room to say
+ * so — the caller renders a team list, and an empty one is the safe render.
+ * If that distinction ever matters, widen the return type rather than
+ * inventing a tenant.
  */
 export async function listMyTenants(): Promise<TenantMembership[]> {
   const token = getToken();
@@ -26,6 +40,8 @@ export async function listMyTenants(): Promise<TenantMembership[]> {
     if (!res.ok || !data?.ok || !Array.isArray(data.tenants)) return [];
     return data.tenants.map((t: any) => ({
       id: t.id,
+      // Fall back to the id rather than to an empty string: a nameless row in
+      // a team switcher is unpickable.
       name: t.name || t.id,
       role: t.role ?? null,
     }));

package/src/authSession.ts

@@ -0,0 +1,241 @@
+/**
+ * SDK-owned session state machine (R6).
+ *
+ * Until R6 the JWT lifecycle lived in the app (apps/mobile/src/stores/
+ * authStore.ts): token storage, the decode/user projection, the startup
+ * restore + silent refresh, and the refresh decision table. A second host
+ * (host-demo, a third-party app) had to re-implement all of it. R6 moves the
+ * MECHANISM here; the host keeps only what is genuinely its own — secure
+ * storage and the side effects of signing out.
+ *
+ * Two seams keep this free of any app/Expo import and free of an auth<->bridge
+ * cycle (the plan's explicit constraint):
+ *   - `persistence`  the host's secure JWT storage (get/save/clear). The SDK
+ *                    never imports expo-secure-store.
+ *   - `onLogout`     the host's teardown, run in ONE place so the order is
+ *                    owned here: stop the device/relay bridge, unregister push
+ *                    (while the token still exists), clear plugin storage +
+ *                    bundle cache + device-tool registry, close chat. The SDK
+ *                    calls it; it never imports the stores that do the work.
+ *
+ * The refresh decision table and JWT projection are moved VERBATIM from the app
+ * so behaviour is identical (the R0.5 authRefresh baseline is the oracle).
+ */
+import { getCoreApiUrl, type RefreshOutcome } from './config';
+
+export interface SessionUser {
+  actorId: string;
+  email?: string;
+  displayName?: string;
+  // Explicit role axes (Phase 4). `roles` is legacy (empty for newer tokens).
+  tenantRole?: string | null;
+  serviceRole?: string | null;
+  platformRoles?: string[];
+  roles: string[];
+}
+
+export type SessionStatus = 'loading' | 'authenticated' | 'signed_out';
+
+export interface AuthSessionState {
+  token: string | null;
+  user: SessionUser | null;
+  status: SessionStatus;
+}
+
+/**
+ * The host's secure JWT storage. Only the token lives here — tenant selection
+ * and env are resolved through the config getters, not stored by the session
+ * (derive-never-store).
+ */
+export interface SessionPersistence {
+  loadToken(): Promise<string | null>;
+  saveToken(token: string): Promise<void>;
+  clearToken(): Promise<void>;
+}
+
+export interface AuthSessionDeps {
+  persistence: SessionPersistence;
+  /**
+   * Host teardown for sign-out, run by `logout()` WHILE THE TOKEN STILL EXISTS
+   * (push unregister needs the JWT) and BEFORE the SDK clears it. The host does
+   * the app-specific work — stop the bridge, unregister push, clear the tenant
+   * keys, evict plugin storage / bundle cache / device-tool registry, close
+   * chat — in this one hook, so there is no auth->bridge import cycle.
+   */
+  onLogout?: () => void | Promise<void>;
+  /**
+   * Called when a token is adopted (login, or a successful refresh) with the
+   * projected user, so the host can persist side data (e.g. its TENANT key)
+   * without the session reaching into app storage.
+   */
+  onToken?: (token: string, user: SessionUser | null) => void | Promise<void>;
+}
+
+// ── JWT projection (verbatim from the app) ──────────────────────────────────
+
+function decodeJwtPayload(token: string): Record<string, any> | null {
+  try {
+    const segs = token.split('.');
+    if (segs.length !== 3) return null;
+    // base64url → base64
+    const b64 = segs[1].replace(/-/g, '+').replace(/_/g, '/');
+    // Pad to a multiple of 4
+    const padded = b64 + '='.repeat((4 - (b64.length % 4)) % 4);
+    const json = typeof atob === 'function'
+      ? atob(padded)
+      // Hermes always has atob; fallback for older runtimes
+      : Buffer.from(padded, 'base64').toString('utf8');
+    return JSON.parse(json);
+  } catch {
+    return null;
+  }
+}
+
+export function userFromJwt(token: string): SessionUser | null {
+  const claims = decodeJwtPayload(token);
+  if (!claims?.sub) return null;
+  return {
+    actorId: String(claims.sub),
+    email: claims.email,
+    displayName: claims.name || claims.email,
+    tenantRole: claims.tenantRole ?? null,
+    serviceRole: claims.serviceRole ?? null,
+    platformRoles: Array.isArray(claims.platformRoles) ? claims.platformRoles : [],
+    roles: Array.isArray(claims.roles) ? claims.roles : [],
+  };
+}
+
+// ── Refresh decision table (verbatim from the app) ──────────────────────────
+//
+// Three outcomes so a caller can tell "log out" from "transient blip":
+//   ok           — a fresh JWT, adopt it.
+//   auth_failed  — 401/403 or a malformed 2xx: session genuinely broken.
+//   transient    — network / 5xx / other non-auth: keep the session, retry later.
+
+type RefreshResult =
+  | { ok: 'ok'; token: string }
+  | { ok: 'auth_failed'; status: number; reason: string }
+  | { ok: 'transient'; status?: number; reason: string };
+
+/**
+ * Hit Core's POST /api/auth/refresh with the (possibly expired) token. The
+ * endpoint accepts expired tokens within a grace period. Standalone so
+ * `restore()` can call it before anything reads `getToken()`.
+ */
+async function attemptRefresh(expiredToken: string): Promise<RefreshResult> {
+  let res: Response;
+  try {
+    res = await fetch(`${getCoreApiUrl()}/api/auth/refresh`, {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${expiredToken}`,
+        'Content-Type': 'application/json',
+      },
+    });
+  } catch (e: any) {
+    console.warn('[adas/session] refresh fetch threw (network):', e?.message || e);
+    return { ok: 'transient', reason: `network: ${e?.message || 'unknown'}` };
+  }
+  if (res.status === 401 || res.status === 403) {
+    console.warn(`[adas/session] refresh rejected with ${res.status} — auth genuinely broken`);
+    return { ok: 'auth_failed', status: res.status, reason: `core ${res.status}` };
+  }
+  if (!res.ok) {
+    console.warn(`[adas/session] refresh server error ${res.status} — treating as transient`);
+    return { ok: 'transient', status: res.status, reason: `core ${res.status}` };
+  }
+  const body = await res.json().catch(() => null);
+  if (typeof body?.token === 'string') return { ok: 'ok', token: body.token };
+  console.warn('[adas/session] refresh returned 2xx but no token — treating as auth_failed');
+  return { ok: 'auth_failed', status: res.status, reason: 'malformed refresh response' };
+}
+
+export interface AuthSession {
+  /** Current token (synchronous, in-memory) — the TokenProvider read path. */
+  getToken(): string | null;
+  getUser(): SessionUser | null;
+  getState(): AuthSessionState;
+  subscribe(cb: (s: AuthSessionState) => void): () => void;
+  /** Startup: load the persisted token, project the user, and silently refresh
+   *  an expired JWT (ok → adopt, auth_failed → sign out, transient → keep). */
+  restore(): Promise<void>;
+  /** Adopt a freshly-minted token (host authenticated the user). */
+  login(token: string): Promise<void>;
+  /** Sign out: host teardown (with token still present) → clear token → state. */
+  logout(): Promise<void>;
+  /** The 401 refresh path. Adopts a new token on success; returns the API
+   *  client's outcome shape ('ok' → retry, 'auth_failed' → sign out). */
+  refresh(): Promise<RefreshOutcome>;
+}
+
+export function createAuthSession(deps: AuthSessionDeps): AuthSession {
+  let state: AuthSessionState = { token: null, user: null, status: 'loading' };
+  const subs = new Set<(s: AuthSessionState) => void>();
+  const set = (patch: Partial<AuthSessionState>) => {
+    state = { ...state, ...patch };
+    for (const cb of subs) cb(state);
+  };
+
+  async function adopt(token: string): Promise<void> {
+    await deps.persistence.saveToken(token);
+    const user = userFromJwt(token);
+    set({ token, user, status: 'authenticated' });
+    await deps.onToken?.(token, user);
+  }
+
+  async function refresh(): Promise<RefreshOutcome> {
+    const current = state.token;
+    if (!current) return { ok: 'auth_failed', status: 0, reason: 'no token in store' };
+    const outcome = await attemptRefresh(current);
+    if (outcome.ok === 'ok') { await adopt(outcome.token); return { ok: 'ok', status: 200 }; }
+    if (outcome.ok === 'auth_failed') return { ok: 'auth_failed', status: outcome.status, reason: outcome.reason };
+    return { ok: 'transient', status: outcome.status ?? 0, reason: outcome.reason };
+  }
+
+  async function logout(): Promise<void> {
+    // Host teardown runs FIRST, while the token still exists — push unregister
+    // needs the JWT — then the SDK clears the token and flips to signed_out.
+    await deps.onLogout?.();
+    await deps.persistence.clearToken();
+    set({ token: null, user: null, status: 'signed_out' });
+  }
+
+  return {
+    getToken: () => state.token,
+    getUser: () => state.user,
+    getState: () => state,
+    subscribe(cb) { subs.add(cb); return () => { subs.delete(cb); }; },
+
+    async restore() {
+      const token = await deps.persistence.loadToken();
+      if (!token) { set({ status: 'signed_out' }); return; }
+      const user = userFromJwt(token);
+      if (!user) { await deps.persistence.clearToken(); set({ status: 'signed_out' }); return; }
+      const claims = decodeJwtPayload(token);
+      const exp = typeof claims?.exp === 'number' ? claims.exp * 1000 : 0;
+      if (exp && Date.now() >= exp) {
+        const outcome = await attemptRefresh(token);
+        if (outcome.ok === 'ok') { await adopt(outcome.token); return; }
+        if (outcome.ok === 'auth_failed') {
+          await deps.persistence.clearToken();
+          set({ token: null, user: null, status: 'signed_out' });
+          return;
+        }
+        // transient — keep the stale token; apiFetch retries and next launch
+        // refreshes again. Better than a re-login on a server blip.
+        set({ token, user, status: 'authenticated' });
+        return;
+      }
+      set({ token, user, status: 'authenticated' });
+    },
+
+    async login(token: string) {
+      const user = userFromJwt(token);
+      if (!user) throw new Error('Invalid JWT — could not decode subject');
+      await adopt(token);
+    },
+
+    logout,
+    refresh,
+  };
+}

package/src/chat/store.ts

@@ -725,6 +725,20 @@ function dispatchPluginCommands(cmds: any[]) {
 // Persistent WS connection — stays open across jobs
 let _ws: WebSocket | null = null;
 let _wsReady = false;
+
+/** What this client can execute, supplied by the host (see setClientDeclarationProvider). */
+type ClientDeclaration = { device_host: boolean; tools: Array<{ name: string }> };
+let _clientDeclarationProvider: (() => ClientDeclaration | null) | null = null;
+
+/**
+ * Host DI: what to tell the server about this client on connect.
+ *
+ * Kept as a provider rather than a value because the answer changes — plugins
+ * load after boot, so the tool list is not known when the socket first opens.
+ */
+export function setClientDeclarationProvider(fn: (() => ClientDeclaration | null) | null): void {
+  _clientDeclarationProvider = fn;
+}
 let _currentJobId: string | null = null;
 
 function ensureWs(tenant: string, token: string | null): WebSocket {
@@ -737,6 +751,18 @@ function ensureWs(tenant: string, token: string | null): WebSocket {
 
   ws.onopen = () => {
     _wsReady = true;
+
+    // Tell the server what this client IS. A device tool executes here, so the
+    // server has to reach the right connection: the same person may also have a
+    // browser tab on this stream, and "read the GPS" has one correct answer.
+    // Without this the server can only broadcast and hope.
+    try {
+      const declared = _clientDeclarationProvider?.();
+      if (declared) ws.send(JSON.stringify({ type: 'declare_client', ...declared }));
+    } catch {
+      // Never let a declaration failure cost us the connection.
+    }
+
     // If a job is waiting for the connection, subscribe now
     if (_currentJobId) {
       ws.send(JSON.stringify({ type: 'subscribe', jobId: _currentJobId }));

package/src/consumerAuth.ts

@@ -0,0 +1,216 @@
+/**
+ * Consumer-auth service client (R9 — moved from the app).
+ *
+ * Wraps the public consumer-auth service: config fetch, Google/Apple sign-in,
+ * the web→app handoff exchange, the invite/open-join flows, and channel-link OTP.
+ * Generic auth-flow mechanism — the host's native layer acquires the provider
+ * id_token; this trades it for a tenant-scoped session JWT. It reads only the
+ * SDK config getters (consumer-auth URL + the resolved tenant, which pre-auth
+ * resolves to the host's active pick), so any host reuses it unchanged.
+ */
+import { getConsumerAuthApiUrl, getTenant } from './config';
+
+export interface ConsumerProviderConfig {
+  google?: {
+    // Platform-specific client IDs. Each is its own Google OAuth client
+    // (Web / iOS / Android — registered separately in Google Cloud Console).
+    // The id_token's `aud` claim is whichever client minted it, so the
+    // backend accepts any of them as a valid audience. The host picks the
+    // right one for the current Platform.OS.
+    web_client_id?: string;
+    ios_client_id?: string;
+    android_client_id?: string;
+    // Legacy single field — kept for backward compat with older configs.
+    client_id?: string;
+  };
+  apple?: { service_id: string };
+}
+
+export interface ConsumerCapabilityConfig {
+  ok: boolean;
+  tenant: string;
+  providers: ConsumerProviderConfig;
+  linked_channels: string[];
+}
+
+export interface ConsumerSignInResult {
+  ok: boolean;
+  jwt: string;
+  actor: { id: string; email: string; role: string };
+}
+
+export interface OtpStartResult {
+  ok: boolean;
+  challenge_id: string;
+  sent_to: string;
+  provider: string;
+  debug_code?: string; // present only in stub mode
+}
+
+/**
+ * Build a user-facing error message that NEVER includes raw HTML response
+ * bodies. Cloudflare's 502 page is several KB of `<html>...` markup; bubbling
+ * it through `Error.message` dumps it onto the login screen as raw text. We
+ * trim aggressively and detect HTML so the user sees something useful.
+ */
+function cleanErrorMessage(status: number, rawText: string, fallback: string): string {
+  const trimmed = (rawText || '').trim();
+  // Cloudflare / nginx / generic web-server error pages all start with `<`.
+  if (trimmed.startsWith('<')) {
+    return `${fallback} (${status}) — backend unreachable`;
+  }
+  if (!trimmed) return `${fallback} (${status})`;
+  // Cap to 200 chars so a verbose JSON error doesn't still dump a wall of text.
+  const short = trimmed.length > 200 ? `${trimmed.slice(0, 200)}…` : trimmed;
+  return `${fallback} (${status}): ${short}`;
+}
+
+async function postJson<T>(path: string, body: unknown, jwt?: string): Promise<T> {
+  const res = await fetch(`${getConsumerAuthApiUrl()}${path}`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      ...(jwt ? { Authorization: `Bearer ${jwt}` } : {}),
+    },
+    body: JSON.stringify(body),
+  });
+  const text = await res.text();
+  let parsed: any = null;
+  try { parsed = JSON.parse(text); } catch { /* leave as null — text isn't JSON */ }
+  if (!res.ok || parsed?.ok === false) {
+    if (parsed?.error) throw new Error(parsed.error);
+    throw new Error(cleanErrorMessage(res.status, text, `consumer-auth ${path} failed`));
+  }
+  return parsed as T;
+}
+
+/**
+ * Fetch the public consumer config for the active tenant. Returns the public
+ * OAuth client IDs needed to render Google/Apple sign-in buttons.
+ */
+export async function fetchConsumerConfig(): Promise<ConsumerCapabilityConfig> {
+  const url = `${getConsumerAuthApiUrl()}/platform/consumer/config?tenant=${encodeURIComponent(getTenant())}`;
+  const res = await fetch(url);
+  // Read as text first so a Cloudflare 502 HTML page doesn't crash res.json()
+  // with a multi-KB error message that ends up rendered on the login screen.
+  const text = await res.text();
+  let data: any = null;
+  try { data = JSON.parse(text); } catch { /* not JSON — leave null, fall through */ }
+  if (!res.ok || !data?.ok) {
+    if (data?.error) throw new Error(data.error);
+    throw new Error(cleanErrorMessage(res.status, text, 'Failed to load sign-in config'));
+  }
+  return data;
+}
+
+/**
+ * Exchange a Google id_token for a tenant-scoped consumer JWT. The id_token
+ * comes from the host's native Google sign-in flow.
+ */
+export async function signInWithGoogle(idToken: string): Promise<ConsumerSignInResult> {
+  return postJson<ConsumerSignInResult>('/platform/consumer/oauth/google', {
+    tenant: getTenant(),
+    id_token: idToken,
+  });
+}
+
+/** Exchange an Apple id_token for a tenant-scoped consumer JWT. */
+export async function signInWithApple(idToken: string): Promise<ConsumerSignInResult> {
+  return postJson<ConsumerSignInResult>('/platform/consumer/oauth/apple', {
+    tenant: getTenant(),
+    id_token: idToken,
+  });
+}
+
+// ─── Web → app sign-in handoff ─────────────────────────────────────────
+// An already-authenticated WEB session mints a short-lived, single-use code
+// (QR / deep link: <scheme>://handoff?handoff=<code>). The app trades that code
+// for a normal session JWT here — NO auth header: the code IS the credential.
+// The code is single-use and 60s-lived; the returned JWT is a normal session
+// token. Second use / expired → the server 410s (surface as a friendly retry).
+//
+// `tenant` echoes the tenant the code was bound to. The session sets the active
+// tenant from the host, NOT from the JWT, so the caller must adopt this tenant
+// before login() or a cross-tenant handoff would mislabel the session.
+export interface HandoffExchangeResult extends ConsumerSignInResult {
+  tenant?: string;
+}
+export async function exchangeHandoff(code: string): Promise<HandoffExchangeResult> {
+  return postJson<HandoffExchangeResult>('/platform/consumer/handoff/exchange', { code });
+}
+
+// ─── Invite join flow ──────────────────────────────────────────────────
+// A tenant admin issues an invite; the code IS the tenant proof (no slug is
+// ever sent).
+
+export interface InvitePreview {
+  ok: boolean;
+  org: string;            // display name only — never the tenant slug
+  role: string | null;
+}
+
+/**
+ * Preview an invite (no auth) to render the "Join <Org> as <role>?" screen.
+ * Throws with a friendly message on 404 (invalid/expired).
+ */
+export async function previewInvite(code: string): Promise<InvitePreview> {
+  const url = `${getConsumerAuthApiUrl()}/platform/consumer/invite/${encodeURIComponent(code)}`;
+  const res = await fetch(url);
+  const text = await res.text();
+  let data: any = null;
+  try { data = JSON.parse(text); } catch { /* not JSON */ }
+  if (res.status === 404) throw new Error('This invite is invalid or has expired.');
+  if (!res.ok || !data?.ok) {
+    if (data?.error) throw new Error(data.error);
+    throw new Error(cleanErrorMessage(res.status, text, 'Could not load invite'));
+  }
+  return data;
+}
+
+/**
+ * Exchange an invite + Google id_token for a tenant-scoped consumer JWT.
+ * NOTE: no `tenant` field — the invite carries the tenant. Sending `tenant`
+ * instead would be the open-signup path (403 on invite-only tenants).
+ */
+export async function joinWithGoogle(invite: string, idToken: string): Promise<ConsumerSignInResult> {
+  return postJson<ConsumerSignInResult>('/platform/consumer/oauth/google', { invite, id_token: idToken });
+}
+
+/** Exchange an invite + Apple id_token for a tenant-scoped consumer JWT. */
+export async function joinWithApple(invite: string, idToken: string): Promise<ConsumerSignInResult> {
+  return postJson<ConsumerSignInResult>('/platform/consumer/oauth/apple', { invite, id_token: idToken });
+}
+
+// ─── Open self-signup (no invite) ──────────────────────────────────────
+// For tenants the admin marked FREE-TO-JOIN. The user names the team (slug),
+// we send { tenant, id_token } with no invite. The server accepts only if that
+// tenant allows open signup, else 403 — the client just surfaces the message.
+
+export async function openJoinWithGoogle(tenant: string, idToken: string): Promise<ConsumerSignInResult> {
+  return postJson<ConsumerSignInResult>('/platform/consumer/oauth/google', { tenant, id_token: idToken });
+}
+
+export async function openJoinWithApple(tenant: string, idToken: string): Promise<ConsumerSignInResult> {
+  return postJson<ConsumerSignInResult>('/platform/consumer/oauth/apple', { tenant, id_token: idToken });
+}
+
+/**
+ * Start a channel-link OTP challenge. The consumer must be authenticated
+ * (their JWT is passed via the Authorization header).
+ */
+export async function linkChannelStart(
+  jwt: string,
+  channel: string,
+  handle: string,
+): Promise<OtpStartResult> {
+  return postJson<OtpStartResult>('/platform/consumer/link-channel/start', { channel, handle }, jwt);
+}
+
+/** Verify the OTP and complete the channel link. */
+export async function linkChannelVerify(
+  jwt: string,
+  challengeId: string,
+  code: string,
+): Promise<{ ok: boolean; channel: string; handle: string; actorId: string; transferred: boolean }> {
+  return postJson('/platform/consumer/link-channel/verify', { challenge_id: challengeId, code }, jwt);
+}

package/src/deepLinks.ts

@@ -0,0 +1,38 @@
+/**
+ * Deep-link parsing (R9) — the generic navigation-orchestration half of the
+ * host's invite/handoff capture. Extracting a code from a link's query string
+ * is the same for any host; only the URL SCHEME (adas://, universal-link
+ * domains) is host-specific and stays in the host's Expo Router config.
+ */
+
+/**
+ * Pull a query param's value out of a deep link, URL-decoded. Returns null when
+ * the link is empty, the param is absent, or the value is empty. Tolerant of a
+ * malformed encoding (falls back to the raw match) so a valid code is never
+ * dropped on a stray `%`.
+ */
+export function parseDeepLinkParam(url: string | null | undefined, param: string): string | null {
+  if (!url) return null;
+  const re = new RegExp(`[?&]${param}=([^&#\\s]+)`, 'i');
+  const m = url.match(re);
+  if (!m) return null;
+  try {
+    const v = decodeURIComponent(m[1]);
+    return v.length > 0 ? v : null;
+  } catch {
+    return m[1].length > 0 ? m[1] : null;
+  }
+}
+
+/** A tenant-invite code from `?invite=<code>`. */
+export function parseInviteCode(url: string | null | undefined): string | null {
+  return parseDeepLinkParam(url, 'invite');
+}
+
+/**
+ * A web→app handoff code from `?handoff=<code>`. Deliberately keyed on `handoff=`
+ * and NOT `code=`, so it never collides with an OAuth `?code=` redirect.
+ */
+export function parseHandoffCode(url: string | null | undefined): string | null {
+  return parseDeepLinkParam(url, 'handoff');
+}