Passman Client TS

A TypeScript based Passman client library for web frontends, browser extensions (including Manifest V3), and Node/JavaScript projects connecting to a Passman server.

This is currently under development, do not use in productive! Things should break :D

Notes about PassmanClient initialization workflow and caching

• Create a PassmanClient instance as data and API (connection) manager to the Passman server.
  • Providing a PersistenceInterface (e.g. IndexedDbPersistenceService or a custom override of DefaultPersistenceService) configures reconstruction from persisted model data.
• Preload available vaults with passmanClient.preloadVaults() for a vault list and vault-password checks.
  • Preloaded vaults only contain metadata (no credentials / mutation APIs).
• Call preloadedVault.testVaultKey('myPassword123') for one of passmanClient.preloadedVaults.
• After the vault key is validated, load the full vault (including credentials) via Vault.fetchFullVaultFromServer(...).

The primary persistence path is the model store (PersistenceInterface.getModelStore(), default: IndexedDbModelStore via IndexedDbPersistenceService). It stores encrypted serializable vault/credential DTOs and supports incremental single-credential writes. The legacy but deprecated request-cache (getRequestCacheHandler()) remains for compatibility only.

Credential decrypted data can still be cached by providing a custom DecryptedDataCachingHandlerInterface implementation. Useful to avoid re-decrypting the same data multiple times.

Persistence / How to use IndexedDbPersistenceService

You can use IndexedDbPersistenceService in any project, but it is especially useful in the service worker (IndexedDB is available in MV3 backgrounds):

import { PassmanClient } from '@binsky/passman-client-ts';
import { IndexedDbPersistenceService } from '@binsky/passman-client-ts/lib/Service/IndexedDbPersistenceService';

const persistence = new IndexedDbPersistenceService({
  autoRestoreOnReconstruction: true
});

const client = await PassmanClient.createInstance(
  {
    baseUrl: 'https://cloud.example.com',
    user: 'alice',
    token: 'app-password-or-token',
    persistence: ''
  },
  undefined,
  undefined,
  persistence
);

await client.preloadVaults();

Package builds (CJS + ESM)

npm run build emits:

| Format | Output | Package field | |--------|--------|---------------| | CommonJS | lib/ | main / exports.require | | ESM | lib/esm/ | module / exports.import |

Types stay in lib/**/*.d.ts (shared). Bundlers (like webpack, rollup, vite, esbuild, etc.) typically pick the ESM build via module / exports.import. Deep imports under @binsky/passman-client-ts/lib/... remain supported through the exports["./lib/*"] map.

Manifest V3 (service worker) wiring

The core client path is safe to run in an MV3 service worker: fetch, Web Crypto, and IndexedDB work there. UI-only helpers that need a DOM (DownloadService.download, OTPService QR canvas/parse) are guarded and throw a clear error if called without document — call them from a page, popup, or offscreen document instead (or use Credential.downloadFile(..., false) / OTPService.updateOTP).