sealkeep 0.9.0 → 0.11.1

package/dist/src/secrets.d.ts

@@ -1,9 +1,31 @@
 import type { GdriveCredentials } from "./providers/gdrive.js";
+import type { StorageDestinationIdentity } from "./types.js";
+declare const nativeSecretOptions: {
+    timeout: number;
+    killSignal: "SIGKILL";
+};
+export type MacosSecurityInvocation = {
+    file: "/usr/sbin/taskpolicy";
+    args: string[];
+    options: typeof nativeSecretOptions;
+};
+/**
+ * launchd releases before v0.10 marked the complete daemon job Background.
+ * Even after the daemon clears its own Darwin background bit, launchd applies
+ * the old job policy to helpers it spawns; a normally instant Keychain lookup
+ * can then consume the whole timeout while the machine is busy.  `-a` gives
+ * only this Apple-owned helper ordinary application resource policy.  The
+ * daemon's Nice=5 and LowPriorityIO settings, and every archive worker, remain
+ * deferential.
+ */
+export declare function macosSecurityInvocation(args: readonly string[]): MacosSecurityInvocation;
+/** `security` returns errSecItemNotFound (-25300) as its low-byte exit status. */
+export declare function isMacosSecurityItemNotFound(error: unknown): boolean;
 export type SecretRef = {
     service: string;
     account: string;
 };
-export type BackendName = "macos-keychain" | "secret-service" | "windows-dpapi" | "file";
+export type BackendName = "macos-keychain" | "secret-service" | "linux-systemd-creds" | "windows-dpapi" | "file";
 export interface SecretBackend {
     readonly name: BackendName;
     /** True when this backend can actually be used on this machine right now. */
@@ -27,11 +49,6 @@ export declare class FileSecretBackend implements SecretBackend {
     delete(ref: SecretRef): Promise<void>;
 }
 export declare function secretBackends(dataDir: string): SecretBackend[];
-/**
- * Picks the strongest backend this machine supports. The file fallback always
- * qualifies. `SEALKEEP_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;
@@ -41,6 +58,24 @@ export type ProviderCredentials = {
     clientEmail: string;
     privateKey: string;
 } | GdriveCredentials;
+/**
+ * Non-secret evidence attached to a provider credential after the connection
+ * probe succeeds.  The routing label is intentionally absent: labels can be
+ * edited account-wide, while this snapshot identifies the destination whose
+ * write/read/delete permissions were actually proved on this machine.
+ */
+export type ProviderCredentialBinding = {
+    destination: StorageDestinationIdentity;
+    destinationFingerprint: string;
+    /** Null only for the narrowly-scoped local legacy migration. */
+    verifiedAt: string | null;
+};
+export type ProviderCredentialRecord = {
+    credentials: ProviderCredentials;
+    binding: ProviderCredentialBinding | null;
+    /** Raw credentials written by releases which predate destination binding. */
+    legacy: boolean;
+};
 /**
  * Remembering the recovery phrase.
  *
@@ -77,10 +112,19 @@ export declare function resolveRecoveryPhrase(dataDir: string, vaultId: string,
  * 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<{
+export declare function storeProviderCredentials(dataDir: string, storageConfigId: string, credentials: ProviderCredentials, preferred?: BackendName, binding?: ProviderCredentialBinding): Promise<{
     backend: BackendName;
 }>;
+export declare function loadProviderCredentialRecord(dataDir: string, storageConfigId: string, preferred?: BackendName): Promise<ProviderCredentialRecord>;
 export declare function loadProviderCredentials(dataDir: string, storageConfigId: string, preferred?: BackendName): Promise<ProviderCredentials>;
+/**
+ * Raw slot presence for disconnect.  Parsing is deliberately skipped: a
+ * truncated or obsolete secret still belongs to the requested target and must
+ * remain removable. Backend failures propagate instead of being reported as
+ * an already-disconnected success.
+ */
+export declare function providerCredentialSlotPresent(dataDir: string, storageConfigId: string, preferred?: BackendName): Promise<boolean>;
 export declare function deleteProviderCredentials(dataDir: string, storageConfigId: string, preferred?: BackendName): Promise<{
     backend: BackendName;
 }>;
+export {};

package/dist/src/secrets.js

@@ -1,4 +1,5 @@
 import { execFile } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
 import { chmod, mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
 import { platform } from "node:os";
 import { join } from "node:path";
@@ -6,6 +7,36 @@ import { promisify } from "node:util";
 import { fail } from "./errors.js";
 import { envVar } from "./env.js";
 const run = promisify(execFile);
+// Native secret helpers can wait for a locked/login keychain prompt forever.
+// An unattended daemon has nobody to answer that prompt, so every call must
+// fail closed on a short bound and let the durable queue retry later.
+const NATIVE_SECRET_TIMEOUT_MS = 5_000;
+const nativeSecretOptions = { timeout: NATIVE_SECRET_TIMEOUT_MS, killSignal: "SIGKILL" };
+/**
+ * launchd releases before v0.10 marked the complete daemon job Background.
+ * Even after the daemon clears its own Darwin background bit, launchd applies
+ * the old job policy to helpers it spawns; a normally instant Keychain lookup
+ * can then consume the whole timeout while the machine is busy.  `-a` gives
+ * only this Apple-owned helper ordinary application resource policy.  The
+ * daemon's Nice=5 and LowPriorityIO settings, and every archive worker, remain
+ * deferential.
+ */
+export function macosSecurityInvocation(args) {
+    return {
+        file: "/usr/sbin/taskpolicy",
+        args: ["-a", "/usr/bin/security", ...args],
+        options: { ...nativeSecretOptions },
+    };
+}
+const runMacosSecurity = (args) => {
+    const invocation = macosSecurityInvocation(args);
+    return run(invocation.file, invocation.args, invocation.options);
+};
+/** `security` returns errSecItemNotFound (-25300) as its low-byte exit status. */
+export function isMacosSecurityItemNotFound(error) {
+    return typeof error === "object" && error !== null
+        && "code" in error && error.code === 44;
+}
 async function commandExists(command) {
     try {
         await run(platform() === "win32" ? "where" : "which", [command]);
@@ -15,6 +46,17 @@ async function commandExists(command) {
         return false;
     }
 }
+async function commandWithInput(command, args, input, timeout = 5_000) {
+    return new Promise((resolve, reject) => {
+        const child = execFile(command, args, { encoding: "utf8", timeout, maxBuffer: 2 * 1024 * 1024 }, (error, stdout) => {
+            if (error)
+                reject(error);
+            else
+                resolve(stdout);
+        });
+        child.stdin?.end(input);
+    });
+}
 /**
  * macOS Keychain.
  *
@@ -25,29 +67,81 @@ async function commandExists(command) {
  */
 class MacosKeychain {
     name = "macos-keychain";
-    async available() { return platform() === "darwin" && (await commandExists("security")); }
-    async get(ref) {
+    /**
+     * Having the `security` binary is not the same as having a keychain.
+     *
+     * This used to answer yes on any Mac, so a process whose HOME does not hold a
+     * login keychain — a test with a throwaway HOME, CI, a container — was told
+     * the keychain was usable, tried to write, and macOS put a MODAL DIALOG in
+     * front of a human offering to "Reset To Defaults" on their real keychain.
+     * A storage backend that cannot store must say so and let the file backend
+     * take over; `security list-keychains` is the cheapest honest answer.
+     */
+    async available() {
+        if (platform() !== "darwin")
+            return false;
         try {
-            return (await run("security", ["find-generic-password", "-s", ref.service, "-a", ref.account, "-w"])).stdout.trim();
+            const { stdout } = await runMacosSecurity(["list-keychains", "-d", "user"]);
+            return stdout.trim().length > 0;
         }
         catch {
-            return null;
+            return false;
+        }
+    }
+    async get(ref) {
+        try {
+            return (await runMacosSecurity(["find-generic-password", "-s", ref.service, "-a", ref.account, "-w"])).stdout.trim();
+        }
+        catch (error) {
+            if (isMacosSecurityItemNotFound(error))
+                return null;
+            throw error;
         }
     }
     async set(ref, value) {
-        await run("security", ["add-generic-password", "-U", "-s", ref.service, "-a", ref.account, "-w", value]);
+        await runMacosSecurity(["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]);
+            await runMacosSecurity(["delete-generic-password", "-s", ref.service, "-a", ref.account]);
+        }
+        catch (error) {
+            if (!isMacosSecurityItemNotFound(error))
+                throw error;
         }
-        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 available() {
+        if (platform() !== "linux" || !(await commandExists("secret-tool")))
+            return false;
+        // `secret-tool` is only a client. Minimal servers and containers often
+        // install the binary without a D-Bus Secret Service; choosing it there
+        // makes the first unattended write fail instead of falling back safely.
+        // A read-only search is insufficient: a headless VPS can expose the D-Bus
+        // API and a volatile session collection while its persistent login
+        // collection is missing/locked. Prove the exact operation Sealkeep needs
+        // with a random reversible store/read/clear, each time-bounded so a prompt
+        // that nobody can answer cannot hang every hook.
+        const account = `probe-${process.pid}-${randomUUID()}`;
+        const value = randomUUID();
+        try {
+            await new Promise((resolve, reject) => {
+                const child = execFile("secret-tool", ["store", "--label", "Sealkeep native-keystore availability probe", "service", "sealkeep-availability-probe", "account", account], { timeout: 2_000 }, (error) => error ? reject(error) : resolve());
+                child.stdin?.end(value);
+            });
+            const found = (await run("secret-tool", ["lookup", "service", "sealkeep-availability-probe", "account", account], { timeout: 2_000 })).stdout.trim();
+            return found === value;
+        }
+        catch {
+            return false;
+        }
+        finally {
+            await run("secret-tool", ["clear", "service", "sealkeep-availability-probe", "account", account], { timeout: 2_000 }).catch(() => undefined);
+        }
+    }
     async get(ref) {
         try {
             return (await run("secret-tool", ["lookup", "service", ref.service, "account", ref.account])).stdout.trim() || null;
@@ -69,6 +163,64 @@ class SecretService {
         catch { /* already absent */ }
     }
 }
+/**
+ * systemd encrypted credentials for headless Linux.
+ *
+ * Secret Service is the preferred desktop backend, where PAM unlocks the
+ * login collection. A key-only server session often has no unlock password at
+ * all. On modern systemd, root (and environments granted access to a host/TPM
+ * credential key) can instead seal a user-scoped credential to this OS
+ * installation. The plaintext travels over stdin/stdout only; the vault keeps
+ * the authenticated Base64 ciphertext. A reversible probe prevents merely
+ * having the binary from selecting an unusable backend.
+ */
+class LinuxSystemdCredentials {
+    root;
+    name = "linux-systemd-creds";
+    constructor(root) {
+        this.root = root;
+    }
+    nameFor(ref) {
+        return `sealkeep-${createHash("sha256").update(`${ref.service}\0${ref.account}`).digest("hex")}`;
+    }
+    path(ref) { return join(this.root, `${this.nameFor(ref)}.credential`); }
+    async encrypt(name, value) {
+        return commandWithInput("systemd-creds", ["--user", "--no-ask-password", "--with-key=host", `--name=${name}`, "encrypt", "-", "-"], value);
+    }
+    async decrypt(name, value) {
+        return commandWithInput("systemd-creds", ["--user", "--no-ask-password", `--name=${name}`, "decrypt", "-", "-"], value);
+    }
+    async available() {
+        if (platform() !== "linux" || !(await commandExists("systemd-creds")))
+            return false;
+        const name = `sealkeep-probe-${process.pid}-${randomUUID()}`;
+        const value = randomUUID();
+        try {
+            return (await this.decrypt(name, await this.encrypt(name, value))).trim() === value;
+        }
+        catch {
+            return false;
+        }
+    }
+    async get(ref) {
+        const encrypted = await readFile(this.path(ref), "utf8").catch(() => null);
+        if (!encrypted)
+            return null;
+        try {
+            return (await this.decrypt(this.nameFor(ref), encrypted)).trim() || null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async set(ref, value) {
+        const encrypted = await this.encrypt(this.nameFor(ref), value);
+        await mkdir(this.root, { recursive: true, mode: 0o700 });
+        await writeFile(this.path(ref), encrypted.trim() + "\n", { mode: 0o600 });
+        await chmod(this.path(ref), 0o600);
+    }
+    async delete(ref) { await rm(this.path(ref), { force: true }); }
+}
 /**
  * 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.
@@ -127,13 +279,111 @@ export class FileSecretBackend {
     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"))];
+    const root = join(dataDir, "secrets");
+    return [new MacosKeychain(), new SecretService(), new LinuxSystemdCredentials(root), new WindowsDpapi(root), new FileSecretBackend(root)];
 }
 /**
  * Picks the strongest backend this machine supports. The file fallback always
  * qualifies. `SEALKEEP_SECRET_BACKEND` pins the choice, which is how a test suite
  * or a sandboxed environment stays out of the real OS keystore.
  */
+/**
+ * The service ids these secrets were stored under before the rename.
+ *
+ * A keystore entry is not ours to orphan. Renaming the id without moving the
+ * entry does not fail loudly — the lookup simply misses, and the product
+ * quietly behaves as though the user had never signed in, never stored a
+ * provider credential, never chose to remember a phrase. The secret is still
+ * sitting in their keychain under a name nothing looks for any more.
+ */
+const LEGACY_SERVICE = new Map([
+    ["sealkeep-provider", "vaultline-provider"],
+    ["sealkeep-recovery", "vaultline-recovery"],
+    ["sealkeep-cloud", "vaultline-cloud"]
+]);
+/**
+ * A backend whose reads heal. A miss under the current id retries the old one,
+ * and a hit is rewritten under the new id and the old entry removed — so the
+ * move happens once, on first use, without a migration step anyone has to run
+ * and without a second copy of a secret left behind.
+ */
+function migrating(backend) {
+    return {
+        name: backend.name,
+        available: () => backend.available(),
+        async get(ref) {
+            const current = await backend.get(ref);
+            if (current !== null)
+                return current;
+            const legacy = LEGACY_SERVICE.get(ref.service);
+            if (!legacy)
+                return null;
+            const found = await backend.get({ ...ref, service: legacy });
+            if (found === null)
+                return null;
+            await backend.set(ref, found);
+            // Read it back before removing the only other copy. Without this, a
+            // write that reported success but did not land — a locked keychain, a
+            // full disk on the file backend — took the legacy entry with it and the
+            // secret was gone. And if another process rotated or forgot this secret
+            // between our read and our write, the value under the new id is theirs,
+            // not ours: leave it, and leave the legacy entry alone too rather than
+            // resurrecting something a user explicitly forgot.
+            const settled = await backend.get(ref);
+            if (settled !== found)
+                return settled;
+            await backend.delete({ ...ref, service: legacy });
+            return found;
+        },
+        set: (ref, value) => backend.set(ref, value),
+        // Forgetting must forget both, or a "forgotten" phrase comes back.
+        async delete(ref) {
+            await backend.delete(ref);
+            const legacy = LEGACY_SERVICE.get(ref.service);
+            if (legacy)
+                await backend.delete({ ...ref, service: legacy });
+        }
+    };
+}
+/**
+ * A stronger backend can become available after an upgrade (for example,
+ * systemd-creds arrives on a headless server that previously used the
+ * owner-only file fallback). Selecting it must not make the existing secret
+ * disappear. On a primary miss, read lower-priority usable backends, copy the
+ * value into the primary, verify the copy, and only then remove the old one.
+ */
+function migratingBackends(primary, fallbacks) {
+    return {
+        name: primary.name,
+        available: () => primary.available(),
+        async get(ref) {
+            const current = await primary.get(ref);
+            if (current !== null)
+                return current;
+            for (const fallback of fallbacks) {
+                if (!(await fallback.available()))
+                    continue;
+                const found = await fallback.get(ref);
+                if (found === null)
+                    continue;
+                await primary.set(ref, found);
+                const settled = await primary.get(ref);
+                if (settled !== found)
+                    return settled;
+                await fallback.delete(ref);
+                return found;
+            }
+            return null;
+        },
+        set: (ref, value) => primary.set(ref, value),
+        async delete(ref) {
+            await primary.delete(ref);
+            for (const fallback of fallbacks)
+                if (await fallback.available())
+                    await fallback.delete(ref);
+        },
+    };
+}
 export async function chooseBackend(dataDir, preferred, env = process.env) {
     preferred = preferred ?? envVar("SECRET_BACKEND", env);
     const backends = secretBackends(dataDir);
@@ -143,15 +393,17 @@ export async function chooseBackend(dataDir, preferred, env = process.env) {
             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;
+        return migrating(chosen);
+    }
+    for (let index = 0; index < backends.length; index += 1) {
+        if (!(await backends[index].available()))
+            continue;
+        return migratingBackends(migrating(backends[index]), backends.slice(index + 1).map(migrating));
     }
-    for (const backend of backends)
-        if (await backend.available())
-            return backend;
-    return new FileSecretBackend(join(dataDir, "secrets"));
+    return migrating(new FileSecretBackend(join(dataDir, "secrets")));
 }
-const SERVICE = "vaultline-provider";
-const PHRASE_SERVICE = "vaultline-recovery";
+const SERVICE = "sealkeep-provider";
+const PHRASE_SERVICE = "sealkeep-recovery";
 /**
  * Remembering the recovery phrase.
  *
@@ -197,22 +449,62 @@ export async function resolveRecoveryPhrase(dataDir, vaultId, explicit, env = pr
  * 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) {
+export async function storeProviderCredentials(dataDir, storageConfigId, credentials, preferred, binding) {
     const backend = await chooseBackend(dataDir, preferred);
-    await backend.set({ service: SERVICE, account: storageConfigId }, JSON.stringify(credentials));
+    const stored = binding
+        ? { version: 2, credentials, binding }
+        : credentials;
+    await backend.set({ service: SERVICE, account: storageConfigId }, JSON.stringify(stored));
     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 });
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function providerCredentialRecord(raw, storageConfigId) {
+    let parsed;
     try {
-        return JSON.parse(raw);
+        parsed = JSON.parse(raw);
     }
     catch {
         return fail("invalid_argument", `Stored credentials for ${storageConfigId} are not readable JSON`, { storageConfigId });
     }
+    if (isObject(parsed) && parsed.version === 2) {
+        if (!isObject(parsed.credentials) || !isObject(parsed.binding)
+            || !isObject(parsed.binding.destination)
+            || typeof parsed.binding.destinationFingerprint !== "string"
+            || (parsed.binding.verifiedAt !== null && typeof parsed.binding.verifiedAt !== "string")) {
+            return fail("invalid_argument", `Stored credentials for ${storageConfigId} have an invalid destination binding`, { storageConfigId });
+        }
+        return {
+            credentials: parsed.credentials,
+            binding: parsed.binding,
+            legacy: false,
+        };
+    }
+    if (!isObject(parsed)) {
+        return fail("invalid_argument", `Stored credentials for ${storageConfigId} have an invalid shape`, { storageConfigId });
+    }
+    return { credentials: parsed, binding: null, legacy: true };
+}
+export async function loadProviderCredentialRecord(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 });
+    return providerCredentialRecord(raw, storageConfigId);
+}
+export async function loadProviderCredentials(dataDir, storageConfigId, preferred) {
+    return (await loadProviderCredentialRecord(dataDir, storageConfigId, preferred)).credentials;
+}
+/**
+ * Raw slot presence for disconnect.  Parsing is deliberately skipped: a
+ * truncated or obsolete secret still belongs to the requested target and must
+ * remain removable. Backend failures propagate instead of being reported as
+ * an already-disconnected success.
+ */
+export async function providerCredentialSlotPresent(dataDir, storageConfigId, preferred) {
+    const backend = await chooseBackend(dataDir, preferred);
+    return (await backend.get({ service: SERVICE, account: storageConfigId })) !== null;
 }
 export async function deleteProviderCredentials(dataDir, storageConfigId, preferred) {
     const backend = await chooseBackend(dataDir, preferred);

package/dist/src/service.d.ts

@@ -10,16 +10,20 @@ export type ServiceOptions = {
      * 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
-     * `SEALKEEP_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.
+     * inherit the shell that installed it. Upload-capable service definitions
+     * carry `SEALKEEP_ENABLE_SIGNER`; configured targets and machine-local
+     * credentials remain the separate gates which decide whether any write can
+     * actually happen.
      */
     environment?: Record<string, string>;
+    /** Grace distinguishes a package upgrade's brief gap from a real uninstall. */
+    cleanupGraceMs?: number;
+    /** Shortened only by isolated lifecycle rehearsals. */
+    cleanupMonitorMs?: number;
     /** Injected in tests so no real service manager is touched. */
     exec?: (file: string, args: string[]) => Promise<unknown>;
+    /** Current numeric user. Injected only by hermetic platform rehearsals. */
+    uid?: number;
 };
 export type ServicePlan = {
     kind: ServiceKind;
@@ -28,8 +32,22 @@ export type ServicePlan = {
     contents: string;
     enable: [string, string[]][];
     disable: [string, string[]][];
+    managerPath: string;
+    receiptPath: string;
 };
-export declare const SERVICE_LABEL = "ai.vaultline.agent";
+export declare const SERVICE_LABEL = "ai.sealkeep.agent";
+/**
+ * What this service was called before the rename, and why that is not just
+ * trivia.
+ *
+ * A launchd agent is not owned by the file that wrote it — it is owned by the
+ * OS, under a label, until something tells the OS to let go. Rename the label
+ * and install, and the old agent does not disappear: it keeps loading at every
+ * login, running an executable that may no longer exist, next to the new one.
+ * So every install and every uninstall tears the old label down first.
+ */
+export declare const LEGACY_SERVICE_LABEL = "ai.vaultline.agent";
+export declare const LEGACY_SYSTEMD_UNIT = "vaultline.service";
 /**
  * Describes the service this machine would install, without touching anything.
  *
@@ -37,22 +55,36 @@ export declare const SERVICE_LABEL = "ai.vaultline.agent";
  * exact file and commands, and tests can assert them without a service manager.
  */
 export declare function servicePlan(options: ServiceOptions): ServicePlan;
+export type ServicePersistence = "boot" | "login";
 export type ServiceOutcome = {
     kind: ServiceKind;
     installed: boolean;
     path: string;
     ranCommands: string[];
+    managerPath?: string;
+    receiptPath?: string;
+    /** `boot` is verified systemd lingering; other native services start at login. */
+    persistence?: ServicePersistence;
     note?: string;
 };
+/**
+ * Upgrade path for units installed before the package-independent manager
+ * existed. No new service is installed on a machine that did not already
+ * consent to one; an existing stale or inactive registration is repaired and
+ * activated immediately instead of waiting for the next login/reboot.
+ */
+export declare function reconcileInstalledService(options: ServiceOptions): Promise<boolean>;
 /** 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. */
+/** Reports durable installation separately from whether the manager has it live now. */
 export declare function serviceStatus(options: ServiceOptions): Promise<{
     kind: ServiceKind;
+    installed: boolean;
     present: boolean;
     path: string;
     runs?: string;
+    persistence?: ServicePersistence;
 }>;
 /**
  * The environment a service unit needs beyond its flags. A service manager
@@ -60,14 +92,20 @@ export declare function serviceStatus(options: ServiceOptions): Promise<{
  * where secrets live has to ride along in the unit — a vault set up with
  * SEALKEEP_SECRET_BACKEND=file kept its phrase in a keystore the daemon then
  * never looked in, and every tick died on "No recovery phrase available".
+ * Upload capability is included by default because storage may be connected
+ * after installation; target configuration and credentials remain mandatory.
+ * Callers representing an explicit `--no-upload` omit it with `uploads:false`.
  */
-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 serviceUnitEnvironment(base?: Record<string, string>, env?: NodeJS.ProcessEnv, options?: {
+    uploads?: boolean;
+}): Record<string, string>;
+/** The argv the service should run: this package's daemon plus its loopback UI lane. */
 export declare function daemonInvocation(dataDir: string, options?: {
     reclaim?: boolean;
+    upload?: boolean;
     cliPath?: string;
+    intervalSeconds?: number;
 }): {
     executable: string;
     args: string[];
 };
-export declare function serviceKind(target?: NodeJS.Platform): ServiceKind;