dsh-vault 0.3.0 → 0.5.0

package/lib/store.js

@@ -57,10 +57,55 @@ export class VaultStore {
      * contend for the cross-process file lock and every write sees the latest
      * in-memory state. */
     persistChain = Promise.resolve();
+    /** Auto-lock: after this many ms of inactivity the vault re-locks (key
+     * wiped). `0`/undefined disables auto-lock. */
+    lockTimeoutMs;
+    /** Epoch millis of the last operation; used for the auto-lock timer. */
+    lastActivity = Date.now();
+    /** Whether the vault is currently locked (key wiped, requires re-unlock). */
+    locked = false;
+    /** Weak-password heuristic: too short or in a tiny common list. */
+    static MIN_PASSWORD_LENGTH = 12;
     constructor(path, masterPassword) {
         this.path = path;
         this.masterPassword = masterPassword;
     }
+    /** Enable auto-lock with the given idle timeout (ms). */
+    setAutoLock(timeoutMs) {
+        this.lockTimeoutMs = timeoutMs;
+        this.lastActivity = Date.now();
+    }
+    /** Whether the vault is currently locked. */
+    get isLocked() {
+        return this.locked;
+    }
+    /** Touch the activity timestamp; call before every read/write. */
+    touch() {
+        this.lastActivity = Date.now();
+    }
+    /** Whether the auto-lock idle window has elapsed. */
+    get expired() {
+        if (this.lockTimeoutMs === undefined || this.lockTimeoutMs <= 0)
+            return false;
+        return Date.now() - this.lastActivity > this.lockTimeoutMs;
+    }
+    /** Lock the vault: wipe the derived key and require re-unlock. */
+    lock() {
+        this.key?.fill(0);
+        this.key = undefined;
+        this.locked = true;
+        this.lastActivity = Date.now();
+    }
+    /** Re-derive the key from the master password (after a lock). */
+    async unlock() {
+        if (this.kdf === undefined) {
+            await this.load();
+            return;
+        }
+        this.key = await deriveKey(this.masterPassword, this.kdf);
+        this.locked = false;
+        this.lastActivity = Date.now();
+    }
     /**
      * Load the vault document from disk (creating an empty one on first use)
      * and derive the vault key from the document's fixed KDF parameters.
@@ -79,6 +124,8 @@ export class VaultStore {
             // First run: persist the empty document so the file exists with the
             // chosen KDF (and its verify envelope) before any entry is added.
             await this.persist();
+            this.locked = false;
+            this.lastActivity = Date.now();
             return;
         }
         for (const blob of file.entries) {
@@ -91,29 +138,41 @@ export class VaultStore {
         if (!safeEqual(verify, Buffer.from(VERIFY_PLAINTEXT, 'utf8'))) {
             throw new Error('vault master password is incorrect');
         }
+        this.locked = false;
+        this.lastActivity = Date.now();
     }
     /** The vault file path (useful for messages and debugging). */
     get filePath() {
         return this.path;
     }
-    /** All entries, in insertion order. */
+    /** All active (non-trashed) entries, in insertion order. */
     list() {
-        return [...this.entries.values()];
+        return [...this.entries.values()].filter(entry => entry.deletedAt === undefined);
+    }
+    /** All trashed entries (soft-deleted, awaiting purge or restore). */
+    listTrash() {
+        return [...this.entries.values()].filter(entry => entry.deletedAt !== undefined);
     }
-    /** Read one entry by id. */
+    /** Read one active entry by id. */
     get(id) {
+        const entry = this.entries.get(id);
+        return entry !== undefined && entry.deletedAt === undefined ? entry : undefined;
+    }
+    /** Read one entry by id, including trashed entries. */
+    getIncludingTrash(id) {
         return this.entries.get(id);
     }
-    /** Search entries across text fields; returns summaries without secrets. */
+    /** Search entries across text fields; returns summaries without secrets.
+     * Multiple whitespace-separated terms match when ANY term hits (OR). */
     search(query, limit = 20) {
-        const needle = query.trim().toLowerCase();
-        if (needle.length === 0)
+        const terms = query.trim().toLowerCase().split(/\s+/).filter(Boolean);
+        if (terms.length === 0)
             return [];
         const results = [];
         for (const entry of this.list()) {
             if (results.length >= limit)
                 break;
-            if (matches(entry, needle))
+            if (terms.some(term => matches(entry, term)))
                 results.push(toSummary(entry));
         }
         return results;
@@ -134,6 +193,10 @@ export class VaultStore {
         await this.persist();
         return entry;
     }
+    /** Insert an entry directly (used by bulk import); caller owns timestamps. */
+    insertDirect(entry) {
+        this.entries.set(entry.id, entry);
+    }
     /** Update an existing entry's fields; returns the updated entry or undefined.
      * Every defined field in `patch` replaces the stored value; an empty string
      * clears (removes) that field. `id`/`createdAt` can never change. */
@@ -163,8 +226,27 @@ export class VaultStore {
         await this.persist();
         return updated;
     }
-    /** Delete an entry; returns true when it existed. */
+    /** Soft-delete an entry (move to trash); returns true when it existed.
+     * The entry stays encrypted on disk until purged or restored. */
     async delete(id) {
+        const entry = this.entries.get(id);
+        if (!entry || entry.deletedAt !== undefined)
+            return false;
+        entry.deletedAt = Date.now();
+        await this.persist();
+        return true;
+    }
+    /** Restore a trashed entry; returns true when it existed in trash. */
+    async restore(id) {
+        const entry = this.entries.get(id);
+        if (!entry || entry.deletedAt === undefined)
+            return false;
+        delete entry.deletedAt;
+        await this.persist();
+        return true;
+    }
+    /** Permanently remove a trashed (or active) entry; returns true when it existed. */
+    async purge(id) {
         const existed = this.entries.delete(id);
         if (existed)
             await this.persist();
@@ -178,6 +260,128 @@ export class VaultStore {
     get unlocked() {
         return this.key !== undefined;
     }
+    /**
+     * Rotation & expiry report: entries whose `rotationDays` elapsed since
+     * their last update, or whose `expiresAt` is near/past. Returns only
+     * summaries plus the computed due state (no secrets).
+     */
+    rotationReport(now = Date.now()) {
+        const report = [];
+        for (const entry of this.list()) {
+            const base = entry.updatedAt ?? entry.createdAt;
+            const rotationAt = entry.rotationDays !== undefined ? base + entry.rotationDays * 86_400_000 : undefined;
+            const expiresAt = entry.expiresAt;
+            let due;
+            let daysLeft;
+            if (rotationAt !== undefined && now >= rotationAt) {
+                due = 'due';
+                daysLeft = 0;
+            }
+            else if (expiresAt !== undefined && now >= expiresAt) {
+                due = 'expired';
+                daysLeft = 0;
+            }
+            else if (expiresAt !== undefined) {
+                daysLeft = Math.ceil((expiresAt - now) / 86_400_000);
+                if (daysLeft <= 7) {
+                    due = 'soon';
+                }
+            }
+            else if (rotationAt !== undefined) {
+                daysLeft = Math.ceil((rotationAt - now) / 86_400_000);
+                if (daysLeft <= 7) {
+                    due = 'soon';
+                }
+            }
+            else {
+                continue;
+            }
+            if (due === undefined)
+                continue;
+            report.push({ ...toSummary(entry), due, daysLeft });
+        }
+        return report;
+    }
+    /**
+     * Health scan: weak passwords (too short), and passwords/API keys reused
+     * across entries. Returns non-secret findings keyed by entry id.
+     */
+    health() {
+        const weak = [];
+        const passwordCounts = new Map();
+        const keyCounts = new Map();
+        for (const entry of this.list()) {
+            const summary = toSummary(entry);
+            if (entry.password !== undefined) {
+                if (entry.password.length < VaultStore.MIN_PASSWORD_LENGTH)
+                    weak.push(summary);
+                const list = passwordCounts.get(entry.password) ?? [];
+                list.push(summary);
+                passwordCounts.set(entry.password, list);
+            }
+            for (const key of [entry.apiKey, entry.accessToken, entry.refreshToken, entry.secret]) {
+                if (key === undefined)
+                    continue;
+                const list = keyCounts.get(key) ?? [];
+                list.push(summary);
+                keyCounts.set(key, list);
+            }
+        }
+        const reused = [
+            ...[...passwordCounts.entries()].filter(([, v]) => v.length > 1),
+            ...[...keyCounts.entries()].filter(([, v]) => v.length > 1),
+        ].map(([value, entries]) => ({ value, entries }));
+        return { weak, reused };
+    }
+    /**
+     * Export the whole vault (including trash) as a single encrypted blob under
+     * a separate export password: a portable, machine-independent document that
+     * can be re-imported elsewhere. Returns the armored JSON string.
+     */
+    async exportEncrypted(exportPassword, now = Date.now()) {
+        if (exportPassword.length === 0)
+            throw new Error('vault: export password must not be empty');
+        const exportKdf = newKdfParams();
+        const exportKey = await deriveKey(exportPassword, exportKdf);
+        const payload = {
+            exportedAt: now,
+            kdf: exportKdf,
+            entries: [...this.entries.values()].map(entry => ({
+                id: entry.id,
+                ...encrypt(Buffer.from(JSON.stringify(entry), 'utf8'), exportKey),
+            })),
+        };
+        exportKey.fill(0);
+        return JSON.stringify(payload);
+    }
+    /**
+     * Import an exported vault blob, merging entries by id (existing entries win
+     * unless `overwrite`). Returns the number of entries added.
+     */
+    async importEncrypted(blob, exportPassword, overwrite = false) {
+        if (exportPassword.length === 0)
+            throw new Error('vault: export password must not be empty');
+        const parsed = JSON.parse(blob);
+        if (!parsed.kdf || !Array.isArray(parsed.entries)) {
+            throw new Error('vault: invalid export document');
+        }
+        const exportKey = await deriveKey(exportPassword, parsed.kdf);
+        let added = 0;
+        for (const blobEntry of parsed.entries) {
+            const plaintext = decrypt(blobEntry, exportKey);
+            const entry = JSON.parse(plaintext.toString('utf8'));
+            const existing = this.entries.get(entry.id);
+            if (existing !== undefined && !overwrite)
+                continue;
+            // Imported entries come back as active (clear any soft-delete marker).
+            const { deletedAt, ...active } = entry;
+            this.entries.set(entry.id, { ...active, updatedAt: Date.now() });
+            added++;
+        }
+        exportKey.fill(0);
+        await this.persist();
+        return added;
+    }
     /**
      * Persist the current in-memory state: encrypt every entry under the vault
      * key, then atomically replace the document under the cross-process lock.
@@ -187,7 +391,40 @@ export class VaultStore {
      * The derived key is cached after load and reused, so a mutation does not
      * re-run scrypt; only a fresh vault (no cached key yet) derives once.
      */
-    persist() {
+    /**
+     * Re-key the vault with fresh scrypt KDF parameters (cost upgrade): derive a
+     * new key from the master password under `newKdfParams()` and re-encrypt
+     * every entry under it, atomically. The old key buffer is wiped. Returns the
+     * new cost parameter `n` for reporting.
+     */
+    async rekey() {
+        if (this.key === undefined) {
+            await this.load();
+        }
+        const newKdf = newKdfParams();
+        const newKey = await deriveKey(this.masterPassword, newKdf);
+        // Encrypt every entry under the new key first (in memory), so a failure
+        // mid-encrypt leaves the on-disk document untouched.
+        const reEncrypted = [...this.entries.values()].map(entry => ({
+            id: entry.id,
+            ...encrypt(Buffer.from(JSON.stringify(entry), 'utf8'), newKey),
+        }));
+        await mkdir(dirname(this.path), { recursive: true, mode: 0o700 });
+        await withFileLock(this.path, async () => {
+            const file = {
+                version: VAULT_FORMAT_VERSION,
+                kdf: newKdf,
+                verify: encrypt(Buffer.from(VERIFY_PLAINTEXT, 'utf8'), newKey),
+                entries: reEncrypted,
+            };
+            await writeFileAtomic(this.path, JSON.stringify(file), { mode: 0o600, dirMode: 0o700 });
+        });
+        this.kdf = newKdf;
+        this.key?.fill(0);
+        this.key = newKey;
+        return { n: newKdf.n };
+    }
+    async persist() {
         const run = async () => {
             const kdf = this.kdf ?? newKdfParams();
             this.kdf = kdf;
@@ -289,6 +526,7 @@ function toSummary(entry) {
     return {
         id: entry.id,
         title: entry.title,
+        ...(entry.sensitivity !== undefined ? { sensitivity: entry.sensitivity } : {}),
         ...(entry.kind !== undefined ? { kind: entry.kind } : {}),
         ...(entry.username !== undefined ? { username: entry.username } : {}),
         ...(entry.email !== undefined ? { email: entry.email } : {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-vault",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Encrypted credential vault for DeepSeek Harness: store and retrieve usernames, emails, phone numbers, passwords, TOTP secrets, SSH/API-key/OAuth developer credentials through model tools and a Settings UI page.",
   "type": "module",
   "license": "MIT",