@dsh-enhanced/lark-channel 0.1.3 → 0.1.4

package/lib/setup.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 import { createHash, randomBytes } from 'node:crypto';
-import { realpathSync } from 'node:fs';
-import { chmod, mkdir, open, readFile, readdir, rename, rm, unlink } from 'node:fs/promises';
+import { accessSync, constants, realpathSync } from 'node:fs';
+import { chmod, lstat, mkdir, open, readFile, readdir, rename, rm, unlink } from 'node:fs/promises';
 import { homedir } from 'node:os';
-import { basename, dirname, isAbsolute, join, win32 } from 'node:path';
+import { basename, dirname, isAbsolute, join, normalize, win32 } from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
 import { fileURLToPath } from 'node:url';
 import { createInterface } from 'node:readline/promises';
@@ -13,6 +13,7 @@ import * as QRCode from 'qrcode';
 import { isMap, isSeq, parseDocument } from 'yaml';
 import { createOfficialLarkTransport } from './sdk.js';
 import { installDshResidentService } from './resident.js';
+import { prepareDshSystemdUserService } from './systemd.js';
 import { configureLarkProfilePatch, refreshLarkAgentPolicyPatch } from './setup-profile.js';
 import { assertRawManagedProfileIntegrity, materializeManagedProfileOverride, } from './setup-materialization.js';
 const setupKeyPattern = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/u;
@@ -36,6 +37,7 @@ export function parseLarkSetupArgs(argv) {
         installServiceOnly: false,
         refreshAgentPolicy: false,
         manageService: true,
+        linuxCredentialProvider: 'auto',
         agentTools: 'preserve',
         help: false,
     };
@@ -67,6 +69,9 @@ export function parseLarkSetupArgs(argv) {
             result.refreshAgentPolicy = true;
         else if (option === '--no-service')
             result.manageService = false;
+        else if (option === '--linux-credential-provider') {
+            result.linuxCredentialProvider = argumentValue(argv, index++, option);
+        }
         else if (option === '--allow-agent-tools' || option === '--disable-agent-tools') {
             if (result.agentTools !== 'preserve') {
                 throw new Error('lark-channel setup: --allow-agent-tools and --disable-agent-tools are mutually exclusive');
@@ -92,7 +97,7 @@ export function parseLarkSetupArgs(argv) {
     if (!result.help && result.refreshAgentPolicy) {
         const incompatible = [
             '--domain', '--tenant', '--app-id', '--create-app', '--install-service',
-            '--no-service', '--app-name', '--timeout-ms',
+            '--no-service', '--linux-credential-provider', '--app-name', '--timeout-ms',
         ].find(option => argv.includes(option));
         if (incompatible !== undefined) {
             throw new Error(`lark-channel setup: --refresh-agent-policy cannot be combined with ${incompatible}`);
@@ -107,6 +112,9 @@ export function parseLarkSetupArgs(argv) {
     if (result.installServiceOnly && (result.createApp || result.appId !== undefined)) {
         throw new Error('lark-channel setup: --install-service cannot be combined with application setup options');
     }
+    if (result.installServiceOnly && argv.includes('--linux-credential-provider')) {
+        throw new Error('lark-channel setup: --install-service cannot be combined with --linux-credential-provider');
+    }
     if (result.installServiceOnly && result.agentTools !== 'preserve') {
         throw new Error('lark-channel setup: --install-service cannot be combined with agent-tools options');
     }
@@ -117,6 +125,9 @@ export function parseLarkSetupArgs(argv) {
     }
     if (result.domain !== 'feishu' && result.domain !== 'lark')
         throw new Error('lark-channel setup: domain must be feishu or lark');
+    if (!['auto', 'protected-file', 'secret-service'].includes(result.linuxCredentialProvider)) {
+        throw new Error('lark-channel setup: linux-credential-provider must be auto, protected-file, or secret-service');
+    }
     if (!Number.isSafeInteger(result.timeoutMs) || result.timeoutMs < 30_000 || result.timeoutMs > 900_000) {
         throw new Error('lark-channel setup: timeout-ms must be an integer from 30000 to 900000');
     }
@@ -168,6 +179,12 @@ export function createVersionedCredentialLocator(input) {
     if (!credentialVersionPattern.test(version)) {
         throw new Error('lark-channel setup: invalid credential version');
     }
+    if (input.provider === 'linux-protected-file') {
+        return {
+            provider: input.provider,
+            path: join(input.dshHome, 'credentials-keychain', `lark-${input.profile}-${input.account}-${version}.secret`),
+        };
+    }
     if (input.provider === 'windows-dpapi') {
         return {
             provider: input.provider,
@@ -264,6 +281,8 @@ Options:
   --install-service       Only install/restart the profile's resident service
   --refresh-agent-policy  Only refresh policy from the existing channel binding
   --no-service            Configure Lark without installing a resident service
+  --linux-credential-provider <mode>
+                          auto, protected-file, or secret-service (default: auto)
   --allow-agent-tools     Allow mounted foreground/external Agent capabilities
   --disable-agent-tools   Remove setup-managed Agent capability rules
   --timeout-ms <ms>      Owner DM wait, 30000..900000 (default: 300000)
@@ -271,7 +290,8 @@ Options:
 
 Without --create-app or --app-id, press Enter at the App ID prompt to select or create an app.
 App Secret is intentionally not accepted as an argument. It is stored in macOS Keychain,
-Linux Secret Service, or a per-user Windows DPAPI file.`;
+Linux Secret Service (with an automatic private-file fallback for headless Linux),
+or a per-user Windows DPAPI file.`;
 }
 function runSecurity(args, stdio) {
     const result = spawnSync('/usr/bin/security', [...args], {
@@ -284,45 +304,556 @@ function runSecurity(args, stdio) {
         throw new Error('lark-channel setup: macOS Keychain operation failed');
     return typeof result.stdout === 'string' ? result.stdout.trimEnd() : '';
 }
-function linuxCredentialEnv() {
+function linuxCredentialEnv(environment = process.env) {
     return {
         PATH: '/usr/bin:/bin',
-        ...(process.env.DBUS_SESSION_BUS_ADDRESS === undefined
-            ? {} : { DBUS_SESSION_BUS_ADDRESS: process.env.DBUS_SESSION_BUS_ADDRESS }),
-        ...(process.env.XDG_RUNTIME_DIR === undefined ? {} : { XDG_RUNTIME_DIR: process.env.XDG_RUNTIME_DIR }),
+        ...(environment.DBUS_SESSION_BUS_ADDRESS === undefined
+            ? {} : { DBUS_SESSION_BUS_ADDRESS: environment.DBUS_SESSION_BUS_ADDRESS }),
+        ...(environment.XDG_RUNTIME_DIR === undefined ? {} : { XDG_RUNTIME_DIR: environment.XDG_RUNTIME_DIR }),
+    };
+}
+const linuxSecretTool = '/usr/bin/secret-tool';
+/** Bound every Secret Service client call, including transaction recovery. */
+const linuxSecretServiceTimeoutMs = 30_000;
+/** A deliberately static diagnostic: never include a provider's stderr or a secret value. */
+class LarkSetupDiagnosticError extends Error {
+    diagnostic;
+    constructor(diagnostic) {
+        super(`lark-channel setup: ${diagnostic}`);
+        this.diagnostic = diagnostic;
+        this.name = 'LarkSetupDiagnosticError';
+    }
+}
+function commandErrorCode(result) {
+    const error = result?.error;
+    if (error === null || typeof error !== 'object' || !('code' in error))
+        return undefined;
+    const code = error.code;
+    return typeof code === 'string' ? code : undefined;
+}
+function hasLinuxSecretServiceSession(environment) {
+    const dbus = environment.DBUS_SESSION_BUS_ADDRESS?.trim() ?? '';
+    const runtimeDirectory = environment.XDG_RUNTIME_DIR?.trim() ?? '';
+    return dbus !== '' || runtimeDirectory !== '';
+}
+function linuxSecretServiceDiagnostic(operation, result, environment) {
+    const common = 'Run setup as the target logged-in user (not via sudo or a detached SSH session). '
+        + 'For a headless server or container, use the default auto fallback or rerun with '
+        + '--linux-credential-provider protected-file.';
+    if (commandErrorCode(result) === 'ENOENT') {
+        return new LarkSetupDiagnosticError(`Linux Secret Service ${operation} cannot find ${linuxSecretTool}. Install libsecret-tools and a Secret Service provider, then retry. ${common}`);
+    }
+    if (!hasLinuxSecretServiceSession(environment)) {
+        return new LarkSetupDiagnosticError(`Linux Secret Service ${operation} has no user D-Bus session. Start from the target user's desktop/login session with DBUS_SESSION_BUS_ADDRESS or XDG_RUNTIME_DIR set. ${common}`);
+    }
+    const wasSignalled = result?.signal !== undefined && result.signal !== null;
+    if (commandErrorCode(result) === 'ETIMEDOUT' || wasSignalled) {
+        return new LarkSetupDiagnosticError(`Linux Secret Service ${operation} did not respond. Unlock or start a Secret Service provider such as GNOME Keyring, KWallet, or KeePassXC, then retry. ${common}`);
+    }
+    return new LarkSetupDiagnosticError(`Linux Secret Service ${operation} failed. Ensure ${linuxSecretTool} is installed and an unlocked org.freedesktop.secrets provider is available in this user's session, then retry. ${common}`);
+}
+function defaultLinuxSecretToolAvailable(path) {
+    try {
+        accessSync(path, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function defaultLinuxSecretServiceCommand(input) {
+    const result = spawnSync(input.executable, [...input.args], {
+        encoding: 'utf8',
+        env: input.environment,
+        timeout: linuxSecretServiceTimeoutMs,
+        maxBuffer: 128 * 1024,
+        ...(input.input === undefined ? {} : { input: input.input }),
+        stdio: [input.input === undefined ? 'ignore' : 'pipe', input.captureStdout ? 'pipe' : 'ignore', 'pipe'],
+    });
+    return {
+        status: result.status,
+        signal: result.signal,
+        ...(typeof result.stdout === 'string' ? { stdout: result.stdout } : {}),
+        ...(typeof result.stderr === 'string' ? { stderr: result.stderr } : {}),
+        ...(result.error === undefined ? {} : { error: result.error }),
+    };
+}
+function captureLinuxSecretServiceCommand(run, input) {
+    try {
+        return run(input);
+    }
+    catch (error) {
+        // Test seams and alternate runners may throw rather than return spawnSync's
+        // structured error. Preserve only the error code for static diagnostics;
+        // provider messages can contain secret material and must never be rendered.
+        return { status: null, signal: null, error };
+    }
+}
+/** libsecret reports a clear with no matching item as status 1 and no diagnostics. */
+export function isLinuxSecretServiceClearAbsent(result) {
+    return result.status === 1
+        && result.signal === null
+        && result.error === undefined
+        && typeof result.stderr === 'string'
+        && result.stderr.trim() === '';
+}
+function verifyLinuxSecretServiceWriteCanary(input) {
+    const service = `dsh/lark/setup-preflight/${input.random(16).toString('hex')}`;
+    const account = 'setup-probe';
+    const secret = input.random(32).toString('hex');
+    const write = createSecretServiceWriteRequest(service, account, secret);
+    let primaryError;
+    try {
+        const stored = captureLinuxSecretServiceCommand(input.run, {
+            executable: linuxSecretTool,
+            args: write.args,
+            environment: input.environment,
+            input: write.input,
+        });
+        if (stored.status !== 0) {
+            throw linuxSecretServiceDiagnostic('credential store', stored, input.environment);
+        }
+        const read = captureLinuxSecretServiceCommand(input.run, {
+            executable: linuxSecretTool,
+            args: ['lookup', 'service', service, 'account', account],
+            environment: input.environment,
+            captureStdout: true,
+        });
+        if (read.status !== 0) {
+            throw linuxSecretServiceDiagnostic('credential lookup', read, input.environment);
+        }
+        if ((read.stdout ?? '').trimEnd() !== secret) {
+            throw new LarkSetupDiagnosticError('Linux Secret Service preflight could not read back its generated test credential. '
+                + 'Unlock or repair the Secret Service provider, then retry.');
+        }
+    }
+    catch (error) {
+        primaryError = error;
+    }
+    finally {
+        write.input.fill(0);
+    }
+    const cleared = captureLinuxSecretServiceCommand(input.run, {
+        executable: linuxSecretTool,
+        args: ['clear', 'service', service, 'account', account],
+        environment: input.environment,
+    });
+    if (cleared.status !== 0 && !isLinuxSecretServiceClearAbsent(cleared)) {
+        const cleanupError = linuxSecretServiceDiagnostic('credential cleanup', cleared, input.environment);
+        if (primaryError !== undefined) {
+            throw new AggregateError([primaryError, cleanupError], 'lark-channel setup: Linux Secret Service preflight failed and canary cleanup also failed');
+        }
+        throw cleanupError;
+    }
+    if (primaryError !== undefined)
+        throw primaryError;
+}
+/**
+ * Checks the Linux credential prerequisites before an OAuth flow changes a
+ * cloud app. It stores, reads, and clears a random non-production canary, and
+ * never reads, writes, or prints an application credential.
+ */
+export function assertLinuxSecretServiceAvailable(options = {}) {
+    const environment = linuxCredentialEnv(options.environment ?? process.env);
+    const available = options.executableAvailable ?? defaultLinuxSecretToolAvailable;
+    if (!available(linuxSecretTool)) {
+        throw linuxSecretServiceDiagnostic('preflight', {
+            status: null, signal: null, error: { code: 'ENOENT' },
+        }, environment);
+    }
+    if (!hasLinuxSecretServiceSession(environment)) {
+        throw linuxSecretServiceDiagnostic('preflight', undefined, environment);
+    }
+    verifyLinuxSecretServiceWriteCanary({
+        environment,
+        random: options.randomBytes ?? randomBytes,
+        run: options.run ?? defaultLinuxSecretServiceCommand,
+    });
+}
+export function preflightLarkCredentialProvider(provider) {
+    if (provider === 'linux-secret-service')
+        assertLinuxSecretServiceAvailable();
+}
+async function assertLinuxProtectedFileRuntimeSupported() {
+    let providers;
+    try {
+        const keychain = await import('@dsh-enhanced/credentials-keychain/capabilities');
+        providers = keychain.supportedCredentialProviders;
+    }
+    catch (error) {
+        throw new Error('lark-channel setup: cannot load a compatible credentials-keychain package; reinstall matching plugin versions', { cause: error });
+    }
+    if (!Array.isArray(providers) || !providers.includes('linux-protected-file')) {
+        throw new Error('lark-channel setup: installed credentials-keychain does not support headless Linux; reinstall matching plugin versions');
+    }
+}
+/** Verifies that the headless backend can survive the same write/read/delete lifecycle as onboarding. */
+export async function assertLinuxProtectedFileAvailable(input) {
+    if (!isAbsolute(input.dshHome))
+        throw new Error('lark-channel setup: DSH_HOME must be absolute');
+    const random = input.randomBytes ?? randomBytes;
+    const path = join(input.dshHome, 'credentials-keychain', `.lark-setup-preflight-${random(16).toString('hex')}.secret`);
+    const secret = random(32).toString('hex');
+    let stored = false;
+    let primaryError;
+    try {
+        await storeLinuxProtectedCredential(path, secret);
+        stored = true;
+        await input.afterStore?.(path);
+        if (await readLinuxProtectedCredential(path) !== secret) {
+            throw new Error('lark-channel setup: Linux protected credential preflight readback did not match');
+        }
+    }
+    catch (error) {
+        primaryError = error;
+    }
+    if (stored) {
+        try {
+            await removeCredential({ provider: 'linux-protected-file', path });
+        }
+        catch (cleanupError) {
+            if (primaryError !== undefined) {
+                throw new AggregateError([primaryError, cleanupError], 'lark-channel setup: Linux protected credential preflight and cleanup both failed');
+            }
+            throw cleanupError;
+        }
+    }
+    if (primaryError !== undefined)
+        throw primaryError;
+}
+/**
+ * Prefers the desktop keyring but lets a headless Linux login continue without
+ * weakening the profile to an ambient environment variable. Unexpected setup
+ * errors remain fail-closed; only our static Secret Service diagnostics select
+ * the protected-file backend.
+ */
+export async function selectLarkCredentialProvider(preferred, options) {
+    const mode = options.mode ?? 'auto';
+    if (preferred !== 'linux-secret-service') {
+        if (mode !== 'auto') {
+            throw new Error('lark-channel setup: --linux-credential-provider is only valid on Linux');
+        }
+        return { provider: preferred };
+    }
+    if (mode === 'protected-file') {
+        await assertLinuxProtectedFileRuntimeSupported();
+        await assertLinuxProtectedFileAvailable(options);
+        return { provider: 'linux-protected-file' };
+    }
+    try {
+        assertLinuxSecretServiceAvailable(options);
+        return { provider: preferred };
+    }
+    catch (error) {
+        if (mode === 'secret-service' || safeDiagnosticMessages(error).length === 0)
+            throw error;
+        await assertLinuxProtectedFileRuntimeSupported();
+        await assertLinuxProtectedFileAvailable(options);
+        return { provider: 'linux-protected-file', fallbackReason: error };
+    }
+}
+function safeDiagnosticMessages(error) {
+    const messages = new Set();
+    const visited = new Set();
+    const walk = (current) => {
+        if (current === null || typeof current !== 'object' || visited.has(current))
+            return;
+        visited.add(current);
+        if (current instanceof LarkSetupDiagnosticError) {
+            messages.add(current.diagnostic);
+            return;
+        }
+        if (current instanceof AggregateError) {
+            for (const nested of current.errors)
+                walk(nested);
+            return;
+        }
+        if (current instanceof Error)
+            walk(current.cause);
     };
+    walk(error);
+    return [...messages];
+}
+/** Adds only static, credential-safe diagnostics to AggregateError CLI output. */
+export function formatLarkSetupError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (!(error instanceof AggregateError))
+        return message;
+    const diagnostics = safeDiagnosticMessages(error);
+    return diagnostics.length === 0 ? message : `${message}\n${diagnostics.map(value => `Hint: ${value}`).join('\n')}`;
+}
+const protectedCredentialMaxBytes = 65_536;
+function currentLinuxCredentialUid() {
+    const uid = process.getuid?.();
+    const effectiveUid = process.geteuid?.();
+    if (uid === undefined || effectiveUid === undefined || uid !== effectiveUid) {
+        throw new Error('lark-channel setup: Linux protected credentials require matching real and effective user IDs');
+    }
+    return uid;
+}
+function linuxProtectedCredentialDirectory(path) {
+    if (!isAbsolute(path) || normalize(path) !== path || path.length > 1_024
+        || path.includes('\0') || !path.endsWith('.secret')) {
+        throw new Error('lark-channel setup: invalid Linux protected credential path');
+    }
+    return dirname(path);
+}
+async function ensureLinuxProtectedCredentialDirectory(path) {
+    const directory = linuxProtectedCredentialDirectory(path);
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    let metadata = await lstat(directory);
+    const uid = currentLinuxCredentialUid();
+    if (!metadata.isDirectory() || metadata.isSymbolicLink()
+        || metadata.uid !== uid) {
+        throw new Error('lark-channel setup: Linux protected credential directory is not private to the current user');
+    }
+    if ((metadata.mode & 0o7777) !== 0o700) {
+        await chmod(directory, 0o700);
+        metadata = await lstat(directory);
+        if (!metadata.isDirectory() || metadata.isSymbolicLink()
+            || metadata.uid !== uid || (metadata.mode & 0o7777) !== 0o700) {
+            throw new Error('lark-channel setup: Linux protected credential directory could not be secured');
+        }
+    }
+}
+async function assertLinuxProtectedCredentialDirectory(path) {
+    const directory = linuxProtectedCredentialDirectory(path);
+    const metadata = await lstat(directory);
+    const uid = currentLinuxCredentialUid();
+    if (!metadata.isDirectory() || metadata.isSymbolicLink()
+        || metadata.uid !== uid || (metadata.mode & 0o7777) !== 0o700) {
+        throw new Error('lark-channel setup: Linux protected credential directory failed its security check');
+    }
+}
+async function storeLinuxProtectedCredential(path, secret) {
+    const value = Buffer.from(secret, 'utf8');
+    if (value.byteLength < 1 || value.byteLength > protectedCredentialMaxBytes || value.includes(0)) {
+        value.fill(0);
+        throw new Error('lark-channel setup: Linux protected credential value is invalid');
+    }
+    let file;
+    let created = false;
+    try {
+        await ensureLinuxProtectedCredentialDirectory(path);
+        // The locator contains a fresh random version, so an existing final item
+        // is a collision or interference. O_EXCL avoids following or replacing it.
+        file = await open(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+        created = true;
+        await file.chmod(0o600);
+        await file.writeFile(value);
+        await file.sync();
+        const metadata = await file.stat();
+        const uid = currentLinuxCredentialUid();
+        if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.nlink !== 1
+            || metadata.uid !== uid || (metadata.mode & 0o7777) !== 0o600
+            || metadata.size !== value.byteLength) {
+            throw new Error('lark-channel setup: Linux protected credential file failed its security check');
+        }
+        await file.close();
+        file = undefined;
+        await syncDirectory(dirname(path));
+    }
+    catch (error) {
+        try {
+            await file?.close();
+        }
+        catch { }
+        file = undefined;
+        if (created) {
+            try {
+                await unlink(path);
+                await syncDirectory(dirname(path));
+            }
+            catch (cleanupError) {
+                if (fileSystemErrorCode(cleanupError) !== 'ENOENT') {
+                    throw new AggregateError([error, cleanupError], 'lark-channel setup: Linux protected credential write and cleanup both failed');
+                }
+            }
+        }
+        throw error;
+    }
+    finally {
+        value.fill(0);
+        await file?.close();
+    }
+}
+async function readLinuxProtectedCredential(path) {
+    await assertLinuxProtectedCredentialDirectory(path);
+    let file;
+    let value;
+    try {
+        file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        const before = await file.stat();
+        const uid = currentLinuxCredentialUid();
+        if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1
+            || before.uid !== uid || (before.mode & 0o7777) !== 0o600
+            || before.size < 1 || before.size > protectedCredentialMaxBytes) {
+            throw new Error('lark-channel setup: Linux protected credential file failed its security check');
+        }
+        value = Buffer.alloc(protectedCredentialMaxBytes + 1);
+        let bytesRead = 0;
+        while (bytesRead < value.byteLength) {
+            const result = await file.read(value, bytesRead, value.byteLength - bytesRead, bytesRead);
+            if (result.bytesRead === 0)
+                break;
+            bytesRead += result.bytesRead;
+        }
+        const after = await file.stat();
+        if (bytesRead < 1 || bytesRead > protectedCredentialMaxBytes
+            || bytesRead !== after.size
+            || after.dev !== before.dev || after.ino !== before.ino
+            || !after.isFile() || after.nlink !== 1 || after.uid !== uid || (after.mode & 0o7777) !== 0o600
+            || value.subarray(0, bytesRead).includes(0)) {
+            throw new Error('lark-channel setup: Linux protected credential value is invalid');
+        }
+        return value.toString('utf8', 0, bytesRead);
+    }
+    catch (error) {
+        throw new Error('lark-channel setup: Linux protected credential lookup failed', { cause: error });
+    }
+    finally {
+        value?.fill(0);
+        await file?.close();
+    }
+}
+export async function readSecretFromRawTerminal(prompt, options = {}) {
+    const input = options.input ?? process.stdin;
+    const output = options.output ?? process.stdout;
+    const signals = options.signals ?? process;
+    if (!input.isTTY || !output.isTTY || typeof input.setRawMode !== 'function') {
+        throw new Error('lark-channel setup: no secure interactive terminal is available for the App Secret');
+    }
+    output.write(prompt);
+    return new Promise((resolve, reject) => {
+        const bytes = [];
+        const wasRaw = input.isRaw;
+        const wasPaused = input.isPaused();
+        let settled = false;
+        const signalHandlers = new Map();
+        let onData;
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            let restorationError;
+            try {
+                input.off('data', onData);
+                for (const [signal, listener] of signalHandlers)
+                    signals.off(signal, listener);
+                input.setRawMode(Boolean(wasRaw));
+                if (wasPaused)
+                    input.pause();
+            }
+            catch (caught) {
+                restorationError = caught;
+            }
+            finally {
+                output.write('\n');
+            }
+            const secretBytes = Buffer.from(bytes);
+            const secret = secretBytes.toString('utf8');
+            secretBytes.fill(0);
+            bytes.fill(0);
+            if (restorationError !== undefined) {
+                reject(new Error('lark-channel setup: failed to restore terminal input mode', { cause: restorationError }));
+            }
+            else if (error !== undefined)
+                reject(error);
+            else if (secret.length === 0)
+                reject(new Error('lark-channel setup: Linux could not read the App Secret securely'));
+            else
+                resolve(secret);
+        };
+        onData = (chunk) => {
+            const value = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            try {
+                for (const byte of value) {
+                    if (byte === 3) {
+                        finish(new Error('lark-channel setup: App Secret input was cancelled'));
+                        return;
+                    }
+                    if (byte === 10 || byte === 13) {
+                        finish();
+                        return;
+                    }
+                    if (byte === 8 || byte === 127) {
+                        bytes.pop();
+                        continue;
+                    }
+                    if (byte < 32 || bytes.length >= protectedCredentialMaxBytes) {
+                        finish(new Error('lark-channel setup: App Secret input is invalid or too large'));
+                        return;
+                    }
+                    bytes.push(byte);
+                }
+            }
+            finally {
+                value.fill(0);
+            }
+        };
+        for (const signal of ['SIGHUP', 'SIGINT', 'SIGTERM']) {
+            const listener = () => finish(new Error(`lark-channel setup: App Secret input interrupted by ${signal}`));
+            signalHandlers.set(signal, listener);
+            signals.once(signal, listener);
+        }
+        try {
+            input.setRawMode(true);
+            input.on('data', onData);
+            input.resume();
+        }
+        catch (error) {
+            finish(new Error('lark-channel setup: could not enter secure terminal input mode', { cause: error }));
+        }
+    });
+}
+async function readLinuxManualSecret() {
+    if (defaultLinuxSecretToolAvailable('/usr/bin/systemd-ask-password')) {
+        const prompt = spawnSync('/usr/bin/systemd-ask-password', ['飞书 App Secret：'], {
+            encoding: 'utf8', env: linuxCredentialEnv(), maxBuffer: 128 * 1024, stdio: ['inherit', 'pipe', 'inherit'],
+        });
+        const secret = typeof prompt.stdout === 'string' ? prompt.stdout.replace(/[\r\n]+$/u, '') : '';
+        if (prompt.status !== 0 || secret.length === 0) {
+            throw new Error('lark-channel setup: Linux could not read the App Secret securely');
+        }
+        return secret;
+    }
+    return readSecretFromRawTerminal('\n飞书 App Secret（输入不会回显）：');
 }
 function executeSecretWrite(request, env, failure) {
     try {
         const result = spawnSync(request.executable, request.args, {
             encoding: 'utf8',
             env,
+            ...(request.executable === linuxSecretTool ? { timeout: linuxSecretServiceTimeoutMs } : {}),
             input: request.input,
             maxBuffer: 128 * 1024,
             stdio: ['pipe', 'ignore', 'pipe'],
         });
-        if (result.status !== 0)
-            throw new Error(failure);
+        if (result.status !== 0) {
+            throw typeof failure === 'string' ? new Error(failure) : failure(result);
+        }
     }
     finally {
         request.input.fill(0);
     }
 }
-function storeSecret(provider, service, account, credentialPath) {
+async function storeSecret(provider, service, account, credentialPath) {
     if (provider === 'macos-keychain') {
         process.stdout.write('\n请在 macOS Keychain 的安全提示中输入 App Secret（输入不会回显）：\n');
         runSecurity(['add-generic-password', '-U', '-a', account, '-s', service, '-w'], 'inherit');
         return;
     }
-    if (provider === 'linux-secret-service') {
-        const prompt = spawnSync('/usr/bin/systemd-ask-password', ['飞书 App Secret：'], {
-            encoding: 'utf8', env: linuxCredentialEnv(), maxBuffer: 128 * 1024, stdio: ['inherit', 'pipe', 'inherit'],
-        });
-        const secret = typeof prompt.stdout === 'string' ? prompt.stdout.replace(/[\r\n]+$/u, '') : '';
-        if (prompt.status !== 0 || secret.length === 0) {
-            throw new Error('lark-channel setup: Linux could not read the App Secret securely');
+    if (provider === 'linux-secret-service' || provider === 'linux-protected-file') {
+        const secret = await readLinuxManualSecret();
+        if (provider === 'linux-protected-file') {
+            if (credentialPath === undefined)
+                throw new Error('lark-channel setup: missing Linux protected credential path');
+            await storeLinuxProtectedCredential(credentialPath, secret);
+        }
+        else {
+            const environment = linuxCredentialEnv();
+            executeSecretWrite(createSecretServiceWriteRequest(service, account, secret), environment, result => linuxSecretServiceDiagnostic('credential store', result, environment));
         }
-        executeSecretWrite(createSecretServiceWriteRequest(service, account, secret), linuxCredentialEnv(), 'lark-channel setup: Linux Secret Service operation failed');
         return;
     }
     if (credentialPath === undefined || (!isAbsolute(credentialPath) && !win32.isAbsolute(credentialPath))) {
@@ -335,7 +866,7 @@ function storeSecret(provider, service, account, credentialPath) {
     if (result.status !== 0)
         throw new Error('lark-channel setup: Windows DPAPI operation failed');
 }
-function storeGeneratedSecret(provider, service, account, secret, credentialPath) {
+async function storeGeneratedSecret(provider, service, account, secret, credentialPath) {
     if (provider === 'macos-keychain') {
         const request = createKeychainWriteRequest(service, account, secret);
         try {
@@ -352,7 +883,14 @@ function storeGeneratedSecret(provider, service, account, secret, credentialPath
         return;
     }
     if (provider === 'linux-secret-service') {
-        executeSecretWrite(createSecretServiceWriteRequest(service, account, secret), linuxCredentialEnv(), 'lark-channel setup: Linux Secret Service operation failed');
+        const environment = linuxCredentialEnv();
+        executeSecretWrite(createSecretServiceWriteRequest(service, account, secret), environment, result => linuxSecretServiceDiagnostic('credential store', result, environment));
+        return;
+    }
+    if (provider === 'linux-protected-file') {
+        if (credentialPath === undefined)
+            throw new Error('lark-channel setup: missing Linux protected credential path');
+        await storeLinuxProtectedCredential(credentialPath, secret);
         return;
     }
     if (credentialPath === undefined)
@@ -361,19 +899,26 @@ function storeGeneratedSecret(provider, service, account, secret, credentialPath
         PATH: 'C:\\Windows\\System32;C:\\Windows', SystemRoot: 'C:\\Windows',
     }, 'lark-channel setup: Windows DPAPI operation failed');
 }
-function readSecret(provider, service, account, credentialPath) {
+async function readSecret(provider, service, account, credentialPath) {
     let value = '';
     if (provider === 'macos-keychain') {
         value = runSecurity(['find-generic-password', '-w', '-a', account, '-s', service], 'pipe');
     }
     else if (provider === 'linux-secret-service') {
-        const result = spawnSync('/usr/bin/secret-tool', ['lookup', 'service', service, 'account', account], {
-            encoding: 'utf8', env: linuxCredentialEnv(), maxBuffer: 128 * 1024, stdio: ['ignore', 'pipe', 'pipe'],
+        const environment = linuxCredentialEnv();
+        const result = spawnSync(linuxSecretTool, ['lookup', 'service', service, 'account', account], {
+            encoding: 'utf8', env: environment, timeout: linuxSecretServiceTimeoutMs,
+            maxBuffer: 128 * 1024, stdio: ['ignore', 'pipe', 'pipe'],
         });
         if (result.status !== 0)
-            throw new Error('lark-channel setup: Linux Secret Service lookup failed');
+            throw linuxSecretServiceDiagnostic('credential lookup', result, environment);
         value = typeof result.stdout === 'string' ? result.stdout.trimEnd() : '';
     }
+    else if (provider === 'linux-protected-file') {
+        if (credentialPath === undefined)
+            throw new Error('lark-channel setup: missing Linux protected credential path');
+        value = await readLinuxProtectedCredential(credentialPath);
+    }
     else {
         if (credentialPath === undefined)
             throw new Error('lark-channel setup: missing DPAPI credential path');
@@ -412,7 +957,7 @@ function exactYamlStringSequence(node, expected) {
     return node.items.every((item, index) => item?.toJSON() === expected[index]);
 }
 function exactManagedCredentialHandleShape(handle, provider) {
-    const expectedKeys = provider === 'windows-dpapi'
+    const expectedKeys = provider === 'windows-dpapi' || provider === 'linux-protected-file'
         ? ['consumers', 'id', 'maxLeaseMs', 'path', 'provider', 'purposes']
         : ['account', 'consumers', 'id', 'maxLeaseMs', 'provider', 'purposes', 'service'];
     const value = handle.toJSON();
@@ -424,8 +969,9 @@ function exactManagedCredentialHandleShape(handle, provider) {
 function credentialHandleAliasesLocator(handle, locator) {
     if (!isMap(handle) || handle.get('provider') !== locator.provider)
         return false;
-    if (locator.provider === 'windows-dpapi')
+    if (locator.provider === 'windows-dpapi' || locator.provider === 'linux-protected-file') {
         return handle.get('path') === locator.path;
+    }
     return handle.get('service') === locator.service && handle.get('account') === locator.account;
 }
 /**
@@ -460,7 +1006,10 @@ export function findManagedLarkCredentialLocator(input) {
     if (!isMap(handle))
         return undefined;
     const provider = handle.get('provider');
-    if ((provider !== 'macos-keychain' && provider !== 'linux-secret-service' && provider !== 'windows-dpapi')
+    if ((provider !== 'macos-keychain'
+        && provider !== 'linux-protected-file'
+        && provider !== 'linux-secret-service'
+        && provider !== 'windows-dpapi')
         || !exactManagedCredentialHandleShape(handle, provider))
         return undefined;
     if (provider === 'macos-keychain' || provider === 'linux-secret-service') {
@@ -480,17 +1029,19 @@ export function findManagedLarkCredentialLocator(input) {
             return undefined;
         return locator;
     }
-    if (provider === 'windows-dpapi') {
+    if (provider === 'windows-dpapi' || provider === 'linux-protected-file') {
         const path = handle.get('path');
         if (typeof path !== 'string')
             return undefined;
         const directory = platformJoin(input.dshHome, 'credentials-keychain');
-        const legacyPath = platformJoin(directory, `lark-${input.profile}-${account}.clixml`);
+        const extension = provider === 'windows-dpapi' ? '.clixml' : '.secret';
+        const legacyPath = platformJoin(directory, `lark-${input.profile}-${account}${extension}`);
         const versionPrefix = platformJoin(directory, `lark-${input.profile}-${account}-`);
-        const version = path.startsWith(versionPrefix) && path.endsWith('.clixml')
-            ? path.slice(versionPrefix.length, -'.clixml'.length)
+        const version = path.startsWith(versionPrefix) && path.endsWith(extension)
+            ? path.slice(versionPrefix.length, -extension.length)
             : undefined;
-        if (path !== legacyPath && (version === undefined || !credentialVersionPattern.test(version)))
+        const acceptsLegacy = provider === 'windows-dpapi' && path === legacyPath;
+        if (!acceptsLegacy && (version === undefined || !credentialVersionPattern.test(version)))
             return undefined;
         const locator = { provider, path };
         if (handles.items.some(item => item !== handle && credentialHandleAliasesLocator(item, locator)))
@@ -500,33 +1051,43 @@ export function findManagedLarkCredentialLocator(input) {
     return undefined;
 }
 async function removeCredential(locator) {
-    if (locator.provider === 'windows-dpapi') {
+    if (locator.provider === 'windows-dpapi' || locator.provider === 'linux-protected-file') {
         try {
             await unlink(locator.path);
+            if (locator.provider === 'linux-protected-file')
+                await syncDirectory(dirname(locator.path));
         }
         catch (error) {
             if (fileSystemErrorCode(error) !== 'ENOENT') {
-                throw new Error('lark-channel setup: Windows DPAPI credential cleanup failed', { cause: error });
+                const backend = locator.provider === 'windows-dpapi' ? 'Windows DPAPI' : 'Linux protected file';
+                throw new Error(`lark-channel setup: ${backend} credential cleanup failed`, { cause: error });
             }
         }
         return;
     }
-    const result = locator.provider === 'macos-keychain'
-        ? spawnSync('/usr/bin/security', [
-            'delete-generic-password', '-a', locator.account, '-s', locator.service,
-        ], {
-            encoding: 'utf8', env: { PATH: '/usr/bin:/bin' }, maxBuffer: 128 * 1024, stdio: ['ignore', 'ignore', 'pipe'],
-        })
-        : spawnSync('/usr/bin/secret-tool', [
+    if (locator.provider === 'linux-secret-service') {
+        const environment = linuxCredentialEnv();
+        const result = spawnSync(linuxSecretTool, [
             'clear', 'service', locator.service, 'account', locator.account,
         ], {
-            encoding: 'utf8', env: linuxCredentialEnv(), maxBuffer: 128 * 1024, stdio: ['ignore', 'ignore', 'pipe'],
+            encoding: 'utf8', env: environment, timeout: linuxSecretServiceTimeoutMs,
+            maxBuffer: 128 * 1024, stdio: ['ignore', 'ignore', 'pipe'],
         });
-    const missingMacosItem = locator.provider === 'macos-keychain' && result.status === 44;
+        if (result.status !== 0 && !isLinuxSecretServiceClearAbsent(result)) {
+            throw linuxSecretServiceDiagnostic('credential cleanup', result, environment);
+        }
+        return;
+    }
+    const result = spawnSync('/usr/bin/security', [
+        'delete-generic-password', '-a', locator.account, '-s', locator.service,
+    ], {
+        encoding: 'utf8', env: { PATH: '/usr/bin:/bin' }, maxBuffer: 128 * 1024, stdio: ['ignore', 'ignore', 'pipe'],
+    });
+    const missingMacosItem = result.status === 44;
     const missingItemMessage = typeof result.stderr === 'string'
         && /(?:could not be found|not found|no matching|no such)/iu.test(result.stderr);
     if (result.status !== 0 && !missingMacosItem && !missingItemMessage) {
-        throw new Error(`lark-channel setup: ${locator.provider} credential cleanup failed`);
+        throw new Error('lark-channel setup: macos-keychain credential cleanup failed');
     }
 }
 function credentialIsAlreadyAbsent(error) {
@@ -542,14 +1103,27 @@ async function removeCredentialIdempotently(locator, operation) {
             throw error;
     }
 }
-async function retirePreviousCredentialBestEffort(locator, operation) {
+async function retirePreviousCredential(locator, operation) {
     try {
         await removeCredentialIdempotently(locator, operation);
     }
+    catch (error) {
+        // The profile and Delivery owner already reference the staged credential,
+        // so rollback is unsafe. Callers retain their paired journal and retry the
+        // exact old locator before allowing another credential rotation.
+        throw new AggregateError([error], 'lark-channel setup: profile and owner were committed, but previous credential cleanup is pending; repair the credential provider and rerun setup');
+    }
+}
+/**
+ * Compatibility behavior for the legacy non-journal commit helper below.
+ * Full onboarding uses retirePreviousCredential directly so it can retain its
+ * paired journal and retry the exact locator on the next invocation.
+ */
+async function retirePreviousCredentialBestEffort(locator, operation) {
+    try {
+        await retirePreviousCredential(locator, operation);
+    }
     catch {
-        // The profile and Delivery owner already reference the staged credential.
-        // Retaining an inactive old secret is safer than blocking all future setup
-        // recovery or falsely reporting that the committed rotation failed.
         process.stderr.write('lark-channel setup: previous credential cleanup failed after commit\n');
     }
 }
@@ -728,9 +1302,12 @@ export async function withProfileSetupLock(patchPath, operation, options = {}) {
 }
 async function atomicWrite(path, value) {
     const temporary = join(dirname(path), `.cordis.patch.yml.lark-setup-${process.pid}-${randomBytes(8).toString('hex')}`);
+    let created = false;
     try {
-        const file = await open(temporary, 'w', 0o600);
+        const file = await open(temporary, 'wx', 0o600);
+        created = true;
         try {
+            await file.chmod(0o600);
             await file.writeFile(value, 'utf8');
             await file.sync();
         }
@@ -741,7 +1318,8 @@ async function atomicWrite(path, value) {
         await syncDirectory(dirname(path));
     }
     catch (error) {
-        await rm(temporary, { force: true });
+        if (created)
+            await rm(temporary, { force: true });
         throw error;
     }
 }
@@ -762,6 +1340,9 @@ async function syncDirectory(path) {
 function setupJournalPath(patchPath) {
     return `${patchPath}.lark-setup.journal.json`;
 }
+function deferredCredentialCleanupPath(patchPath) {
+    return `${patchPath}.lark-credential-cleanup.json`;
+}
 function textSha256(value) {
     return createHash('sha256').update(value).digest('hex');
 }
@@ -771,9 +1352,14 @@ function escapeRegularExpression(value) {
 function credentialLocatorEquals(left, right) {
     if (left.provider !== right.provider)
         return false;
-    if (left.provider === 'windows-dpapi' && right.provider === 'windows-dpapi')
+    if ((left.provider === 'windows-dpapi' && right.provider === 'windows-dpapi')
+        || (left.provider === 'linux-protected-file' && right.provider === 'linux-protected-file')) {
         return left.path === right.path;
-    if (left.provider === 'windows-dpapi' || right.provider === 'windows-dpapi')
+    }
+    if (left.provider === 'windows-dpapi'
+        || left.provider === 'linux-protected-file'
+        || right.provider === 'windows-dpapi'
+        || right.provider === 'linux-protected-file')
         return false;
     return left.service === right.service && left.account === right.account;
 }
@@ -801,28 +1387,202 @@ function validateJournalCredentialLocator(input) {
         }
         return { provider: locator.provider, service: locator.service, account: locator.account };
     }
-    if (locator.provider === 'windows-dpapi') {
+    if (locator.provider === 'windows-dpapi' || locator.provider === 'linux-protected-file') {
         if (typeof locator.path !== 'string') {
-            throw new Error('lark-channel setup: setup journal DPAPI locator is invalid');
+            throw new Error('lark-channel setup: setup journal file credential locator is invalid');
         }
         const directory = platformJoin(input.dshHome, 'credentials-keychain');
         if (dirname(locator.path) !== directory) {
-            throw new Error('lark-channel setup: setup journal DPAPI locator is outside the credential directory');
+            throw new Error('lark-channel setup: setup journal file credential locator is outside the credential directory');
         }
         const name = locator.path.slice(directory.length + 1);
         const profile = escapeRegularExpression(input.profile);
         const account = input.stagedAccount === undefined
             ? '[A-Za-z0-9][A-Za-z0-9._-]{0,63}'
             : escapeRegularExpression(input.stagedAccount);
-        const versioned = new RegExp(`^lark-${profile}-${account}-[0-9a-f]{32}\\.clixml$`, 'u');
+        const extension = locator.provider === 'windows-dpapi' ? 'clixml' : 'secret';
+        const versioned = new RegExp(`^lark-${profile}-${account}-[0-9a-f]{32}\\.${extension}$`, 'u');
         const legacy = new RegExp(`^lark-${profile}-${account}\\.clixml$`, 'u');
-        if (!versioned.test(name) && (input.stagedAccount !== undefined || !legacy.test(name))) {
-            throw new Error('lark-channel setup: setup journal DPAPI locator is not setup-managed');
+        const acceptsLegacy = locator.provider === 'windows-dpapi'
+            && input.stagedAccount === undefined
+            && legacy.test(name);
+        if (!versioned.test(name) && !acceptsLegacy) {
+            throw new Error('lark-channel setup: setup journal file credential locator is not setup-managed');
         }
         return { provider: locator.provider, path: locator.path };
     }
     throw new Error('lark-channel setup: setup journal credential provider is invalid');
 }
+function profileReferencesCredentialLocator(profilePatch, locator) {
+    const document = parseDocument(profilePatch, { uniqueKeys: true });
+    if (document.errors.length > 0 || !isSeq(document.contents)) {
+        throw new Error('lark-channel setup: cannot prove a deferred credential is inactive in an invalid profile');
+    }
+    const rows = document.contents.items.filter(item => isMap(item)
+        && item.get('id') === 'dsh-enhanced-credentials-keychain');
+    for (const row of rows) {
+        const config = row.get('config', true);
+        if (!isMap(config)) {
+            throw new Error('lark-channel setup: cannot prove a deferred credential is inactive in malformed credentials config');
+        }
+        const handles = config.get('handles', true);
+        if (handles === undefined)
+            continue;
+        if (!isSeq(handles)) {
+            throw new Error('lark-channel setup: cannot prove a deferred credential is inactive in malformed handles config');
+        }
+        if (handles.items.some(handle => credentialHandleAliasesLocator(handle, locator)))
+            return true;
+    }
+    return false;
+}
+function deferredCleanupChecksum(locators) {
+    return textSha256(JSON.stringify(locators));
+}
+async function readDeferredCredentialCleanup(input) {
+    const path = deferredCredentialCleanupPath(input.patchPath);
+    let file;
+    let buffer;
+    let text;
+    try {
+        file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        const before = await file.stat();
+        const uid = currentLinuxCredentialUid();
+        if (!before.isFile() || before.nlink !== 1 || before.uid !== uid
+            || (before.mode & 0o7777) !== 0o600 || before.size < 1 || before.size > 1024 * 1024) {
+            throw new Error('lark-channel setup: deferred credential cleanup record failed its security check');
+        }
+        buffer = Buffer.alloc(1024 * 1024 + 1);
+        let bytesRead = 0;
+        while (bytesRead < buffer.byteLength) {
+            const result = await file.read(buffer, bytesRead, buffer.byteLength - bytesRead, bytesRead);
+            if (result.bytesRead === 0)
+                break;
+            bytesRead += result.bytesRead;
+        }
+        const after = await file.stat();
+        if (bytesRead !== after.size || after.dev !== before.dev || after.ino !== before.ino
+            || !after.isFile() || after.nlink !== 1 || after.uid !== uid || (after.mode & 0o7777) !== 0o600) {
+            throw new Error('lark-channel setup: deferred credential cleanup record changed while being read');
+        }
+        text = buffer.toString('utf8', 0, bytesRead);
+    }
+    catch (error) {
+        if (fileSystemErrorCode(error) === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+    finally {
+        buffer?.fill(0);
+        await file?.close();
+    }
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch (error) {
+        throw new Error('lark-channel setup: deferred credential cleanup record is not valid JSON', { cause: error });
+    }
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('lark-channel setup: deferred credential cleanup record is invalid');
+    }
+    const record = value;
+    const keys = Object.keys(record).sort();
+    if (keys.join('\0') !== ['dshHome', 'locators', 'patchPath', 'profile', 'sha256', 'version'].join('\0')
+        || record.version !== 1
+        || record.patchPath !== input.patchPath
+        || record.dshHome !== input.dshHome
+        || record.profile !== input.profile
+        || !Array.isArray(record.locators)
+        || record.locators.length < 1
+        || record.locators.length > 256) {
+        throw new Error('lark-channel setup: deferred credential cleanup record identity is invalid');
+    }
+    const locators = record.locators.map(locator => validateJournalCredentialLocator({
+        locator,
+        dshHome: input.dshHome,
+        profile: input.profile,
+    }));
+    if (record.sha256 !== deferredCleanupChecksum(locators)
+        || new Set(locators.map(locator => JSON.stringify(locator))).size !== locators.length) {
+        throw new Error('lark-channel setup: deferred credential cleanup record checksum or entries are invalid');
+    }
+    return { version: 1, ...input, locators, sha256: record.sha256 };
+}
+async function persistDeferredCredentialCleanup(input) {
+    const identifiers = new Set();
+    const locators = input.locators.map(locator => validateJournalCredentialLocator({
+        locator,
+        dshHome: input.dshHome,
+        profile: input.profile,
+    })).filter(locator => {
+        const identifier = JSON.stringify(locator);
+        if (identifiers.has(identifier))
+            return false;
+        identifiers.add(identifier);
+        return true;
+    });
+    const path = deferredCredentialCleanupPath(input.patchPath);
+    if (locators.length === 0) {
+        try {
+            await unlink(path);
+            await syncDirectory(dirname(path));
+        }
+        catch (error) {
+            if (fileSystemErrorCode(error) !== 'ENOENT')
+                throw error;
+        }
+        return;
+    }
+    if (locators.length > 256)
+        throw new Error('lark-channel setup: too many deferred credential cleanup entries');
+    const record = {
+        version: 1,
+        patchPath: input.patchPath,
+        dshHome: input.dshHome,
+        profile: input.profile,
+        locators,
+        sha256: deferredCleanupChecksum(locators),
+    };
+    await atomicWrite(path, `${JSON.stringify(record)}\n`);
+}
+function canDeferSecretServiceCleanup(locator, error) {
+    return locator.provider === 'linux-secret-service' && safeDiagnosticMessages(error).length > 0;
+}
+async function deferInactiveCredentialCleanup(input) {
+    if (profileReferencesCredentialLocator(input.profilePatch, input.locator)) {
+        throw new Error('lark-channel setup: refusing to defer cleanup for a credential still referenced by the profile');
+    }
+    const current = await readDeferredCredentialCleanup(input);
+    await persistDeferredCredentialCleanup({
+        patchPath: input.patchPath,
+        dshHome: input.dshHome,
+        profile: input.profile,
+        locators: [...(current?.locators ?? []), input.locator],
+    });
+}
+/** Best-effort retry for already proven-inactive credentials. Call while holding the profile lock. */
+export async function retryDeferredLarkCredentialCleanup(input) {
+    const pending = await readDeferredCredentialCleanup(input);
+    if (pending === undefined)
+        return 0;
+    const profilePatch = await readFile(input.patchPath, 'utf8');
+    const remove = input.removeCredential ?? removeCredential;
+    const remaining = [];
+    for (const locator of pending.locators) {
+        if (profileReferencesCredentialLocator(profilePatch, locator)) {
+            throw new Error('lark-channel setup: a deferred credential cleanup entry became active; refusing cleanup');
+        }
+        try {
+            await removeCredentialIdempotently(locator, remove);
+        }
+        catch {
+            remaining.push(locator);
+        }
+    }
+    await persistDeferredCredentialCleanup({ ...input, locators: remaining });
+    return remaining.length;
+}
 function normalizeSetupJournalInput(input) {
     if ((!isAbsolute(input.patchPath) && !win32.isAbsolute(input.patchPath))
         || (!isAbsolute(input.dshHome) && !win32.isAbsolute(input.dshHome))
@@ -1406,6 +2166,23 @@ async function withDeliveryOwnerSetupLock(databasePath, operation, options = {})
     await mkdir(dirname(resourcePath), { recursive: true, mode: 0o700 });
     return withProfileSetupLock(`${resourcePath}.lark-owner`, operation, options);
 }
+async function removeInactiveCredentialForRecovery(input) {
+    try {
+        await removeCredentialIdempotently(input.locator, input.remove);
+    }
+    catch (error) {
+        if (!input.recovery.allowDeferredSecretServiceCleanup
+            || !canDeferSecretServiceCleanup(input.locator, error))
+            throw error;
+        await deferInactiveCredentialCleanup({
+            patchPath: input.recovery.patchPath,
+            dshHome: input.recovery.dshHome,
+            profile: input.recovery.profile,
+            profilePatch: input.profilePatch,
+            locator: input.locator,
+        });
+    }
+}
 async function recoverLarkSetupJournalRecordUnlocked(input, journal) {
     const remove = input.operations?.removeCredential ?? removeCredential;
     const pair = input.operations?.pairPrincipal ?? defaultPairPrincipal;
@@ -1416,7 +2193,12 @@ async function recoverLarkSetupJournalRecordUnlocked(input, journal) {
         if (current !== journal.originalPatch) {
             throw new Error('lark-channel setup: staging journal conflicts with the live profile');
         }
-        await removeCredentialIdempotently(journal.stagedCredential, remove);
+        await removeInactiveCredentialForRecovery({
+            recovery: input,
+            locator: journal.stagedCredential,
+            profilePatch: current,
+            remove,
+        });
         await clearLarkSetupJournal(input.patchPath);
         return true;
     }
@@ -1427,7 +2209,12 @@ async function recoverLarkSetupJournalRecordUnlocked(input, journal) {
             throw new Error('lark-channel setup: candidate recovery refused because the live profile diverged');
         }
         if (journal.stagedCredential !== undefined) {
-            await removeCredentialIdempotently(journal.stagedCredential, remove);
+            await removeInactiveCredentialForRecovery({
+                recovery: input,
+                locator: journal.stagedCredential,
+                profilePatch: journal.originalPatch,
+                remove,
+            });
         }
         await clearLarkSetupJournal(input.patchPath);
         return true;
@@ -1446,7 +2233,22 @@ async function recoverLarkSetupJournalRecordUnlocked(input, journal) {
             await persistLarkSetupJournal(journalPersistInput(journal, 'paired'));
         if (journal.previousCredential !== undefined
             && !credentialLocatorEquals(journal.previousCredential, journal.stagedCredential)) {
-            await retirePreviousCredentialBestEffort(journal.previousCredential, remove);
+            try {
+                await retirePreviousCredential(journal.previousCredential, remove);
+            }
+            catch (error) {
+                const migratingToProtectedFile = journal.stagedCredential?.provider === 'linux-protected-file';
+                if ((!input.allowDeferredSecretServiceCleanup && !migratingToProtectedFile)
+                    || !canDeferSecretServiceCleanup(journal.previousCredential, error))
+                    throw error;
+                await deferInactiveCredentialCleanup({
+                    patchPath: input.patchPath,
+                    dshHome: input.dshHome,
+                    profile: input.profile,
+                    profilePatch: journal.updatedPatch,
+                    locator: journal.previousCredential,
+                });
+            }
         }
         if (journal.installService)
             await install();
@@ -1493,6 +2295,14 @@ async function recoverValidatedRefreshJournalUnlocked(input, journal) {
     return true;
 }
 async function recoverLarkSetupJournalUnlocked(input) {
+    await retryDeferredLarkCredentialCleanup({
+        patchPath: input.patchPath,
+        dshHome: input.dshHome,
+        profile: input.profile,
+        ...(input.operations?.removeCredential === undefined
+            ? {}
+            : { removeCredential: input.operations.removeCredential }),
+    });
     const journal = await readLarkSetupJournal(input);
     if (journal === undefined)
         return false;
@@ -1626,15 +2436,7 @@ export async function commitValidatedLarkOwnerSetup(input) {
     }
     const previous = input.credentialTransition?.previous;
     if (previous !== undefined && JSON.stringify(previous) !== JSON.stringify(input.credentialTransition?.staged)) {
-        try {
-            await remove(previous);
-        }
-        catch {
-            // The profile and owner are already committed. Keep the now-inactive
-            // credential rather than reporting a false setup failure or rolling back
-            // a successful handoff; a later setup can retire the orphan safely.
-            process.stderr.write('lark-channel setup: previous credential cleanup failed after commit\n');
-        }
+        await retirePreviousCredentialBestEffort(previous, remove);
     }
 }
 async function abortStagingJournal(input) {
@@ -1644,6 +2446,22 @@ async function abortStagingJournal(input) {
             cause: input.setupError,
         });
     }
+    if (input.stagedCredential.provider === 'linux-protected-file'
+        && fileSystemErrorCode(input.setupError) === 'EEXIST') {
+        // O_EXCL proves this setup never created the colliding path. Removing it
+        // here would delete somebody else's file merely because our random locator
+        // collided (or was deliberately pre-created). Clear only our journal; the
+        // next invocation will generate a new versioned locator.
+        try {
+            await clearLarkSetupJournal(input.patchPath);
+        }
+        catch (journalError) {
+            throw new AggregateError([input.setupError, journalError], 'lark-channel setup: protected credential path collided and setup journal cleanup also failed');
+        }
+        throw new Error('lark-channel setup: protected credential path collision; rerun setup', {
+            cause: input.setupError,
+        });
+    }
     try {
         await removeCredentialIdempotently(input.stagedCredential, input.remove);
         await clearLarkSetupJournal(input.patchPath);
@@ -1690,6 +2508,7 @@ export async function executeLarkSetupProfileTransaction(input) {
                 readEffectiveProfile,
                 ...(input.operations.afterCommit === undefined ? {} : { installService: input.operations.afterCommit }),
             },
+            allowDeferredSecretServiceCleanup: input.credentialProvider === 'linux-protected-file',
         });
         const originalPatch = await readFile(input.patchPath, 'utf8');
         const effectiveProfile = await readEffectiveProfile(input.args.profile);
@@ -1716,7 +2535,8 @@ export async function executeLarkSetupProfileTransaction(input) {
                 profile: input.args.profile,
                 account: input.args.account,
             });
-            if (stagedCredential.provider === 'windows-dpapi') {
+            if (stagedCredential.provider === 'windows-dpapi'
+                || stagedCredential.provider === 'linux-protected-file') {
                 await mkdir(dirname(stagedCredential.path), { recursive: true, mode: 0o700 });
             }
             const transactionId = randomBytes(16).toString('hex');
@@ -1756,7 +2576,9 @@ export async function executeLarkSetupProfileTransaction(input) {
                     }
                     const keychainService = stagedCredential.provider === 'windows-dpapi'
                         ? `dsh/lark/${input.args.profile}/${input.args.account}/versions/windows-dpapi`
-                        : stagedCredential.service;
+                        : stagedCredential.provider === 'linux-protected-file'
+                            ? `dsh/lark/${input.args.profile}/${input.args.account}/versions/linux-protected-file`
+                            : stagedCredential.service;
                     return {
                         owner,
                         updatedPatch: configureLarkProfilePatch({
@@ -1771,7 +2593,10 @@ export async function executeLarkSetupProfileTransaction(input) {
                             keychainAccount: input.args.account,
                             credentialProvider: input.credentialProvider,
                             agentTools: input.args.agentTools,
-                            ...(stagedCredential.provider === 'windows-dpapi' ? { credentialPath: stagedCredential.path } : {}),
+                            ...(stagedCredential.provider === 'windows-dpapi'
+                                || stagedCredential.provider === 'linux-protected-file'
+                                ? { credentialPath: stagedCredential.path }
+                                : {}),
                         }),
                     };
                 }
@@ -1876,7 +2701,21 @@ export async function executeLarkSetupProfileTransaction(input) {
             // the idempotent exact-owner handoff and converges forward.
             await persistLarkSetupJournal({ ...candidateJournal, phase: 'paired' });
             if (previousCredential !== undefined && !credentialLocatorEquals(previousCredential, stagedCredential)) {
-                await retirePreviousCredentialBestEffort(previousCredential, remove);
+                try {
+                    await retirePreviousCredential(previousCredential, remove);
+                }
+                catch (error) {
+                    if (input.credentialProvider !== 'linux-protected-file'
+                        || !canDeferSecretServiceCleanup(previousCredential, error))
+                        throw error;
+                    await deferInactiveCredentialCleanup({
+                        patchPath: input.patchPath,
+                        dshHome: input.dshHome,
+                        profile: input.args.profile,
+                        profilePatch: updatedPatch,
+                        locator: previousCredential,
+                    });
+                }
             }
             await input.operations.afterCommit?.();
             await clearLarkSetupJournal(input.patchPath);
@@ -1896,6 +2735,7 @@ export async function runLarkSetup(argv = process.argv.slice(2), runtime = {}) {
     const validate = runtime.validateProfile ?? validateProfile;
     const readEffectiveProfile = runtime.readEffectiveProfile ?? dumpProfile;
     const installResidentService = runtime.installResidentService ?? installDshResidentService;
+    const prepareResidentService = runtime.prepareResidentService ?? prepareDshSystemdUserService;
     const recoveryOperations = {
         ...runtime.journalOperations,
         readEffectiveProfile: runtime.journalOperations?.readEffectiveProfile ?? readEffectiveProfile,
@@ -1986,6 +2826,11 @@ export async function runLarkSetup(argv = process.argv.slice(2), runtime = {}) {
         return;
     }
     if (args.installServiceOnly) {
+        if (process.platform === 'linux') {
+            const prepared = await prepareResidentService({ dshHome, profile: args.profile });
+            if (prepared?.enabledLinger)
+                process.stdout.write('已为当前 Linux 用户启用 linger，注销 SSH 后服务仍会保持。\n');
+        }
         const service = await withProfileSetupLock(patchPath, async () => {
             await recoverLarkSetupJournalUnlocked({
                 patchPath,
@@ -2017,6 +2862,31 @@ export async function runLarkSetup(argv = process.argv.slice(2), runtime = {}) {
             + `状态：${service.statusCommand}\n日志：${service.logCommand}\n`);
         return;
     }
+    const preferredCredentialProvider = credentialProviderForPlatform(process.platform);
+    if (process.platform === 'linux' && args.manageService) {
+        const prepared = await prepareResidentService({ dshHome, profile: args.profile });
+        if (prepared?.enabledLinger)
+            process.stdout.write('已为当前 Linux 用户启用 linger，注销 SSH 后服务仍会保持。\n');
+    }
+    let credentialProvider;
+    if (runtime.preflightCredentialProvider === undefined) {
+        const selection = await selectLarkCredentialProvider(preferredCredentialProvider, {
+            dshHome,
+            mode: args.linuxCredentialProvider,
+        });
+        credentialProvider = selection.provider;
+        if (selection.fallbackReason !== undefined) {
+            process.stdout.write('Linux Secret Service 当前不可用；向导已自动切换到当前用户 0600 私有凭据文件。'
+                + '该文件未额外加密，同一 UID 与 root 可读取，但不会进入 profile、命令参数、环境变量或日志。\n');
+        }
+    }
+    else {
+        if (args.linuxCredentialProvider !== 'auto') {
+            throw new Error('lark-channel setup: an injected credential preflight cannot be combined with an explicit Linux provider');
+        }
+        credentialProvider = await runtime.preflightCredentialProvider(preferredCredentialProvider)
+            ?? preferredCredentialProvider;
+    }
     // Resolve a prior crash before prompting the user or mutating a cloud app.
     // The mutation transaction repeats this check after registration to close
     // the gap against a different setup process that completed in the meantime.
@@ -2026,6 +2896,7 @@ export async function runLarkSetup(argv = process.argv.slice(2), runtime = {}) {
             dshHome,
             profile: args.profile,
             operations: recoveryOperations,
+            allowDeferredSecretServiceCleanup: credentialProvider === 'linux-protected-file',
         });
         const databasePath = deliveryDatabasePathFromEffectiveProfile(await readEffectiveProfile(args.profile), dshHome);
         await withDeliveryOwnerSetupLock(databasePath, async () => {
@@ -2037,7 +2908,6 @@ export async function runLarkSetup(argv = process.argv.slice(2), runtime = {}) {
             });
         }, runtime.profileLockOptions);
     }, runtime.profileLockOptions);
-    const credentialProvider = credentialProviderForPlatform(process.platform);
     let appId = args.appId;
     let createApp = args.createApp;
     if (appId === undefined && !createApp) {
@@ -2081,24 +2951,31 @@ export async function runLarkSetup(argv = process.argv.slice(2), runtime = {}) {
         credentialProvider,
         ...(runtime.profileLockOptions === undefined ? {} : { profileLockOptions: runtime.profileLockOptions }),
         operations: {
-            storeCredential(locator) {
+            async storeCredential(locator) {
                 const service = locator.provider === 'windows-dpapi'
                     ? `dsh/lark/${args.profile}/${args.account}/versions/windows-dpapi`
-                    : locator.service;
-                const credentialPath = locator.provider === 'windows-dpapi' ? locator.path : undefined;
+                    : locator.provider === 'linux-protected-file'
+                        ? `dsh/lark/${args.profile}/${args.account}/versions/linux-protected-file`
+                        : locator.service;
+                const credentialPath = locator.provider === 'windows-dpapi'
+                    || locator.provider === 'linux-protected-file' ? locator.path : undefined;
                 if (generatedSecret === undefined) {
-                    storeSecret(credentialProvider, service, args.account, credentialPath);
+                    await storeSecret(credentialProvider, service, args.account, credentialPath);
                 }
                 else {
-                    storeGeneratedSecret(credentialProvider, service, args.account, generatedSecret, credentialPath);
+                    await storeGeneratedSecret(credentialProvider, service, args.account, generatedSecret, credentialPath);
                 }
-                process.stdout.write(`候选凭据已安全暂存到 ${credentialProvider}；旧凭据仍保持有效。\n`);
+                process.stdout.write(`候选凭据已暂存到 ${credentialProvider}；旧凭据仍保持有效。\n`);
             },
             readCredential(locator) {
                 const service = locator.provider === 'windows-dpapi'
                     ? `dsh/lark/${args.profile}/${args.account}/versions/windows-dpapi`
-                    : locator.service;
-                return readSecret(credentialProvider, service, args.account, locator.provider === 'windows-dpapi' ? locator.path : undefined);
+                    : locator.provider === 'linux-protected-file'
+                        ? `dsh/lark/${args.profile}/${args.account}/versions/linux-protected-file`
+                        : locator.service;
+                return readSecret(credentialProvider, service, args.account, locator.provider === 'windows-dpapi' || locator.provider === 'linux-protected-file'
+                    ? locator.path
+                    : undefined);
             },
             readEffectiveProfile,
             async discoverOwner(ownerInput) {
@@ -2136,7 +3013,7 @@ export async function runLarkSetup(argv = process.argv.slice(2), runtime = {}) {
 }
 if (process.argv[1] !== undefined && isMainEntry(import.meta.url, process.argv[1])) {
     void runLarkSetup().catch(error => {
-        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        process.stderr.write(`${formatLarkSetupError(error)}\n`);
         process.exitCode = 1;
     });
 }