@tidecloak/js 0.13.11 → 0.13.14

package/dist/types/src/IAMService.d.ts

@@ -4,9 +4,10 @@ declare const IAMServiceInstance: IAMService;
 /**
  * Singleton IAMService wrapping the TideCloak client.
  *
- * Supports two modes:
+ * Supports three modes:
  * - **Front-channel mode**: Browser handles all token operations (standard OIDC)
  * - **Hybrid/BFF mode**: Browser handles PKCE, backend exchanges code for tokens (more secure)
+ * - **Native mode**: External browser for login, app handles tokens via adapter (Electron, Tauri, React Native)
  *
  * ---
  * ## Front-channel Mode
@@ -122,6 +123,19 @@ declare class IAMService {
         error: null;
         errorDescription: null;
     } | null;
+    _nativeAdapter: any;
+    _nativeAuthenticated: boolean;
+    _nativeTokens: any;
+    _nativeCallbackUnsubscribe: any;
+    _nativeCallbackHandled: boolean;
+    _nativeCallbackPromise: any;
+    _nativeCallbackProcessing: boolean;
+    _nativeDoken: any;
+    _nativeDokenParsed: Object | null;
+    _nativeVoucher: any;
+    _nativeRequestEnclave: RequestEnclave | null;
+    _nativeEncryptionCallbackUnsubscribe: any;
+    _pendingEncryptionRequests: Map<any, any>;
     /**
      * Register an event listener.
      * @param {'ready'|'initError'|'authSuccess'|'authError'|'authRefreshSuccess'|'authRefreshError'|'logout'|'tokenExpired'} event
@@ -143,6 +157,11 @@ declare class IAMService {
      * @returns {boolean}
      */
     isHybridMode(): boolean;
+    /**
+     * Check if running in native mode.
+     * @returns {boolean}
+     */
+    isNativeMode(): boolean;
     /**
      * Load TideCloak configuration and instantiate the client once.
      * @param {Object} config - TideCloak configuration object.
@@ -161,7 +180,7 @@ declare class IAMService {
     private getTideCloakClient;
     /** @returns {Object} Loaded config */
     getConfig(): Object;
-    /** @returns {boolean} Whether there's a valid token (or session in hybrid mode) */
+    /** @returns {boolean} Whether there's a valid token (or session in hybrid/native mode) */
     isLoggedIn(): boolean;
     /**
      * Get valid token (refreshing if needed).
@@ -237,24 +256,36 @@ declare class IAMService {
     /**
      * Start login redirect.
      * In hybrid mode, initiates PKCE flow and redirects to IdP.
-     * @param {string} [returnUrl] - URL to redirect to after successful auth (hybrid mode only)
+     * In native mode, opens external browser with auth URL.
+     * @param {string} [returnUrl] - URL to redirect to after successful auth (hybrid/native mode)
      */
     doLogin(returnUrl?: string): Promise<void> | undefined;
     /**
      * Encrypt data via adapter.
      * Not available in hybrid mode (encryption requires client-side doken).
+     * @param {{ data: string | Uint8Array, tags: string[] }[]} data - Array of objects to encrypt
+     * @returns {Promise<(string | Uint8Array)[]>} Array of encrypted values
      */
-    doEncrypt(data: any): Promise<(string | Uint8Array<ArrayBufferLike>)[]>;
+    doEncrypt(data: {
+        data: string | Uint8Array;
+        tags: string[];
+    }[]): Promise<(string | Uint8Array)[]>;
     /**
      * Decrypt data via adapter.
      * Not available in hybrid mode (decryption requires client-side doken).
+     * @param {{ encrypted: string | Uint8Array, tags: string[] }[]} data - Array of objects to decrypt
+     * @returns {Promise<(string | Uint8Array)[]>} Array of decrypted values
      */
-    doDecrypt(data: any): Promise<(string | Uint8Array<ArrayBufferLike>)[]>;
+    doDecrypt(data: {
+        encrypted: string | Uint8Array;
+        tags: string[];
+    }[]): Promise<(string | Uint8Array)[]>;
     /**
      * Logout, clear cookie/session, then redirect.
      * In hybrid mode, clears local state and emits logout event.
+     * In native mode, deletes tokens via adapter and emits logout event.
      */
-    doLogout(): void;
+    doLogout(): Promise<void>;
     /**
      * Base URL for Tidecloak realm (no trailing slash).
      * In hybrid mode returns empty string.
@@ -324,5 +355,128 @@ declare class IAMService {
      * @returns {Promise<{handled: boolean, authenticated: boolean, returnUrl: string}>}
      */
     private _handleHybridRedirectCallback;
+    /**
+     * Get OIDC configuration from the native config.
+     * @private
+     * @returns {{ authServerUrl: string, realm: string, clientId: string, scope: string }}
+     */
+    private _getNativeOIDCConfig;
+    /**
+     * Get encryption configuration from the native config.
+     * Automatically selects clientOriginAuth based on window.location.origin.
+     * @private
+     * @returns {{ vendorId: string, homeOrkUrl: string, clientOriginAuth: string } | null}
+     */
+    private _getNativeEncryptionConfig;
+    /**
+     * Start native login flow: generate PKCE, open external browser with auth URL.
+     * @private
+     * @param {string} returnUrl - URL to redirect to after successful auth
+     */
+    private _startNativeLogin;
+    /**
+     * Handle native auth callback: exchange code for tokens.
+     * @private
+     * @param {string} code - Authorization code from IdP
+     * @param {string} [voucher] - Optional voucher fetched during login (for encryption)
+     */
+    private _handleNativeCallback;
+    /**
+     * Refresh native token using refresh token.
+     * @private
+     * @param {string} refreshToken - The refresh token
+     * @returns {Promise<Object>} New token data
+     */
+    private _refreshNativeToken;
+    /**
+     * Initialize the native RequestEnclave for encryption/decryption.
+     * @private
+     * @param {string} voucherDataUrl - Pre-fetched voucher as data URL
+     */
+    private _initNativeRequestEnclave;
+    /**
+     * Build the encryption page URL for external browser.
+     * This page is hosted on the TideCloak server and has session cookies.
+     * @private
+     * @param {string} operation - 'encrypt' or 'decrypt'
+     * @param {string} requestId - Unique request ID
+     * @param {string} dataBase64 - Base64-encoded data to process
+     * @param {string} tagsJson - JSON-encoded tags array
+     * @param {string} callbackUrl - URL to redirect with result
+     * @returns {string} URL to open in external browser
+     */
+    private _buildEncryptionPageUrl;
+    /**
+     * Perform an encryption operation via external browser.
+     * @private
+     * @param {'encrypt' | 'decrypt'} operation - The operation to perform
+     * @param {string} dataBase64 - Base64-encoded data to process
+     * @param {string[]} tags - Tags for the operation
+     * @returns {Promise<string>} Base64-encoded result
+     */
+    private _doExternalBrowserOperation;
+    /**
+     * Get the voucher URL for native mode.
+     * @private
+     * @returns {string} Voucher URL
+     */
+    private _getNativeVoucherUrl;
+    /**
+     * Check if user has a realm role (native mode helper).
+     * @private
+     * @param {string} role - Role to check
+     * @returns {boolean}
+     */
+    private _nativeHasRealmRole;
+    /**
+     * Native mode encryption using RequestEnclave.
+     * Uses either a pre-fetched voucher (as data URL) or the live voucherURL
+     * that the ORK iframe will fetch with session cookies.
+     * @private
+     * @param {{ data: string | Uint8Array, tags: string[] }[]} toEncrypt
+     * @returns {Promise<(string | Uint8Array)[]>}
+     */
+    private _nativeEncrypt;
+    /**
+     * Native mode decryption using RequestEnclave.
+     * Uses either a pre-fetched voucher (as data URL) or the live voucherURL
+     * that the ORK iframe will fetch with session cookies.
+     * @private
+     * @param {{ encrypted: string | Uint8Array, tags: string[] }[]} toDecrypt
+     * @returns {Promise<(string | Uint8Array)[]>}
+     */
+    private _nativeDecrypt;
+    /**
+     * Convert string to Uint8Array.
+     * @private
+     */
+    private _stringToUint8Array;
+    /**
+     * Convert Uint8Array to string.
+     * @private
+     */
+    private _stringFromUint8Array;
+    /**
+     * Convert bytes to base64.
+     * @private
+     */
+    private _bytesToBase64;
+    /**
+     * Convert base64 to bytes.
+     * @private
+     */
+    private _base64ToBytes;
+    /**
+     * Parse a JWT token and return its payload.
+     * @private
+     * @param {string} token - JWT token string
+     * @returns {Object|null} Parsed token payload or null on error
+     */
+    private _parseToken;
+    /**
+     * Cleanup native mode resources.
+     */
+    destroy(): void;
 }
 import TideCloak from "../lib/tidecloak.js";
+import { RequestEnclave } from "../lib/tidecloak.js";

package/dist/types/src/index.d.ts

@@ -1,3 +1,9 @@
 export { default as IAMService } from "./IAMService.js";
+export type NativeAdapter = import("./types.js").NativeAdapter;
+export type NativeTokenData = import("./types.js").NativeTokenData;
+export type NativeAuthCallbackResult = import("./types.js").NativeAuthCallbackResult;
+export type NativeEncryptionCallbackResult = import("./types.js").NativeEncryptionCallbackResult;
+export type NativeConfig = import("./types.js").NativeConfig;
 export { default as TideCloak, RequestEnclave, ApprovalEnclaveNew } from "../lib/tidecloak.js";
 export { TideMemory, BaseTideRequest } from "heimdall-tide";
+export { default as AdminAPI, AdminAPI as AdminAPIClass } from "./AdminAPI.js";

package/dist/types/src/types.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Type definitions for @tidecloak/js native mode
+ */
+/**
+ * Token data for native mode storage.
+ */
+export interface NativeTokenData {
+    accessToken: string;
+    refreshToken: string;
+    idToken?: string;
+    /** Tide doken (delegated token) for encryption/decryption operations */
+    doken?: string;
+    expiresAt: number;
+}
+/**
+ * Auth callback result from native app.
+ */
+export interface NativeAuthCallbackResult {
+    code?: string;
+    error?: string;
+    errorDescription?: string;
+}
+/**
+ * Native adapter interface for platform-specific operations.
+ *
+ * This is the MINIMAL interface developers must implement for their platform.
+ * The SDK handles everything else (encryption, token management, etc.).
+ *
+ * @example
+ * ```typescript
+ * // Electron example - minimal implementation
+ * const adapter: NativeAdapter = {
+ *   getRedirectUri: () => 'myapp://auth/callback',
+ *   openExternalUrl: (url) => shell.openExternal(url),
+ *   onAuthCallback: (callback) => {
+ *     ipcRenderer.on('auth-callback', (_, data) => callback(data));
+ *     return () => ipcRenderer.off('auth-callback');
+ *   },
+ *   saveTokens: (tokens) => store.set('tokens', tokens),
+ *   getTokens: () => store.get('tokens'),
+ *   deleteTokens: () => store.delete('tokens'),
+ * };
+ * ```
+ */
+export interface NativeAdapter {
+    /** Get the redirect URI for this platform (can be async for dynamic URIs) */
+    getRedirectUri: () => string | Promise<string>;
+    /** Open a URL in the external browser or popup window */
+    openExternalUrl: (url: string) => Promise<void>;
+    /** Subscribe to auth callbacks - returns cleanup function */
+    onAuthCallback: (callback: (result: NativeAuthCallbackResult) => void) => () => void;
+    /** Store tokens securely on the device */
+    saveTokens: (tokens: NativeTokenData) => Promise<boolean>;
+    /** Retrieve stored tokens */
+    getTokens: () => Promise<NativeTokenData | null>;
+    /** Delete stored tokens (logout) */
+    deleteTokens: () => Promise<boolean>;
+}
+/**
+ * Native mode configuration.
+ * All TideCloak configuration is here - the adapter only handles platform-specific operations.
+ *
+ * @example
+ * ```typescript
+ * import adapterConfig from './adapter.json';
+ *
+ * const config: NativeConfig = {
+ *   authMode: 'native',
+ *   adapter: myAdapter,
+ *   // Spread the adapter.json config - it has all the TideCloak settings
+ *   ...adapterConfig,
+ * };
+ * ```
+ */
+export interface NativeConfig {
+    /** Must be "native" for native mode */
+    authMode: "native";
+    /** Native adapter with platform-specific implementations */
+    adapter: NativeAdapter;
+    /** Auth server URL (e.g., "http://localhost:8080") */
+    "auth-server-url": string;
+    /** Realm name */
+    realm: string;
+    /** Client ID (resource in adapter.json) */
+    resource: string;
+    /** Tide vendor ID for encryption operations */
+    vendorId?: string;
+    /** Home ORK URL (e.g., "https://ork1.tideprotocol.com") */
+    homeOrkUrl?: string;
+    /**
+     * Client origin authentication signatures.
+     * These are keyed by origin (e.g., "client-origin-auth-http://localhost:5173").
+     * The SDK automatically selects the right one based on window.location.origin.
+     */
+    [key: `client-origin-auth-${string}`]: string;
+    /** Session mode: 'online' (default) validates tokens, 'offline' accepts stored tokens */
+    sessionMode?: 'online' | 'offline';
+    /** OAuth scopes (defaults to "openid profile email") */
+    scope?: string;
+    /** JWK for token verification (from adapter.json) */
+    jwk?: {
+        keys: Array<{
+            kid: string;
+            kty: string;
+            alg: string;
+            use: string;
+            crv?: string;
+            x?: string;
+            [key: string]: unknown;
+        }>;
+    };
+}

package/dist/types/types.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Type definitions for @tidecloak/js native mode
+ */
+/**
+ * Token data for native mode storage.
+ */
+export interface NativeTokenData {
+    accessToken: string;
+    refreshToken: string;
+    idToken?: string;
+    /** Tide doken (delegated token) for encryption/decryption operations */
+    doken?: string;
+    expiresAt: number;
+}
+/**
+ * Auth callback result from native app.
+ */
+export interface NativeAuthCallbackResult {
+    code?: string;
+    error?: string;
+    errorDescription?: string;
+}
+/**
+ * Native adapter interface for platform-specific operations.
+ *
+ * This is the MINIMAL interface developers must implement for their platform.
+ * The SDK handles everything else (encryption, token management, etc.).
+ *
+ * @example
+ * ```typescript
+ * // Electron example - minimal implementation
+ * const adapter: NativeAdapter = {
+ *   getRedirectUri: () => 'myapp://auth/callback',
+ *   openExternalUrl: (url) => shell.openExternal(url),
+ *   onAuthCallback: (callback) => {
+ *     ipcRenderer.on('auth-callback', (_, data) => callback(data));
+ *     return () => ipcRenderer.off('auth-callback');
+ *   },
+ *   saveTokens: (tokens) => store.set('tokens', tokens),
+ *   getTokens: () => store.get('tokens'),
+ *   deleteTokens: () => store.delete('tokens'),
+ * };
+ * ```
+ */
+export interface NativeAdapter {
+    /** Get the redirect URI for this platform (can be async for dynamic URIs) */
+    getRedirectUri: () => string | Promise<string>;
+    /** Open a URL in the external browser or popup window */
+    openExternalUrl: (url: string) => Promise<void>;
+    /** Subscribe to auth callbacks - returns cleanup function */
+    onAuthCallback: (callback: (result: NativeAuthCallbackResult) => void) => () => void;
+    /** Store tokens securely on the device */
+    saveTokens: (tokens: NativeTokenData) => Promise<boolean>;
+    /** Retrieve stored tokens */
+    getTokens: () => Promise<NativeTokenData | null>;
+    /** Delete stored tokens (logout) */
+    deleteTokens: () => Promise<boolean>;
+}
+/**
+ * Native mode configuration.
+ * All TideCloak configuration is here - the adapter only handles platform-specific operations.
+ *
+ * @example
+ * ```typescript
+ * import adapterConfig from './adapter.json';
+ *
+ * const config: NativeConfig = {
+ *   authMode: 'native',
+ *   adapter: myAdapter,
+ *   // Spread the adapter.json config - it has all the TideCloak settings
+ *   ...adapterConfig,
+ * };
+ * ```
+ */
+export interface NativeConfig {
+    /** Must be "native" for native mode */
+    authMode: "native";
+    /** Native adapter with platform-specific implementations */
+    adapter: NativeAdapter;
+    /** Auth server URL (e.g., "http://localhost:8080") */
+    "auth-server-url": string;
+    /** Realm name */
+    realm: string;
+    /** Client ID (resource in adapter.json) */
+    resource: string;
+    /** Tide vendor ID for encryption operations */
+    vendorId?: string;
+    /** Home ORK URL (e.g., "https://ork1.tideprotocol.com") */
+    homeOrkUrl?: string;
+    /**
+     * Client origin authentication signatures.
+     * These are keyed by origin (e.g., "client-origin-auth-http://localhost:5173").
+     * The SDK automatically selects the right one based on window.location.origin.
+     */
+    [key: `client-origin-auth-${string}`]: string;
+    /** Session mode: 'online' (default) validates tokens, 'offline' accepts stored tokens */
+    sessionMode?: 'online' | 'offline';
+    /** OAuth scopes (defaults to "openid profile email") */
+    scope?: string;
+    /** JWK for token verification (from adapter.json) */
+    jwk?: {
+        keys: Array<{
+            kid: string;
+            kty: string;
+            alg: string;
+            use: string;
+            crv?: string;
+            x?: string;
+            [key: string]: unknown;
+        }>;
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tidecloak/js",
-  "version": "0.13.11",
+  "version": "0.13.14",
   "type": "module",
   "main": "dist/cjs/src/index.js",
   "module": "dist/esm/src/index.js",
@@ -32,6 +32,6 @@
     "silent-check-sso.html"
   ],
   "dependencies": {
-    "heimdall-tide": "^0.13.11"
+    "heimdall-tide": "^0.13.14"
   }
 }