@icoretech/warden-mcp 0.1.0

package/dist/sdk/keychainSdk.js

@@ -0,0 +1,1225 @@
+// src/sdk/keychainSdk.ts
+import { mkdtemp, readdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
+import { BwCliError } from '../bw/bwCli.js';
+import { buildBwGenerateArgs } from './generateArgs.js';
+import { applyItemPatch } from './patch.js';
+import { redactItem } from './redact.js';
+import { generateUsername } from './usernameGenerator.js';
+const ITEM_TYPE = {
+    login: 1,
+    note: 2,
+    card: 3,
+    identity: 4,
+};
+const URI_MATCH = {
+    domain: 0,
+    host: 1,
+    startsWith: 2,
+    exact: 3,
+    regex: 4,
+    never: 5,
+};
+const URI_MATCH_REVERSE = {
+    0: 'domain',
+    1: 'host',
+    2: 'startsWith',
+    3: 'exact',
+    4: 'regex',
+    5: 'never',
+};
+function deepClone(obj) {
+    return JSON.parse(JSON.stringify(obj));
+}
+function encodeJsonForBw(value) {
+    return Buffer.from(JSON.stringify(value), 'utf8').toString('base64');
+}
+function normalizeFields(fields) {
+    if (!fields)
+        return undefined;
+    return fields.map((f) => ({
+        name: f.name,
+        value: f.value,
+        // Bitwarden uses numeric "type" for custom fields:
+        // 0 = text, 1 = hidden.
+        type: f.hidden ? 1 : 0,
+    }));
+}
+function normalizeUris(uris) {
+    if (!uris)
+        return undefined;
+    return uris.map((u) => ({
+        uri: u.uri,
+        match: u.match ? URI_MATCH[u.match] : null,
+    }));
+}
+function denormalizeUris(raw) {
+    if (!Array.isArray(raw))
+        return undefined;
+    const out = [];
+    for (const u of raw) {
+        if (!u || typeof u !== 'object')
+            continue;
+        const rec = u;
+        const uri = rec.uri;
+        if (typeof uri !== 'string' || uri.length === 0)
+            continue;
+        const match = typeof rec.match === 'number' ? URI_MATCH_REVERSE[rec.match] : undefined;
+        out.push({ uri, match });
+    }
+    return out;
+}
+function kindFromItem(item) {
+    const type = item.type;
+    if (type === ITEM_TYPE.login)
+        return 'login';
+    if (type === ITEM_TYPE.card)
+        return 'card';
+    if (type === ITEM_TYPE.identity)
+        return 'identity';
+    if (type === ITEM_TYPE.note)
+        return isSshKeyItem(item) ? 'ssh_key' : 'note';
+    return 'note';
+}
+function isSshKeyItem(item) {
+    if (item.type !== ITEM_TYPE.note)
+        return false;
+    const fields = item.fields;
+    if (!Array.isArray(fields))
+        return false;
+    const names = new Set(fields
+        .map((f) => (f && typeof f === 'object' ? f.name : null))
+        .filter((n) => typeof n === 'string'));
+    return names.has('public_key') && names.has('private_key');
+}
+export class KeychainSdk {
+    bw;
+    constructor(bw) {
+        this.bw = bw;
+    }
+    async createLoginForSession(session, input) {
+        const tpl = (await this.bw.getTemplateItemForSession(session));
+        const item = deepClone(tpl);
+        item.type = ITEM_TYPE.login;
+        item.name = input.name;
+        item.notes = input.notes ?? '';
+        item.favorite = input.favorite ?? false;
+        if (input.organizationId)
+            item.organizationId = input.organizationId;
+        if (input.folderId)
+            item.folderId = input.folderId;
+        item.fields = normalizeFields(input.fields) ?? [];
+        const login = (item.login && typeof item.login === 'object'
+            ? item.login
+            : {});
+        if (input.username !== undefined)
+            login.username = input.username;
+        if (input.password !== undefined)
+            login.password = input.password;
+        if (input.totp !== undefined)
+            login.totp = input.totp;
+        if (input.uris !== undefined)
+            login.uris = normalizeUris(input.uris);
+        item.login = login;
+        // Set collectionIds optimistically; we'll also enforce with item-collections edit.
+        if (input.collectionIds)
+            item.collectionIds = input.collectionIds;
+        const encoded = encodeJsonForBw(item);
+        const { stdout } = await this.bw.runForSession(session, ['create', 'item', encoded], { timeoutMs: 120_000 });
+        const created = JSON.parse(stdout);
+        if (input.attachments?.length) {
+            const dir = await mkdtemp(join(tmpdir(), 'keychain-attach-'));
+            try {
+                for (const att of input.attachments) {
+                    const safeBase = basename(att.filename || 'attachment.bin').replace(/[^A-Za-z0-9._-]+/g, '_');
+                    const safeName = safeBase.length > 0 ? safeBase : 'attachment.bin';
+                    const p = join(dir, safeName);
+                    await writeFile(p, Buffer.from(att.contentBase64, 'base64'));
+                    const { stdout: attOut } = await this.bw.runForSession(session, [
+                        'create',
+                        'attachment',
+                        '--file',
+                        p,
+                        '--itemid',
+                        String(created.id),
+                    ], { timeoutMs: 120_000 });
+                    // IMPORTANT: bw may return the full item JSON (including secrets) here.
+                    // Never parse or include it in our response.
+                    void attOut;
+                }
+            }
+            finally {
+                await rm(dir, { recursive: true, force: true });
+            }
+        }
+        if (input.collectionIds?.length) {
+            const encodedCols = encodeJsonForBw(input.collectionIds);
+            await this.bw
+                .runForSession(session, ['edit', 'item-collections', String(created.id), encodedCols], { timeoutMs: 120_000 })
+                .catch(() => { });
+        }
+        // Refetch so attachments metadata is accurate, but redact secrets by default.
+        const { stdout: gotOut } = await this.bw.runForSession(session, ['get', 'item', String(created.id)], { timeoutMs: 60_000 });
+        const got = JSON.parse(gotOut);
+        return this.maybeRedact(got, input.reveal);
+    }
+    syncOnWrite() {
+        return ((process.env.KEYCHAIN_SYNC_ON_WRITE ?? 'true').toLowerCase() === 'true');
+    }
+    maybeRedact(value, reveal) {
+        return (reveal ? value : redactItem(value));
+    }
+    valueResult(value, revealed) {
+        return { value, revealed };
+    }
+    tryParseJson(stdout) {
+        const trimmed = stdout.trim();
+        if (!trimmed)
+            return '';
+        try {
+            return JSON.parse(trimmed);
+        }
+        catch {
+            return trimmed;
+        }
+    }
+    async readSingleFileAsBase64(dir) {
+        const files = await readdir(dir);
+        if (files.length !== 1) {
+            throw new Error(`Expected exactly 1 downloaded file, found ${files.length}`);
+        }
+        const filename = files[0] ?? '';
+        const buf = await readFile(join(dir, filename));
+        return {
+            filename,
+            bytes: buf.byteLength,
+            contentBase64: buf.toString('base64'),
+        };
+    }
+    redactPasswordHistoryForTool(history) {
+        // For secret-returning tools we avoid returning sentinel strings like "[REDACTED]"
+        // because downstream utilities might accidentally pass them through.
+        return history.map((h) => {
+            if (!h || typeof h !== 'object')
+                return h;
+            const rec = { ...h };
+            if (typeof rec.password === 'string')
+                rec.password = null;
+            return rec;
+        });
+    }
+    async status() {
+        return this.bw.status();
+    }
+    async encode(input) {
+        // `bw encode` base64-encodes stdin.
+        const { stdout } = await this.bw.withSession(async (session) => {
+            return this.bw.runForSession(session, ['encode'], {
+                stdin: `${input.value}\n`,
+                timeoutMs: 30_000,
+            });
+        });
+        return { encoded: stdout.trim() };
+    }
+    async generate(input = {}) {
+        if (!input.reveal)
+            return this.valueResult(null, false);
+        const args = buildBwGenerateArgs(input);
+        const { stdout } = await this.bw.withSession(async (session) => this.bw.runForSession(session, args, { timeoutMs: 30_000 }));
+        return this.valueResult(stdout.trim(), true);
+    }
+    async generateUsername(input = {}) {
+        if (!input.reveal)
+            return this.valueResult(null, false);
+        const value = generateUsername(input);
+        return this.valueResult(value, true);
+    }
+    async getAttachment(input) {
+        return this.bw.withSession(async (session) => {
+            const dir = await mkdtemp(join(tmpdir(), 'keychain-attachment-'));
+            try {
+                await this.bw.runForSession(session, [
+                    'get',
+                    'attachment',
+                    input.attachmentId,
+                    '--itemid',
+                    input.itemId,
+                    '--output',
+                    dir,
+                ], { timeoutMs: 120_000 });
+                return await this.readSingleFileAsBase64(dir);
+            }
+            finally {
+                await rm(dir, { recursive: true, force: true });
+            }
+        });
+    }
+    async sendList() {
+        return this.bw.withSession(async (session) => {
+            const { stdout } = await this.bw.runForSession(session, ['send', 'list'], {
+                timeoutMs: 60_000,
+            });
+            return this.tryParseJson(stdout);
+        });
+    }
+    async sendTemplate(input) {
+        return this.bw.withSession(async (session) => {
+            const { stdout } = await this.bw.runForSession(session, ['send', 'template', input.object], { timeoutMs: 60_000 });
+            return this.tryParseJson(stdout);
+        });
+    }
+    async sendGet(input) {
+        return this.bw.withSession(async (session) => {
+            if (input.text) {
+                const { stdout } = await this.bw.runForSession(session, ['--raw', 'send', 'get', input.id, '--text'], { timeoutMs: 60_000 });
+                return { text: stdout.trim() };
+            }
+            if (input.downloadFile) {
+                const dir = await mkdtemp(join(tmpdir(), 'keychain-sendfile-'));
+                try {
+                    await this.bw.runForSession(session, ['send', 'get', input.id, '--output', dir], { timeoutMs: 120_000 });
+                    const file = await this.readSingleFileAsBase64(dir);
+                    return { file };
+                }
+                finally {
+                    await rm(dir, { recursive: true, force: true });
+                }
+            }
+            const { stdout } = await this.bw.runForSession(session, ['send', 'get', input.id], {
+                timeoutMs: 60_000,
+            });
+            return this.tryParseJson(stdout);
+        });
+    }
+    async sendRemovePassword(input) {
+        return this.bw.withSession(async (session) => {
+            const { stdout } = await this.bw.runForSession(session, ['send', 'remove-password', input.id], { timeoutMs: 60_000 });
+            return this.tryParseJson(stdout);
+        });
+    }
+    async sendDelete(input) {
+        return this.bw.withSession(async (session) => {
+            const { stdout } = await this.bw.runForSession(session, ['send', 'delete', input.id], {
+                timeoutMs: 60_000,
+            });
+            return this.tryParseJson(stdout);
+        });
+    }
+    async sendCreate(input) {
+        return this.bw.withSession(async (session) => {
+            const args = ['send'];
+            if (input.type === 'file')
+                args.push('--file');
+            if (typeof input.deleteInDays === 'number')
+                args.push('--deleteInDays', String(input.deleteInDays));
+            if (typeof input.password === 'string')
+                args.push('--password', input.password);
+            if (typeof input.maxAccessCount === 'number')
+                args.push('--maxAccessCount', String(input.maxAccessCount));
+            if (input.hidden)
+                args.push('--hidden');
+            if (typeof input.name === 'string')
+                args.push('--name', input.name);
+            if (typeof input.notes === 'string')
+                args.push('--notes', input.notes);
+            if (input.fullObject)
+                args.push('--fullObject');
+            if (input.type === 'text') {
+                if (typeof input.text !== 'string')
+                    throw new Error('Missing text for text send');
+                const { stdout } = await this.bw.runForSession(session, ['--raw', ...args, input.text], { timeoutMs: 60_000 });
+                return this.tryParseJson(stdout);
+            }
+            if (typeof input.filename !== 'string' ||
+                typeof input.contentBase64 !== 'string') {
+                throw new Error('Missing filename/contentBase64 for file send');
+            }
+            const dir = await mkdtemp(join(tmpdir(), 'keychain-send-create-'));
+            const filePath = join(dir, basename(input.filename));
+            try {
+                await writeFile(filePath, Buffer.from(input.contentBase64, 'base64'));
+                const { stdout } = await this.bw.runForSession(session, ['--raw', ...args, filePath], { timeoutMs: 120_000 });
+                return this.tryParseJson(stdout);
+            }
+            finally {
+                await rm(dir, { recursive: true, force: true });
+            }
+        });
+    }
+    async sendCreateEncoded(input) {
+        return this.bw.withSession(async (session) => {
+            let encodedJson = input.encodedJson;
+            if (!encodedJson && typeof input.json !== 'undefined') {
+                const enc = await this.encode({ value: JSON.stringify(input.json) });
+                encodedJson = enc.encoded;
+            }
+            if (typeof encodedJson !== 'string' &&
+                typeof input.text !== 'string' &&
+                typeof input.file === 'undefined') {
+                throw new Error('sendCreateEncoded requires one of: encodedJson, json, text, or file');
+            }
+            const args = ['send', 'create'];
+            if (typeof input.text === 'string')
+                args.push('--text', input.text);
+            if (input.hidden)
+                args.push('--hidden');
+            let dir = null;
+            try {
+                if (input.file) {
+                    dir = await mkdtemp(join(tmpdir(), 'keychain-send-create-'));
+                    const filePath = join(dir, basename(input.file.filename));
+                    await writeFile(filePath, Buffer.from(input.file.contentBase64, 'base64'));
+                    args.push('--file', filePath);
+                }
+                if (typeof encodedJson === 'string')
+                    args.push(encodedJson);
+                const { stdout } = await this.bw.runForSession(session, args, {
+                    timeoutMs: 120_000,
+                });
+                return this.tryParseJson(stdout);
+            }
+            finally {
+                if (dir)
+                    await rm(dir, { recursive: true, force: true });
+            }
+        });
+    }
+    async sendEdit(input) {
+        return this.bw.withSession(async (session) => {
+            let encodedJson = input.encodedJson;
+            if (!encodedJson && typeof input.json !== 'undefined') {
+                const enc = await this.encode({ value: JSON.stringify(input.json) });
+                encodedJson = enc.encoded;
+            }
+            if (typeof encodedJson !== 'string') {
+                throw new Error('sendEdit requires encodedJson or json');
+            }
+            const args = ['send', 'edit'];
+            if (typeof input.itemId === 'string')
+                args.push('--itemid', input.itemId);
+            args.push(encodedJson);
+            const { stdout } = await this.bw.runForSession(session, args, {
+                timeoutMs: 120_000,
+            });
+            return this.tryParseJson(stdout);
+        });
+    }
+    async receive(input) {
+        return this.bw.withSession(async (session) => {
+            const args = ['receive', input.url];
+            if (typeof input.password === 'string')
+                args.push('--password', input.password);
+            if (input.obj) {
+                const { stdout } = await this.bw.runForSession(session, ['--raw', ...args, '--obj'], { timeoutMs: 60_000 });
+                return this.tryParseJson(stdout);
+            }
+            if (input.downloadFile) {
+                const dir = await mkdtemp(join(tmpdir(), 'keychain-receive-'));
+                const outPath = join(dir, 'received');
+                try {
+                    await this.bw.runForSession(session, [...args, '--output', outPath], {
+                        timeoutMs: 120_000,
+                    });
+                    const buf = await readFile(outPath);
+                    return {
+                        file: {
+                            filename: basename(outPath),
+                            bytes: buf.byteLength,
+                            contentBase64: buf.toString('base64'),
+                        },
+                    };
+                }
+                finally {
+                    await rm(dir, { recursive: true, force: true });
+                }
+            }
+            const { stdout } = await this.bw.runForSession(session, ['--raw', ...args], {
+                timeoutMs: 60_000,
+            });
+            return { text: stdout.trim() };
+        });
+    }
+    async searchItems(input) {
+        const { limit } = input;
+        const rawText = (input.text ?? '').trim();
+        const tokens = rawText.includes('|')
+            ? rawText
+                .split('|')
+                .map((s) => s.trim())
+                .filter((s) => s.length > 0)
+            : rawText.length > 0
+                ? [rawText]
+                : [];
+        const orgFilter = input.organizationId;
+        const orgId = orgFilter && orgFilter !== 'null' && orgFilter !== 'notnull'
+            ? orgFilter
+            : undefined;
+        const folderFilter = input.folderId;
+        const folderId = folderFilter && folderFilter !== 'null' && folderFilter !== 'notnull'
+            ? folderFilter
+            : undefined;
+        const items = await this.bw.withSession(async (session) => {
+            const baseArgs = ['list', 'items'];
+            if (input.url)
+                baseArgs.push('--url', input.url);
+            if (folderId)
+                baseArgs.push('--folderid', folderId);
+            if (input.collectionId)
+                baseArgs.push('--collectionid', input.collectionId);
+            if (orgId)
+                baseArgs.push('--organizationid', orgId);
+            if (input.trash)
+                baseArgs.push('--trash');
+            // NOTE: bw's `--search` does not treat "a | b" as "a OR b". If callers pass
+            // a pipe-delimited string (common when combining name + username), we split
+            // and union the results.
+            const terms = tokens.length ? tokens : [undefined];
+            const byId = new Map();
+            for (const term of terms) {
+                const args = [...baseArgs];
+                if (term)
+                    args.push('--search', term);
+                const { stdout } = await this.bw.runForSession(session, args, {
+                    timeoutMs: 120_000,
+                });
+                const results = JSON.parse(stdout);
+                for (const raw of results) {
+                    if (!raw || typeof raw !== 'object')
+                        continue;
+                    const id = raw.id;
+                    if (typeof id === 'string' && id.length > 0)
+                        byId.set(id, raw);
+                }
+            }
+            return [...byId.values()];
+        });
+        const orgFiltered = items.filter((raw) => {
+            if (!raw || typeof raw !== 'object')
+                return false;
+            const item = raw;
+            if (orgFilter === 'null') {
+                return item.organizationId == null;
+            }
+            if (orgFilter === 'notnull') {
+                return typeof item.organizationId === 'string' && item.organizationId;
+            }
+            return true;
+        });
+        const folderFiltered = orgFiltered.filter((raw) => {
+            if (!raw || typeof raw !== 'object')
+                return false;
+            const item = raw;
+            if (folderFilter === 'null') {
+                return item.folderId == null;
+            }
+            if (folderFilter === 'notnull') {
+                return typeof item.folderId === 'string' && item.folderId;
+            }
+            return true;
+        });
+        const filtered = folderFiltered.filter((raw) => {
+            if (!raw || typeof raw !== 'object')
+                return false;
+            const item = raw;
+            if (!input.type)
+                return true;
+            if (input.type === 'ssh_key')
+                return isSshKeyItem(item);
+            if (input.type === 'login')
+                return item.type === ITEM_TYPE.login;
+            if (input.type === 'card')
+                return item.type === ITEM_TYPE.card;
+            if (input.type === 'identity')
+                return item.type === ITEM_TYPE.identity;
+            if (input.type === 'note')
+                return item.type === ITEM_TYPE.note && !isSshKeyItem(item);
+            return true;
+        });
+        return typeof limit === 'number' ? filtered.slice(0, limit) : filtered;
+    }
+    async listFolders(input = {}) {
+        const { limit } = input;
+        const folders = await this.bw.withSession(async (session) => {
+            const args = ['list', 'folders'];
+            if (input.search)
+                args.push('--search', input.search);
+            const { stdout } = await this.bw.runForSession(session, args, {
+                timeoutMs: 60_000,
+            });
+            return JSON.parse(stdout);
+        });
+        return typeof limit === 'number' ? folders.slice(0, limit) : folders;
+    }
+    async listCollections(input = {}) {
+        const { limit } = input;
+        const collections = await this.bw.withSession(async (session) => {
+            const args = ['list', 'collections'];
+            if (input.search)
+                args.push('--search', input.search);
+            if (input.organizationId)
+                args.push('--organizationid', input.organizationId);
+            const { stdout } = await this.bw.runForSession(session, args, {
+                timeoutMs: 60_000,
+            });
+            return JSON.parse(stdout);
+        });
+        return typeof limit === 'number'
+            ? collections.slice(0, limit)
+            : collections;
+    }
+    async listOrganizations(input = {}) {
+        const { limit } = input;
+        const orgs = await this.bw.withSession(async (session) => {
+            const args = ['list', 'organizations'];
+            if (input.search)
+                args.push('--search', input.search);
+            const { stdout } = await this.bw.runForSession(session, args, {
+                timeoutMs: 60_000,
+            });
+            return JSON.parse(stdout);
+        });
+        return typeof limit === 'number' ? orgs.slice(0, limit) : orgs;
+    }
+    async createFolder(name) {
+        return this.bw.withSession(async (session) => {
+            if (this.syncOnWrite()) {
+                await this.bw
+                    .runForSession(session, ['sync'], { timeoutMs: 120_000 })
+                    .catch(() => { });
+            }
+            const encoded = encodeJsonForBw({ name });
+            const { stdout } = await this.bw.runForSession(session, ['create', 'folder', encoded], { timeoutMs: 60_000 });
+            return JSON.parse(stdout);
+        });
+    }
+    async editFolder(input) {
+        return this.bw.withSession(async (session) => {
+            if (this.syncOnWrite()) {
+                await this.bw
+                    .runForSession(session, ['sync'], { timeoutMs: 120_000 })
+                    .catch(() => { });
+            }
+            const encoded = encodeJsonForBw({ name: input.name });
+            const { stdout } = await this.bw.runForSession(session, ['edit', 'folder', input.id, encoded], { timeoutMs: 60_000 });
+            return JSON.parse(stdout);
+        });
+    }
+    async deleteFolder(input) {
+        return this.bw.withSession(async (session) => {
+            if (this.syncOnWrite()) {
+                await this.bw
+                    .runForSession(session, ['sync'], { timeoutMs: 120_000 })
+                    .catch(() => { });
+            }
+            await this.bw.runForSession(session, ['delete', 'folder', input.id], {
+                timeoutMs: 60_000,
+            });
+        });
+    }
+    async listOrgCollections(input) {
+        const { limit } = input;
+        const cols = await this.bw.withSession(async (session) => {
+            const args = [
+                'list',
+                'org-collections',
+                '--organizationid',
+                input.organizationId,
+            ];
+            if (input.search)
+                args.push('--search', input.search);
+            const { stdout } = await this.bw.runForSession(session, args, {
+                timeoutMs: 60_000,
+            });
+            return JSON.parse(stdout);
+        });
+        return typeof limit === 'number' ? cols.slice(0, limit) : cols;
+    }
+    async createOrgCollection(input) {
+        return this.bw.withSession(async (session) => {
+            if (this.syncOnWrite()) {
+                await this.bw
+                    .runForSession(session, ['sync'], { timeoutMs: 120_000 })
+                    .catch(() => { });
+            }
+            // Newer bw CLI versions validate that --organizationid matches the request payload.
+            const encoded = encodeJsonForBw({
+                name: input.name,
+                organizationId: input.organizationId,
+            });
+            const { stdout } = await this.bw.runForSession(session, [
+                'create',
+                'org-collection',
+                '--organizationid',
+                input.organizationId,
+                encoded,
+            ], { timeoutMs: 60_000 });
+            return JSON.parse(stdout);
+        });
+    }
+    async editOrgCollection(input) {
+        return this.bw.withSession(async (session) => {
+            if (this.syncOnWrite()) {
+                await this.bw
+                    .runForSession(session, ['sync'], { timeoutMs: 120_000 })
+                    .catch(() => { });
+            }
+            // Newer bw CLI versions validate that --organizationid matches the request payload.
+            const encoded = encodeJsonForBw({
+                id: input.id,
+                name: input.name,
+                organizationId: input.organizationId,
+            });
+            const { stdout } = await this.bw.runForSession(session, [
+                'edit',
+                'org-collection',
+                input.id,
+                encoded,
+                '--organizationid',
+                input.organizationId,
+            ], { timeoutMs: 60_000 });
+            return JSON.parse(stdout);
+        });
+    }
+    async deleteOrgCollection(input) {
+        return this.bw.withSession(async (session) => {
+            if (this.syncOnWrite()) {
+                await this.bw
+                    .runForSession(session, ['sync'], { timeoutMs: 120_000 })
+                    .catch(() => { });
+            }
+            await this.bw.runForSession(session, [
+                'delete',
+                'org-collection',
+                input.id,
+                '--organizationid',
+                input.organizationId,
+            ], { timeoutMs: 60_000 });
+        });
+    }
+    async moveItemToOrganization(input) {
+        return this.bw.withSession(async (session) => {
+            if (this.syncOnWrite()) {
+                await this.bw
+                    .runForSession(session, ['sync'], { timeoutMs: 120_000 })
+                    .catch(() => { });
+            }
+            const args = ['move', input.id, input.organizationId];
+            if (input.collectionIds) {
+                args.push(encodeJsonForBw(input.collectionIds));
+            }
+            const { stdout } = await this.bw.runForSession(session, args, {
+                timeoutMs: 120_000,
+            });
+            const moved = JSON.parse(stdout);
+            return this.maybeRedact(moved, input.reveal);
+        });
+    }
+    async getItem(id, opts = {}) {
+        const item = await this.bw.withSession(async (session) => {
+            const { stdout } = await this.bw.runForSession(session, ['get', 'item', id], { timeoutMs: 60_000 });
+            return JSON.parse(stdout);
+        });
+        return this.maybeRedact(item, opts.reveal);
+    }
+    async deleteItem(input) {
+        return this.bw.withSession(async (session) => {
+            if (this.syncOnWrite()) {
+                await this.bw
+                    .runForSession(session, ['sync'], { timeoutMs: 120_000 })
+                    .catch(() => { });
+            }
+            const args = ['delete', 'item', input.id];
+            if (input.permanent)
+                args.push('--permanent');
+            await this.bw.runForSession(session, args, { timeoutMs: 60_000 });
+        });
+    }
+    async deleteItems(input) {
+        if (input.ids.length === 0)
+            return [];
+        if (input.ids.length > 200)
+            throw new Error('Too many ids (max 200)');
+        // Run inside a single session lock to avoid re-syncing/unlocking per item.
+        return this.bw.withSession(async (session) => {
+            if (this.syncOnWrite()) {
+                await this.bw
+                    .runForSession(session, ['sync'], { timeoutMs: 120_000 })
+                    .catch(() => { });
+            }
+            const results = [];
+            for (const id of input.ids) {
+                try {
+                    const args = ['delete', 'item', id];
+                    if (input.permanent)
+                        args.push('--permanent');
+                    await this.bw.runForSession(session, args, { timeoutMs: 60_000 });
+                    results.push({ id, ok: true });
+                }
+                catch (e) {
+                    results.push({
+                        id,
+                        ok: false,
+                        error: e instanceof Error ? e.message : String(e),
+                    });
+                }
+            }
+            return results;
+        });
+    }
+    async restoreItem(input) {
+        return this.bw.withSession(async (session) => {
+            if (this.syncOnWrite()) {
+                await this.bw
+                    .runForSession(session, ['sync'], { timeoutMs: 120_000 })
+                    .catch(() => { });
+            }
+            const { stdout } = await this.bw.runForSession(session, ['restore', 'item', input.id], { timeoutMs: 60_000 });
+            // restore may not return JSON; ignore stdout and refetch.
+            void stdout;
+            const { stdout: gotOut } = await this.bw.runForSession(session, ['get', 'item', input.id], { timeoutMs: 60_000 });
+            return this.maybeRedact(JSON.parse(gotOut), input.reveal);
+        });
+    }
+    async createAttachment(input) {
+        return this.bw.withSession(async (session) => {
+            if (this.syncOnWrite()) {
+                await this.bw
+                    .runForSession(session, ['sync'], { timeoutMs: 120_000 })
+                    .catch(() => { });
+            }
+            const dir = await mkdtemp(join(tmpdir(), 'keychain-attach-'));
+            try {
+                const safeBase = basename(input.filename || 'attachment.bin').replace(/[^A-Za-z0-9._-]+/g, '_');
+                const safeName = safeBase.length > 0 ? safeBase : 'attachment.bin';
+                const p = join(dir, safeName);
+                await writeFile(p, Buffer.from(input.contentBase64, 'base64'));
+                const { stdout: out } = await this.bw.runForSession(session, ['create', 'attachment', '--file', p, '--itemid', input.itemId], { timeoutMs: 120_000 });
+                // bw may return a full item JSON; ignore it and refetch the item.
+                void out;
+            }
+            finally {
+                await rm(dir, { recursive: true, force: true });
+            }
+            const { stdout: gotOut } = await this.bw.runForSession(session, ['get', 'item', input.itemId], { timeoutMs: 60_000 });
+            return this.maybeRedact(JSON.parse(gotOut), input.reveal);
+        });
+    }
+    async deleteAttachment(input) {
+        return this.bw.withSession(async (session) => {
+            if (this.syncOnWrite()) {
+                await this.bw
+                    .runForSession(session, ['sync'], { timeoutMs: 120_000 })
+                    .catch(() => { });
+            }
+            await this.bw.runForSession(session, ['delete', 'attachment', input.attachmentId, '--itemid', input.itemId], { timeoutMs: 60_000 });
+            const { stdout: gotOut } = await this.bw.runForSession(session, ['get', 'item', input.itemId], { timeoutMs: 60_000 });
+            return this.maybeRedact(JSON.parse(gotOut), input.reveal);
+        });
+    }
+    async getUsername(input) {
+        return this.bw.withSession(async (session) => {
+            const { stdout } = await this.bw.runForSession(session, ['--raw', 'get', 'username', input.term], { timeoutMs: 60_000 });
+            return this.valueResult(stdout.trim(), true);
+        });
+    }
+    async getPassword(input, opts = {}) {
+        if (!opts.reveal)
+            return this.valueResult(null, false);
+        return this.bw.withSession(async (session) => {
+            const { stdout } = await this.bw.runForSession(session, ['--raw', 'get', 'password', input.term], { timeoutMs: 60_000 });
+            return this.valueResult(stdout.trim(), true);
+        });
+    }
+    async getTotp(input, opts = {}) {
+        if (!opts.reveal)
+            return this.valueResult(null, false);
+        return this.bw.withSession(async (session) => {
+            const { stdout } = await this.bw.runForSession(session, ['--raw', 'get', 'totp', input.term], { timeoutMs: 60_000 });
+            return this.valueResult(stdout.trim(), true);
+        });
+    }
+    async getUri(input) {
+        return this.bw.withSession(async (session) => {
+            const { stdout } = await this.bw.runForSession(session, ['--raw', 'get', 'uri', input.term], { timeoutMs: 60_000 });
+            return this.valueResult(stdout.trim(), true);
+        });
+    }
+    async getNotes(input, opts = {}) {
+        if (!opts.reveal)
+            return this.valueResult(null, false);
+        return this.bw.withSession(async (session) => {
+            const { stdout } = await this.bw.runForSession(session, ['--raw', 'get', 'notes', input.term], { timeoutMs: 60_000 });
+            return this.valueResult(stdout.trim(), true);
+        });
+    }
+    async getExposed(input) {
+        const isNotFoundError = (err) => {
+            const combined = `${err.stderr}\n${err.stdout}`.trim().toLowerCase();
+            if (/more than one result/.test(combined)) {
+                return false;
+            }
+            if (/could not connect/.test(combined) ||
+                /connection/.test(combined) ||
+                /network/.test(combined) ||
+                /timeout/.test(combined) ||
+                /unauthorized|forbidden|not logged|authentication|permission/.test(combined)) {
+                return false;
+            }
+            return true;
+        };
+        return this.bw.withSession(async (session) => {
+            try {
+                const { stdout } = await this.bw.runForSession(session, ['--raw', 'get', 'exposed', input.term], { timeoutMs: 60_000 });
+                return this.valueResult(stdout.trim(), true);
+            }
+            catch (err) {
+                if ((err instanceof BwCliError &&
+                    err.exitCode === 1 &&
+                    isNotFoundError(err)) ||
+                    (err instanceof Error &&
+                        /exit code 1/.test(err.message.toLowerCase()))) {
+                    return this.valueResult(null, false);
+                }
+                throw err;
+            }
+        });
+    }
+    async getFolder(input) {
+        return this.bw.withSession(async (session) => {
+            const { stdout } = await this.bw.runForSession(session, ['get', 'folder', input.id], { timeoutMs: 60_000 });
+            return JSON.parse(stdout);
+        });
+    }
+    async getCollection(input) {
+        return this.bw.withSession(async (session) => {
+            const args = ['get', 'collection', input.id];
+            if (input.organizationId)
+                args.push('--organizationid', input.organizationId);
+            const { stdout } = await this.bw.runForSession(session, args, {
+                timeoutMs: 60_000,
+            });
+            return JSON.parse(stdout);
+        });
+    }
+    async getOrganization(input) {
+        return this.bw.withSession(async (session) => {
+            const { stdout } = await this.bw.runForSession(session, ['get', 'organization', input.id], { timeoutMs: 60_000 });
+            return JSON.parse(stdout);
+        });
+    }
+    async getOrgCollection(input) {
+        return this.bw.withSession(async (session) => {
+            const args = ['get', 'org-collection', input.id];
+            if (input.organizationId)
+                args.push('--organizationid', input.organizationId);
+            const { stdout } = await this.bw.runForSession(session, args, {
+                timeoutMs: 60_000,
+            });
+            return JSON.parse(stdout);
+        });
+    }
+    async getPasswordHistory(id, opts = {}) {
+        const item = await this.bw.withSession(async (session) => {
+            const { stdout } = await this.bw.runForSession(session, ['get', 'item', id], { timeoutMs: 60_000 });
+            return JSON.parse(stdout);
+        });
+        const history = Array.isArray(item.passwordHistory)
+            ? item.passwordHistory
+            : [];
+        if (opts.reveal)
+            return { value: history, revealed: true };
+        return {
+            value: this.redactPasswordHistoryForTool(history),
+            revealed: false,
+        };
+    }
+    async createLogin(input) {
+        return this.bw.withSession(async (session) => {
+            if (this.syncOnWrite()) {
+                await this.bw
+                    .runForSession(session, ['sync'], {
+                    timeoutMs: 120_000,
+                })
+                    .catch(() => { });
+            }
+            return this.createLoginForSession(session, input);
+        });
+    }
+    async createLogins(input) {
+        const continueOnError = input.continueOnError ?? true;
+        return this.bw.withSession(async (session) => {
+            if (this.syncOnWrite()) {
+                await this.bw
+                    .runForSession(session, ['sync'], { timeoutMs: 120_000 })
+                    .catch(() => { });
+            }
+            const results = [];
+            for (const it of input.items) {
+                try {
+                    const created = await this.createLoginForSession(session, it);
+                    results.push({ ok: true, item: created });
+                }
+                catch (err) {
+                    const msg = err && typeof err === 'object' && 'message' in err
+                        ? String(err.message)
+                        : String(err);
+                    results.push({ ok: false, error: msg });
+                    if (!continueOnError)
+                        break;
+                }
+            }
+            return results;
+        });
+    }
+    async createNote(input) {
+        return this.bw.withSession(async (session) => {
+            if (this.syncOnWrite()) {
+                await this.bw
+                    .runForSession(session, ['sync'], {
+                    timeoutMs: 120_000,
+                })
+                    .catch(() => { });
+            }
+            const tpl = (await this.bw.getTemplateItemForSession(session));
+            const item = deepClone(tpl);
+            item.type = ITEM_TYPE.note;
+            item.name = input.name;
+            item.notes = input.notes ?? '';
+            item.favorite = input.favorite ?? false;
+            if (input.organizationId)
+                item.organizationId = input.organizationId;
+            if (input.folderId)
+                item.folderId = input.folderId;
+            if (!item.secureNote || typeof item.secureNote !== 'object') {
+                item.secureNote = { type: 0 };
+            }
+            item.fields = normalizeFields(input.fields) ?? [];
+            if (input.collectionIds)
+                item.collectionIds = input.collectionIds;
+            const encoded = encodeJsonForBw(item);
+            const { stdout } = await this.bw.runForSession(session, ['create', 'item', encoded], { timeoutMs: 120_000 });
+            const created = JSON.parse(stdout);
+            if (input.collectionIds?.length) {
+                const encodedCols = encodeJsonForBw(input.collectionIds);
+                await this.bw
+                    .runForSession(session, ['edit', 'item-collections', String(created.id), encodedCols], { timeoutMs: 120_000 })
+                    .catch(() => { });
+            }
+            return this.maybeRedact(created, input.reveal);
+        });
+    }
+    async createSshKey(input) {
+        const fields = [
+            { name: 'public_key', value: input.publicKey, hidden: false },
+            { name: 'private_key', value: input.privateKey, hidden: true },
+        ];
+        if (input.fingerprint)
+            fields.push({
+                name: 'fingerprint',
+                value: input.fingerprint,
+                hidden: false,
+            });
+        if (input.comment)
+            fields.push({ name: 'comment', value: input.comment, hidden: false });
+        return this.createNote({
+            name: input.name,
+            notes: input.notes,
+            reveal: input.reveal,
+            favorite: input.favorite,
+            organizationId: input.organizationId,
+            collectionIds: input.collectionIds,
+            folderId: input.folderId,
+            fields,
+        });
+    }
+    async createCard(input) {
+        return this.bw.withSession(async (session) => {
+            if (this.syncOnWrite()) {
+                await this.bw
+                    .runForSession(session, ['sync'], { timeoutMs: 120_000 })
+                    .catch(() => { });
+            }
+            const tpl = (await this.bw.getTemplateItemForSession(session));
+            const item = deepClone(tpl);
+            item.type = ITEM_TYPE.card;
+            item.name = input.name;
+            item.notes = input.notes ?? '';
+            item.favorite = input.favorite ?? false;
+            if (input.organizationId)
+                item.organizationId = input.organizationId;
+            if (input.folderId)
+                item.folderId = input.folderId;
+            item.fields = normalizeFields(input.fields) ?? [];
+            const card = (item.card && typeof item.card === 'object'
+                ? item.card
+                : {});
+            if (input.cardholderName !== undefined)
+                card.cardholderName = input.cardholderName;
+            if (input.brand !== undefined)
+                card.brand = input.brand;
+            if (input.number !== undefined)
+                card.number = input.number;
+            if (input.expMonth !== undefined)
+                card.expMonth = input.expMonth;
+            if (input.expYear !== undefined)
+                card.expYear = input.expYear;
+            if (input.code !== undefined)
+                card.code = input.code;
+            item.card = card;
+            if (input.collectionIds)
+                item.collectionIds = input.collectionIds;
+            const encoded = encodeJsonForBw(item);
+            const { stdout } = await this.bw.runForSession(session, ['create', 'item', encoded], { timeoutMs: 120_000 });
+            const created = JSON.parse(stdout);
+            if (input.collectionIds?.length) {
+                const encodedCols = encodeJsonForBw(input.collectionIds);
+                await this.bw
+                    .runForSession(session, ['edit', 'item-collections', String(created.id), encodedCols], { timeoutMs: 120_000 })
+                    .catch(() => { });
+            }
+            return this.maybeRedact(created, input.reveal);
+        });
+    }
+    async createIdentity(input) {
+        return this.bw.withSession(async (session) => {
+            if (this.syncOnWrite()) {
+                await this.bw
+                    .runForSession(session, ['sync'], { timeoutMs: 120_000 })
+                    .catch(() => { });
+            }
+            const tpl = (await this.bw.getTemplateItemForSession(session));
+            const item = deepClone(tpl);
+            item.type = ITEM_TYPE.identity;
+            item.name = input.name;
+            item.notes = input.notes ?? '';
+            item.favorite = input.favorite ?? false;
+            if (input.organizationId)
+                item.organizationId = input.organizationId;
+            if (input.folderId)
+                item.folderId = input.folderId;
+            item.fields = normalizeFields(input.fields) ?? [];
+            const identity = (item.identity && typeof item.identity === 'object'
+                ? item.identity
+                : {});
+            if (input.identity) {
+                for (const [k, v] of Object.entries(input.identity)) {
+                    if (v !== undefined)
+                        identity[k] = v;
+                }
+            }
+            item.identity = identity;
+            if (input.collectionIds)
+                item.collectionIds = input.collectionIds;
+            const encoded = encodeJsonForBw(item);
+            const { stdout } = await this.bw.runForSession(session, ['create', 'item', encoded], { timeoutMs: 120_000 });
+            const created = JSON.parse(stdout);
+            if (input.collectionIds?.length) {
+                const encodedCols = encodeJsonForBw(input.collectionIds);
+                await this.bw
+                    .runForSession(session, ['edit', 'item-collections', String(created.id), encodedCols], { timeoutMs: 120_000 })
+                    .catch(() => { });
+            }
+            return this.maybeRedact(created, input.reveal);
+        });
+    }
+    async updateItem(id, patch, opts = {}) {
+        return this.bw.withSession(async (session) => {
+            if (this.syncOnWrite()) {
+                await this.bw
+                    .runForSession(session, ['sync'], {
+                    timeoutMs: 120_000,
+                })
+                    .catch(() => { });
+            }
+            const { stdout } = await this.bw.runForSession(session, ['get', 'item', id], { timeoutMs: 60_000 });
+            const current = JSON.parse(stdout);
+            // Convert uri match strings to bw enum numbers if needed.
+            const normalizedPatch = deepClone(patch);
+            if (normalizedPatch.login?.uris) {
+                normalizedPatch.login.uris = normalizedPatch.login.uris.map((u) => ({
+                    uri: u.uri,
+                    match: u.match,
+                }));
+            }
+            const next = applyItemPatch(current, normalizedPatch);
+            // If uris were provided, convert match strings to numbers now.
+            if (patch.login?.uris) {
+                const login = (next.login && typeof next.login === 'object'
+                    ? next.login
+                    : {});
+                login.uris = normalizeUris(patch.login.uris);
+                next.login = login;
+            }
+            const encoded = encodeJsonForBw(next);
+            const { stdout: out } = await this.bw.runForSession(session, ['edit', 'item', id, encoded], { timeoutMs: 120_000 });
+            const updated = JSON.parse(out);
+            if (patch.collectionIds !== undefined) {
+                const encodedCols = encodeJsonForBw(patch.collectionIds);
+                await this.bw
+                    .runForSession(session, ['edit', 'item-collections', id, encodedCols], { timeoutMs: 120_000 })
+                    .catch(() => { });
+            }
+            return this.maybeRedact(updated, opts.reveal);
+        });
+    }
+    async setLoginUris(input) {
+        const mode = input.mode ?? 'replace';
+        if (mode !== 'replace' && mode !== 'merge') {
+            throw new Error(`Invalid mode: ${String(mode)}`);
+        }
+        // IMPORTANT: do not call updateItem from inside a bw.withSession callback.
+        // BwSessionManager can serialize session access; nesting can deadlock.
+        const current = await this.bw.withSession(async (session) => {
+            const { stdout } = await this.bw.runForSession(session, ['get', 'item', input.id], { timeoutMs: 60_000 });
+            return JSON.parse(stdout);
+        });
+        const currentLogin = current.login && typeof current.login === 'object'
+            ? current.login
+            : null;
+        const existing = denormalizeUris(currentLogin?.uris) ?? [];
+        let nextUris = input.uris;
+        if (mode === 'merge') {
+            const byUri = new Map();
+            for (const u of existing)
+                byUri.set(u.uri, u);
+            for (const u of input.uris)
+                byUri.set(u.uri, u);
+            const seen = new Set();
+            const merged = [];
+            // Existing order first (updated in place if overridden)
+            for (const u of existing) {
+                const v = byUri.get(u.uri);
+                if (!v || seen.has(v.uri))
+                    continue;
+                seen.add(v.uri);
+                merged.push(v);
+            }
+            // Append new entries
+            for (const u of input.uris) {
+                if (seen.has(u.uri))
+                    continue;
+                seen.add(u.uri);
+                merged.push(u);
+            }
+            nextUris = merged;
+        }
+        return this.updateItem(input.id, { login: { uris: nextUris } }, { reveal: input.reveal });
+    }
+    minimalSummary(item) {
+        if (!item || typeof item !== 'object')
+            return item;
+        const rec = item;
+        return {
+            id: typeof rec.id === 'string' ? rec.id : undefined,
+            name: typeof rec.name === 'string' ? rec.name : undefined,
+            type: kindFromItem(rec),
+            organizationId: typeof rec.organizationId === 'string' ? rec.organizationId : null,
+            folderId: typeof rec.folderId === 'string' ? rec.folderId : null,
+            collectionIds: Array.isArray(rec.collectionIds)
+                ? rec.collectionIds
+                : undefined,
+            favorite: typeof rec.favorite === 'boolean' ? rec.favorite : undefined,
+        };
+    }
+}