@darkauth/client 1.17.0 → 1.18.0

package/README.md

@@ -13,6 +13,7 @@ The client supports both:
 - **Token Management**: First-party cookie refresh by default, with optional legacy token storage
 - **Data Encryption Keys (DEK)**: Support for deriving and managing data encryption keys
 - **DRK Custody**: Memory-only DRK handling by default for hosted web zero-knowledge apps
+- **Organization Switching**: App-owned and hosted organization selection flows for tenant-scoped apps
 - **TypeScript Support**: Full TypeScript definitions included
 
 ## Installation
@@ -82,10 +83,12 @@ The client also supports environment variables for configuration:
 
 ### Authentication Functions
 
-#### `initiateLogin(): Promise<void>`
+#### `initiateLogin(options?: InitiateLoginOptions): Promise<void>`
 
 Starts the OAuth2/OIDC login flow with PKCE. Redirects the user to the DarkAuth authorization server.
 
+Pass `organizationId` when the app already knows which organization the user wants to enter. The SDK sends it as `organization_id` on `/authorize`, and DarkAuth validates active membership before issuing a code. Omit it when the app wants DarkAuth to select the only active organization or show the hosted organization selector for multi-organization users.
+
 #### `handleCallback(): Promise<AuthSession | null>`
 
 Processes the OAuth callback after successful authentication. Returns an `AuthSession` object containing:
@@ -111,10 +114,84 @@ Retrieves the current in-memory session if valid. For non-ZK sessions, returns `
 
 If `tokenStorage: 'localStorage'` or `drkStorage: 'localStorage'` is configured for a legacy app, this function can also restore those explicitly persisted values.
 
-#### `refreshSession(): Promise<AuthSession | null>`
+#### `refreshSession(options?: { force?: boolean }): Promise<AuthSession | null>`
 
 Refreshes the current session. In default first-party mode, the browser sends the DarkAuth refresh cookie and no JavaScript-readable refresh token is required. For non-ZK sessions, returns `drk` as an empty `Uint8Array`.
 
+Use `{ force: true }` after a hosted organization switch so the app receives tokens for the newly selected DarkAuth session organization even if the current in-memory ID token has not expired.
+
+### Organization Switching
+
+DarkAuth treats organization switching as choosing a new authorization context. Tokens are scoped to one selected organization at a time. Apps must not merge roles or permissions across organizations.
+
+#### `listOrganizations(): Promise<DarkAuthOrganization[]>`
+
+Returns the current user's organizations for app-owned switcher UI. Use `status` to decide which memberships are selectable.
+
+#### `getSessionInfo(): Promise<{ authenticated: boolean; sub?: string; email?: string | null; name?: string | null; organizationId?: string; organizationSlug?: string | null }>`
+
+Returns current first-party session and organization context for app chrome before a fresh OAuth callback is needed.
+
+#### `switchOrganization(organizationId: string, options?: SwitchOrganizationOptions): Promise<void>`
+
+Switches the selected organization. The default `authorize` mode starts a new authorization-code flow. `hosted` mode redirects to DarkAuth's `/switch-org` page.
+
+#### App-owned switcher
+
+Use this pattern when the app owns the workspace rail, menu, or account switcher UI.
+
+```typescript
+import {
+  getCurrentUser,
+  handleCallback,
+  listOrganizations,
+  switchOrganization,
+} from '@DarkAuth/client';
+
+const organizations = await listOrganizations();
+const activeOrganizationId = getCurrentUser()?.org_id;
+
+async function selectOrganization(organizationId: string) {
+  await switchOrganization(organizationId, {
+    mode: 'authorize',
+    returnTo: window.location.href,
+  });
+}
+
+const session = await handleCallback();
+const selectedOrganizationId = getCurrentUser()?.org_id;
+```
+
+After the callback, verify that `selectedOrganizationId` matches the workspace being loaded. Treat the switch as a tenant or workspace state reset: clear tenant-local caches, selected resources, open realtime subscriptions, in-flight requests, and authorization decisions before loading data for the new `org_id`.
+
+#### Hosted switcher
+
+Use this pattern when DarkAuth should own the organization picker UI.
+
+```typescript
+import { refreshSession, switchOrganization } from '@DarkAuth/client';
+
+await switchOrganization('org_123', {
+  mode: 'hosted',
+  returnTo: window.location.href,
+});
+
+const session = await refreshSession({ force: true });
+```
+
+Hosted mode redirects to DarkAuth's `/switch-org` page. DarkAuth updates the first-party session organization and returns to the app. The app then forces a refresh so the ID and access tokens reflect the selected organization.
+
+#### Token claims
+
+When organization context is resolved, ID and access tokens can include:
+
+- `org_id`: selected organization ID.
+- `org_slug`: selected organization slug.
+- `roles`: roles for the selected organization only.
+- `permissions`: permissions for the selected organization only.
+
+Use `sub` for the user identity and `org_id` for the active tenant or workspace. A user can have different roles in different organizations, so apps must authorize each request against the token's selected `org_id` and must reject resource access for a different organization.
+
 ### User Information
 
 #### `getCurrentUser(): JwtClaims | null`
@@ -208,6 +285,10 @@ interface JwtClaims {
   exp?: number;
   iat?: number;
   iss?: string;
+  org_id?: string;
+  org_slug?: string;
+  roles?: string[];
+  permissions?: string[];
 }
 ```
 
@@ -226,6 +307,33 @@ type Config = {
 }
 ```
 
+### `DarkAuthOrganization`
+```typescript
+type DarkAuthOrganization = {
+  organizationId: string;
+  slug: string;
+  name: string;
+  status: string;
+  roles?: Array<{ id: string; key: string; name: string }>;
+}
+```
+
+### `InitiateLoginOptions`
+```typescript
+type InitiateLoginOptions = {
+  organizationId?: string;
+  returnTo?: string;
+}
+```
+
+### `SwitchOrganizationOptions`
+```typescript
+type SwitchOrganizationOptions = {
+  mode?: 'authorize' | 'hosted';
+  returnTo?: string;
+}
+```
+
 ### `ClientHooks`
 ```typescript
 type ClientHooks = {

package/dist/index.d.ts

@@ -33,13 +33,65 @@ export interface JwtClaims {
     exp?: number;
     iat?: number;
     iss?: string;
+    org_id?: string;
+    org_slug?: string;
+    roles?: string[];
+    permissions?: string[];
+}
+export type DarkAuthOrganization = {
+    organizationId: string;
+    slug: string;
+    name: string;
+    status: string;
+    roles?: Array<{
+        id: string;
+        key: string;
+        name: string;
+    }>;
+};
+export type InitiateLoginOptions = {
+    organizationId?: string;
+    returnTo?: string;
+};
+export type SwitchOrganizationOptions = {
+    mode?: "authorize" | "hosted";
+    returnTo?: string;
+};
+export type RefreshSessionOptions = {
+    force?: boolean;
+};
+export type DarkAuthSessionInfo = {
+    authenticated: boolean;
+    sub?: string;
+    email?: string | null;
+    name?: string | null;
+    organizationId?: string;
+    organizationSlug?: string | null;
+};
+export type DarkAuthErrorCode = "unauthenticated_session" | "invalid_organization" | "org_context_required" | "request_failed";
+export declare class DarkAuthError extends Error {
+    code: DarkAuthErrorCode;
+    status?: number;
+    constructor(message: string, code: DarkAuthErrorCode, status?: number);
+}
+export declare class UnauthenticatedSessionError extends DarkAuthError {
+    constructor(message?: string, status?: number);
+}
+export declare class InvalidOrganizationError extends DarkAuthError {
+    constructor(message?: string, status?: number);
+}
+export declare class OrgContextRequiredError extends DarkAuthError {
+    constructor(message?: string, status?: number);
 }
 export declare function setConfig(next: Partial<Config>): void;
 export declare function parseJwt(token: string): JwtClaims | null;
 export declare function isTokenValid(token: string): boolean;
-export declare function initiateLogin(): Promise<void>;
+export declare function initiateLogin(options?: InitiateLoginOptions): Promise<void>;
 export declare function handleCallback(): Promise<AuthSession | null>;
 export declare function getStoredSession(): AuthSession | null;
-export declare function refreshSession(): Promise<AuthSession | null>;
+export declare function refreshSession(options?: RefreshSessionOptions): Promise<AuthSession | null>;
+export declare function listOrganizations(): Promise<DarkAuthOrganization[]>;
+export declare function getSessionInfo(): Promise<DarkAuthSessionInfo>;
+export declare function switchOrganization(organizationId: string, options?: SwitchOrganizationOptions): Promise<void>;
 export declare function logout(): void;
 export declare function getCurrentUser(): JwtClaims | null;

package/dist/index.js

@@ -2,6 +2,34 @@ import { compactDecrypt } from "jose";
 export * from "./crypto.js";
 export * from "./dek.js";
 export { setHooks } from "./hooks.js";
+export class DarkAuthError extends Error {
+    code;
+    status;
+    constructor(message, code, status) {
+        super(message);
+        this.name = "DarkAuthError";
+        this.code = code;
+        this.status = status;
+    }
+}
+export class UnauthenticatedSessionError extends DarkAuthError {
+    constructor(message = "User session required", status = 401) {
+        super(message, "unauthenticated_session", status);
+        this.name = "UnauthenticatedSessionError";
+    }
+}
+export class InvalidOrganizationError extends DarkAuthError {
+    constructor(message = "Invalid organization", status = 403) {
+        super(message, "invalid_organization", status);
+        this.name = "InvalidOrganizationError";
+    }
+}
+export class OrgContextRequiredError extends DarkAuthError {
+    constructor(message = "Organization context required", status = 400) {
+        super(message, "org_context_required", status);
+        this.name = "OrgContextRequiredError";
+    }
+}
 function viteEnvGet(key) {
     try {
         const im = import.meta || undefined;
@@ -75,6 +103,52 @@ function fetchCredentials() {
 function rootEndpoint(path) {
     return new URL(path, cfg.issuer).toString();
 }
+function isSafeReturnTo(returnTo) {
+    if (returnTo.startsWith("/")) {
+        return !returnTo.startsWith("//") && !returnTo.includes("\\");
+    }
+    try {
+        const url = new URL(returnTo);
+        return url.protocol === "http:" || url.protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}
+function requestFailed(status, message = "DarkAuth request failed") {
+    return new DarkAuthError(message, "request_failed", status);
+}
+async function readErrorPayload(response) {
+    try {
+        const data = (await response.json());
+        if (data && typeof data === "object" && !Array.isArray(data)) {
+            return data;
+        }
+    }
+    catch { }
+    return null;
+}
+async function errorForResponse(response) {
+    const payload = await readErrorPayload(response);
+    const code = typeof payload?.code === "string"
+        ? payload.code
+        : typeof payload?.error === "string"
+            ? payload.error
+            : undefined;
+    const message = typeof payload?.message === "string"
+        ? payload.message
+        : typeof payload?.error_description === "string"
+            ? payload.error_description
+            : undefined;
+    if (response.status === 401)
+        return new UnauthenticatedSessionError(message, response.status);
+    if (code === "ORG_CONTEXT_REQUIRED" || code === "org_context_required") {
+        return new OrgContextRequiredError(message, response.status);
+    }
+    if (response.status === 403)
+        return new InvalidOrganizationError(message, response.status);
+    return requestFailed(response.status, message);
+}
 async function resolveEndpoints() {
     const cacheKey = [
         cfg.issuer,
@@ -265,7 +339,7 @@ export function isTokenValid(token) {
         return false;
     return claims.exp * 1000 > Date.now() + 5000;
 }
-export async function initiateLogin() {
+export async function initiateLogin(options = {}) {
     const zkEnabled = cfg.zk !== false;
     let zkPubParam;
     if (zkEnabled) {
@@ -294,6 +368,8 @@ export async function initiateLogin() {
     authUrl.searchParams.set("code_challenge_method", "S256");
     if (zkEnabled && zkPubParam)
         authUrl.searchParams.set("zk_pub", zkPubParam);
+    if (options.organizationId)
+        authUrl.searchParams.set("organization_id", options.organizationId);
     location.assign(authUrl.toString());
 }
 export async function handleCallback() {
@@ -503,7 +579,12 @@ export function getStoredSession() {
         refreshToken: refreshMode() === "token" ? localStorage.getItem(REFRESH_TOKEN_KEY) || undefined : undefined,
     };
 }
-export async function refreshSession() {
+export async function refreshSession(options = {}) {
+    if (!options.force) {
+        const current = getStoredSession();
+        if (current)
+            return current;
+    }
     const currentRefreshMode = refreshMode();
     const refreshToken = currentRefreshMode === "token"
         ? memoryRefreshToken || localStorage.getItem(REFRESH_TOKEN_KEY)
@@ -526,6 +607,9 @@ export async function refreshSession() {
         credentials: fetchCredentials(),
     });
     if (!response.ok) {
+        const error = await errorForResponse(response);
+        if (error instanceof OrgContextRequiredError)
+            throw error;
         if (response.status === 401) {
             if (currentRefreshMode === "token") {
                 const latestRefreshToken = localStorage.getItem(REFRESH_TOKEN_KEY);
@@ -562,6 +646,58 @@ export async function refreshSession() {
         refreshToken: currentRefreshMode === "token" ? newRefreshToken || refreshToken || undefined : undefined,
     });
 }
+export async function listOrganizations() {
+    const response = await fetch(rootEndpoint("/api/user/organizations"), {
+        credentials: fetchCredentials(),
+    });
+    if (!response.ok)
+        throw await errorForResponse(response);
+    const data = (await response.json());
+    if (!Array.isArray(data.organizations))
+        return [];
+    return data.organizations.filter((org) => {
+        if (!org || typeof org !== "object")
+            return false;
+        const candidate = org;
+        return (typeof candidate.organizationId === "string" &&
+            typeof candidate.slug === "string" &&
+            typeof candidate.name === "string" &&
+            typeof candidate.status === "string");
+    });
+}
+export async function getSessionInfo() {
+    const response = await fetch(rootEndpoint("/api/user/session"), {
+        credentials: fetchCredentials(),
+    });
+    if (response.status === 401)
+        return { authenticated: false };
+    if (!response.ok)
+        throw await errorForResponse(response);
+    const data = (await response.json());
+    return {
+        authenticated: data.authenticated === true,
+        sub: typeof data.sub === "string" ? data.sub : undefined,
+        email: typeof data.email === "string" || data.email === null ? data.email : undefined,
+        name: typeof data.name === "string" || data.name === null ? data.name : undefined,
+        organizationId: typeof data.organizationId === "string" ? data.organizationId : undefined,
+        organizationSlug: typeof data.organizationSlug === "string" || data.organizationSlug === null
+            ? data.organizationSlug
+            : undefined,
+    };
+}
+export async function switchOrganization(organizationId, options = {}) {
+    if ((options.mode || "authorize") === "authorize") {
+        await initiateLogin({ organizationId, returnTo: options.returnTo });
+        return;
+    }
+    const switchUrl = new URL(rootEndpoint("/switch-org"));
+    switchUrl.searchParams.set("organization_id", organizationId);
+    switchUrl.searchParams.set("client_id", cfg.clientId);
+    if (options.returnTo && isSafeReturnTo(options.returnTo)) {
+        switchUrl.searchParams.set("return_to", options.returnTo);
+    }
+    location.assign(switchUrl.toString());
+}
 export function logout() {
     memorySession = null;
     memoryRefreshToken = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@darkauth/client",
-  "version": "1.17.0",
+  "version": "1.18.0",
   "license": "MIT",
   "repository": {
     "directory": "packages/darkauth-client",