@korajs/auth 0.3.3 → 0.5.0

package/dist/org-client-q2u55qod.d.ts

@@ -0,0 +1,665 @@
+import { KoraError } from '@korajs/core';
+
+/**
+ * Thrown when a device key store operation fails.
+ * Provides context about the operation and the underlying cause.
+ */
+declare class DeviceKeyStoreError extends KoraError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * Persistent storage interface for ECDSA P-256 device key pairs.
+ *
+ * Device key pairs are used for proof-of-possession authentication:
+ * the private key never leaves the device, and the public key is
+ * registered with the server. This store persists key pairs across
+ * page reloads and app restarts.
+ *
+ * In the browser, CryptoKey objects are structured-cloneable, so they
+ * can be stored directly in IndexedDB without serialization. In Node.js
+ * or test environments, an in-memory implementation is used instead.
+ */
+interface DeviceKeyStore {
+    /**
+     * Persist a key pair for the given device.
+     *
+     * Overwrites any previously stored key pair for the same device ID.
+     *
+     * @param deviceId - The unique device identifier (typically a UUID v7)
+     * @param keyPair - The ECDSA P-256 CryptoKeyPair to store
+     * @throws {DeviceKeyStoreError} If the storage operation fails
+     */
+    saveKeyPair(deviceId: string, keyPair: CryptoKeyPair): Promise<void>;
+    /**
+     * Load a previously stored key pair for the given device.
+     *
+     * @param deviceId - The unique device identifier
+     * @returns The stored CryptoKeyPair, or null if no key pair exists for the device
+     * @throws {DeviceKeyStoreError} If the storage operation fails
+     */
+    loadKeyPair(deviceId: string): Promise<CryptoKeyPair | null>;
+    /**
+     * Delete a stored key pair for the given device.
+     *
+     * No-op if no key pair exists for the device ID.
+     *
+     * @param deviceId - The unique device identifier
+     * @throws {DeviceKeyStoreError} If the storage operation fails
+     */
+    deleteKeyPair(deviceId: string): Promise<void>;
+    /**
+     * Check whether a key pair exists for the given device.
+     *
+     * @param deviceId - The unique device identifier
+     * @returns True if a key pair is stored for the device, false otherwise
+     * @throws {DeviceKeyStoreError} If the storage operation fails
+     */
+    hasKeyPair(deviceId: string): Promise<boolean>;
+}
+/**
+ * Browser-based device key store backed by IndexedDB.
+ *
+ * CryptoKey objects are structured-cloneable, so they can be stored
+ * directly in IndexedDB without needing to export/import them as JWK.
+ * This preserves the non-extractable flag on private keys, ensuring
+ * they cannot be read even from storage.
+ *
+ * The database uses a single object store (`keypairs`) with the device ID
+ * as the key and the full CryptoKeyPair as the value.
+ *
+ * @example
+ * ```typescript
+ * const store = new IndexedDBDeviceKeyStore()
+ * const keyPair = await generateDeviceKeyPair()
+ * await store.saveKeyPair('device-123', keyPair)
+ *
+ * const loaded = await store.loadKeyPair('device-123')
+ * // loaded.privateKey is still non-extractable
+ * ```
+ */
+declare class IndexedDBDeviceKeyStore implements DeviceKeyStore {
+    private dbPromise;
+    /**
+     * Opens (or creates) the IndexedDB database.
+     *
+     * The database connection is lazily initialized on first use and
+     * reused for subsequent operations. If the database does not exist,
+     * it is created with the `keypairs` object store.
+     */
+    private openDatabase;
+    /** @inheritdoc */
+    saveKeyPair(deviceId: string, keyPair: CryptoKeyPair): Promise<void>;
+    /** @inheritdoc */
+    loadKeyPair(deviceId: string): Promise<CryptoKeyPair | null>;
+    /** @inheritdoc */
+    deleteKeyPair(deviceId: string): Promise<void>;
+    /** @inheritdoc */
+    hasKeyPair(deviceId: string): Promise<boolean>;
+}
+/**
+ * In-memory device key store for Node.js and testing environments.
+ *
+ * Key pairs are stored in a plain Map and do not survive process restarts.
+ * This is suitable for server-side rendering, Node.js scripts, and unit tests
+ * where IndexedDB is not available.
+ *
+ * @example
+ * ```typescript
+ * const store = new InMemoryDeviceKeyStore()
+ * const keyPair = await generateDeviceKeyPair()
+ * await store.saveKeyPair('device-123', keyPair)
+ *
+ * const loaded = await store.loadKeyPair('device-123')
+ * ```
+ */
+declare class InMemoryDeviceKeyStore implements DeviceKeyStore {
+    private readonly store;
+    /** @inheritdoc */
+    saveKeyPair(deviceId: string, keyPair: CryptoKeyPair): Promise<void>;
+    /** @inheritdoc */
+    loadKeyPair(deviceId: string): Promise<CryptoKeyPair | null>;
+    /** @inheritdoc */
+    deleteKeyPair(deviceId: string): Promise<void>;
+    /** @inheritdoc */
+    hasKeyPair(deviceId: string): Promise<boolean>;
+}
+/**
+ * Creates a DeviceKeyStore appropriate for the current environment.
+ *
+ * In browsers where IndexedDB is available, returns an {@link IndexedDBDeviceKeyStore}
+ * that persists CryptoKeyPair objects as structured clones. In Node.js, SSR,
+ * or environments without IndexedDB, returns an {@link InMemoryDeviceKeyStore}.
+ *
+ * @returns A DeviceKeyStore instance for the current environment
+ *
+ * @example
+ * ```typescript
+ * const store = createDeviceKeyStore()
+ * const keyPair = await generateDeviceKeyPair()
+ * await store.saveKeyPair(deviceId, keyPair)
+ * ```
+ */
+declare function createDeviceKeyStore(): DeviceKeyStore;
+
+type MaybePromise$1<T> = T | Promise<T>;
+/**
+ * Minimal key-value credential storage interface used by Kora auth adapters.
+ *
+ * This intentionally matches the shape of secure stores across runtimes:
+ * browser Storage, Tauri secure storage plugins, Expo SecureStore, iOS Keychain,
+ * Android Keystore wrappers, and encrypted desktop stores.
+ */
+interface AuthKeyValueStorage {
+    getItem(key: string): MaybePromise$1<string | null>;
+    setItem(key: string, value: string): MaybePromise$1<void>;
+    removeItem(key: string): MaybePromise$1<void>;
+}
+interface AuthTokenStorageOptions {
+    /** Backing credential store. */
+    store: AuthKeyValueStorage;
+    /** Storage key prefix. Defaults to `kora_auth`. */
+    prefix?: string;
+}
+/**
+ * Creates an `AuthTokenStorage` adapter from a runtime key-value store.
+ *
+ * Use this with platform credential stores instead of wiring `AuthClient`
+ * directly to browser localStorage in desktop and mobile apps.
+ */
+declare function createAuthTokenStorage(options: AuthTokenStorageOptions): AuthTokenStorage;
+/**
+ * Creates an in-memory token storage adapter.
+ *
+ * Useful for tests, demos, and SSR. Production desktop and mobile apps should
+ * prefer a secure platform-backed store.
+ */
+declare function createMemoryAuthTokenStorage(): AuthTokenStorage;
+/**
+ * Adapts Web Storage-compatible APIs such as `localStorage` or `sessionStorage`.
+ */
+declare function createWebStorageAuthTokenStorage(storage: Storage, prefix?: string): AuthTokenStorage;
+
+interface AuthDeviceIdentity {
+    /** Stable local device ID used in token `dev` claims. */
+    deviceId: string;
+    /** Public proof-of-possession key serialized as a JSON Web Key string. */
+    devicePublicKey: string;
+}
+interface AuthDeviceIdentityProvider {
+    getDeviceIdentity(): Promise<AuthDeviceIdentity>;
+}
+interface PersistentDeviceIdentityOptions {
+    /** Store for the stable device ID. Use a platform credential store in production. */
+    storage: AuthKeyValueStorage;
+    /** Store for the non-extractable device key pair. Defaults to IndexedDB when available. */
+    keyStore?: DeviceKeyStore;
+    /** Storage key for the device ID. Defaults to `kora_auth_device_id`. */
+    deviceIdKey?: string;
+    /** Optional device ID generator for tests or custom device registries. */
+    generateDeviceId?: () => string;
+}
+declare class AuthDeviceIdentityError extends KoraError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * Creates a persistent device identity provider for `AuthClient`.
+ *
+ * The provider keeps a stable device ID in the supplied key-value store and a
+ * non-extractable ECDSA P-256 key pair in the supplied `DeviceKeyStore`. The
+ * public key is returned during sign-up/sign-in so the server can bind tokens
+ * to a real offline device instead of a transient browser session.
+ */
+declare function createPersistentDeviceIdentity(options: PersistentDeviceIdentityOptions): AuthDeviceIdentityProvider;
+
+/**
+ * Thrown when an authentication operation fails.
+ * Includes a machine-readable code and optional context for debugging.
+ */
+declare class AuthError extends KoraError {
+    constructor(message: string, code: string, context?: Record<string, unknown>);
+}
+/**
+ * Possible authentication states for the client.
+ * - 'loading': Initial state while restoring tokens from storage
+ * - 'authenticated': User is signed in with a valid session
+ * - 'unauthenticated': No valid session exists
+ */
+type AuthState = 'loading' | 'authenticated' | 'unauthenticated';
+/**
+ * Authenticated user information.
+ */
+interface AuthUser {
+    /** Unique user identifier */
+    id: string;
+    /** User email address */
+    email: string;
+    /** Display name (may be absent if user did not provide one) */
+    name: string | null;
+}
+interface LinkedOAuthAccount {
+    id: string;
+    userId: string;
+    provider: string;
+    providerUserId: string;
+    email: string | null;
+    linkedAt: number;
+}
+interface OAuthAuthorizationResult {
+    url: string;
+    state: string;
+}
+interface OAuthAuthorizationOptions {
+    /**
+     * Redirect the current browser window to the provider after creating the URL.
+     * Defaults to true when `window.location.assign` is available.
+     */
+    redirect?: boolean;
+    /**
+     * Optional app-specific return path stored in OAuth state metadata.
+     */
+    returnTo?: string;
+    /**
+     * Optional extra metadata stored in OAuth state. Use this for app handoff data.
+     */
+    metadata?: Record<string, unknown>;
+    deviceId?: string;
+    devicePublicKey?: string;
+}
+interface OAuthCallbackParams {
+    code: string;
+    state: string;
+    deviceId?: string;
+    devicePublicKey?: string;
+}
+/**
+ * Configuration for the AuthClient.
+ */
+interface AuthClientConfig {
+    /** Base URL of the auth server (e.g. 'http://localhost:3001') */
+    serverUrl: string;
+    /** Storage key prefix for tokens. Defaults to 'kora_auth' */
+    storageKey?: string;
+    /**
+     * Optional token storage adapter.
+     *
+     * Use this for runtimes where localStorage is not the right place for
+     * credentials, such as React Native/Expo SecureStore, iOS Keychain,
+     * Android Keystore, or a Tauri secure storage plugin.
+     */
+    storage?: AuthTokenStorage;
+    /**
+     * Optional fetch implementation. Defaults to globalThis.fetch.
+     * Useful for tests, SSR adapters, and mobile runtimes with a custom fetch.
+     */
+    fetch?: typeof fetch;
+    /**
+     * Optional local device identity provider.
+     *
+     * When configured, sign-up and sign-in automatically include stable
+     * `deviceId` and `devicePublicKey` fields unless the caller provides them.
+     */
+    deviceIdentity?: AuthDeviceIdentityProvider;
+}
+type MaybePromise<T> = T | Promise<T>;
+interface AuthTokenStorage {
+    getAccessToken(): MaybePromise<string | null>;
+    getRefreshToken(): MaybePromise<string | null>;
+    setTokens(access: string, refresh: string): MaybePromise<void>;
+    clear(): MaybePromise<void>;
+}
+/**
+ * Client-side authentication manager for Kora.js.
+ *
+ * Manages token storage, session restoration, sign-up, sign-in, sign-out,
+ * token refresh, and auth state change notifications. Framework-agnostic --
+ * works in any JavaScript environment with `fetch` and optionally `localStorage`.
+ *
+ * @example
+ * ```typescript
+ * const auth = new AuthClient({ serverUrl: 'http://localhost:3001' })
+ * await auth.initialize()
+ *
+ * if (!auth.isAuthenticated) {
+ *   await auth.signIn({ email: 'user@example.com', password: 'secret' })
+ * }
+ *
+ * const unsub = auth.onAuthChange((state) => {
+ *   console.log('Auth state:', state)
+ * })
+ * ```
+ */
+declare class AuthClient {
+    private readonly serverUrl;
+    private readonly storage;
+    private readonly fetchFn;
+    private readonly deviceIdentity;
+    private readonly listeners;
+    private _state;
+    private _user;
+    private _refreshPromise;
+    private _initialized;
+    /**
+     * Creates a new AuthClient.
+     *
+     * @param config - Auth client configuration
+     */
+    constructor(config: AuthClientConfig);
+    /** Current authentication state. */
+    get state(): AuthState;
+    /** Current authenticated user, or null if not signed in. */
+    get currentUser(): AuthUser | null;
+    /** Whether the user is currently authenticated. */
+    get isAuthenticated(): boolean;
+    /**
+     * Initialize the auth client by restoring a session from stored tokens.
+     *
+     * Loads tokens from storage, validates the access token, and attempts a
+     * refresh if the access token is expired but a refresh token is available.
+     * Safe to call multiple times -- subsequent calls are no-ops once initialized.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Register a new user account.
+     *
+     * @param params - Sign-up credentials
+     * @returns The newly created AuthUser
+     * @throws {AuthError} If the request fails or the server returns an error
+     */
+    signUp(params: {
+        email: string;
+        password: string;
+        name?: string;
+        deviceId?: string;
+        devicePublicKey?: string;
+    }): Promise<AuthUser>;
+    /**
+     * Sign in with email and password.
+     *
+     * @param params - Sign-in credentials
+     * @returns The authenticated AuthUser
+     * @throws {AuthError} If the credentials are invalid or the request fails
+     */
+    signIn(params: {
+        email: string;
+        password: string;
+        deviceId?: string;
+        devicePublicKey?: string;
+    }): Promise<AuthUser>;
+    /**
+     * Create an OAuth authorization URL and optionally redirect the current window.
+     *
+     * For web apps, call this from a button click and keep the default redirect behavior.
+     * For desktop/mobile, pass `redirect: false`, open the returned URL with the runtime's
+     * browser API, then call `completeOAuthSignIn()` after receiving the callback.
+     */
+    signInWithOAuth(provider: string, options?: OAuthAuthorizationOptions): Promise<OAuthAuthorizationResult>;
+    /**
+     * Complete an OAuth sign-in callback and store the issued Kora tokens.
+     */
+    completeOAuthSignIn(provider: string, params: OAuthCallbackParams): Promise<AuthUser>;
+    /**
+     * Create an OAuth authorization URL for linking another provider to the current user.
+     */
+    getOAuthAuthorizationUrl(provider: string, options?: OAuthAuthorizationOptions): Promise<OAuthAuthorizationResult>;
+    /**
+     * Link an OAuth provider to the current authenticated user.
+     */
+    linkOAuth(provider: string, params: OAuthCallbackParams): Promise<LinkedOAuthAccount>;
+    /**
+     * List OAuth accounts linked to the current authenticated user.
+     */
+    listLinkedAccounts(): Promise<LinkedOAuthAccount[]>;
+    /**
+     * Unlink an OAuth provider from the current authenticated user.
+     */
+    unlinkOAuth(provider: string): Promise<void>;
+    /**
+     * Sign out the current user.
+     *
+     * Clears local tokens and attempts to revoke the refresh token on the server
+     * (best-effort — succeeds even if the server is unreachable). This ensures that
+     * stolen refresh tokens cannot be used after the user explicitly signs out.
+     */
+    signOut(): Promise<void>;
+    /**
+     * Get a valid access token, automatically refreshing if expired.
+     *
+     * @returns A valid access token string, or null if the user is not
+     *          authenticated and refresh is not possible
+     */
+    getAccessToken(): Promise<string | null>;
+    /**
+     * Get a valid token for the sync engine handshake.
+     * Alias for {@link getAccessToken}.
+     *
+     * @returns A valid access token string, or null if unavailable
+     */
+    getSyncToken(): Promise<string | null>;
+    /**
+     * Subscribe to authentication state changes.
+     *
+     * The callback is invoked whenever the auth state transitions (e.g., from
+     * 'unauthenticated' to 'authenticated' on sign-in).
+     *
+     * @param callback - Function called with the new AuthState on each change
+     * @returns An unsubscribe function that removes the listener
+     *
+     * @example
+     * ```typescript
+     * const unsub = auth.onAuthChange((state) => {
+     *   console.log('Auth state changed to:', state)
+     * })
+     * // Later: unsub()
+     * ```
+     */
+    onAuthChange(callback: (state: AuthState) => void): () => void;
+    /**
+     * Update internal state and notify all listeners.
+     */
+    private setState;
+    /**
+     * Restore a session from a valid access token by fetching the user profile.
+     * Falls back to extracting the user ID from the token payload if the
+     * /auth/me request fails (offline scenario).
+     */
+    private restoreSession;
+    /**
+     * Fetch the current user profile from the server.
+     */
+    private fetchUserProfile;
+    private createOAuthAuthorization;
+    private withDeviceIdentity;
+    /**
+     * Refresh the access token using a refresh token.
+     * De-duplicates concurrent refresh calls so only one network request is made.
+     */
+    private refreshAccessToken;
+    private requireAccessToken;
+    /**
+     * Execute the token refresh network request.
+     */
+    private performRefresh;
+    /**
+     * Make an HTTP request to the auth server.
+     *
+     * @param path - URL path relative to serverUrl (e.g. '/auth/signin')
+     * @param options - Request options
+     * @returns Parsed JSON response body
+     * @throws {AuthError} On network failure or non-2xx response
+     */
+    private request;
+}
+
+/**
+ * Organization info returned by the server.
+ */
+interface ClientOrganization {
+    id: string;
+    name: string;
+    slug: string;
+    ownerId: string;
+    createdAt: number;
+    updatedAt: number;
+    metadata: Record<string, unknown>;
+}
+/**
+ * Membership info returned by the server.
+ */
+interface ClientMembership {
+    id: string;
+    orgId: string;
+    userId: string;
+    role: string;
+    invitedBy: string | null;
+    joinedAt: number;
+}
+/**
+ * Invitation info returned by the server.
+ */
+interface ClientInvitation {
+    id: string;
+    orgId: string;
+    email: string;
+    role: string;
+    invitedBy: string;
+    token: string;
+    createdAt: number;
+    expiresAt: number;
+    status: string;
+}
+/**
+ * Configuration for the OrgClient.
+ */
+interface OrgClientConfig {
+    /** Base URL of the auth/org server */
+    serverUrl: string;
+    /** Function that returns a valid access token for authenticated requests */
+    getAccessToken: () => Promise<string | null>;
+}
+/**
+ * Thrown when an org operation fails.
+ */
+declare class OrgClientError extends KoraError {
+    constructor(message: string, code: string, context?: Record<string, unknown>);
+}
+/**
+ * Client-side organization manager.
+ *
+ * Handles org CRUD, member management, invitations, and active org switching.
+ * Framework-agnostic — works in any JavaScript environment with `fetch`.
+ *
+ * @example
+ * ```typescript
+ * const orgClient = new OrgClient({
+ *   serverUrl: 'http://localhost:3001',
+ *   getAccessToken: () => authClient.getAccessToken(),
+ * })
+ *
+ * const org = await orgClient.createOrg({ name: 'Acme Inc', slug: 'acme' })
+ * orgClient.switchOrg(org.id)
+ * ```
+ */
+declare class OrgClient {
+    private readonly serverUrl;
+    private readonly getAccessToken;
+    private readonly listeners;
+    private _activeOrgId;
+    private _activeOrg;
+    private _activeRole;
+    constructor(config: OrgClientConfig);
+    /** Currently active organization ID */
+    get activeOrgId(): string | null;
+    /** Currently active organization */
+    get activeOrg(): ClientOrganization | null;
+    /** Current user's role in the active organization */
+    get activeRole(): string | null;
+    /**
+     * Create a new organization.
+     */
+    createOrg(params: {
+        name: string;
+        slug?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<ClientOrganization>;
+    /**
+     * List all organizations the current user belongs to.
+     */
+    listOrgs(): Promise<ClientOrganization[]>;
+    /**
+     * Get an organization by ID.
+     */
+    getOrg(orgId: string): Promise<ClientOrganization>;
+    /**
+     * Update an organization.
+     */
+    updateOrg(orgId: string, params: {
+        name?: string;
+        slug?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<ClientOrganization>;
+    /**
+     * Delete an organization.
+     */
+    deleteOrg(orgId: string): Promise<void>;
+    /**
+     * Switch the active organization context.
+     * Fetches the org details and the user's membership/role.
+     */
+    switchOrg(orgId: string): Promise<void>;
+    /**
+     * Clear the active organization (no org selected).
+     */
+    clearActiveOrg(): void;
+    /**
+     * List members of an organization.
+     */
+    listMembers(orgId: string): Promise<ClientMembership[]>;
+    /**
+     * Remove a member from an organization.
+     */
+    removeMember(orgId: string, userId: string): Promise<void>;
+    /**
+     * Update a member's role.
+     */
+    updateMemberRole(orgId: string, userId: string, role: string): Promise<ClientMembership>;
+    /**
+     * Transfer ownership to another member.
+     */
+    transferOwnership(orgId: string, newOwnerId: string): Promise<void>;
+    /**
+     * Leave an organization (remove yourself).
+     */
+    leaveOrg(orgId: string): Promise<void>;
+    /**
+     * Invite a user to an organization by email.
+     */
+    inviteMember(orgId: string, params: {
+        email: string;
+        role: string;
+    }): Promise<ClientInvitation>;
+    /**
+     * Accept an invitation by token.
+     */
+    acceptInvitation(token: string): Promise<ClientMembership>;
+    /**
+     * List pending invitations for an organization.
+     */
+    listInvitations(orgId: string): Promise<ClientInvitation[]>;
+    /**
+     * Revoke a pending invitation.
+     */
+    revokeInvitation(orgId: string, invitationId: string): Promise<void>;
+    /**
+     * List pending invitations for the current user's email.
+     */
+    listMyInvitations(email: string): Promise<ClientInvitation[]>;
+    /**
+     * Subscribe to active org changes.
+     * @returns Unsubscribe function
+     */
+    onOrgChange(callback: (orgId: string | null) => void): () => void;
+    private notifyListeners;
+    private request;
+}
+
+export { type AuthClientConfig as A, type ClientInvitation as C, type DeviceKeyStore as D, InMemoryDeviceKeyStore as I, type LinkedOAuthAccount as L, type OAuthAuthorizationOptions as O, type PersistentDeviceIdentityOptions as P, type AuthTokenStorage as a, type AuthKeyValueStorage as b, type AuthDeviceIdentityProvider as c, AuthClient as d, type AuthState as e, type AuthDeviceIdentity as f, AuthDeviceIdentityError as g, AuthError as h, type AuthTokenStorageOptions as i, type AuthUser as j, type ClientMembership as k, type ClientOrganization as l, DeviceKeyStoreError as m, IndexedDBDeviceKeyStore as n, type OAuthAuthorizationResult as o, type OAuthCallbackParams as p, OrgClient as q, type OrgClientConfig as r, OrgClientError as s, createAuthTokenStorage as t, createDeviceKeyStore as u, createMemoryAuthTokenStorage as v, createPersistentDeviceIdentity as w, createWebStorageAuthTokenStorage as x };

package/dist/{password-hash-HDH6VQCQ.js → password-hash-QRBG6BNJ.js}

@@ -1,9 +1,9 @@
 import {
   hashPassword,
   verifyPassword
-} from "./chunk-HOZXDR6Y.js";
+} from "./chunk-L7GXPS74.js";
 export {
   hashPassword,
   verifyPassword
 };
-//# sourceMappingURL=password-hash-HDH6VQCQ.js.map
+//# sourceMappingURL=password-hash-QRBG6BNJ.js.map