@skrr-ai/auth-core 0.1.2

package/dist/esm/kek/linux.js

@@ -0,0 +1,585 @@
+/**
+ * kek/linux.ts — Linux KEK strategy. Two-tier selector chosen once per
+ * process based on what the host environment supports.
+ *
+ *   Tier-2 (libsecret shellout): when `secret-tool` (libsecret) and a
+ *   reachable D-Bus Secret Service session are both present, the master
+ *   KEK lives in the user's keyring (gnome-keyring on GNOME,
+ *   ksecretservice on KDE — both speak the freedesktop.org Secret
+ *   Service API). The keyring is encrypted at rest under the user's
+ *   login and is session-gated, so neither cold-disk theft nor a
+ *   same-UID file reader without the keystore ACL can recover the KEK.
+ *
+ *   Tier-3 (machine-id HKDF): when libsecret is unavailable (headless
+ *   server, no D-Bus session, no `secret-tool` binary), the master KEK
+ *   is derived deterministically via HKDF-SHA256 from machine identity
+ *   (hostname + UID + loginuid + /etc/machine-id). No KEK is ever
+ *   written to disk on this path.
+ *
+ * Tier-3 threat model — be precise about what we ship vs. what we don't:
+ *   - DEFENDS against backup theft to a different machine: an attacker
+ *     who copies the wrapped credential file off the host cannot
+ *     re-derive the KEK without also reading machine-id from the
+ *     original host (different machine-id ⇒ different KEK ⇒ GCM tag
+ *     mismatch on unwrap).
+ *   - DOES NOT defend against same-user offline brute force on the SAME
+ *     machine. Tier-3 inputs (hostname, UID, loginuid, /etc/machine-id)
+ *     are world-readable to a process running on the host. An attacker
+ *     who lands code on the box can recompute the KEK deterministically
+ *     and decrypt the wrapped DEK without ever touching libsecret.
+ *   - Tier-3 is therefore a FLOOR, not a ceiling: shipping it is
+ *     strictly better than the legacy plaintext-on-disk path, but it
+ *     does not match Tier-2's session-gated guarantee. We ship it
+ *     unconditionally because headless servers without a session keyring
+ *     would otherwise have no KEK protection at all.
+ *
+ * Race semantics on Tier-2 first-run enrollment: second-writer-wins (two
+ * daemon processes both missing on the same TOCTOU window both call
+ * `secret-tool store`, the second overwrites the first). Any DEKs
+ * wrapped under the first KEK become unrecoverable. The upstream caller
+ * (`credEnvelope.ts:initCredEnvelope`) handles this gracefully — unwrap
+ * failure → log + treat as first enrollment. A proper-lockfile layer
+ * upstream eliminates the race in practice. Tier-3 has no race because
+ * the KEK is recomputed (not stored) on every cold start.
+ *
+ * Service/account override (Tier-2 only): the `LinuxKek` constructor
+ * accepts an optional `{ service, account }` override that scopes the
+ * Secret Service item attributes used by `secret-tool lookup`/`store`.
+ * This exists for multi-tenant test isolation and for the real-shellout
+ * smoke test, which uses a per-run unique service name so it cannot
+ * pollute a developer's libsecret store. The override only affects
+ * Tier-2; Tier-3 derives the KEK via HKDF from machine identity and
+ * has no service/account concept — overrides are silently ignored on
+ * the HKDF path. Callers that override the service are responsible for
+ * cleaning up the corresponding Secret Service entry when finished.
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import crypto from 'node:crypto';
+import os from 'node:os';
+import fs from 'node:fs';
+import { openBuffer, sealBuffer, deserialize as envelopeDeserialize, serialize as envelopeSerialize, KEY_LEN, } from '../credentialEnvelope.js';
+import { KekUnavailableError } from './types.js';
+import { registerZeroizeHook } from './zeroize-registry.js';
+/** Stable telemetry kind strings — one per backend tier. */
+const KIND_LIBSECRET = 'linux-libsecret-shellout';
+const KIND_HKDF = 'linux-machineid-hkdf';
+/** Secret Service item attributes for the master KEK (Tier-2). */
+const SS_SERVICE = 'ai.skrr.daemon.kek';
+const SS_ACCOUNT = 'master-kek-v1';
+/** D-Bus transport error substrings — any of these in stderr means no session. */
+const DBUS_TRANSPORT_ERRORS = [
+    'D-Bus',
+    'org.freedesktop.secrets',
+    'No such interface',
+    'Cannot autolaunch',
+];
+/** HKDF-SHA256 parameters for Tier-3. Stable across versions; bumping the
+ *  `v1` suffix would silently invalidate every wrapped DEK on disk. */
+const HKDF_SALT = Buffer.from('oversky-cred-kek-salt-v1');
+const HKDF_INFO = Buffer.from('oversky-cred-kek-v1');
+/** Filesystem paths for Tier-3 IKM components. */
+const PATH_LOGINUID = '/proc/self/loginuid';
+const PATH_MACHINE_ID = '/etc/machine-id';
+const execFileAsync = promisify(execFile);
+let _execFileForTest = null;
+/**
+ * @internal Test seam — inject a mock execFile for hermetic tests so the
+ * suite never touches the real Secret Service. Reset to `null` to restore
+ * the real `child_process.execFile`.
+ */
+export function __setExecFileForTest(fn) {
+    _execFileForTest = fn;
+    // Probe + tier selection caches are keyed to the process; reset so the
+    // next available() call re-evaluates with the new mock.
+    _secretToolProbeCache = undefined;
+    _tierSelection = null;
+}
+/** Default execFile wrapper used when no test override is installed. */
+const defaultExec = async (file, args, options) => {
+    const result = await execFileAsync(file, args, {
+        encoding: 'utf-8',
+        ...(options ?? {}),
+    });
+    // Defensive coercion — when callers override the encoding, stdout may
+    // surface as Buffer/Uint8Array; the typeof guard keeps both shapes safe.
+    return {
+        stdout: typeof result.stdout === 'string'
+            ? result.stdout
+            : Buffer.from(result.stdout).toString('utf-8'),
+        stderr: typeof result.stderr === 'string'
+            ? result.stderr
+            : Buffer.from(result.stderr).toString('utf-8'),
+    };
+};
+function exec(file, args, options) {
+    const impl = _execFileForTest ?? defaultExec;
+    return impl(file, args, { encoding: 'utf-8', ...options });
+}
+let _readFileSyncForTest = null;
+/**
+ * @internal Test seam — inject a mock readFileSync so Tier-3 derivation
+ * tests can drive deterministic IKM without writing to /proc or /etc.
+ * Reset to `null` to restore the real `fs.readFileSync`. Pass `null` to
+ * also clear the tier selection + KEK cache so the next call re-probes.
+ */
+export function __setFsForTest(fn) {
+    _readFileSyncForTest = fn;
+    _tierSelection = null;
+    zeroizeLinuxKekCache();
+}
+function readFileTrimmed(path) {
+    const reader = _readFileSyncForTest ?? fs.readFileSync.bind(fs);
+    try {
+        const raw = reader(path, 'utf-8');
+        return raw.trim();
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Probe — cached for the process lifetime.
+// ---------------------------------------------------------------------------
+/** `undefined` = not yet probed; `boolean` = cached probe outcome. */
+let _secretToolProbeCache;
+/**
+ * Probe secret-tool availability. Two checks:
+ *   1. `secret-tool --version` — ENOENT or exit 127 means binary missing.
+ *   2. `secret-tool search service ai.skrr.daemon.kek.probe` — exit 1
+ *      with no output is fine (nothing matched), but stderr containing a
+ *      D-Bus transport error means the session bus is not running.
+ */
+async function probeSecretTool() {
+    if (process.platform !== 'linux')
+        return false;
+    if (_secretToolProbeCache !== undefined)
+        return _secretToolProbeCache;
+    // Step 1: binary presence.
+    try {
+        await exec('secret-tool', ['--version']);
+    }
+    catch (err) {
+        const code = err.code;
+        const status = err.status;
+        if (code === 'ENOENT' || status === 127) {
+            _secretToolProbeCache = false;
+            return false;
+        }
+        // Binary exists but --version exited non-zero; treat as present and
+        // continue to the D-Bus probe.
+    }
+    // Step 2: D-Bus session probe.
+    try {
+        await exec('secret-tool', ['search', 'service', 'ai.skrr.daemon.kek.probe']);
+        // Exit 0 (found something) — fine.
+        _secretToolProbeCache = true;
+    }
+    catch (err) {
+        const stderr = err.stderr ?? '';
+        const isTransportError = DBUS_TRANSPORT_ERRORS.some((s) => stderr.includes(s));
+        if (isTransportError) {
+            _secretToolProbeCache = false;
+            return false;
+        }
+        // Exit 1 with empty stderr (no item found) — that's the expected case,
+        // it just means no item matched the probe key. D-Bus is working.
+        _secretToolProbeCache = true;
+    }
+    return _secretToolProbeCache;
+}
+// ---------------------------------------------------------------------------
+// Tier-3: HKDF-SHA256 from machine identity.
+// ---------------------------------------------------------------------------
+/**
+ * Derive the master KEK from machine identity via HKDF-SHA256. IKM is the
+ * NUL-separated concatenation of:
+ *   - os.hostname()
+ *   - process UID (or "0" when not exposed)
+ *   - /proc/self/loginuid (empty string when unreadable)
+ *   - /etc/machine-id (REQUIRED — throws KekUnavailableError when absent)
+ *
+ * machine-id is the only required input because it's the cross-boot
+ * binding anchor; without it, the derivation has nothing host-specific
+ * to bind to and Tier-3 collapses into "shared secret across all hosts."
+ */
+function deriveTier3Kek() {
+    const hostname = os.hostname();
+    const uid = String(process.getuid?.() ?? 0);
+    const loginuid = readFileTrimmed(PATH_LOGINUID) ?? '';
+    const machineId = readFileTrimmed(PATH_MACHINE_ID);
+    if (machineId === null || machineId.length === 0) {
+        throw new KekUnavailableError(KIND_HKDF, 'Tier-3 unavailable: /etc/machine-id is missing or empty');
+    }
+    const NUL = Buffer.from([0]);
+    const ikm = Buffer.concat([
+        Buffer.from(hostname, 'utf-8'),
+        NUL,
+        Buffer.from(uid, 'utf-8'),
+        NUL,
+        Buffer.from(loginuid, 'utf-8'),
+        NUL,
+        Buffer.from(machineId, 'utf-8'),
+    ]);
+    // crypto.hkdfSync returns an ArrayBuffer — coerce to Buffer for the
+    // rest of the pipeline (which expects Node Buffers, not ArrayBuffers).
+    const derived = crypto.hkdfSync('sha256', ikm, HKDF_SALT, HKDF_INFO, KEY_LEN);
+    return Buffer.from(derived);
+}
+// ---------------------------------------------------------------------------
+// Secret Service read/write — master KEK (Tier-2).
+// ---------------------------------------------------------------------------
+/**
+ * Read the master KEK from the Secret Service. Returns null when no item
+ * exists (first run). Throws `KekUnavailableError` on all other failures.
+ *
+ * `service` and `account` are passed in (rather than read from the
+ * module-level constants) so a `LinuxKek` instance constructed with an
+ * override scopes its lookups to a unique Secret Service entry.
+ */
+async function readKekFromSecretService(service, account) {
+    try {
+        const { stdout } = await exec('secret-tool', [
+            'lookup',
+            'service',
+            service,
+            'account',
+            account,
+        ]);
+        const trimmed = stdout.trim();
+        if (trimmed.length === 0)
+            return null; // item not present
+        let raw;
+        try {
+            raw = Buffer.from(trimmed, 'base64');
+        }
+        catch {
+            throw new KekUnavailableError(KIND_LIBSECRET, 'Secret Service KEK is not valid base64');
+        }
+        if (raw.length !== KEY_LEN) {
+            throw new KekUnavailableError(KIND_LIBSECRET, `Secret Service KEK has wrong length (got ${raw.length}, want ${KEY_LEN})`);
+        }
+        return raw;
+    }
+    catch (err) {
+        if (err instanceof KekUnavailableError)
+            throw err;
+        // secret-tool lookup exits 1 with empty stdout when the item is absent.
+        const stdout = err.stdout ?? '';
+        const isAbsent = stdout.trim().length === 0;
+        if (isAbsent)
+            return null;
+        throw new KekUnavailableError(KIND_LIBSECRET, 'secret-tool lookup failed', { cause: err });
+    }
+}
+/**
+ * Write the master KEK to the Secret Service. Uses stdin (base64-encoded)
+ * as required by `secret-tool store`. Idempotent — `secret-tool store`
+ * overwrites an existing item silently.
+ *
+ * `service` and `account` are passed in (rather than read from the
+ * module-level constants) so a `LinuxKek` instance constructed with an
+ * override stores under a unique Secret Service entry.
+ *
+ * Race note: see module-level comment above.
+ */
+async function writeKekToSecretService(kek, service, account) {
+    if (kek.length !== KEY_LEN) {
+        throw new KekUnavailableError(KIND_LIBSECRET, `writeKekToSecretService: expected ${KEY_LEN}-byte buffer, got ${kek.length}`);
+    }
+    const b64 = kek.toString('base64');
+    try {
+        await exec('secret-tool', ['store', '--label=OverSky daemon master KEK', 'service', service, 'account', account], { input: b64 });
+    }
+    catch (err) {
+        throw new KekUnavailableError(KIND_LIBSECRET, 'secret-tool store failed', { cause: err });
+    }
+}
+// ---------------------------------------------------------------------------
+// In-process KEK cache + tier selection.
+// ---------------------------------------------------------------------------
+/**
+ * In-process cache of the Tier-2 master KEK, keyed on
+ * `${service}::${account}` so multiple `LinuxKek` instances constructed
+ * with distinct service/account overrides do not collide. Loaded lazily
+ * on the first wrap/unwrap call per key. Cleared by
+ * `__resetKekCacheForTest()` so the test suite can simulate fresh-process
+ * state.
+ */
+const _tier2KekCacheBySvc = new Map();
+/**
+ * In-process cache of the Tier-3 master KEK. Single module-level buffer
+ * because Tier-3 derivation is deterministic per host — there is no
+ * service/account dimension to key on. Cleared alongside the Tier-2 map
+ * by `zeroizeLinuxKekCache()`.
+ */
+let _tier3KekCache = null;
+let _tierSelection = null;
+/**
+ * Zero out and drop every in-process master-KEK cache buffer (both the
+ * Tier-2 by-service map and the Tier-3 single buffer).
+ *
+ * Must be called on:
+ *   - Daemon shutdown (SIGTERM / SIGINT) so the KEK does not linger in
+ *     memory across the process exit window where coredumps could land.
+ *   - KEK rotation, after the new KEK has been resolved.
+ *   - Logout flows that wipe at-rest credentials.
+ *
+ * Idempotent — safe to call when the caches are already empty.
+ */
+export function zeroizeLinuxKekCache() {
+    for (const buf of _tier2KekCacheBySvc.values()) {
+        buf.fill(0);
+    }
+    _tier2KekCacheBySvc.clear();
+    if (_tier3KekCache !== null) {
+        _tier3KekCache.fill(0);
+        _tier3KekCache = null;
+    }
+}
+// Register the zeroize hook at module-load time so any caller that
+// invokes `zeroizeKekCaches()` from `@skrr-ai/auth-core` (e.g. the
+// daemon's graceful-shutdown handler) clears this cache without needing
+// a direct import of linux.ts.
+registerZeroizeHook(zeroizeLinuxKekCache);
+/** @internal Test seam — clear the in-process master-KEK cache + tier
+ *  selection. Routes through the production zeroize helper so the
+ *  test-reset path exercises the same buffer-fill that ships in
+ *  production, and additionally clears `_tierSelection` so a subsequent
+ *  test re-probes (otherwise Tier-3 caching across tests poisons later
+ *  cases). */
+export function __resetKekCacheForTest() {
+    zeroizeLinuxKekCache();
+    _tierSelection = null;
+}
+/**
+ * Resolve the active tier exactly once per process. Tier-2 is preferred
+ * when libsecret is reachable; otherwise Tier-3 takes over if
+ * /etc/machine-id can be read. Throws `KekUnavailableError` only when
+ * NEITHER tier can satisfy a wrap.
+ */
+async function resolveTier() {
+    if (_tierSelection !== null)
+        return _tierSelection;
+    if (await probeSecretTool()) {
+        _tierSelection = 'libsecret';
+        return _tierSelection;
+    }
+    // Tier-3 probe: derive once to confirm machine-id is present. Discard
+    // the derived key here — `resolveOrCreateKek` re-derives and caches it
+    // so we don't hold two KEK buffers in memory simultaneously.
+    try {
+        const probe = deriveTier3Kek();
+        probe.fill(0);
+    }
+    catch (err) {
+        if (err instanceof KekUnavailableError) {
+            throw new KekUnavailableError('linux', 'Linux KEK unavailable: secret-tool missing/D-Bus unreachable AND /etc/machine-id absent');
+        }
+        throw err;
+    }
+    _tierSelection = 'hkdf';
+    return _tierSelection;
+}
+/**
+ * Resolve the master KEK, generating + storing one on first use (Tier-2)
+ * or deriving deterministically (Tier-3). Cached after the first
+ * successful resolution.
+ *
+ * `service` and `account` only affect the Tier-2 path — they key the
+ * Tier-2 cache and are passed to the `secret-tool` shellout. Tier-3
+ * ignores them; its derivation depends solely on machine identity.
+ */
+async function resolveOrCreateKek(service, account) {
+    const tier = await resolveTier();
+    if (tier === 'libsecret') {
+        const cacheKey = `${service}::${account}`;
+        const cached = _tier2KekCacheBySvc.get(cacheKey);
+        if (cached !== undefined)
+            return cached;
+        const existing = await readKekFromSecretService(service, account);
+        if (existing !== null) {
+            _tier2KekCacheBySvc.set(cacheKey, existing);
+            return existing;
+        }
+        const fresh = crypto.randomBytes(KEY_LEN);
+        await writeKekToSecretService(fresh, service, account);
+        _tier2KekCacheBySvc.set(cacheKey, fresh);
+        return fresh;
+    }
+    // Tier-3: deterministic derivation, no writeback. The KEK is
+    // recomputed on every cold start. Service/account are ignored —
+    // derivation depends solely on machine identity, so a single
+    // module-level cache suffices.
+    if (_tier3KekCache !== null)
+        return _tier3KekCache;
+    const derived = deriveTier3Kek();
+    _tier3KekCache = derived;
+    return derived;
+}
+/** Resolve an existing/deterministic KEK without persisting new native material. */
+async function resolveExistingKek(service, account) {
+    const tier = await resolveTier();
+    if (tier === 'libsecret') {
+        const cacheKey = `${service}::${account}`;
+        const cached = _tier2KekCacheBySvc.get(cacheKey);
+        if (cached !== undefined)
+            return cached;
+        const existing = await readKekFromSecretService(service, account);
+        if (existing === null) {
+            throw new KekUnavailableError(KIND_LIBSECRET, 'Secret Service master KEK is missing; refusing to create it outside the enrollment lock');
+        }
+        _tier2KekCacheBySvc.set(cacheKey, existing);
+        return existing;
+    }
+    // Tier-3 is deterministic and performs no writeback, so deriving it is a
+    // read-only operation safe outside the enrollment mutex.
+    if (_tier3KekCache !== null)
+        return _tier3KekCache;
+    const derived = deriveTier3Kek();
+    _tier3KekCache = derived;
+    return derived;
+}
+// ---------------------------------------------------------------------------
+// Shellout wrap / unwrap.
+// ---------------------------------------------------------------------------
+async function shelloutWrap(dek, aad, service, account) {
+    const kek = await resolveOrCreateKek(service, account);
+    const sealed = sealBuffer(dek, kek, aad);
+    return Buffer.from(envelopeSerialize(sealed), 'utf-8');
+}
+async function shelloutUnwrap(wrapped, aad, service, account, createIfMissing = true) {
+    const kek = await (createIfMissing
+        ? resolveOrCreateKek(service, account)
+        : resolveExistingKek(service, account));
+    const text = wrapped.toString('utf-8');
+    const sealed = envelopeDeserialize(text);
+    if (!sealed) {
+        throw new KekUnavailableError(KIND_LIBSECRET, 'wrapped blob is not a valid serialized envelope');
+    }
+    const out = openBuffer(sealed, kek, aad);
+    if (out.length !== KEY_LEN) {
+        throw new KekUnavailableError(KIND_LIBSECRET, `unwrapped DEK has wrong length (got ${out.length}, want ${KEY_LEN})`);
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// LinuxKek — KekStrategy implementation.
+// ---------------------------------------------------------------------------
+export class LinuxKek {
+    id = 'linux-libsecret-machineid';
+    _lastKind = null;
+    service;
+    account;
+    /**
+     * Construct a Linux KEK strategy.
+     *
+     * @param opts.service Optional Secret Service `service` attribute used
+     *   by Tier-2 `secret-tool lookup`/`store`. Defaults to
+     *   `'ai.skrr.daemon.kek'`. Override only for test isolation /
+     *   smoke tests; production callers should use the default so different
+     *   daemon processes on the same host share the same KEK and can unwrap
+     *   each other's persisted credentials. Ignored on the Tier-3 (HKDF)
+     *   path. Callers that override are responsible for cleaning up the
+     *   corresponding Secret Service entry when done.
+     * @param opts.account Optional Secret Service `account` attribute.
+     *   Defaults to `'master-kek-v1'`. Same scoping rules as `service`.
+     */
+    constructor(opts) {
+        this.service = opts?.service ?? SS_SERVICE;
+        this.account = opts?.account ?? SS_ACCOUNT;
+    }
+    /**
+     * Telemetry kind of the most recent successful wrap/unwrap. `null` before
+     * any call. After the first successful wrap or unwrap, one of:
+     *   - `'linux-libsecret-shellout'` (Tier-2)
+     *   - `'linux-machineid-hkdf'` (Tier-3)
+     */
+    get kind() {
+        return this._lastKind;
+    }
+    /**
+     * `available()` is true on Linux when EITHER backend can satisfy a
+     * wrap: libsecret is reachable, or `/etc/machine-id` exists so Tier-3
+     * derivation can succeed. Probe results are cached for the process
+     * lifetime.
+     */
+    async available() {
+        if (process.platform !== 'linux')
+            return false;
+        if (await probeSecretTool())
+            return true;
+        // Tier-3 fallback: machine-id presence is sufficient.
+        try {
+            const probe = deriveTier3Kek();
+            probe.fill(0);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async wrap(dek, aad) {
+        if (process.platform !== 'linux') {
+            throw new KekUnavailableError(this.id, 'Linux KEK called on non-linux platform');
+        }
+        const aadBuf = aad ?? Buffer.alloc(0);
+        const tier = await resolveTier();
+        try {
+            const out = await shelloutWrap(dek, aadBuf, this.service, this.account);
+            this._lastKind = tier === 'libsecret' ? KIND_LIBSECRET : KIND_HKDF;
+            return out;
+        }
+        catch (err) {
+            if (err instanceof KekUnavailableError)
+                throw err;
+            throw new KekUnavailableError(this.id, err?.message ?? 'shellout wrap failed', {
+                cause: err,
+            });
+        }
+    }
+    async unwrap(wrapped, aad) {
+        if (process.platform !== 'linux') {
+            throw new KekUnavailableError(this.id, 'Linux KEK called on non-linux platform');
+        }
+        const aadBuf = aad ?? Buffer.alloc(0);
+        const tier = await resolveTier();
+        try {
+            const out = await shelloutUnwrap(wrapped, aadBuf, this.service, this.account);
+            this._lastKind = tier === 'libsecret' ? KIND_LIBSECRET : KIND_HKDF;
+            return out;
+        }
+        catch (err) {
+            if (err instanceof KekUnavailableError)
+                throw err;
+            // Pass cipher errors (tag mismatch, malformed blob) through without
+            // swallowing — credEnvelope.ts decides fail-open vs fail-closed.
+            throw err;
+        }
+    }
+    async unwrapExisting(wrapped, aad) {
+        if (process.platform !== 'linux') {
+            throw new KekUnavailableError(this.id, 'Linux KEK called on non-linux platform');
+        }
+        const aadBuf = aad ?? Buffer.alloc(0);
+        const tier = await resolveTier();
+        const out = await shelloutUnwrap(wrapped, aadBuf, this.service, this.account, false);
+        this._lastKind = tier === 'libsecret' ? KIND_LIBSECRET : KIND_HKDF;
+        return out;
+    }
+    describe() {
+        if (process.platform !== 'linux') {
+            return 'Linux libsecret + machine-id KEK (not linux — unavailable)';
+        }
+        if (_tierSelection === 'libsecret') {
+            return 'Linux Secret Service via secret-tool shellout (libsecret / gnome-keyring / ksecretservice)';
+        }
+        if (_tierSelection === 'hkdf') {
+            return 'Linux machine-id HKDF KEK (Tier-3 fallback — backup-theft floor only)';
+        }
+        if (_secretToolProbeCache === false) {
+            return 'Linux KEK (Tier-3 candidate — call available() to materialize)';
+        }
+        return 'Linux KEK (probe pending — call available() to materialize)';
+    }
+}