Skip to main content

@idpass/data-collect-core / IndexedDbAuthStorageAdapter

Class: IndexedDbAuthStorageAdapter

Defined in: storage/IndexedDbAuthStorageAdapter.ts:119

IndexedDB implementation of the AuthStorageAdapter for browser-based authentication token persistence.

This adapter provides secure, offline-first storage of authentication tokens using the browser's IndexedDB API. It implements the full AuthStorageAdapter interface with proper token management and multi-tenant support.

Key features:

  • Secure Token Storage: Stores authentication tokens locally in the browser using IndexedDB.
  • Multi-Tenant Support: Isolated token storage per tenant using tenant ID prefixes.
  • Token Lifecycle Management: Handles token storage, retrieval, and removal operations.
  • Offline Capability: Tokens persist across browser sessions and offline scenarios.
  • Privacy-First: Tokens are stored locally and not transmitted to external servers.

Architecture:

  • Uses IndexedDB object store with token as the primary data.
  • Implements proper error handling for IndexedDB operations.
  • Provides ACID transaction support for data consistency.
  • Supports both single and multi-tenant deployments.

Security Considerations:

  • Tokens are stored in the browser's IndexedDB, which is subject to browser security policies.
  • Tokens persist until explicitly removed or browser data is cleared.
  • Consider implementing token encryption for additional security if required.

Examples​

Basic usage:

const adapter = new IndexedDbAuthStorageAdapter('tenant-123');
await adapter.initialize();

// Store authentication token
await adapter.setToken('eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...');

// Retrieve token for API calls
const token = await adapter.getToken();
if (token) {
  // Use token for authenticated requests
  const response = await fetch('/api/data', {
    headers: { 'Authorization': `Bearer ${token}` }
  });
}

// Remove token on logout
await adapter.removeToken();

Multi-tenant setup:

// Tenant-specific adapter
const tenantAdapter = new IndexedDbAuthStorageAdapter('org-xyz');
await tenantAdapter.initialize(); // Creates database: authStore_org-xyz

// Default adapter
const defaultAdapter = new IndexedDbAuthStorageAdapter();
await defaultAdapter.initialize(); // Creates database: authStore

Authentication flow integration:

class AuthManager {
  private storage: IndexedDbAuthStorageAdapter;

  constructor(tenantId: string) {
    this.storage = new IndexedDbAuthStorageAdapter(tenantId);
  }

  async initialize() {
    await this.storage.initialize();
  }

  async login(credentials: PasswordCredentials) {
    // Authenticate with server
    const response = await fetch('/auth/login', {
      method: 'POST',
      body: JSON.stringify(credentials)
    });

    const { token } = await response.json();

    // Store token locally
    await this.storage.setToken(token);
  }

  async logout() {
    // Remove token from local storage
    await this.storage.removeToken();
  }

  async isAuthenticated(): Promise<boolean> {
    const token = await this.storage.getToken();
    return !!token;
  }
}

Implements​

Constructors​

Constructor​

new IndexedDbAuthStorageAdapter(tenantId): IndexedDbAuthStorageAdapter

Defined in: storage/IndexedDbAuthStorageAdapter.ts:139

Creates a new IndexedDbAuthStorageAdapter instance.

Parameters​

tenantId​

string = ""

Optional tenant identifier for multi-tenant isolation. When provided, creates a separate database prefixed with tenant ID.

Returns​

IndexedDbAuthStorageAdapter

Example​

// Default database (authStore)
const adapter = new IndexedDbAuthStorageAdapter();

// Tenant-specific database (authStore_org-123)
const tenantAdapter = new IndexedDbAuthStorageAdapter('org-123');

Properties​

tenantId​

readonly tenantId: string = ""

Defined in: storage/IndexedDbAuthStorageAdapter.ts:139

Optional tenant identifier for multi-tenant isolation. When provided, creates a separate database prefixed with tenant ID.

Methods​

getUsername()​

getUsername(): Promise<string>

Defined in: storage/IndexedDbAuthStorageAdapter.ts:150

Retrieves the stored username.

Returns​

Promise<string>

The stored username, or an empty string if no username exists.

Implementation of​

AuthStorageAdapter.getUsername

getToken()​

getToken(): Promise<{ provider: string; token: string; } | null>

Defined in: storage/IndexedDbAuthStorageAdapter.ts:178

Retrieves the first available authentication token.

Returns​

Promise<{ provider: string; token: string; } | null>

The first available token with provider information, or null if no tokens exist.

Implementation of​

AuthStorageAdapter.getToken

removeAllTokens()​

removeAllTokens(): Promise<void>

Defined in: storage/IndexedDbAuthStorageAdapter.ts:217

Removes all stored authentication tokens from IndexedDB.

Returns​

Promise<void>

A Promise that resolves when all tokens are removed.

Throws​

When IndexedDB is not initialized or token removal fails.

Implementation of​

AuthStorageAdapter.removeAllTokens

closeConnection()​

closeConnection(): Promise<void>

Defined in: storage/IndexedDbAuthStorageAdapter.ts:247

Closes the IndexedDB connection and cleans up resources.

For IndexedDB, connections are automatically managed by the browser, so this method is a no-op but maintained for interface compatibility.

Returns​

Promise<void>

A Promise that resolves when the connection is closed.

Implementation of​

AuthStorageAdapter.closeConnection

initialize()​

initialize(): Promise<void>

Defined in: storage/IndexedDbAuthStorageAdapter.ts:264

Initializes the IndexedDB database with required object stores for token storage.

Returns​

Promise<void>

A Promise that resolves when the database is initialized.

Throws​

When IndexedDB is not supported or database creation fails.

Example​

const adapter = new IndexedDbAuthStorageAdapter('tenant-123');
await adapter.initialize();
// Now ready for token operations

Implementation of​

AuthStorageAdapter.initialize

getTokenByProvider()​

getTokenByProvider(provider): Promise<string>

Defined in: storage/IndexedDbAuthStorageAdapter.ts:294

Retrieves a stored authentication token by key.

Parameters​

provider​

string = "current_token"

The provider name identifying the token to retrieve.

Returns​

Promise<string>

The stored authentication token, or an empty string if not found.

Implementation of​

AuthStorageAdapter.getTokenByProvider

setUsername()​

setUsername(username): Promise<void>

Defined in: storage/IndexedDbAuthStorageAdapter.ts:333

Stores a username in IndexedDB.

Parameters​

username​

string

The username to store.

Returns​

Promise<void>

A Promise that resolves when the username is stored.

Throws​

When IndexedDB is not initialized, invalid parameters provided, or username storage fails.

Example​

// Store username (replaces any existing username)
await adapter.setUsername('john.doe@example.com');

// Store a different username (replaces the previous one)
await adapter.setUsername('jane.smith@example.com');

Implementation of​

AuthStorageAdapter.setUsername

setToken()​

setToken(key, token): Promise<void>

Defined in: storage/IndexedDbAuthStorageAdapter.ts:371

Stores an authentication token with a specific key in IndexedDB.

Parameters​

key​

string

The key to associate with the token.

token​

string

The authentication token to store (JWT, Bearer token, etc.).

Returns​

Promise<void>

A Promise that resolves when the token is stored.

Throws​

When IndexedDB is not initialized or token storage fails.

Implementation of​

AuthStorageAdapter.setToken

removeToken()​

removeToken(key): Promise<void>

Defined in: storage/IndexedDbAuthStorageAdapter.ts:412

Removes a specific authentication token by key from IndexedDB.

Parameters​

key​

string

The key identifying the token to remove.

Returns​

Promise<void>

A Promise that resolves when the token is removed.

Throws​

When IndexedDB is not initialized or token removal fails.

Implementation of​

AuthStorageAdapter.removeToken

clearStore()​

clearStore(): Promise<void>

Defined in: storage/IndexedDbAuthStorageAdapter.ts:452

Clears all authentication data from the store.

⚠️ WARNING: This permanently deletes all stored tokens! Only use for testing or when intentionally clearing all authentication data.

Returns​

Promise<void>

A Promise that resolves when the store is cleared.

Throws​

When IndexedDB is not initialized or clear operation fails.

Example​

// For testing environments only
if (process.env.NODE_ENV === 'test') {
  await adapter.clearStore();
  console.log('Authentication data cleared for testing');
}

Implementation of​

AuthStorageAdapter.clearStore