sealkeep 0.5.0

package/dist/src/secrets.d.ts

@@ -0,0 +1,86 @@
+import type { GdriveCredentials } from "./providers/gdrive.js";
+export type SecretRef = {
+    service: string;
+    account: string;
+};
+export type BackendName = "macos-keychain" | "secret-service" | "windows-dpapi" | "file";
+export interface SecretBackend {
+    readonly name: BackendName;
+    /** True when this backend can actually be used on this machine right now. */
+    available(): Promise<boolean>;
+    get(ref: SecretRef): Promise<string | null>;
+    set(ref: SecretRef, value: string): Promise<void>;
+    delete(ref: SecretRef): Promise<void>;
+}
+/**
+ * Owner-only file storage. This is the documented fallback when no OS keystore is
+ * present; it refuses to read a secret whose file is readable by group or others.
+ */
+export declare class FileSecretBackend implements SecretBackend {
+    private readonly root;
+    readonly name: "file";
+    constructor(root: string);
+    private path;
+    available(): Promise<boolean>;
+    get(ref: SecretRef): Promise<string | null>;
+    set(ref: SecretRef, value: string): Promise<void>;
+    delete(ref: SecretRef): Promise<void>;
+}
+export declare function secretBackends(dataDir: string): SecretBackend[];
+/**
+ * Picks the strongest backend this machine supports. The file fallback always
+ * qualifies. `VAULTLINE_SECRET_BACKEND` pins the choice, which is how a test suite
+ * or a sandboxed environment stays out of the real OS keystore.
+ */
+export declare function chooseBackend(dataDir: string, preferred?: BackendName, env?: NodeJS.ProcessEnv): Promise<SecretBackend>;
+export type ProviderCredentials = {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken?: string;
+} | {
+    clientEmail: string;
+    privateKey: string;
+} | GdriveCredentials;
+/**
+ * Remembering the recovery phrase.
+ *
+ * This is opt-in and it is a real trade-off, so it is stated plainly rather than
+ * buried: a phrase in the OS keystore is readable by anything running as this user
+ * once the account is unlocked. That is the same bargain a password manager or a
+ * synced-folder client makes, and it is what lets the background service seal
+ * sessions without a human pasting a secret on every boot.
+ *
+ * The written-down phrase remains the disaster-recovery path. This copy is a
+ * convenience for one machine and is never uploaded, synced, or included in a backup
+ * of the vault directory.
+ */
+export declare function rememberRecoveryPhrase(dataDir: string, vaultId: string, phrase: string, preferred?: BackendName): Promise<{
+    backend: BackendName;
+}>;
+export declare function recallRecoveryPhrase(dataDir: string, vaultId: string, preferred?: BackendName): Promise<string | null>;
+export declare function forgetRecoveryPhrase(dataDir: string, vaultId: string, preferred?: BackendName): Promise<{
+    backend: BackendName;
+}>;
+/**
+ * Where every command looks for the phrase, in order: an explicit flag, the
+ * environment, then this machine's keystore. Returns null rather than throwing so
+ * callers can give an instruction instead of a stack trace.
+ *
+ * The vault password (password-lock.ts) is deliberately not a source here. A
+ * password is exchanged for the phrase at an explicit moment — a prompt, or the
+ * unlock endpoint — never resolved ambiently, because an ambient password would
+ * quietly become a second phrase: one more thing lying around that opens
+ * everything, without the keystore's opt-in or its stated trade-off.
+ */
+export declare function resolveRecoveryPhrase(dataDir: string, vaultId: string, explicit?: string, env?: NodeJS.ProcessEnv, preferred?: BackendName): Promise<string | null>;
+/**
+ * Provider credentials are addressed by storage config id, never by bucket name,
+ * so rotating a config cannot silently reuse an old credential.
+ */
+export declare function storeProviderCredentials(dataDir: string, storageConfigId: string, credentials: ProviderCredentials, preferred?: BackendName): Promise<{
+    backend: BackendName;
+}>;
+export declare function loadProviderCredentials(dataDir: string, storageConfigId: string, preferred?: BackendName): Promise<ProviderCredentials>;
+export declare function deleteProviderCredentials(dataDir: string, storageConfigId: string, preferred?: BackendName): Promise<{
+    backend: BackendName;
+}>;

package/dist/src/secrets.js

@@ -0,0 +1,220 @@
+import { execFile } from "node:child_process";
+import { chmod, mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { platform } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { fail } from "./errors.js";
+const run = promisify(execFile);
+async function commandExists(command) {
+    try {
+        await run(platform() === "win32" ? "where" : "which", [command]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * macOS Keychain.
+ *
+ * Note: `security add-generic-password` takes the secret as an argument, so it is
+ * briefly visible in this user's own process list. Anyone who can see it can also
+ * read the keychain as that user, so this does not widen the trust boundary — but it
+ * is why writes go through a short-lived process and are never shell-interpolated.
+ */
+class MacosKeychain {
+    name = "macos-keychain";
+    async available() { return platform() === "darwin" && (await commandExists("security")); }
+    async get(ref) {
+        try {
+            return (await run("security", ["find-generic-password", "-s", ref.service, "-a", ref.account, "-w"])).stdout.trim();
+        }
+        catch {
+            return null;
+        }
+    }
+    async set(ref, value) {
+        await run("security", ["add-generic-password", "-U", "-s", ref.service, "-a", ref.account, "-w", value]);
+    }
+    async delete(ref) {
+        try {
+            await run("security", ["delete-generic-password", "-s", ref.service, "-a", ref.account]);
+        }
+        catch { /* already absent */ }
+    }
+}
+/** Freedesktop Secret Service via `secret-tool`, which reads the secret from stdin. */
+class SecretService {
+    name = "secret-service";
+    async available() { return platform() === "linux" && (await commandExists("secret-tool")); }
+    async get(ref) {
+        try {
+            return (await run("secret-tool", ["lookup", "service", ref.service, "account", ref.account])).stdout.trim() || null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async set(ref, value) {
+        await new Promise((resolve, reject) => {
+            const child = execFile("secret-tool", ["store", "--label", `${ref.service}:${ref.account}`, "service", ref.service, "account", ref.account], (error) => error ? reject(error) : resolve());
+            child.stdin?.end(value);
+        });
+    }
+    async delete(ref) {
+        try {
+            await run("secret-tool", ["clear", "service", ref.service, "account", ref.account]);
+        }
+        catch { /* already absent */ }
+    }
+}
+/**
+ * Windows DPAPI through PowerShell. The ciphertext is bound to the current user
+ * account, so the stored file is useless to any other user on the machine.
+ */
+class WindowsDpapi {
+    root;
+    name = "windows-dpapi";
+    constructor(root) {
+        this.root = root;
+    }
+    path(ref) { return join(this.root, `${encodeURIComponent(ref.service)}.${encodeURIComponent(ref.account)}.dpapi`); }
+    async available() { return platform() === "win32" && (await commandExists("powershell")); }
+    async get(ref) {
+        const stored = await readFile(this.path(ref), "utf8").catch(() => null);
+        if (!stored)
+            return null;
+        const script = `$secure = ConvertTo-SecureString -String $env:VL_BLOB; [Runtime.InteropServices.Marshal]::PtrToStringAuto([Runtime.InteropServices.Marshal]::SecureStringToBSTR($secure))`;
+        const { stdout } = await run("powershell", ["-NoProfile", "-NonInteractive", "-Command", script], { env: { ...process.env, VL_BLOB: stored.trim() } });
+        return stdout.trim();
+    }
+    async set(ref, value) {
+        const script = `ConvertFrom-SecureString -SecureString (ConvertTo-SecureString -String $env:VL_SECRET -AsPlainText -Force)`;
+        const { stdout } = await run("powershell", ["-NoProfile", "-NonInteractive", "-Command", script], { env: { ...process.env, VL_SECRET: value } });
+        await mkdir(this.root, { recursive: true });
+        await writeFile(this.path(ref), stdout.trim(), { mode: 0o600 });
+    }
+    async delete(ref) { await rm(this.path(ref), { force: true }); }
+}
+/**
+ * Owner-only file storage. This is the documented fallback when no OS keystore is
+ * present; it refuses to read a secret whose file is readable by group or others.
+ */
+export class FileSecretBackend {
+    root;
+    name = "file";
+    constructor(root) {
+        this.root = root;
+    }
+    path(ref) { return join(this.root, `${encodeURIComponent(ref.service)}.${encodeURIComponent(ref.account)}.secret`); }
+    async available() { return true; }
+    async get(ref) {
+        const path = this.path(ref);
+        const info = await stat(path).catch(() => null);
+        if (!info)
+            return null;
+        if (platform() !== "win32" && (info.mode & 0o077) !== 0) {
+            fail("forbidden", `Refusing to read ${path}: mode ${(info.mode & 0o777).toString(8)} allows other users to read it. Run: chmod 600 ${path}`, { path });
+        }
+        return (await readFile(path, "utf8")).trim() || null;
+    }
+    async set(ref, value) {
+        await mkdir(this.root, { recursive: true, mode: 0o700 });
+        await writeFile(this.path(ref), `${value}\n`, { mode: 0o600 });
+        await chmod(this.path(ref), 0o600);
+    }
+    async delete(ref) { await rm(this.path(ref), { force: true }); }
+}
+export function secretBackends(dataDir) {
+    return [new MacosKeychain(), new SecretService(), new WindowsDpapi(join(dataDir, "secrets")), new FileSecretBackend(join(dataDir, "secrets"))];
+}
+/**
+ * Picks the strongest backend this machine supports. The file fallback always
+ * qualifies. `VAULTLINE_SECRET_BACKEND` pins the choice, which is how a test suite
+ * or a sandboxed environment stays out of the real OS keystore.
+ */
+export async function chooseBackend(dataDir, preferred, env = process.env) {
+    preferred = preferred ?? env.VAULTLINE_SECRET_BACKEND;
+    const backends = secretBackends(dataDir);
+    if (preferred) {
+        const chosen = backends.find((backend) => backend.name === preferred);
+        if (!chosen)
+            fail("invalid_argument", `Unknown secret backend: ${preferred}`);
+        if (!(await chosen.available()))
+            fail("invalid_argument", `Secret backend ${preferred} is not available on this machine`);
+        return chosen;
+    }
+    for (const backend of backends)
+        if (await backend.available())
+            return backend;
+    return new FileSecretBackend(join(dataDir, "secrets"));
+}
+const SERVICE = "vaultline-provider";
+const PHRASE_SERVICE = "vaultline-recovery";
+/**
+ * Remembering the recovery phrase.
+ *
+ * This is opt-in and it is a real trade-off, so it is stated plainly rather than
+ * buried: a phrase in the OS keystore is readable by anything running as this user
+ * once the account is unlocked. That is the same bargain a password manager or a
+ * synced-folder client makes, and it is what lets the background service seal
+ * sessions without a human pasting a secret on every boot.
+ *
+ * The written-down phrase remains the disaster-recovery path. This copy is a
+ * convenience for one machine and is never uploaded, synced, or included in a backup
+ * of the vault directory.
+ */
+export async function rememberRecoveryPhrase(dataDir, vaultId, phrase, preferred) {
+    const backend = await chooseBackend(dataDir, preferred);
+    await backend.set({ service: PHRASE_SERVICE, account: vaultId }, phrase);
+    return { backend: backend.name };
+}
+export async function recallRecoveryPhrase(dataDir, vaultId, preferred) {
+    const backend = await chooseBackend(dataDir, preferred);
+    return backend.get({ service: PHRASE_SERVICE, account: vaultId });
+}
+export async function forgetRecoveryPhrase(dataDir, vaultId, preferred) {
+    const backend = await chooseBackend(dataDir, preferred);
+    await backend.delete({ service: PHRASE_SERVICE, account: vaultId });
+    return { backend: backend.name };
+}
+/**
+ * Where every command looks for the phrase, in order: an explicit flag, the
+ * environment, then this machine's keystore. Returns null rather than throwing so
+ * callers can give an instruction instead of a stack trace.
+ *
+ * The vault password (password-lock.ts) is deliberately not a source here. A
+ * password is exchanged for the phrase at an explicit moment — a prompt, or the
+ * unlock endpoint — never resolved ambiently, because an ambient password would
+ * quietly become a second phrase: one more thing lying around that opens
+ * everything, without the keystore's opt-in or its stated trade-off.
+ */
+export async function resolveRecoveryPhrase(dataDir, vaultId, explicit, env = process.env, preferred) {
+    return explicit ?? env.VAULTLINE_RECOVERY_PHRASE ?? (await recallRecoveryPhrase(dataDir, vaultId, preferred).catch(() => null));
+}
+/**
+ * Provider credentials are addressed by storage config id, never by bucket name,
+ * so rotating a config cannot silently reuse an old credential.
+ */
+export async function storeProviderCredentials(dataDir, storageConfigId, credentials, preferred) {
+    const backend = await chooseBackend(dataDir, preferred);
+    await backend.set({ service: SERVICE, account: storageConfigId }, JSON.stringify(credentials));
+    return { backend: backend.name };
+}
+export async function loadProviderCredentials(dataDir, storageConfigId, preferred) {
+    const backend = await chooseBackend(dataDir, preferred);
+    const raw = await backend.get({ service: SERVICE, account: storageConfigId });
+    if (!raw)
+        fail("signer_not_configured", `No stored credentials for storage config ${storageConfigId}. Run: sealkeep storage credentials set`, { storageConfigId, backend: backend.name });
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return fail("invalid_argument", `Stored credentials for ${storageConfigId} are not readable JSON`, { storageConfigId });
+    }
+}
+export async function deleteProviderCredentials(dataDir, storageConfigId, preferred) {
+    const backend = await chooseBackend(dataDir, preferred);
+    await backend.delete({ service: SERVICE, account: storageConfigId });
+    return { backend: backend.name };
+}

package/dist/src/service.d.ts

@@ -0,0 +1,73 @@
+export type ServiceKind = "launchd" | "systemd" | "schtasks" | "unsupported";
+export type ServiceOptions = {
+    dataDir: string;
+    /** The command the service runs. Defaults to this install's `sealkeep daemon`. */
+    executable?: string;
+    args?: string[];
+    home?: string;
+    platform?: NodeJS.Platform;
+    /**
+     * Environment the service runs with.
+     *
+     * A service manager starts the daemon with a bare environment — it does not
+     * inherit the shell that installed it. The upload pass is gated on
+     * `VAULTLINE_ENABLE_SIGNER`, so a service definition that carries no
+     * environment produces a daemon that seals sessions, uploads nothing, and
+     * therefore reclaims nothing, logging one line to `daemon.log` that nobody
+     * reads. Whatever the installer decides uploads need, it has to be written
+     * into the unit.
+     */
+    environment?: Record<string, string>;
+    /** Injected in tests so no real service manager is touched. */
+    exec?: (file: string, args: string[]) => Promise<unknown>;
+};
+export type ServicePlan = {
+    kind: ServiceKind;
+    label: string;
+    path: string;
+    contents: string;
+    enable: [string, string[]][];
+    disable: [string, string[]][];
+};
+export declare const SERVICE_LABEL = "ai.vaultline.agent";
+/**
+ * Describes the service this machine would install, without touching anything.
+ *
+ * Keeping the plan separate from the act means `autopilot --dry-run` can show the
+ * exact file and commands, and tests can assert them without a service manager.
+ */
+export declare function servicePlan(options: ServiceOptions): ServicePlan;
+export type ServiceOutcome = {
+    kind: ServiceKind;
+    installed: boolean;
+    path: string;
+    ranCommands: string[];
+    note?: string;
+};
+/** Writes the unit file and asks the platform's service manager to start it at login. */
+export declare function installService(options: ServiceOptions): Promise<ServiceOutcome>;
+export declare function uninstallService(options: ServiceOptions): Promise<ServiceOutcome>;
+/** Reports whether the unit file this build would write is currently present. */
+export declare function serviceStatus(options: ServiceOptions): Promise<{
+    kind: ServiceKind;
+    present: boolean;
+    path: string;
+    runs?: string;
+}>;
+/**
+ * The environment a service unit needs beyond its flags. A service manager
+ * starts the daemon bare, so anything the installing session was told about
+ * where secrets live has to ride along in the unit — a vault set up with
+ * VAULTLINE_SECRET_BACKEND=file kept its phrase in a keystore the daemon then
+ * never looked in, and every tick died on "No recovery phrase available".
+ */
+export declare function serviceUnitEnvironment(base?: Record<string, string>, env?: NodeJS.ProcessEnv): Record<string, string>;
+/** The argv the service should run: this package's CLI, with the daemon subcommand. */
+export declare function daemonInvocation(dataDir: string, options?: {
+    reclaim?: boolean;
+    cliPath?: string;
+}): {
+    executable: string;
+    args: string[];
+};
+export declare function serviceKind(target?: NodeJS.Platform): ServiceKind;

package/dist/src/service.js

@@ -0,0 +1,197 @@
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir, platform } from "node:os";
+import { dirname, join } from "node:path";
+import { promisify } from "node:util";
+import { fail } from "./errors.js";
+const run = promisify(execFile);
+export const SERVICE_LABEL = "ai.vaultline.agent";
+function kindFor(target) {
+    if (target === "darwin")
+        return "launchd";
+    if (target === "linux")
+        return "systemd";
+    if (target === "win32")
+        return "schtasks";
+    return "unsupported";
+}
+function escapeXml(value) {
+    return value.replace(/[<>&'"]/g, (char) => ({ "<": "&lt;", ">": "&gt;", "&": "&amp;", "'": "&apos;", '"': "&quot;" })[char]);
+}
+/**
+ * Describes the service this machine would install, without touching anything.
+ *
+ * Keeping the plan separate from the act means `autopilot --dry-run` can show the
+ * exact file and commands, and tests can assert them without a service manager.
+ */
+export function servicePlan(options) {
+    const target = options.platform ?? platform();
+    const kind = kindFor(target);
+    const home = options.home ?? homedir();
+    const executable = options.executable ?? process.execPath;
+    const args = options.args ?? [];
+    const logs = join(options.dataDir, "logs");
+    const environment = options.environment ?? {};
+    const environmentEntries = Object.entries(environment);
+    if (kind === "launchd") {
+        const path = join(home, "Library", "LaunchAgents", `${SERVICE_LABEL}.plist`);
+        const contents = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${SERVICE_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+${[executable, ...args].map((value) => `    <string>${escapeXml(value)}</string>`).join("\n")}
+  </array>
+${environmentEntries.length === 0 ? "" : `  <key>EnvironmentVariables</key>
+  <dict>
+${environmentEntries.map(([key, value]) => `    <key>${escapeXml(key)}</key><string>${escapeXml(value)}</string>`).join("\n")}
+  </dict>
+`}  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key>
+  <dict><key>SuccessfulExit</key><false/></dict>
+  <key>ProcessType</key><string>Background</string>
+  <key>LowPriorityIO</key><true/>
+  <key>Nice</key><integer>5</integer>
+  <key>StandardOutPath</key><string>${escapeXml(join(logs, "daemon.log"))}</string>
+  <key>StandardErrorPath</key><string>${escapeXml(join(logs, "daemon.error.log"))}</string>
+</dict>
+</plist>
+`;
+        return {
+            kind, label: SERVICE_LABEL, path, contents,
+            enable: [["launchctl", ["load", "-w", path]]],
+            disable: [["launchctl", ["unload", "-w", path]]]
+        };
+    }
+    if (kind === "systemd") {
+        const path = join(process.env.XDG_CONFIG_HOME ?? join(home, ".config"), "systemd", "user", "vaultline.service");
+        const contents = `[Unit]
+Description=Sealkeep — seals and archives AI coding-agent sessions
+Documentation=https://github.com/vaultline/vaultline
+After=default.target
+
+[Service]
+Type=simple
+ExecStart=${[executable, ...args].map((value) => JSON.stringify(value)).join(" ")}
+${environmentEntries.map(([key, value]) => `Environment=${key}=${value}\n`).join("")}Restart=on-failure
+RestartSec=20
+Nice=5
+IOSchedulingClass=idle
+
+[Install]
+WantedBy=default.target
+`;
+        return {
+            kind, label: "vaultline.service", path, contents,
+            enable: [["systemctl", ["--user", "daemon-reload"]], ["systemctl", ["--user", "enable", "--now", "vaultline.service"]]],
+            disable: [["systemctl", ["--user", "disable", "--now", "vaultline.service"]]]
+        };
+    }
+    if (kind === "schtasks") {
+        const path = join(options.dataDir, "vaultline-task.xml");
+        const invocation = [executable, ...args].map((value) => `"${value}"`).join(" ");
+        // schtasks has no environment block, so anything the daemon needs has to be
+        // set inside the command it runs.
+        const commandLine = environmentEntries.length === 0
+            ? invocation
+            : `cmd /c "${environmentEntries.map(([key, value]) => `set ${key}=${value}&& `).join("")}${invocation}"`;
+        return {
+            kind, label: "Sealkeep", path, contents: commandLine,
+            enable: [["schtasks", ["/create", "/f", "/tn", "Sealkeep", "/sc", "onlogon", "/rl", "limited", "/tr", commandLine]]],
+            disable: [["schtasks", ["/delete", "/f", "/tn", "Sealkeep"]]]
+        };
+    }
+    return { kind, label: "", path: "", contents: "", enable: [], disable: [] };
+}
+/** Writes the unit file and asks the platform's service manager to start it at login. */
+export async function installService(options) {
+    const plan = servicePlan(options);
+    if (plan.kind === "unsupported") {
+        return { kind: plan.kind, installed: false, path: "", ranCommands: [], note: `No background service is available on ${options.platform ?? platform()}. Run \`sealkeep daemon\` yourself.` };
+    }
+    const exec = options.exec ?? ((file, args) => run(file, args));
+    await mkdir(join(options.dataDir, "logs"), { recursive: true, mode: 0o700 });
+    if (plan.kind !== "schtasks") {
+        await mkdir(dirname(plan.path), { recursive: true });
+        await writeFile(plan.path, plan.contents, { mode: 0o600 });
+    }
+    const ranCommands = [];
+    for (const [file, args] of plan.enable) {
+        try {
+            await exec(file, args);
+            ranCommands.push([file, ...args].join(" "));
+        }
+        catch (error) {
+            return { kind: plan.kind, installed: false, path: plan.path, ranCommands, note: `${file} failed: ${error instanceof Error ? error.message.split("\n")[0] : "unknown error"}` };
+        }
+    }
+    return { kind: plan.kind, installed: true, path: plan.path, ranCommands };
+}
+export async function uninstallService(options) {
+    const plan = servicePlan(options);
+    if (plan.kind === "unsupported")
+        return { kind: plan.kind, installed: false, path: "", ranCommands: [] };
+    const exec = options.exec ?? ((file, args) => run(file, args));
+    const ranCommands = [];
+    for (const [file, args] of plan.disable) {
+        try {
+            await exec(file, args);
+            ranCommands.push([file, ...args].join(" "));
+        }
+        catch { /* already stopped */ }
+    }
+    if (plan.kind !== "schtasks")
+        await rm(plan.path, { force: true });
+    return { kind: plan.kind, installed: false, path: plan.path, ranCommands };
+}
+/** Reports whether the unit file this build would write is currently present. */
+export async function serviceStatus(options) {
+    const plan = servicePlan(options);
+    if (plan.kind === "unsupported")
+        return { kind: plan.kind, present: false, path: "" };
+    if (plan.kind === "schtasks") {
+        const exec = options.exec ?? ((file, args) => run(file, args));
+        const present = await exec("schtasks", ["/query", "/tn", "Sealkeep"]).then(() => true).catch(() => false);
+        return { kind: plan.kind, present, path: plan.path };
+    }
+    const contents = await readFile(plan.path, "utf8").catch(() => null);
+    const runs = contents?.match(/ExecStart=(.*)/)?.[1] ?? contents?.match(/<string>([^<]*daemon[^<]*)<\/string>/)?.[1];
+    return { kind: plan.kind, present: contents !== null, path: plan.path, runs: runs ?? undefined };
+}
+/**
+ * The environment a service unit needs beyond its flags. A service manager
+ * starts the daemon bare, so anything the installing session was told about
+ * where secrets live has to ride along in the unit — a vault set up with
+ * VAULTLINE_SECRET_BACKEND=file kept its phrase in a keystore the daemon then
+ * never looked in, and every tick died on "No recovery phrase available".
+ */
+export function serviceUnitEnvironment(base = {}, env = process.env) {
+    return { ...(env.VAULTLINE_SECRET_BACKEND ? { VAULTLINE_SECRET_BACKEND: env.VAULTLINE_SECRET_BACKEND } : {}), ...base };
+}
+/** The argv the service should run: this package's CLI, with the daemon subcommand. */
+export function daemonInvocation(dataDir, options = {}) {
+    let cli = options.cliPath ?? process.argv[1] ?? "vaultline";
+    // A service unit runs plain node, and plain node cannot execute TypeScript.
+    // Installed packages always resolve to dist/cli.js, but a source checkout
+    // running under tsx resolves to src/cli.ts — writing that path into launchd
+    // produced a service that crash-looped on its first import, which is worse
+    // than refusing. The built CLI next to the source is the honest substitute;
+    // absent a build, the refusal says what to run instead of installing a unit
+    // that can never start.
+    if (/\.(ts|mts|cts|tsx)$/.test(cli)) {
+        // The published layout is dist/src/cli.js (package.json bin agrees).
+        const built = join(dirname(dirname(cli)), "dist", "src", "cli.js");
+        if (!existsSync(built)) {
+            fail("invalid_argument", "The background service runs plain node, which cannot execute the TypeScript source this session is running from. Run `npm run build` first so dist/src/cli.js exists, then install the service again.");
+        }
+        cli = built;
+    }
+    const args = [cli, "daemon", "--data-dir", dataDir];
+    if (options.reclaim)
+        args.push("--reclaim");
+    return { executable: process.execPath, args };
+}
+export function serviceKind(target = platform()) { return kindFor(target); }

package/dist/src/share.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Sharing one archive, phase one: a self-carrying bundle.
+ *
+ * The bundle is the same framed object the cloud stores — envelope plus
+ * ciphertext — except its key slots are REPLACED with a single wrap under a
+ * share passcode. Replaced, not added: the recipient gets a thing the vault
+ * phrase deliberately does not open and the passcode does, so handing over a
+ * bundle never hands over anything about the vault, and revoking a share is
+ * as simple as not sending the passcode. The content bytes are the archive's
+ * own ciphertext, re-wrapped in kilobytes — nothing is re-encrypted.
+ *
+ * The passcode travels however the sender chooses (said aloud, another
+ * channel); the bundle can go over anything, because without the passcode it
+ * is noise. Team spaces later replace the passcode with member keys — same
+ * slot machinery, different recipients.
+ */
+export type ShareResult = {
+    bundlePath: string;
+    passcode: string;
+    bytes: number;
+    archiveId: string;
+};
+export declare function generateSharePasscode(): string;
+export declare function createShareBundle(dataDir: string, archiveId: string, bundlePath: string, options?: {
+    vaultPhrase: string;
+    passcode?: string;
+}): Promise<ShareResult>;
+/**
+ * Opens a bundle anywhere — no vault, no account, no config. The passcode is
+ * the whole key, which is exactly the promise made to the person receiving it.
+ */
+export declare function openShareBundle(bundlePath: string, destination: string, passcode: string): Promise<{
+    bytes: number;
+}>;