keyshroud 0.5.3 → 0.6.0

package/CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes are documented here. This project follows
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-10-17
+
+### Added
+- `setup --email`: keyshroud gets its own `bw` login on a dedicated agent account
+  (`~/.config/keyshroud/bw`, keychain entry `keyshroud-master-password`), so agents
+  can no longer unlock your personal vault. `--confirm-unlock` (macOS) makes the
+  keychain ask before every unlock. Run from an agent's shell, it generates the
+  agent account's password, stores it over stdin, and hands it to you on the
+  clipboard for the signup page.
+- `migrate`: copies the items your wired names reference from the personal vault
+  into the agent account (dry run unless `--yes`, names only, originals kept).
+
 ## [0.5.3] - 2026-10-15
 
 ### Security

package/README.md

@@ -135,6 +135,32 @@ Optional: put `vaultwarden-api-client-id` / `vaultwarden-api-client-secret` (fro
 also re-login automatically when the `bw` session expires. Linux keyring commands
 and a headless-server option are in the [vault setup guide](examples/vaultwarden#4-let-keyshroud-unlock-without-prompting).
 
+### Least privilege: a separate agent account
+
+With the steps above, keyshroud holds your master password, so an agent that runs
+`bw` as you can open your whole vault. `setup` gives keyshroud its own `bw` login
+on a dedicated account instead, which holds only the secrets agents need:
+
+```bash
+keyshroud setup --email you+agent@example.com   # opens the signup page, then stores the new
+                                                 # master password in the keychain and logs in
+keyshroud migrate                                # dry run: which wired items would be copied
+keyshroud migrate --yes                          # copy them; references keep working
+```
+
+- The agent login lives in `~/.config/keyshroud/bw` (`BITWARDENCLI_APPDATA_DIR`), its master
+  password in the keychain entry `keyshroud-master-password`. Your own `bw` login is untouched.
+- `migrate` copies the items that wired names (and any `--env-file` / `--item`) reference, with
+  the same names, then locks your personal vault again. Originals stay where they are. It needs
+  your personal master password in the keychain once; delete it afterwards (the command prints how).
+- An agent can run `setup` too. Without a terminal, keyshroud generates the agent account's
+  master password, writes it to the keychain over stdin and puts it on the clipboard; you paste
+  it into the signup page, then the agent runs `setup --registered`, which clears the clipboard.
+- `--confirm-unlock` (macOS, off by default) creates the keychain entry so macOS asks you before
+  every read, i.e. every vault unlock.
+- Self-hosted Vaultwarden with `SIGNUPS_ALLOWED=false`: invite the address from the admin page
+  (`/admin`), or allow signups for a minute, then pass `--registered` once the account exists.
+
 ## How it works
 
 ```
@@ -274,6 +300,8 @@ keyshroud import [--from F|-] [--out F] [--prefix P] [--only A,B] [--skip A,B] [
 keyshroud rotate --item ITEM [--stdin|--dialog]
 keyshroud wire --env NAME --item ITEM [--target pi|omp|both] [--force]
 keyshroud unwire --env NAME [--target pi|omp|both]
+keyshroud setup --email EMAIL [--server URL] [--confirm-unlock] [--registered]
+keyshroud migrate [--item NAME]... [--env-file F]... [--yes]
 keyshroud status | unlock | lock | doctor
 keyshroud mcp
 keyshroud hook claude <session-start|post-tool-use>
@@ -397,8 +425,8 @@ as a literal; check its plan before committing `.env.refs`. The Claude Code
 rewrite output) or anything a client sends as telemetry, and it only knows wired
 values, so `keyshroud get bw://…` or `run --no-mask` print in the clear; run
 secret-using commands through `keyshroud run` or `secrets_run`. An agent with shell access as your user can read
-`~/.config/keyshroud/session` and use `bw` directly — run agents in a sandbox or
-container if that matters. Redaction is exact-match, so a *partial* or transformed value
+`~/.config/keyshroud/session` and use `bw` directly — after `setup` that reaches
+only the agent account; otherwise run agents in a sandbox or container if that matters. Redaction is exact-match, so a *partial* or transformed value
 (`${TOKEN:0:10}`, base64, a line wrapped by a tool) is not masked; values
 shorter than 6 characters are not redacted (to avoid noise), so don't wire short
 PINs.

package/dist/cli.js

@@ -31,6 +31,11 @@ Secrets
   unwire --env NAME [--target pi|omp|both]
 
 Vault
+  setup --email EMAIL [--server URL] [--confirm-unlock] [--registered]
+                                   Give ${BRAND.name} its own bw login on a dedicated agent account
+  migrate [--item NAME]... [--env-file F]... [--yes]
+                                   Copy the wired items from your personal vault to that account
+                                   (dry run unless --yes; prints names only)
   status | unlock | lock | doctor
 
 Agents
@@ -241,6 +246,143 @@ async function scan(paths) {
     if (leaks)
         process.exitCode = 1;
 }
+// setup: keyshroud gets its own bw login (CONFIG_DIR/bw) on a separate agent
+// account, so agents never get a session for the user's personal vault.
+async function setupCommand(args) {
+    requireKnownFlags(args, ["--email", "--server"], ["--confirm-unlock", "--registered"]);
+    const email = valueAfter(args, "--email");
+    if (!email || !/^[^\s@]+@[^\s@]+$/.test(email))
+        fail("setup needs --email for a separate agent account (not your personal one)", 2);
+    let server = valueAfter(args, "--server");
+    if (!server) {
+        try {
+            server = JSON.parse(await core.bw(["status"])).serverUrl ?? undefined;
+        }
+        catch { }
+    }
+    if (!server || !/^https:\/\//.test(server))
+        fail("setup needs --server https://… (no bw server is configured)", 2);
+    const confirm = args.includes("--confirm-unlock");
+    if (confirm && process.platform !== "darwin")
+        fail("--confirm-unlock needs the macOS keychain; Linux secret-tool cannot ask before each read", 2);
+    core.useOwnBwLogin();
+    await mkdir(core.OWN_BW_DIR, { recursive: true, mode: 0o700 });
+    const status = JSON.parse(await core.bw(["status"]).catch(() => "{}"));
+    if (status.userEmail && status.userEmail.toLowerCase() !== email.toLowerCase())
+        fail(`${BRAND.name}'s bw login already belongs to ${status.userEmail}; remove ${core.OWN_BW_DIR} to start over`, 5);
+    const loggedOut = !status.status || status.status === "unauthenticated";
+    if (loggedOut)
+        await core.bw(["config", "server", server]);
+    await unlink(core.SESSION_FILE).catch(() => { });
+    console.log(`${BRAND.name} now keeps its own bw login in ${core.OWN_BW_DIR}; your personal bw login is untouched.`);
+    const signupUrl = `${server.replace(/\/$/, "")}/#/signup?email=${encodeURIComponent(email)}`;
+    if (!process.stdin.isTTY) {
+        // An agent's shell: nothing can be typed, so keyshroud picks the password.
+        const hasEntry = Boolean(await core.readKeychain(core.KEYCHAIN_MASTER_SERVICE));
+        if (!loggedOut && (confirm || !hasEntry))
+            fail(`The agent account is already logged in; run \`${BRAND.bin} setup\` in a terminal to store its password`, 2);
+        if (loggedOut && !args.includes("--registered")) {
+            if (!hasEntry && !(await core.generateKeychainSecret(core.KEYCHAIN_MASTER_SERVICE, `${BRAND.name} agent account`, confirm)))
+                fail("Could not store a generated password (needs macOS security or Linux secret-tool)", 3);
+            const master = await core.readKeychain(core.KEYCHAIN_MASTER_SERVICE);
+            if (!master || !(await core.copyToClipboard(master)))
+                fail(`No clipboard tool; run \`${BRAND.bin} setup\` in a terminal instead`, 3);
+            spawn(process.platform === "darwin" ? "open" : "xdg-open", [signupUrl], { stdio: "ignore" }).on("error", () => { });
+            console.log(`A random master password for ${email} is in the keychain (${core.KEYCHAIN_MASTER_SERVICE}) and on the clipboard.`);
+            console.log(`Create the account at ${signupUrl} and paste it into both password fields.`);
+            console.log(`Then: ${BRAND.bin} setup --email ${email} --registered`);
+            return;
+        }
+    }
+    if (loggedOut && !args.includes("--registered")) {
+        const url = signupUrl;
+        console.log(`1. Create the agent account ${email}: ${url}`);
+        console.log("   Pick a new master password, not your personal one.");
+        spawn(process.platform === "darwin" ? "open" : "xdg-open", [url], { stdio: "ignore" }).on("error", () => { });
+        process.stdout.write("   Press Enter once the account exists. ");
+        await new Promise((resolve) => process.stdin.once("data", resolve));
+        process.stdin.pause();
+    }
+    if (confirm || !(await core.readKeychain(core.KEYCHAIN_MASTER_SERVICE))) {
+        console.log(`2. Type the agent account's master password for the keychain entry ${core.KEYCHAIN_MASTER_SERVICE}${confirm ? " (macOS will ask before every unlock)" : ""}:`);
+        if (!(await core.storeKeychainInteractive(core.KEYCHAIN_MASTER_SERVICE, `${BRAND.name} agent account`, confirm)))
+            fail("Could not store it (needs macOS security or Linux secret-tool)", 3);
+    }
+    const master = await core.readKeychain(core.KEYCHAIN_MASTER_SERVICE);
+    if (!master)
+        fail(`The keychain entry ${core.KEYCHAIN_MASTER_SERVICE} is missing or access was denied`, 3);
+    if (loggedOut)
+        await core.loginOwnAccount(email, master);
+    else
+        await core.ensureSession();
+    await core.clearClipboardIf(master);
+    await core.audit("setup", [], "cli");
+    console.log(`ready: bw login=${email} (own). Next: \`${BRAND.bin} migrate\` copies the wired secrets from your personal vault.`);
+}
+// migrate: copy the items that wired names (and env files) reference from the
+// personal vault into the agent account. Same names, so references keep working.
+async function migrateCommand(args) {
+    requireKnownFlags(args, ["--item", "--env-file"], ["--yes"]);
+    if (!core.OWN_BW_LOGIN)
+        fail(`Run \`${BRAND.bin} setup\` first: migrate copies items into ${BRAND.name}'s own agent account`, 2);
+    const entries = [...await core.authEnvEntries()];
+    for (const file of valuesAfter(args, "--env-file"))
+        entries.push(...await core.envFileEntries(file));
+    const names = new Map();
+    for (const entry of entries) {
+        try {
+            const ref = parseRef(entry.raw);
+            if (ref)
+                names.set(ref.item.toLowerCase(), ref.item);
+        }
+        catch { }
+    }
+    for (const name of valuesAfter(args, "--item"))
+        names.set(name.toLowerCase(), name);
+    await core.ensureSession();
+    const own = await core.findItems("");
+    const personal = await core.readPersonalItems();
+    const rows = [...names.values()].sort().map((name) => {
+        if (own.some((item) => item.name.toLowerCase() === name.toLowerCase() || item.id === name))
+            return { name, state: "present" };
+        const matches = personal.filter((item) => String(item.name ?? "").toLowerCase() === name.toLowerCase() || item.id === name);
+        return matches.length === 1 ? { name, state: "copy", item: matches[0] } : { name, state: matches.length ? "ambiguous" : "missing" };
+    });
+    const width = Math.max(4, ...rows.map((row) => row.name.length));
+    console.log("migrate plan (personal vault -> agent account):");
+    for (const row of rows)
+        console.log(`  ${row.name.padEnd(width)}  ${row.state === "present" ? "already in the agent account" : row.state}`);
+    const count = (state) => rows.filter((row) => row.state === state).length;
+    console.log(`${count("copy")} to copy, ${count("present")} already there, ${count("missing")} missing, ${count("ambiguous")} ambiguous`);
+    if (!args.includes("--yes")) {
+        console.log("Dry run: nothing copied. Re-run with --yes.");
+        return;
+    }
+    const copied = [];
+    for (const row of rows.filter((entry) => entry.state === "copy")) {
+        try {
+            await core.copyItemToOwnVault(row.item);
+            copied.push(row.name);
+        }
+        catch {
+            if (copied.length)
+                console.error(`Copied before the failure: ${copied.join(", ")}`);
+            fail(`Failed to copy ${row.name}`, 3);
+        }
+    }
+    await core.syncOwnVault();
+    const after = await core.findItems("");
+    const unverified = copied.filter((name) => !after.some((item) => item.name.toLowerCase() === name.toLowerCase()));
+    await core.audit("migrate", copied, "cli");
+    await core.refreshRedactIndex();
+    console.log(`copied ${copied.length} item(s) into the agent account; references are unchanged.`);
+    const cut = process.platform === "darwin" ? `security delete-generic-password -s ${core.PERSONAL_KEYCHAIN_MASTER_SERVICE}` : `secret-tool clear service ${core.PERSONAL_KEYCHAIN_MASTER_SERVICE} account "$USER"`;
+    console.log(`Your personal master password is still in the keychain, where any program running as you can read it. Once you no longer need it there: ${cut}`);
+    if (unverified.length)
+        fail(`Not found after copying: ${unverified.join(", ")}`, 4);
+    if (count("missing") || count("ambiguous"))
+        process.exitCode = 4;
+}
 async function importCommand(args) {
     requireKnownFlags(args, ["--from", "--out", "--prefix", "--only", "--skip"], ["--yes", "--replace", "--force"]);
     const from = valueAfter(args, "--from") ?? ".env";
@@ -501,6 +643,14 @@ async function main() {
             await importCommand(args);
             return;
         }
+        if (command === "setup") {
+            await setupCommand(args);
+            return;
+        }
+        if (command === "migrate") {
+            await migrateCommand(args);
+            return;
+        }
         if (command === "rotate") {
             requireKnownFlags(args, ["--item"], ["--stdin", "--dialog"]);
             const itemName = valueAfter(args, "--item");
@@ -598,6 +748,7 @@ async function main() {
             }
             catch { }
             const s = await core.getStatus();
+            console.log(`bw login=${core.OWN_BW_LOGIN ? `own agent account (${core.OWN_BW_DIR})` : `shared with your personal bw (run: ${BRAND.bin} setup)`}`);
             console.log(`bw version=${s.version ?? "missing (install @bitwarden/cli)"}`);
             console.log(`bw server=${s.serverUrl ?? "unconfigured (run: bw config server <url>)"}`);
             console.log(`session=${s.status}`);

package/dist/core.d.ts

@@ -5,9 +5,13 @@ export declare const SESSION_FILE: string;
 export declare const MASTER_PASSWORD_FILE: string;
 export declare const REDACT_INDEX_FILE: string;
 export declare const AUDIT_FILE: string;
-export declare const KEYCHAIN_MASTER_SERVICE: string;
-export declare const KEYCHAIN_CLIENT_ID_SERVICE: string;
-export declare const KEYCHAIN_CLIENT_SECRET_SERVICE: string;
+export declare const OWN_BW_DIR: string;
+export declare const PERSONAL_KEYCHAIN_MASTER_SERVICE: string;
+export declare let OWN_BW_LOGIN: boolean;
+export declare let KEYCHAIN_MASTER_SERVICE: string;
+export declare let KEYCHAIN_CLIENT_ID_SERVICE: string;
+export declare let KEYCHAIN_CLIENT_SECRET_SERVICE: string;
+export declare function useOwnBwLogin(): void;
 export declare const PROVIDER_KEYS: ReadonlySet<string>;
 export interface VaultStatus {
     status: string;
@@ -39,8 +43,17 @@ export interface VaultItem {
 }
 export declare function invalidateSecretCache(): void;
 export declare function resolveRef(ref: SecretRef): Promise<string | null>;
+export declare function readKeychain(service: string): Promise<string | null>;
 export declare function keychainPresence(): Promise<Record<string, boolean>>;
 export declare function ensureSession(): Promise<string>;
+export declare function storeKeychainInteractive(service: string, label: string, confirm: boolean): Promise<boolean>;
+export declare function generateKeychainSecret(service: string, label: string, confirm: boolean): Promise<boolean>;
+export declare function copyToClipboard(text: string): Promise<boolean>;
+export declare function clearClipboardIf(text: string): Promise<void>;
+export declare function loginOwnAccount(email: string, master: string): Promise<string>;
+export declare function readPersonalItems(): Promise<Array<Record<string, unknown>>>;
+export declare function copyItemToOwnVault(item: Record<string, unknown>): Promise<void>;
+export declare function syncOwnVault(): Promise<void>;
 export declare function lock(): Promise<void>;
 export declare function audit(action: string, names: string[], consumer: string): Promise<void>;
 export declare function getStatus(): Promise<VaultStatus>;

package/dist/core.js

@@ -1,7 +1,8 @@
 // Runtime-neutral core: no pi/omp/Claude Code imports. Every caller (agent
 // extensions, CLI, MCP server, hooks) goes through these functions.
-import { execFile } from "node:child_process";
+import { execFile, spawn } from "node:child_process";
 import { randomBytes } from "node:crypto";
+import { existsSync } from "node:fs";
 import { appendFile, chmod, mkdir, readFile, realpath, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join, dirname } from "node:path";
@@ -19,9 +20,24 @@ export const SESSION_FILE = join(CONFIG_DIR, "session");
 export const MASTER_PASSWORD_FILE = join(CONFIG_DIR, "master-password");
 export const REDACT_INDEX_FILE = join(CONFIG_DIR, "redact-index.json");
 export const AUDIT_FILE = join(CONFIG_DIR, "audit.jsonl");
-export const KEYCHAIN_MASTER_SERVICE = setting("KEYCHAIN_MASTER") ?? "vaultwarden-master-password";
-export const KEYCHAIN_CLIENT_ID_SERVICE = setting("KEYCHAIN_CLIENT_ID") ?? "vaultwarden-api-client-id";
-export const KEYCHAIN_CLIENT_SECRET_SERVICE = setting("KEYCHAIN_CLIENT_SECRET") ?? "vaultwarden-api-client-secret";
+// After `setup`, keyshroud keeps its own bw login (a dedicated agent account) in
+// CONFIG_DIR/bw, with its own keychain entries, so the user's personal bw login
+// and vault are never unlocked. Without it, keyshroud shares the default bw login.
+export const OWN_BW_DIR = join(CONFIG_DIR, "bw");
+export const PERSONAL_KEYCHAIN_MASTER_SERVICE = setting("PERSONAL_KEYCHAIN_MASTER") ?? "vaultwarden-master-password";
+export let OWN_BW_LOGIN = false;
+export let KEYCHAIN_MASTER_SERVICE = setting("KEYCHAIN_MASTER") ?? PERSONAL_KEYCHAIN_MASTER_SERVICE;
+export let KEYCHAIN_CLIENT_ID_SERVICE = setting("KEYCHAIN_CLIENT_ID") ?? "vaultwarden-api-client-id";
+export let KEYCHAIN_CLIENT_SECRET_SERVICE = setting("KEYCHAIN_CLIENT_SECRET") ?? "vaultwarden-api-client-secret";
+export function useOwnBwLogin() {
+    OWN_BW_LOGIN = true;
+    process.env.BITWARDENCLI_APPDATA_DIR = OWN_BW_DIR;
+    KEYCHAIN_MASTER_SERVICE = setting("KEYCHAIN_MASTER") ?? `${BRAND.bin}-master-password`;
+    KEYCHAIN_CLIENT_ID_SERVICE = setting("KEYCHAIN_CLIENT_ID") ?? `${BRAND.bin}-api-client-id`;
+    KEYCHAIN_CLIENT_SECRET_SERVICE = setting("KEYCHAIN_CLIENT_SECRET") ?? `${BRAND.bin}-api-client-secret`;
+}
+if (!process.env.BITWARDENCLI_APPDATA_DIR && existsSync(join(OWN_BW_DIR, "data.json")))
+    useOwnBwLogin();
 export const PROVIDER_KEYS = new Set([
     "anthropic", "openai", "azure-openai-responses", "deepseek", "google", "mistral",
     "groq", "cerebras", "cloudflare-ai-gateway", "cloudflare-workers-ai", "xai",
@@ -55,7 +71,7 @@ export function getAuthTargets() {
 export const referenceFor = legacyRefFor;
 // Vault credentials never reach commands run on the agent's behalf: with the
 // session token a child could dump the whole vault, defeating `--only`.
-export const VAULT_ENV_KEYS = ["BW_SESSION", "BW_PASSWORD", "BW_CLIENTID", "BW_CLIENTSECRET"];
+export const VAULT_ENV_KEYS = ["BW_SESSION", "BW_PASSWORD", "BW_CLIENTID", "BW_CLIENTSECRET", "BITWARDENCLI_APPDATA_DIR"];
 export function childEnv(extra = {}) {
     const env = {};
     for (const [name, value] of Object.entries(process.env))
@@ -189,10 +205,12 @@ export async function resolveRef(ref) {
         case "totp": return (await bw(["get", "totp", item.id])).trim() || null;
     }
 }
-async function readKeychain(service) {
+// The timeout leaves room for a macOS "allow access" prompt when the entry was
+// stored with `setup --confirm-unlock`; a missing entry still fails at once.
+export async function readKeychain(service) {
     const user = process.env.USER || process.env.LOGNAME || "";
     try {
-        const result = await runFile("security", ["find-generic-password", "-a", user, "-s", service, "-w"], { timeout: 10000, maxBuffer: 1024 * 1024 });
+        const result = await runFile("security", ["find-generic-password", "-a", user, "-s", service, "-w"], { timeout: 120000, maxBuffer: 1024 * 1024 });
         return result.stdout.trim() || null;
     }
     catch { }
@@ -285,6 +303,129 @@ async function ensureSessionInner(existing) {
     invalidateSecretCache();
     return token;
 }
+// Store a keychain entry by letting the OS tool prompt for the value on the
+// user's terminal, so keyshroud never holds it in argv. `confirm` (macOS) trusts
+// no app, so every later read asks the user first.
+export async function storeKeychainInteractive(service, label, confirm) {
+    const user = process.env.USER || process.env.LOGNAME || "";
+    const attempts = process.platform === "darwin"
+        ? [["security", ["add-generic-password", "-U", "-a", user, "-s", service, "-l", label, ...(confirm ? ["-T", ""] : []), "-w"]]]
+        : [["secret-tool", ["store", `--label=${label}`, "service", service, "account", user]]];
+    // -U keeps an existing entry's access list, so an ask-every-time entry is recreated.
+    if (process.platform === "darwin" && confirm)
+        await runFile("security", ["delete-generic-password", "-a", user, "-s", service], { timeout: 10000, maxBuffer: 1024 * 1024 }).catch(() => { });
+    for (const [command, args] of attempts) {
+        const code = await new Promise((resolve) => {
+            const child = spawn(command, args, { stdio: "inherit" });
+            child.on("error", () => resolve(null));
+            child.on("exit", (exit) => resolve(exit));
+        });
+        if (code === 0)
+            return true;
+    }
+    return false;
+}
+// `setup` from an agent's shell (no terminal): a random master password for the
+// new agent account, written to the keychain over stdin. Nobody types it and it
+// never reaches argv or output; the user gets it via the clipboard for signup.
+export async function generateKeychainSecret(service, label, confirm) {
+    const secret = randomBytes(24).toString("base64url");
+    const user = process.env.USER || process.env.LOGNAME || "";
+    const opts = { timeout: 30000, maxBuffer: 1024 * 1024 };
+    try {
+        if (process.platform === "darwin") {
+            // `security -i` reads the command from stdin, so the value is not in argv.
+            await runFile("security", ["-i"], opts, `add-generic-password -U -a "${user}" -s "${service}" -l "${label}"${confirm ? ' -T ""' : ""} -w "${secret}"\n`);
+            await runFile("security", ["find-generic-password", "-a", user, "-s", service], opts);
+        }
+        else {
+            await runFile("secret-tool", ["store", `--label=${label}`, "service", service, "account", user], opts, secret);
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+const CLIPBOARD_TOOLS = process.platform === "darwin"
+    ? [["pbcopy", [], "pbpaste", []]]
+    : [["wl-copy", [], "wl-paste", ["--no-newline"]], ["xclip", ["-selection", "clipboard"], "xclip", ["-selection", "clipboard", "-o"]]];
+export async function copyToClipboard(text) {
+    for (const [copy, args] of CLIPBOARD_TOOLS) {
+        try {
+            await runFile(copy, args, { timeout: 10000, maxBuffer: 1024 * 1024 }, text);
+            return true;
+        }
+        catch { }
+    }
+    return false;
+}
+// Empty the clipboard only if it still holds `text`.
+export async function clearClipboardIf(text) {
+    for (const [copy, copyArgs, paste, pasteArgs] of CLIPBOARD_TOOLS) {
+        try {
+            if ((await runFile(paste, pasteArgs, { timeout: 10000, maxBuffer: 1024 * 1024 })).stdout.trim() === text)
+                await runFile(copy, copyArgs, { timeout: 10000, maxBuffer: 1024 * 1024 }, "");
+            return;
+        }
+        catch { }
+    }
+}
+// `setup`: log keyshroud's own bw login in to the agent account. stdin and
+// stderr stay on the terminal so bw can ask for a two-step login code.
+export async function loginOwnAccount(email, master) {
+    const token = await new Promise((resolve, reject) => {
+        const child = spawn("bw", ["login", email, "--passwordenv", "BW_PASSWORD", "--raw"], { env: { ...process.env, BW_PASSWORD: master }, stdio: ["inherit", "pipe", "inherit"] });
+        let out = "";
+        child.stdout.on("data", (chunk) => { out += chunk; });
+        child.on("error", reject);
+        child.on("exit", (exit) => (exit === 0 && out.trim() ? resolve(out.trim()) : reject(new Error("bw login failed"))));
+    });
+    await writePrivateFile(SESSION_FILE, `${token}\n`);
+    process.env.BW_SESSION = token;
+    try {
+        await bw(["sync", "--quiet"], { session: token });
+    }
+    catch { }
+    invalidateSecretCache();
+    return token;
+}
+// `migrate`: read the items of the bw login the user had before setup (the
+// default bw data dir), then lock it again. The values stay in memory.
+export async function readPersonalItems() {
+    const master = await readKeychain(PERSONAL_KEYCHAIN_MASTER_SERVICE);
+    if (!master)
+        throw new Error(`Personal master password not in the keychain (${PERSONAL_KEYCHAIN_MASTER_SERVICE})`);
+    const env = (extra) => {
+        const out = {};
+        for (const [name, value] of Object.entries(process.env))
+            if (value !== undefined && !VAULT_ENV_KEYS.includes(name))
+                out[name] = value;
+        return { ...out, ...extra };
+    };
+    const token = (await runFile("bw", ["unlock", "--passwordenv", "BW_PASSWORD", "--raw"], { env: env({ BW_PASSWORD: master }), timeout: 30000, maxBuffer: 4 * 1024 * 1024 })).stdout.trim();
+    if (!token)
+        throw new Error("Personal vault unlock returned no session");
+    try {
+        const parsed = JSON.parse((await runFile("bw", ["list", "items"], { env: env({ BW_SESSION: token }), timeout: 120000, maxBuffer: 256 * 1024 * 1024 })).stdout);
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    finally {
+        try {
+            await runFile("bw", ["lock"], { env: env({}), timeout: 20000, maxBuffer: 1024 * 1024 });
+        }
+        catch { }
+    }
+}
+// A personal item as a new item for the agent account: no ids, folders,
+// organizations, history, attachments or per-item key (encrypted to the personal account).
+export async function copyItemToOwnVault(item) {
+    const copy = { ...item, favorite: false };
+    for (const key of ["id", "key", "object", "organizationId", "folderId", "collectionIds", "revisionDate", "creationDate", "deletedDate", "passwordHistory", "attachments"])
+        delete copy[key];
+    await bw(["create", "item"], { input: Buffer.from(JSON.stringify(copy), "utf8").toString("base64") });
+}
+export async function syncOwnVault() { await bw(["sync", "--quiet"]); invalidateSecretCache(); }
 // Forget the cached session and lock the bw CLI. The next resolve unlocks
 // again from the keychain.
 export async function lock() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keyshroud",
-  "version": "0.5.3",
+  "version": "0.6.0",
   "mcpName": "io.github.dinhkarate/keyshroud",
   "description": "Let AI coding agents use your secrets without ever seeing them. Self-hosted Vaultwarden/Bitwarden, masked output, MCP server, Claude Code + pi plugins.",
   "keywords": [

package/skills/keyshroud/SKILL.md

@@ -78,3 +78,6 @@ keyshroud scan .          # exits 1 and lists file:line NAME for any leaked valu
 `0` ok · `2` usage · `3` vault locked/unavailable (ask the user to run
 `keyshroud unlock`) · `4` secret missing or item name ambiguous · `5` would
 overwrite existing state.
+
+`setup` and `migrate` are for the user: they touch the personal vault. If an item
+is missing after `setup`, ask the user to run `keyshroud migrate --item "NAME"`.

package/src/cli.ts

@@ -32,6 +32,11 @@ Secrets
   unwire --env NAME [--target pi|omp|both]
 
 Vault
+  setup --email EMAIL [--server URL] [--confirm-unlock] [--registered]
+                                   Give ${BRAND.name} its own bw login on a dedicated agent account
+  migrate [--item NAME]... [--env-file F]... [--yes]
+                                   Copy the wired items from your personal vault to that account
+                                   (dry run unless --yes; prints names only)
   status | unlock | lock | doctor
 
 Agents
@@ -196,6 +201,103 @@ async function scan(paths: string[]): Promise<void> {
 
 interface ImportRow { entry: DotenvEntry; kind: "new" | "reuse" | "conflict" | "literal" | "ref"; item?: string; note?: string }
 
+// setup: keyshroud gets its own bw login (CONFIG_DIR/bw) on a separate agent
+// account, so agents never get a session for the user's personal vault.
+async function setupCommand(args: string[]): Promise<void> {
+  requireKnownFlags(args, ["--email", "--server"], ["--confirm-unlock", "--registered"]);
+  const email = valueAfter(args, "--email");
+  if (!email || !/^[^\s@]+@[^\s@]+$/.test(email)) fail("setup needs --email for a separate agent account (not your personal one)", 2);
+  let server = valueAfter(args, "--server");
+  if (!server) { try { server = (JSON.parse(await core.bw(["status"])) as { serverUrl?: string }).serverUrl ?? undefined; } catch {} }
+  if (!server || !/^https:\/\//.test(server)) fail("setup needs --server https://… (no bw server is configured)", 2);
+  const confirm = args.includes("--confirm-unlock");
+  if (confirm && process.platform !== "darwin") fail("--confirm-unlock needs the macOS keychain; Linux secret-tool cannot ask before each read", 2);
+  core.useOwnBwLogin();
+  await mkdir(core.OWN_BW_DIR, { recursive: true, mode: 0o700 });
+  const status = JSON.parse(await core.bw(["status"]).catch(() => "{}")) as { status?: string; userEmail?: string };
+  if (status.userEmail && status.userEmail.toLowerCase() !== email.toLowerCase()) fail(`${BRAND.name}'s bw login already belongs to ${status.userEmail}; remove ${core.OWN_BW_DIR} to start over`, 5);
+  const loggedOut = !status.status || status.status === "unauthenticated";
+  if (loggedOut) await core.bw(["config", "server", server]);
+  await unlink(core.SESSION_FILE).catch(() => {});
+  console.log(`${BRAND.name} now keeps its own bw login in ${core.OWN_BW_DIR}; your personal bw login is untouched.`);
+  const signupUrl = `${server.replace(/\/$/, "")}/#/signup?email=${encodeURIComponent(email)}`;
+  if (!process.stdin.isTTY) {
+    // An agent's shell: nothing can be typed, so keyshroud picks the password.
+    const hasEntry = Boolean(await core.readKeychain(core.KEYCHAIN_MASTER_SERVICE));
+    if (!loggedOut && (confirm || !hasEntry)) fail(`The agent account is already logged in; run \`${BRAND.bin} setup\` in a terminal to store its password`, 2);
+    if (loggedOut && !args.includes("--registered")) {
+      if (!hasEntry && !(await core.generateKeychainSecret(core.KEYCHAIN_MASTER_SERVICE, `${BRAND.name} agent account`, confirm))) fail("Could not store a generated password (needs macOS security or Linux secret-tool)", 3);
+      const master = await core.readKeychain(core.KEYCHAIN_MASTER_SERVICE);
+      if (!master || !(await core.copyToClipboard(master))) fail(`No clipboard tool; run \`${BRAND.bin} setup\` in a terminal instead`, 3);
+      spawn(process.platform === "darwin" ? "open" : "xdg-open", [signupUrl], { stdio: "ignore" }).on("error", () => {});
+      console.log(`A random master password for ${email} is in the keychain (${core.KEYCHAIN_MASTER_SERVICE}) and on the clipboard.`);
+      console.log(`Create the account at ${signupUrl} and paste it into both password fields.`);
+      console.log(`Then: ${BRAND.bin} setup --email ${email} --registered`);
+      return;
+    }
+  }
+  if (loggedOut && !args.includes("--registered")) {
+    const url = signupUrl;
+    console.log(`1. Create the agent account ${email}: ${url}`);
+    console.log("   Pick a new master password, not your personal one.");
+    spawn(process.platform === "darwin" ? "open" : "xdg-open", [url], { stdio: "ignore" }).on("error", () => {});
+    process.stdout.write("   Press Enter once the account exists. ");
+    await new Promise((resolve) => process.stdin.once("data", resolve)); process.stdin.pause();
+  }
+  if (confirm || !(await core.readKeychain(core.KEYCHAIN_MASTER_SERVICE))) {
+    console.log(`2. Type the agent account's master password for the keychain entry ${core.KEYCHAIN_MASTER_SERVICE}${confirm ? " (macOS will ask before every unlock)" : ""}:`);
+    if (!(await core.storeKeychainInteractive(core.KEYCHAIN_MASTER_SERVICE, `${BRAND.name} agent account`, confirm))) fail("Could not store it (needs macOS security or Linux secret-tool)", 3);
+  }
+  const master = await core.readKeychain(core.KEYCHAIN_MASTER_SERVICE);
+  if (!master) fail(`The keychain entry ${core.KEYCHAIN_MASTER_SERVICE} is missing or access was denied`, 3);
+  if (loggedOut) await core.loginOwnAccount(email, master); else await core.ensureSession();
+  await core.clearClipboardIf(master);
+  await core.audit("setup", [], "cli");
+  console.log(`ready: bw login=${email} (own). Next: \`${BRAND.bin} migrate\` copies the wired secrets from your personal vault.`);
+}
+
+// migrate: copy the items that wired names (and env files) reference from the
+// personal vault into the agent account. Same names, so references keep working.
+async function migrateCommand(args: string[]): Promise<void> {
+  requireKnownFlags(args, ["--item", "--env-file"], ["--yes"]);
+  if (!core.OWN_BW_LOGIN) fail(`Run \`${BRAND.bin} setup\` first: migrate copies items into ${BRAND.name}'s own agent account`, 2);
+  const entries = [...await core.authEnvEntries()];
+  for (const file of valuesAfter(args, "--env-file")) entries.push(...await core.envFileEntries(file));
+  const names = new Map<string, string>();
+  for (const entry of entries) { try { const ref = parseRef(entry.raw); if (ref) names.set(ref.item.toLowerCase(), ref.item); } catch {} }
+  for (const name of valuesAfter(args, "--item")) names.set(name.toLowerCase(), name);
+  await core.ensureSession();
+  const own = await core.findItems("");
+  const personal = await core.readPersonalItems();
+  type Row = { name: string; state: "copy" | "present" | "missing" | "ambiguous"; item?: Record<string, unknown> };
+  const rows: Row[] = [...names.values()].sort().map((name) => {
+    if (own.some((item) => item.name.toLowerCase() === name.toLowerCase() || item.id === name)) return { name, state: "present" };
+    const matches = personal.filter((item) => String(item.name ?? "").toLowerCase() === name.toLowerCase() || item.id === name);
+    return matches.length === 1 ? { name, state: "copy", item: matches[0] } : { name, state: matches.length ? "ambiguous" : "missing" };
+  });
+  const width = Math.max(4, ...rows.map((row) => row.name.length));
+  console.log("migrate plan (personal vault -> agent account):");
+  for (const row of rows) console.log(`  ${row.name.padEnd(width)}  ${row.state === "present" ? "already in the agent account" : row.state}`);
+  const count = (state: Row["state"]) => rows.filter((row) => row.state === state).length;
+  console.log(`${count("copy")} to copy, ${count("present")} already there, ${count("missing")} missing, ${count("ambiguous")} ambiguous`);
+  if (!args.includes("--yes")) { console.log("Dry run: nothing copied. Re-run with --yes."); return; }
+  const copied: string[] = [];
+  for (const row of rows.filter((entry) => entry.state === "copy")) {
+    try { await core.copyItemToOwnVault(row.item!); copied.push(row.name); }
+    catch { if (copied.length) console.error(`Copied before the failure: ${copied.join(", ")}`); fail(`Failed to copy ${row.name}`, 3); }
+  }
+  await core.syncOwnVault();
+  const after = await core.findItems("");
+  const unverified = copied.filter((name) => !after.some((item) => item.name.toLowerCase() === name.toLowerCase()));
+  await core.audit("migrate", copied, "cli");
+  await core.refreshRedactIndex();
+  console.log(`copied ${copied.length} item(s) into the agent account; references are unchanged.`);
+  const cut = process.platform === "darwin" ? `security delete-generic-password -s ${core.PERSONAL_KEYCHAIN_MASTER_SERVICE}` : `secret-tool clear service ${core.PERSONAL_KEYCHAIN_MASTER_SERVICE} account "$USER"`;
+  console.log(`Your personal master password is still in the keychain, where any program running as you can read it. Once you no longer need it there: ${cut}`);
+  if (unverified.length) fail(`Not found after copying: ${unverified.join(", ")}`, 4);
+  if (count("missing") || count("ambiguous")) process.exitCode = 4;
+}
+
 async function importCommand(args: string[]): Promise<void> {
   requireKnownFlags(args, ["--from", "--out", "--prefix", "--only", "--skip"], ["--yes", "--replace", "--force"]);
   const from = valueAfter(args, "--from") ?? ".env";
@@ -353,6 +455,8 @@ async function main(): Promise<void> {
       return;
     }
     if (command === "import") { await importCommand(args); return; }
+    if (command === "setup") { await setupCommand(args); return; }
+    if (command === "migrate") { await migrateCommand(args); return; }
     if (command === "rotate") {
       requireKnownFlags(args, ["--item"], ["--stdin", "--dialog"]);
       const itemName = valueAfter(args, "--item"); if (!itemName) fail(usage, 2);
@@ -402,7 +506,7 @@ async function main(): Promise<void> {
     if (command === "doctor") {
       requireKnownFlags(args, []);
       try { await core.ensureSession(); } catch {}
-      const s = await core.getStatus(); console.log(`bw version=${s.version ?? "missing (install @bitwarden/cli)"}`); console.log(`bw server=${s.serverUrl ?? "unconfigured (run: bw config server <url>)"}`); console.log(`session=${s.status}`);
+      const s = await core.getStatus(); console.log(`bw login=${core.OWN_BW_LOGIN ? `own agent account (${core.OWN_BW_DIR})` : `shared with your personal bw (run: ${BRAND.bin} setup)`}`); console.log(`bw version=${s.version ?? "missing (install @bitwarden/cli)"}`); console.log(`bw server=${s.serverUrl ?? "unconfigured (run: bw config server <url>)"}`); console.log(`session=${s.status}`);
       for (const [service, present] of Object.entries(await core.keychainPresence())) console.log(`keychain ${service}=${present ? "present" : "missing"}`);
       for (const path of [targetPaths.omp, targetPaths.pi]) for (const name of Object.keys(await core.readAuthEntries(path))) console.log(`${path} ${name} resolved=${(await authValue(name)) ? "yes" : "no"}`);
       console.log(`redact index=${(await core.readRedactIndex()) ? "present" : "missing"}`);

package/src/core.ts

@@ -1,7 +1,8 @@
 // Runtime-neutral core: no pi/omp/Claude Code imports. Every caller (agent
 // extensions, CLI, MCP server, hooks) goes through these functions.
-import { execFile } from "node:child_process";
+import { execFile, spawn } from "node:child_process";
 import { randomBytes } from "node:crypto";
+import { existsSync } from "node:fs";
 import { appendFile, chmod, mkdir, readFile, realpath, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join, dirname } from "node:path";
@@ -21,9 +22,25 @@ export const SESSION_FILE = join(CONFIG_DIR, "session");
 export const MASTER_PASSWORD_FILE = join(CONFIG_DIR, "master-password");
 export const REDACT_INDEX_FILE = join(CONFIG_DIR, "redact-index.json");
 export const AUDIT_FILE = join(CONFIG_DIR, "audit.jsonl");
-export const KEYCHAIN_MASTER_SERVICE = setting("KEYCHAIN_MASTER") ?? "vaultwarden-master-password";
-export const KEYCHAIN_CLIENT_ID_SERVICE = setting("KEYCHAIN_CLIENT_ID") ?? "vaultwarden-api-client-id";
-export const KEYCHAIN_CLIENT_SECRET_SERVICE = setting("KEYCHAIN_CLIENT_SECRET") ?? "vaultwarden-api-client-secret";
+
+// After `setup`, keyshroud keeps its own bw login (a dedicated agent account) in
+// CONFIG_DIR/bw, with its own keychain entries, so the user's personal bw login
+// and vault are never unlocked. Without it, keyshroud shares the default bw login.
+export const OWN_BW_DIR = join(CONFIG_DIR, "bw");
+export const PERSONAL_KEYCHAIN_MASTER_SERVICE = setting("PERSONAL_KEYCHAIN_MASTER") ?? "vaultwarden-master-password";
+export let OWN_BW_LOGIN = false;
+export let KEYCHAIN_MASTER_SERVICE = setting("KEYCHAIN_MASTER") ?? PERSONAL_KEYCHAIN_MASTER_SERVICE;
+export let KEYCHAIN_CLIENT_ID_SERVICE = setting("KEYCHAIN_CLIENT_ID") ?? "vaultwarden-api-client-id";
+export let KEYCHAIN_CLIENT_SECRET_SERVICE = setting("KEYCHAIN_CLIENT_SECRET") ?? "vaultwarden-api-client-secret";
+
+export function useOwnBwLogin(): void {
+  OWN_BW_LOGIN = true;
+  process.env.BITWARDENCLI_APPDATA_DIR = OWN_BW_DIR;
+  KEYCHAIN_MASTER_SERVICE = setting("KEYCHAIN_MASTER") ?? `${BRAND.bin}-master-password`;
+  KEYCHAIN_CLIENT_ID_SERVICE = setting("KEYCHAIN_CLIENT_ID") ?? `${BRAND.bin}-api-client-id`;
+  KEYCHAIN_CLIENT_SECRET_SERVICE = setting("KEYCHAIN_CLIENT_SECRET") ?? `${BRAND.bin}-api-client-secret`;
+}
+if (!process.env.BITWARDENCLI_APPDATA_DIR && existsSync(join(OWN_BW_DIR, "data.json"))) useOwnBwLogin();
 
 export const PROVIDER_KEYS: ReadonlySet<string> = new Set([
   "anthropic", "openai", "azure-openai-responses", "deepseek", "google", "mistral",
@@ -67,7 +84,7 @@ export const referenceFor = legacyRefFor;
 
 // Vault credentials never reach commands run on the agent's behalf: with the
 // session token a child could dump the whole vault, defeating `--only`.
-export const VAULT_ENV_KEYS: readonly string[] = ["BW_SESSION", "BW_PASSWORD", "BW_CLIENTID", "BW_CLIENTSECRET"];
+export const VAULT_ENV_KEYS: readonly string[] = ["BW_SESSION", "BW_PASSWORD", "BW_CLIENTID", "BW_CLIENTSECRET", "BITWARDENCLI_APPDATA_DIR"];
 
 export function childEnv(extra: Record<string, string> = {}): Record<string, string> {
   const env: Record<string, string> = {};
@@ -205,10 +222,12 @@ export async function resolveRef(ref: SecretRef): Promise<string | null> {
   }
 }
 
-async function readKeychain(service: string): Promise<string | null> {
+// The timeout leaves room for a macOS "allow access" prompt when the entry was
+// stored with `setup --confirm-unlock`; a missing entry still fails at once.
+export async function readKeychain(service: string): Promise<string | null> {
   const user = process.env.USER || process.env.LOGNAME || "";
   try {
-    const result = await runFile("security", ["find-generic-password", "-a", user, "-s", service, "-w"], { timeout: 10000, maxBuffer: 1024 * 1024 });
+    const result = await runFile("security", ["find-generic-password", "-a", user, "-s", service, "-w"], { timeout: 120000, maxBuffer: 1024 * 1024 });
     return result.stdout.trim() || null;
   } catch {}
   try {
@@ -294,6 +313,114 @@ async function ensureSessionInner(existing: string | undefined): Promise<string>
   return token;
 }
 
+// Store a keychain entry by letting the OS tool prompt for the value on the
+// user's terminal, so keyshroud never holds it in argv. `confirm` (macOS) trusts
+// no app, so every later read asks the user first.
+export async function storeKeychainInteractive(service: string, label: string, confirm: boolean): Promise<boolean> {
+  const user = process.env.USER || process.env.LOGNAME || "";
+  const attempts: Array<[string, string[]]> = process.platform === "darwin"
+    ? [["security", ["add-generic-password", "-U", "-a", user, "-s", service, "-l", label, ...(confirm ? ["-T", ""] : []), "-w"]]]
+    : [["secret-tool", ["store", `--label=${label}`, "service", service, "account", user]]];
+  // -U keeps an existing entry's access list, so an ask-every-time entry is recreated.
+  if (process.platform === "darwin" && confirm) await runFile("security", ["delete-generic-password", "-a", user, "-s", service], { timeout: 10000, maxBuffer: 1024 * 1024 }).catch(() => {});
+  for (const [command, args] of attempts) {
+    const code = await new Promise<number | null>((resolve) => {
+      const child = spawn(command, args, { stdio: "inherit" });
+      child.on("error", () => resolve(null));
+      child.on("exit", (exit) => resolve(exit));
+    });
+    if (code === 0) return true;
+  }
+  return false;
+}
+
+// `setup` from an agent's shell (no terminal): a random master password for the
+// new agent account, written to the keychain over stdin. Nobody types it and it
+// never reaches argv or output; the user gets it via the clipboard for signup.
+export async function generateKeychainSecret(service: string, label: string, confirm: boolean): Promise<boolean> {
+  const secret = randomBytes(24).toString("base64url");
+  const user = process.env.USER || process.env.LOGNAME || "";
+  const opts = { timeout: 30000, maxBuffer: 1024 * 1024 };
+  try {
+    if (process.platform === "darwin") {
+      // `security -i` reads the command from stdin, so the value is not in argv.
+      await runFile("security", ["-i"], opts, `add-generic-password -U -a "${user}" -s "${service}" -l "${label}"${confirm ? ' -T ""' : ""} -w "${secret}"\n`);
+      await runFile("security", ["find-generic-password", "-a", user, "-s", service], opts);
+    } else {
+      await runFile("secret-tool", ["store", `--label=${label}`, "service", service, "account", user], opts, secret);
+    }
+    return true;
+  } catch { return false; }
+}
+
+const CLIPBOARD_TOOLS: Array<[string, string[], string, string[]]> = process.platform === "darwin"
+  ? [["pbcopy", [], "pbpaste", []]]
+  : [["wl-copy", [], "wl-paste", ["--no-newline"]], ["xclip", ["-selection", "clipboard"], "xclip", ["-selection", "clipboard", "-o"]]];
+
+export async function copyToClipboard(text: string): Promise<boolean> {
+  for (const [copy, args] of CLIPBOARD_TOOLS) {
+    try { await runFile(copy, args, { timeout: 10000, maxBuffer: 1024 * 1024 }, text); return true; } catch {}
+  }
+  return false;
+}
+
+// Empty the clipboard only if it still holds `text`.
+export async function clearClipboardIf(text: string): Promise<void> {
+  for (const [copy, copyArgs, paste, pasteArgs] of CLIPBOARD_TOOLS) {
+    try {
+      if ((await runFile(paste, pasteArgs, { timeout: 10000, maxBuffer: 1024 * 1024 })).stdout.trim() === text) await runFile(copy, copyArgs, { timeout: 10000, maxBuffer: 1024 * 1024 }, "");
+      return;
+    } catch {}
+  }
+}
+
+// `setup`: log keyshroud's own bw login in to the agent account. stdin and
+// stderr stay on the terminal so bw can ask for a two-step login code.
+export async function loginOwnAccount(email: string, master: string): Promise<string> {
+  const token = await new Promise<string>((resolve, reject) => {
+    const child = spawn("bw", ["login", email, "--passwordenv", "BW_PASSWORD", "--raw"], { env: { ...process.env, BW_PASSWORD: master }, stdio: ["inherit", "pipe", "inherit"] });
+    let out = "";
+    child.stdout.on("data", (chunk: Buffer) => { out += chunk; });
+    child.on("error", reject);
+    child.on("exit", (exit) => (exit === 0 && out.trim() ? resolve(out.trim()) : reject(new Error("bw login failed"))));
+  });
+  await writePrivateFile(SESSION_FILE, `${token}\n`);
+  process.env.BW_SESSION = token;
+  try { await bw(["sync", "--quiet"], { session: token }); } catch {}
+  invalidateSecretCache();
+  return token;
+}
+
+// `migrate`: read the items of the bw login the user had before setup (the
+// default bw data dir), then lock it again. The values stay in memory.
+export async function readPersonalItems(): Promise<Array<Record<string, unknown>>> {
+  const master = await readKeychain(PERSONAL_KEYCHAIN_MASTER_SERVICE);
+  if (!master) throw new Error(`Personal master password not in the keychain (${PERSONAL_KEYCHAIN_MASTER_SERVICE})`);
+  const env = (extra: Record<string, string>) => {
+    const out: Record<string, string> = {};
+    for (const [name, value] of Object.entries(process.env)) if (value !== undefined && !VAULT_ENV_KEYS.includes(name)) out[name] = value;
+    return { ...out, ...extra };
+  };
+  const token = (await runFile("bw", ["unlock", "--passwordenv", "BW_PASSWORD", "--raw"], { env: env({ BW_PASSWORD: master }), timeout: 30000, maxBuffer: 4 * 1024 * 1024 })).stdout.trim();
+  if (!token) throw new Error("Personal vault unlock returned no session");
+  try {
+    const parsed = JSON.parse((await runFile("bw", ["list", "items"], { env: env({ BW_SESSION: token }), timeout: 120000, maxBuffer: 256 * 1024 * 1024 })).stdout) as unknown;
+    return Array.isArray(parsed) ? parsed as Array<Record<string, unknown>> : [];
+  } finally {
+    try { await runFile("bw", ["lock"], { env: env({}), timeout: 20000, maxBuffer: 1024 * 1024 }); } catch {}
+  }
+}
+
+// A personal item as a new item for the agent account: no ids, folders,
+// organizations, history, attachments or per-item key (encrypted to the personal account).
+export async function copyItemToOwnVault(item: Record<string, unknown>): Promise<void> {
+  const copy: Record<string, unknown> = { ...item, favorite: false };
+  for (const key of ["id", "key", "object", "organizationId", "folderId", "collectionIds", "revisionDate", "creationDate", "deletedDate", "passwordHistory", "attachments"]) delete copy[key];
+  await bw(["create", "item"], { input: Buffer.from(JSON.stringify(copy), "utf8").toString("base64") });
+}
+
+export async function syncOwnVault(): Promise<void> { await bw(["sync", "--quiet"]); invalidateSecretCache(); }
+
 // Forget the cached session and lock the bw CLI. The next resolve unlocks
 // again from the keychain.
 export async function lock(): Promise<void> {