@bunbase-ae/js 2.4.0 → 2.4.1-next.162.9c38140

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bunbase-ae/js",
-  "version": "2.4.0",
+  "version": "2.4.1-next.162.9c38140",
   "type": "module",
   "description": "TypeScript/JavaScript SDK for BunBase",
   "license": "UNLICENSED",

package/src/auth.ts

@@ -10,6 +10,8 @@ import type {
   AuthUser,
   LoginResult,
   PersistSessionOptions,
+  SwitchTenantResult,
+  TenantMembership,
   TotpChallenge,
   TotpSetup,
 } from "./types";
@@ -17,10 +19,39 @@ import type {
 // Reactive snapshot of auth state. Consumed by useAuth() via useSyncExternalStore.
 export interface AuthSnapshot {
   user: AuthUser | null;
+  /**
+   * Tenant the current session is scoped to. Derived from the access token's
+   * `tenant_id` claim. Null for unscoped sessions (login without tenantId,
+   * API-key auth, logged-out state).
+   */
+  tenantId: string | null;
   loading: boolean;
   error: Error | null;
 }
 
+// Decode the base64url payload of a JWT to read claims client-side. Returns
+// null for malformed tokens — callers treat that as "no tenant claim".
+function decodeJwtPayload(jwt: string): Record<string, unknown> | null {
+  const parts = jwt.split(".");
+  const raw = parts[1];
+  if (parts.length !== 3 || !raw) return null;
+  try {
+    const b64 = raw.replace(/-/g, "+").replace(/_/g, "/");
+    const pad = b64.length % 4 === 0 ? "" : "=".repeat(4 - (b64.length % 4));
+    const decoded = atob(b64 + pad);
+    return JSON.parse(decoded) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
+function tenantIdFromAccessToken(accessToken: string | null | undefined): string | null {
+  if (!accessToken) return null;
+  const payload = decodeJwtPayload(accessToken);
+  const claim = payload?.tenant_id;
+  return typeof claim === "string" && claim.length > 0 ? claim : null;
+}
+
 // Represents the active session passed to onAuthChange listeners.
 // Token-based sessions carry access/refresh tokens; API-key sessions carry the key.
 export type AuthSession = { accessToken: string; refreshToken: string } | { apiKey: string };
@@ -30,18 +61,24 @@ export class AuthClient {
   // Cleared on logout. Lets useAuth() initialize synchronously without a network round-trip.
   private cachedUser: AuthUser | null = null;
 
-  // External store for useSyncExternalStore — holds user/loading/error as a snapshot.
-  private _snap: AuthSnapshot = { user: null, loading: false, error: null };
+  // External store for useSyncExternalStore — holds user/tenantId/loading/error.
+  private _snap: AuthSnapshot = { user: null, tenantId: null, loading: false, error: null };
   private _snapSubs = new Set<() => void>();
 
   constructor(private readonly http: HttpClient) {
-    // When tokens are cleared from ANY path (logout, logoutAll, deleteAccount,
-    // or server-pushed revocation via RealtimeClient), keep cachedUser and the
-    // reactive snapshot in sync automatically.
+    // When tokens change (login, refresh, switch-tenant, logout, logoutAll,
+    // deleteAccount, or server-pushed revocation via RealtimeClient), keep
+    // cachedUser and the reactive snapshot in sync automatically.
+    //
+    // tenantId is derived from the access token's `tenant_id` claim on every
+    // transition, so callers never have to plumb it manually.
     this.http.onTokenChange(({ accessToken }) => {
+      const tenantId = tenantIdFromAccessToken(accessToken);
       if (!accessToken && this.cachedUser !== null) {
         this.cachedUser = null;
-        this.patchSnapshot({ user: null });
+        this.patchSnapshot({ user: null, tenantId });
+      } else {
+        this.patchSnapshot({ tenantId });
       }
     });
   }
@@ -91,7 +128,15 @@ export class AuthClient {
 
   // Returns AuthResult on success, or TotpChallenge when 2FA is enabled.
   // On TotpChallenge, call verifyTotp(result.totp_token, code) to complete sign-in.
-  async login(credentials: { email: string; password: string }): Promise<LoginResult> {
+  //
+  // Pass `tenantId` to scope the issued session to a specific tenant — the
+  // access token then carries a `tenant_id` claim and all subsequent requests
+  // are restricted to that tenant. Omit it for unscoped sessions.
+  async login(credentials: {
+    email: string;
+    password: string;
+    tenantId?: string;
+  }): Promise<LoginResult> {
     const result = await this.http.request<LoginResult>("POST", "/api/v1/auth/login", {
       body: credentials,
       skipAuth: true,
@@ -136,6 +181,41 @@ export class AuthClient {
     return result;
   }
 
+  // Redeem an OAuth handoff code for the token pair.
+  //
+  // The OAuth callback redirects to `{APP_URL}/auth/callback?handoff=<code>`.
+  // Tokens no longer travel through the URL query string (which would leak
+  // them into browser history, proxy logs, and third-party Referer headers);
+  // instead, the frontend reads the `handoff` param and posts it here.
+  //
+  // Single-use — a second call with the same code returns 404.
+  async exchangeHandoff(code: string): Promise<{
+    access_token: string;
+    refresh_token: string;
+    expires_in: number;
+  }> {
+    const result = await this.http.request<{
+      access_token: string;
+      refresh_token: string;
+      expires_in: number;
+    }>("POST", "/api/v1/auth/oauth/handoff", {
+      body: { handoff: code },
+      skipAuth: true,
+    });
+    this.http.setTokens(result.access_token, result.refresh_token);
+    // Populate the reactive snapshot so useAuth() lights up without the caller
+    // having to issue a separate me() round-trip. Swallow errors here — the
+    // token store is already primed; any auth-dependent view can retry.
+    try {
+      const user = await this.me();
+      this.cachedUser = user;
+      this.patchSnapshot({ user });
+    } catch {
+      // Caller can retry via auth.me() — tokens are already stored.
+    }
+    return result;
+  }
+
   async refresh(): Promise<AuthResult> {
     const refreshToken = this.http.getRefreshToken();
     if (!refreshToken) throw new Error("No refresh token stored. Call login() first.");
@@ -325,6 +405,35 @@ export class AuthClient {
     await this.http.request<{ ok: boolean }>("DELETE", `/api/v1/auth/api-keys/${id}`);
   }
 
+  // ─── Multi-tenancy ───────────────────────────────────────────────────────────
+
+  // List the tenants the authenticated user is a member of.
+  // Use the returned `tenant_id` values with switchTenant() to re-scope the session.
+  async listTenants(): Promise<TenantMembership[]> {
+    const result = await this.http.request<{ items: TenantMembership[]; total: number }>(
+      "GET",
+      "/api/v1/auth/tenants",
+    );
+    return result.items;
+  }
+
+  // Re-issue the session token pair scoped to a different tenant.
+  //
+  // The caller's current session is revoked server-side before the new pair is
+  // issued, so the pre-switch refresh/access tokens can no longer be used. The
+  // returned token pair is written into the HTTP layer automatically — the
+  // reactive AuthSnapshot picks up the new `tenant_id` claim on the next tick,
+  // so useAuth() callers see the updated `tenantId` without any extra wiring.
+  async switchTenant(tenantId: string): Promise<SwitchTenantResult> {
+    const result = await this.http.request<SwitchTenantResult>(
+      "POST",
+      "/api/v1/auth/switch-tenant",
+      { body: { tenant_id: tenantId } },
+    );
+    this.http.setTokens(result.access_token, result.refresh_token);
+    return result;
+  }
+
   // ─── Auth change listeners ────────────────────────────────────────────────
 
   // Register a listener for token-based auth transitions: fires with

package/src/index.ts

@@ -82,6 +82,8 @@ export {
   type RealtimeEvent,
   type RealtimeEventType,
   type StorageAdapter,
+  type SwitchTenantResult,
+  type TenantMembership,
   type TotpChallenge,
   type TotpSetup,
   type TransactionCreate,

package/src/types.ts

@@ -6,6 +6,11 @@ export interface BunBaseRecord {
   _created_at: number;
   _updated_at: number;
   _owner_id: string | null;
+  /**
+   * Tenant this record belongs to. Null for records created outside a tenant-scoped session.
+   * Always present on the wire — the server stamps it on every record.
+   */
+  _tenant_id: string | null;
   _deleted_at?: number | null;
 }
 
@@ -170,6 +175,7 @@ export type Filter<T = Record<string, unknown>> = {
   _created_at?: FilterFieldValue<number>;
   _updated_at?: FilterFieldValue<number>;
   _owner_id?: FilterFieldValue<string | null>;
+  _tenant_id?: FilterFieldValue<string | null>;
   _deleted_at?: FilterFieldValue<number | null | undefined>;
 };
 
@@ -361,6 +367,27 @@ export interface ApiKey {
   created_at: number;
 }
 
+// ─── Multi-tenancy ────────────────────────────────────────────────────────────
+
+/** A single tenant membership for the authenticated user. Returned by `AuthClient.listTenants()`. */
+export interface TenantMembership {
+  tenant_id: string;
+  role: string;
+  created_at: number;
+}
+
+/**
+ * Returned by `AuthClient.switchTenant()`. Carries a re-issued token pair scoped
+ * to the target tenant. The caller's prior session is revoked server-side before
+ * the new pair is minted, so stale tokens cannot be replayed.
+ */
+export interface SwitchTenantResult {
+  access_token: string;
+  refresh_token: string;
+  expires_in: number;
+  tenant: { tenant_id: string; role: string };
+}
+
 // Minimal storage interface — deliberately async-compatible so the same API
 // works with synchronous Web Storage (localStorage, sessionStorage) and
 // Promise-based stores such as React Native's AsyncStorage or any custom