@emblemvault/auth-sdk 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Emblem Vault
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,180 @@
+# @emblemvault/auth-sdk
+
+Official TypeScript SDK for Emblem Vault authentication.
+
+## Installation
+
+```bash
+npm install @emblemvault/auth-sdk
+# or
+yarn add @emblemvault/auth-sdk
+```
+
+## Quick Start
+
+```typescript
+import { EmblemAuthSDK } from '@emblemvault/auth-sdk';
+
+// Minimal setup - only appId is required
+const auth = new EmblemAuthSDK({
+  appId: 'your-app-id',
+  onSuccess: (session) => {
+    console.log('Authenticated!', session);
+  },
+  onError: (error) => {
+    console.error('Auth failed:', error);
+  }
+});
+
+// Open authentication modal
+auth.openAuthModal();
+
+// Get current session
+const session = auth.getSession();
+
+// Use JWT for API calls
+fetch('https://api.emblemvault.ai/protected-endpoint', {
+  headers: {
+    'Authorization': `Bearer ${session.authToken}`
+  }
+});
+```
+
+## Features
+
+- 🔐 **Multiple Auth Methods** - Wallet (EVM, Solana, Hedera) and OAuth (Twitter, Google)
+- 🔑 **JWT-based Sessions** - Secure token management with auto-refresh
+- 💾 **Session Persistence** - Stay logged in across page reloads (enabled by default)
+- 🎨 **Flexible UI** - Iframe or popup modal modes
+- 📦 **TypeScript** - Full type definitions included
+- 🌐 **Browser & Node** - Works in browsers and Node.js environments
+- ⚡ **Lightweight** - < 15KB minified and gzipped
+
+## API Reference
+
+### Constructor
+
+```typescript
+new EmblemAuthSDK(config: EmblemAuthConfig)
+```
+
+#### Config Options
+
+| Option | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `appId` | string | ✅ | - | Your application ID |
+| `authUrl` | string | ❌ | `https://auth.emblemvault.ai` | Auth service URL for modal, init, bootstrap, refresh |
+| `apiUrl` | string | ❌ | `https://api.emblemvault.ai` | Backend API for vault operations and signing only |
+| `modalMode` | 'iframe' \| 'popup' \| 'auto' | ❌ | `'auto'` | Modal display mode |
+| `persistSession` | boolean | ❌ | `true` | Persist session to localStorage (stay logged in) |
+| `onSuccess` | (session) => void | ❌ | - | Success callback |
+| `onError` | (error) => void | ❌ | - | Error callback |
+
+**URL Configuration:**
+- `authUrl` handles: auth modal (`/connect`), `/api/auth/init`, `/auth/bootstrap`, `/api/auth/refresh`
+- `apiUrl` handles: vault info, signing, decryption, and other vault operations
+
+### Methods
+
+#### `openAuthModal(): Promise<void>`
+Opens the authentication modal for users to sign in.
+
+#### `getSession(): AuthSession | null`
+Returns the current authentication session.
+
+#### `refreshSession(): Promise<AuthSession | null>`
+Manually refreshes the authentication token.
+
+#### `authenticateWallet(params): Promise<AuthSession | null>`
+Programmatically authenticate with wallet signature.
+
+#### `getVaultInfo(): Promise<VaultInfo>`
+Retrieves information about the user's vault. Caches the result for the session duration.
+
+```typescript
+const vaultInfo = await auth.getVaultInfo();
+console.log(vaultInfo.vaultId);
+console.log(vaultInfo.evmAddress);
+```
+
+#### `getVaultApiKey(): Promise<string>`
+Retrieves or generates the vault API key.
+
+#### `logout(): void`
+Clears the current session.
+
+#### `on(event, handler): void`
+Subscribe to authentication events.
+
+#### `off(event, handler): void`
+Unsubscribe from authentication events.
+
+### Events
+
+- `session` - Fired when session is established or updated
+- `sessionExpired` - Session has expired
+- `sessionRefreshed` - Session was refreshed
+- `sessionWillRefresh` - Session will refresh soon
+- `authError` - Authentication error occurred
+
+### Session Persistence
+
+By default, sessions are persisted to `localStorage`, allowing users to stay logged in across page reloads and browser sessions. This follows the industry-standard "stay logged in" behavior.
+
+```typescript
+// Default behavior - sessions are persisted
+const auth = new EmblemAuthSDK({
+  appId: 'your-app-id'
+});
+
+// Sessions will automatically restore on page load
+const session = auth.getSession(); // Returns persisted session if valid
+
+// To disable persistence (session only lasts until page closes)
+const auth = new EmblemAuthSDK({
+  appId: 'your-app-id',
+  persistSession: false
+});
+```
+
+**Notes:**
+- Sessions are stored with the key `emblem_session_{appId}`
+- Expired sessions are automatically cleared on load
+- Calling `logout()` clears the persisted session
+- Works gracefully in private browsing mode (falls back to memory-only)
+
+### Types
+
+#### `VaultInfo`
+```typescript
+interface VaultInfo {
+  vaultId: string;
+  evmAddress?: string;
+  solanaAddress?: string;
+  hederaAccountId?: string;
+  createdAt?: string;
+  metadata?: Record<string, any>;
+}
+```
+
+## CDN Usage
+
+```html
+<script src="https://unpkg.com/@emblemvault/auth-sdk@latest/dist/emblem-auth.min.js"></script>
+<script>
+  // Only appId is required - authUrl and apiUrl have production defaults
+  const auth = new EmblemAuth.EmblemAuthSDK({
+    appId: 'your-app-id'
+  });
+
+  auth.openAuthModal();
+</script>
+```
+
+Alternative CDNs:
+- jsDelivr: `https://cdn.jsdelivr.net/npm/@emblemvault/auth-sdk@latest/dist/emblem-auth.min.js`
+- unpkg (specific version): `https://unpkg.com/@emblemvault/auth-sdk@2.0.0/dist/emblem-auth.min.js`
+
+## License
+
+MIT

package/dist/EmblemAuthSDK.d.ts

@@ -0,0 +1,150 @@
+import type { EmblemAuthConfig, AuthSession, WalletAuthParams, AuthEventKey, AuthEventHandler, VaultInfo, Hex } from './types';
+import { type EmblemEthersWallet } from './signers/ethers';
+import { EmblemSolanaSigner } from './signers/solana';
+import { EmblemWeb3Adapter } from './signers/web3';
+export declare class EmblemAuthSDK {
+    private readonly config;
+    private session;
+    private pendingNonce;
+    private readonly messageHandler;
+    private overlayEl;
+    private _iframeEl;
+    private overlayCleanup;
+    private readonly sessionMgr;
+    private readonly events;
+    private _cachedVaultInfo;
+    private readonly storageKey;
+    constructor(config: EmblemAuthConfig);
+    /**
+     * Authenticate with a wallet signature (programmatic/headless auth)
+     * Uses the external verification endpoint for cross-origin compatibility
+     */
+    authenticateWallet(params: WalletAuthParams): Promise<AuthSession | null>;
+    /**
+     * Open the authentication modal
+     */
+    openAuthModal(): Promise<void>;
+    /**
+     * Get the current session
+     */
+    getSession(): AuthSession | null;
+    /**
+     * Refresh the current session
+     * Uses the registration site's refresh endpoint with cookies for secure token rotation
+     */
+    refreshSession(): Promise<AuthSession | null>;
+    /**
+     * Get vault information
+     */
+    getVaultInfo(): Promise<VaultInfo>;
+    /**
+     * Get or create the vault API key
+     */
+    getVaultApiKey(): Promise<string>;
+    /**
+     * Hydrate a previously saved session
+     */
+    hydrateSession(session: AuthSession): void;
+    /**
+     * Logout and clear the session
+     */
+    logout(): void;
+    /**
+     * Subscribe to auth events
+     */
+    on<K extends AuthEventKey>(event: K, handler: AuthEventHandler<K>): void;
+    /**
+     * Unsubscribe from auth events
+     */
+    off<K extends AuthEventKey>(event: K, handler: AuthEventHandler<K>): void;
+    /**
+     * Helper to get signer config and vault info
+     */
+    private getSignerContext;
+    /**
+     * Create a viem-compatible account adapter for EVM signing
+     * Requires an active session with authToken
+     *
+     * @example
+     * ```typescript
+     * const account = await sdk.toViemAccount();
+     * const signature = await account.signMessage({ message: 'Hello' });
+     * ```
+     */
+    toViemAccount(): Promise<{
+        address: Hex;
+        signMessage: (args: {
+            message: unknown;
+        }) => Promise<Hex>;
+        signTypedData: (typedData: unknown) => Promise<Hex>;
+        signTransaction: (tx: unknown, opts?: unknown) => Promise<Hex>;
+        type: 'local';
+        source: 'custom';
+    }>;
+    /**
+     * Create an ethers v6 compatible wallet adapter for EVM signing
+     * Requires an active session with authToken
+     *
+     * @param provider - Optional ethers Provider for transaction population
+     *
+     * @example
+     * ```typescript
+     * const wallet = await sdk.toEthersWallet(provider);
+     * const signature = await wallet.signMessage('Hello');
+     * const tx = await wallet.sendTransaction({ to, value });
+     * ```
+     */
+    toEthersWallet(provider?: unknown | null): Promise<EmblemEthersWallet>;
+    /**
+     * Create a Web3.js compatible adapter for EVM signing
+     * Requires an active session with authToken
+     *
+     * @example
+     * ```typescript
+     * const adapter = await sdk.toWeb3Adapter();
+     * const signature = await adapter.signMessage('Hello');
+     * ```
+     */
+    toWeb3Adapter(): Promise<EmblemWeb3Adapter>;
+    /**
+     * Create a Solana Web3.js compatible signer
+     * Requires an active session with authToken
+     *
+     * @example
+     * ```typescript
+     * const signer = await sdk.toSolanaWeb3Signer();
+     * const signature = await signer.signMessage('Hello');
+     * const signedTx = await signer.signTransaction(tx);
+     * ```
+     */
+    toSolanaWeb3Signer(): Promise<EmblemSolanaSigner>;
+    /**
+     * Create a Solana Kit compatible signer
+     * Requires an active session with authToken
+     *
+     * @example
+     * ```typescript
+     * const signer = await sdk.toSolanaKitSigner();
+     * const signature = await signer.signMessage('Hello');
+     * ```
+     */
+    toSolanaKitSigner(): Promise<EmblemSolanaSigner>;
+    /**
+     * Clean up event listeners
+     */
+    destroy(): void;
+    private resolveModalUrl;
+    private onMessage;
+    private emit;
+    private emitError;
+    private popupFeatures;
+    private randomId;
+    private tryGetOriginFromConfig;
+    private getAuthInit;
+    private openIframeModal;
+    private closeOverlay;
+    private safeJson;
+    private loadPersistedSession;
+    private persistSession;
+}
+//# sourceMappingURL=EmblemAuthSDK.d.ts.map

package/dist/EmblemAuthSDK.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EmblemAuthSDK.d.ts","sourceRoot":"","sources":["../src/EmblemAuthSDK.ts"],"names":[],"mappings":"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"}

package/dist/SessionManager.d.ts

@@ -0,0 +1,57 @@
+import type { AuthSession, SessionRefreshInfo } from './types/session';
+interface SessionManagerConfig {
+    /**
+     * Callback to refresh an expiring session
+     */
+    onRefresh?: (session: AuthSession) => Promise<AuthSession | null>;
+    /**
+     * Time before expiry to trigger refresh (milliseconds)
+     * @default 60000 (1 minute)
+     */
+    refreshSkewMs?: number;
+}
+type SessionEventMap = {
+    session: (session: AuthSession | null) => void;
+    sessionExpired: (session: AuthSession) => void;
+    sessionRefreshed: (session: AuthSession) => void;
+    sessionWillRefresh: (info: SessionRefreshInfo) => void;
+};
+type SessionEventKey = keyof SessionEventMap;
+type SessionEventHandler<K extends SessionEventKey> = SessionEventMap[K];
+export declare class SessionManager {
+    private session;
+    private timer;
+    private readonly onRefresh?;
+    private readonly events;
+    private readonly refreshSkewMs;
+    constructor(config?: SessionManagerConfig);
+    /**
+     * Set the current session and schedule refresh
+     */
+    setSession(session: AuthSession | null): void;
+    /**
+     * Get the current session
+     */
+    getSession(): AuthSession | null;
+    /**
+     * Clear the current session
+     */
+    clear(): void;
+    /**
+     * Subscribe to session events
+     */
+    on<K extends SessionEventKey>(event: K, handler: SessionEventHandler<K>): void;
+    /**
+     * Unsubscribe from session events
+     */
+    off<K extends SessionEventKey>(event: K, handler: SessionEventHandler<K>): void;
+    /**
+     * Destroy the session manager
+     */
+    destroy(): void;
+    private emit;
+    private cancel;
+    private schedule;
+}
+export {};
+//# sourceMappingURL=SessionManager.d.ts.map

package/dist/SessionManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SessionManager.d.ts","sourceRoot":"","sources":["../src/SessionManager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAEvE,UAAU,oBAAoB;IAC5B;;OAEG;IACH,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAElE;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,KAAK,eAAe,GAAG;IACrB,OAAO,EAAE,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAC;IAC/C,cAAc,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,IAAI,CAAC;IAC/C,gBAAgB,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,IAAI,CAAC;IACjD,kBAAkB,EAAE,CAAC,IAAI,EAAE,kBAAkB,KAAK,IAAI,CAAC;CACxD,CAAC;AAEF,KAAK,eAAe,GAAG,MAAM,eAAe,CAAC;AAC7C,KAAK,mBAAmB,CAAC,CAAC,SAAS,eAAe,IAAI,eAAe,CAAC,CAAC,CAAC,CAAC;AAEzE,qBAAa,cAAc;IACzB,OAAO,CAAC,OAAO,CAA4B;IAC3C,OAAO,CAAC,KAAK,CAA+B;IAC5C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAwD;IACnF,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoE;IAC3F,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;gBAE3B,MAAM,GAAE,oBAAyB;IAK7C;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,GAAG,IAAI;IAM7C;;OAEG;IACH,UAAU,IAAI,WAAW,GAAG,IAAI;IAIhC;;OAEG;IACH,KAAK,IAAI,IAAI;IAMb;;OAEG;IACH,EAAE,CAAC,CAAC,SAAS,eAAe,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAAG,IAAI;IAO9E;;OAEG;IACH,GAAG,CAAC,CAAC,SAAS,eAAe,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAAG,IAAI;IAU/E;;OAEG;IACH,OAAO,IAAI,IAAI;IAQf,OAAO,CAAC,IAAI;IAgBZ,OAAO,CAAC,MAAM;IAOd,OAAO,CAAC,QAAQ;CA6CjB"}