expandai 0.0.2 → 0.0.3

package/build/esm/Config.js

@@ -1,28 +1,103 @@
 /**
  * CLI configuration. Persisted at `$XDG_CONFIG_HOME/expandai/config.json`
- * (default `~/.config/expandai/config.json`). The `EXPAND_API_KEY` and
- * `EXPAND_API_URL` environment variables override the file.
+ * (default `~/.config/expandai/config.json`). `EXPAND_API_URL` overrides the
+ * file. `EXPAND_API_KEY` overrides an API key stored in the file, but not
+ * credentials established by `expandai login` or agent setup — signing in is a
+ * deliberate act, and an exported API key usually is not. `EXPAND_APP_URL`
+ * points guide links at the web app serving them.
  */
-import { homedir } from 'node:os';
-import { FileSystem, Path } from '@effect/platform';
-import { NodeFileSystem, NodePath } from '@effect/platform-node';
+import { Command, CommandExecutor, FileSystem, Path, Error as PlatformError } from '@effect/platform';
+import { NodeContext } from '@effect/platform-node';
 import { DEFAULT_PLAYGROUND_HOST } from '@expandai/sdk/Playground';
-import { Config, DateTime, Effect, Option, Schema } from 'effect';
+import { Config, DateTime, Effect, Either, Exit, Option, Random, Redacted, Schema } from 'effect';
+import { createExclusiveFile, matchesCreatedFile } from './SecureFile.js';
+import { xdgConfigDirectory } from './Xdg.js';
 /** Production API endpoint used when neither `EXPAND_API_URL` nor the config file overrides it. */
 export const DEFAULT_API_URL = 'https://api.expand.ai';
+/** Production web app used when `EXPAND_APP_URL` does not override it. */
+export const DEFAULT_APP_URL = 'https://expand.ai';
+/**
+ * Lenient env readers. `Config.option` / `Config.withDefault` only absorb
+ * missing data — a present-but-malformed value (`CLAUDECODE=banana`,
+ * `EXPANDAI_HARNESS=bogus`) fails as InvalidData and would crash the CLI at
+ * layer construction. These read the raw string and degrade gracefully:
+ * flags follow the DO_NOT_TRACK convention (set unless an explicit off),
+ * literals decode to None instead of failing.
+ */
+export const envFlag = (name) => Config.string(name).pipe(Config.option, Config.map(Option.match({
+    onNone: () => false,
+    onSome: (value) => value !== '' && value !== '0' && value !== 'false',
+})));
+export const envLiteral = (name, schema) => Config.string(name).pipe(Config.option, Config.map(Option.flatMap(Schema.decodeUnknownOption(schema))));
 export const ApiKey = Schema.Redacted(Schema.NonEmptyTrimmedString.pipe(Schema.brand('ApiKey')));
 export const ApiKeyConfig = Schema.TaggedStruct('ApiKey', { apiKey: ApiKey });
 export const OAuthConfig = Schema.TaggedStruct('OAuth', {
     accessToken: Schema.Redacted(Schema.String),
     refreshToken: Schema.optional(Schema.Redacted(Schema.String)),
     expiresAt: Schema.DateTimeUtc,
+    // Refresh tokens are bound to their issuing client, so a credential minted by
+    // browser-approved setup cannot be refreshed as `expandai-cli`. Optional because
+    // configs written before this existed all came from `expandai login`.
+    clientId: Schema.optional(Schema.String),
+});
+export const TelemetrySettings = Schema.Struct({
+    enabled: Schema.optional(Schema.Boolean),
+    distinctId: Schema.optional(Schema.String),
+    noticeShown: Schema.optional(Schema.Boolean),
 });
 export class ExpandCliConfig extends Schema.Class('ExpandCliConfig')({
     apiUrl: Schema.optional(Schema.URL),
     authMethod: Schema.optional(Schema.Union(ApiKeyConfig, OAuthConfig)),
+    telemetry: Schema.optional(TelemetrySettings),
 }) {
     static Json = Schema.parseJson(ExpandCliConfig);
 }
+export function authMethodState(authMethod, now) {
+    if (authMethod._tag === 'ApiKey')
+        return 'healthy';
+    if (DateTime.lessThan(now, authMethod.expiresAt)) {
+        return Redacted.value(authMethod.accessToken).trim().length > 0 ? 'healthy' : 'unusable';
+    }
+    const refreshToken = authMethod.refreshToken;
+    return refreshToken !== undefined && Redacted.value(refreshToken).trim().length > 0 ? 'refresh_required' : 'unusable';
+}
+/** Returns whether a local credential can be used now or renewed on first API use. */
+export function isAuthMethodLocallyUsable(authMethod, now) {
+    return authMethodState(authMethod, now) !== 'unusable';
+}
+const RawConfigRecord = Schema.Record({ key: Schema.String, value: Schema.Unknown });
+const RawConfigJson = Schema.parseJson(RawConfigRecord);
+// Unknown top-level keys survive a write, so a config written by a newer CLI
+// is not silently truncated by an older one.
+function mergeRawConfig(existing, known) {
+    return { ...existing, ...known };
+}
+function isErrnoCode(input, code) {
+    return typeof input === 'object' && input !== null && 'code' in input && input.code === code;
+}
+function powerShellLiteral(value) {
+    return `'${value.replaceAll("'", "''")}'`;
+}
+function scriptWithTargetPaths(script, targetPaths) {
+    return `$targetPaths = @(${targetPaths.map((targetPath) => powerShellLiteral(targetPath)).join(', ')})
+try {
+  Import-Module (Join-Path $PSHOME 'Modules/Microsoft.PowerShell.Security/Microsoft.PowerShell.Security.psd1') -ErrorAction Stop
+  $null = & {
+${script}
+  }
+  exit 0
+} catch {
+  [Console]::Error.WriteLine($_.Exception.Message)
+  exit 1
+}`;
+}
+function sameIdentity(left, right) {
+    return (left.exists === right.exists &&
+        left.dev === right.dev &&
+        left.ino === right.ino &&
+        left.realPath === right.realPath &&
+        left.type === right.type);
+}
 export class ConfigNotWritable extends Schema.TaggedError()('ConfigNotWritable', {
     path: Schema.String,
 }) {
@@ -30,6 +105,16 @@ export class ConfigNotWritable extends Schema.TaggedError()('ConfigNotWritable',
         return `Cannot write to ${this.path}. Check filesystem permissions on the config directory.`;
     }
 }
+export class ConfigCleanupError extends Schema.TaggedError()('ConfigCleanupError', {
+    path: Schema.String,
+    temporaryPath: Schema.String,
+    error: Schema.Defect,
+    operationError: Schema.Defect,
+}) {
+    get message() {
+        return `Could not safely clean up config temporary state at ${this.temporaryPath}; it was left unchanged.`;
+    }
+}
 export class ConfigParseError extends Schema.TaggedError()('ConfigParseError', {
     path: Schema.String,
     error: Schema.Defect,
@@ -38,6 +123,15 @@ export class ConfigParseError extends Schema.TaggedError()('ConfigParseError', {
         return `Could not parse ${this.path}. Delete the file and run \`expandai login\` to recreate it.`;
     }
 }
+export class CredentialStoreInsecure extends Schema.TaggedError()('CredentialStoreInsecure', {
+    path: Schema.String,
+    reason: Schema.String,
+    error: Schema.Defect,
+}) {
+    get message() {
+        return `Credential storage at ${this.path} is insecure: ${this.reason}`;
+    }
+}
 export class NotAuthenticated extends Schema.TaggedError()('NotAuthenticated', {}) {
     get message() {
         return 'Not authenticated. Run `expandai login` to authenticate.';
@@ -59,19 +153,353 @@ const Environment = Effect.gen(function* () {
     });
 });
 export class ConfigManager extends Effect.Service()('@expandai/cli/Config/ConfigManager', {
-    dependencies: [NodeFileSystem.layer, NodePath.layer],
+    dependencies: [NodeContext.layer],
     effect: Effect.gen(function* () {
+        const commandExecutor = yield* CommandExecutor.CommandExecutor;
         const fs = yield* FileSystem.FileSystem;
         const path = yield* Path.Path;
-        const configPath = yield* Config.string('XDG_CONFIG_HOME').pipe(Config.withDefault(path.join(homedir(), '.config')), Config.map((dir) => path.join(dir, 'expandai', 'config.json')));
-        const EnvironmentFromConfigFile = Effect.gen(function* () {
+        const configPath = path.join(yield* xdgConfigDirectory, 'expandai', 'config.json');
+        const configDirectory = path.dirname(configPath);
+        const insecure = (targetPath, reason, error) => new CredentialStoreInsecure({ path: targetPath, reason, error });
+        const assertNotSymbolicLink = Effect.fnUntraced(function* (targetPath) {
+            const result = yield* Effect.either(fs.readLink(targetPath));
+            if (Either.isRight(result)) {
+                return yield* insecure(targetPath, 'symbolic links are not allowed for credential storage', new Error(result.right));
+            }
+            const error = result.left;
+            if (error instanceof PlatformError.SystemError &&
+                (error.reason === 'InvalidData' ||
+                    error.reason === 'NotFound' ||
+                    (error.method === 'readLink' && isErrnoCode(error.cause, 'EINVAL')))) {
+                return;
+            }
+            return yield* insecure(targetPath, 'could not inspect the credential path without following links', error);
+        });
+        const inspectPath = Effect.fnUntraced(function* (targetPath) {
+            yield* assertNotSymbolicLink(targetPath);
+            const exists = yield* fs
+                .exists(targetPath)
+                .pipe(Effect.mapError((error) => insecure(targetPath, 'could not inspect the credential path', error)));
+            if (!exists) {
+                const missing = { exists: false };
+                return missing;
+            }
+            const info = yield* fs
+                .stat(targetPath)
+                .pipe(Effect.mapError((error) => insecure(targetPath, 'could not inspect the credential path', error)));
+            const realPath = yield* fs
+                .realPath(targetPath)
+                .pipe(Effect.mapError((error) => insecure(targetPath, 'could not resolve the credential path', error)));
+            const identity = {
+                exists: true,
+                dev: info.dev,
+                ino: Option.getOrUndefined(info.ino),
+                realPath,
+                type: info.type,
+            };
+            return identity;
+        });
+        const assertStable = (targetPath, before, after) => sameIdentity(before, after)
+            ? Effect.void
+            : Effect.fail(insecure(targetPath, 'credential path identity changed during the operation', new Error('Path swap detected')));
+        const inspectParentAndFile = Effect.fnUntraced(function* (targetPath) {
+            const parentPath = path.dirname(targetPath);
+            const parent = yield* inspectPath(parentPath);
+            if (!parent.exists || parent.type !== 'Directory') {
+                return yield* insecure(parentPath, 'credential parent is not a directory', new Error('Invalid parent'));
+            }
+            return { parentPath, parent, file: yield* inspectPath(targetPath) };
+        });
+        const readCredentialFile = Effect.fnUntraced(function* (targetPath) {
+            const before = yield* inspectParentAndFile(targetPath);
+            if (!before.file.exists || before.file.type !== 'File') {
+                return yield* insecure(targetPath, 'credential path is not a regular file', new Error('Invalid file'));
+            }
+            const contents = yield* fs
+                .readFileString(targetPath)
+                .pipe(Effect.mapError((error) => insecure(targetPath, 'could not read the credential file', error)));
+            const after = yield* inspectParentAndFile(targetPath);
+            yield* assertStable(before.parentPath, before.parent, after.parent);
+            yield* assertStable(targetPath, before.file, after.file);
+            return contents;
+        });
+        const ensurePosixMode = Effect.fnUntraced(function* (targetPath, mode, expectedType) {
+            const before = yield* inspectPath(targetPath);
+            if (!before.exists || before.type !== expectedType) {
+                return yield* insecure(targetPath, `expected a ${expectedType.toLowerCase()}`, new Error('Invalid path type'));
+            }
+            yield* fs
+                .chmod(targetPath, mode)
+                .pipe(Effect.mapError((error) => insecure(targetPath, `could not set mode ${mode.toString(8)}`, error)));
+            const info = yield* fs
+                .stat(targetPath)
+                .pipe(Effect.mapError((error) => insecure(targetPath, 'could not verify permissions', error)));
+            const actualMode = info.mode & 0o7777;
+            if (info.type !== expectedType || actualMode !== mode) {
+                return yield* insecure(targetPath, `expected ${expectedType.toLowerCase()} mode ${mode.toString(8)}, found ${info.type.toLowerCase()} mode ${actualMode.toString(8)}`, new Error('Permission verification failed'));
+            }
+            const after = yield* inspectPath(targetPath);
+            yield* assertStable(targetPath, before, after);
+        });
+        const WINDOWS_ACL_SCRIPT = String.raw `
+$ErrorActionPreference = 'Stop'
+$currentSid = [System.Security.Principal.WindowsIdentity]::GetCurrent().User.Value
+$allowedSids = @($currentSid, 'S-1-5-18', 'S-1-5-32-544')
+foreach ($targetPath in $targetPaths) {
+  if (-not (Test-Path -LiteralPath $targetPath)) { throw "Missing credential path: $targetPath" }
+  $item = Get-Item -LiteralPath $targetPath -Force
+  $acl = Get-Acl -LiteralPath $targetPath
+  $acl.SetAccessRuleProtection($true, $false)
+  foreach ($rule in @($acl.Access)) { [void]$acl.RemoveAccessRuleSpecific($rule) }
+  $inheritance = if ($item.PSIsContainer) {
+    [System.Security.AccessControl.InheritanceFlags]'ContainerInherit, ObjectInherit'
+  } else {
+    [System.Security.AccessControl.InheritanceFlags]::None
+  }
+  foreach ($sidValue in $allowedSids) {
+    $sid = [System.Security.Principal.SecurityIdentifier]::new($sidValue)
+    $rule = [System.Security.AccessControl.FileSystemAccessRule]::new(
+      $sid,
+      [System.Security.AccessControl.FileSystemRights]::FullControl,
+      $inheritance,
+      [System.Security.AccessControl.PropagationFlags]::None,
+      [System.Security.AccessControl.AccessControlType]::Allow
+    )
+    [void]$acl.AddAccessRule($rule)
+  }
+  Set-Acl -LiteralPath $targetPath -AclObject $acl
+
+  $verified = Get-Acl -LiteralPath $targetPath
+  if (-not $verified.AreAccessRulesProtected) { throw "Inherited ACL remains enabled: $targetPath" }
+  $seenSids = @{}
+  foreach ($rule in @($verified.Access)) {
+    $sid = $rule.IdentityReference.Translate([System.Security.Principal.SecurityIdentifier]).Value
+    if ($allowedSids -notcontains $sid) { throw "Unexpected ACL principal $sid on $targetPath" }
+    if ($rule.AccessControlType -ne [System.Security.AccessControl.AccessControlType]::Allow) {
+      throw "Unexpected deny ACL for $sid on $targetPath"
+    }
+    $requiredRights = [System.Security.AccessControl.FileSystemRights]::FullControl
+    if (($rule.FileSystemRights -band $requiredRights) -ne $requiredRights) {
+      throw "ACL principal $sid lacks FullControl on $targetPath"
+    }
+    $seenSids[$sid] = $true
+  }
+  foreach ($allowedSid in $allowedSids) {
+    if (-not $seenSids.ContainsKey($allowedSid)) { throw "Missing ACL principal $allowedSid on $targetPath" }
+  }
+}
+'SECURE'
+`;
+        const WINDOWS_ACL_INSPECTION_SCRIPT = String.raw `
+$ErrorActionPreference = 'Stop'
+$currentSid = [System.Security.Principal.WindowsIdentity]::GetCurrent().User.Value
+$allowedSids = @($currentSid, 'S-1-5-18', 'S-1-5-32-544')
+foreach ($targetPath in $targetPaths) {
+  if (-not (Test-Path -LiteralPath $targetPath)) { throw "Missing credential path: $targetPath" }
+  $acl = Get-Acl -LiteralPath $targetPath
+  if (-not $acl.AreAccessRulesProtected) { throw "Inherited ACL remains enabled: $targetPath" }
+  $seenSids = @{}
+  foreach ($rule in @($acl.Access)) {
+    $sid = $rule.IdentityReference.Translate([System.Security.Principal.SecurityIdentifier]).Value
+    if ($allowedSids -notcontains $sid) { throw "Unexpected ACL principal $sid on $targetPath" }
+    if ($rule.AccessControlType -ne [System.Security.AccessControl.AccessControlType]::Allow) {
+      throw "Unexpected deny ACL for $sid on $targetPath"
+    }
+    $requiredRights = [System.Security.AccessControl.FileSystemRights]::FullControl
+    if (($rule.FileSystemRights -band $requiredRights) -ne $requiredRights) {
+      throw "ACL principal $sid lacks FullControl on $targetPath"
+    }
+    $seenSids[$sid] = $true
+  }
+  foreach ($allowedSid in $allowedSids) {
+    if (-not $seenSids.ContainsKey($allowedSid)) { throw "Missing ACL principal $allowedSid on $targetPath" }
+  }
+}
+'SECURE'
+`;
+        const ensureWindowsAcl = Effect.fnUntraced(function* (targetPaths) {
+            const exitCode = yield* Command.make('powershell.exe', '-NoLogo', '-NoProfile', '-NonInteractive', '-Command', scriptWithTargetPaths(WINDOWS_ACL_SCRIPT, targetPaths)).pipe(Command.stderr('inherit'), Command.exitCode, Effect.provideService(CommandExecutor.CommandExecutor, commandExecutor), Effect.mapError((error) => insecure(configDirectory, 'could not apply or verify the Windows ACL allowlist', error)));
+            if (exitCode !== 0) {
+                return yield* insecure(configDirectory, 'Windows ACL verification failed', new Error(`PowerShell exited with status ${exitCode}`));
+            }
+        });
+        const inspectWindowsAcl = Effect.fnUntraced(function* (targetPaths) {
+            const exitCode = yield* Command.make('powershell.exe', '-NoLogo', '-NoProfile', '-NonInteractive', '-Command', scriptWithTargetPaths(WINDOWS_ACL_INSPECTION_SCRIPT, targetPaths)).pipe(Command.stderr('inherit'), Command.exitCode, Effect.provideService(CommandExecutor.CommandExecutor, commandExecutor), Effect.mapError((error) => insecure(configDirectory, 'could not inspect the Windows ACL allowlist', error)));
+            if (exitCode !== 0) {
+                return yield* insecure(configDirectory, 'Windows ACL inspection failed', new Error(`PowerShell exited with status ${exitCode}`));
+            }
+        });
+        const inspectSecureStorage = Effect.fn('ConfigManager.inspectSecureStorage')(function* () {
+            const directory = yield* inspectPath(configDirectory);
+            if (!directory.exists)
+                return yield* Effect.void;
+            if (directory.type !== 'Directory') {
+                return yield* insecure(configDirectory, 'config directory is not a regular directory', new Error('Invalid config directory'));
+            }
+            const file = yield* inspectPath(configPath);
+            if (file.exists && file.type !== 'File') {
+                return yield* insecure(configPath, 'credential path is not a regular file', new Error('Invalid file'));
+            }
+            if (process.platform === 'win32') {
+                const targets = file.exists ? [configDirectory, configPath] : [configDirectory];
+                const before = yield* Effect.forEach(targets, inspectPath);
+                yield* inspectWindowsAcl(targets);
+                const after = yield* Effect.forEach(targets, inspectPath);
+                yield* Effect.forEach(targets, (targetPath, index) => assertStable(targetPath, before[index] ?? { exists: false }, after[index] ?? { exists: false }), { discard: true });
+                return yield* Effect.void;
+            }
+            const directoryInfo = yield* fs
+                .stat(configDirectory)
+                .pipe(Effect.mapError((error) => insecure(configDirectory, 'could not inspect directory mode', error)));
+            if ((directoryInfo.mode & 0o7777) !== 0o700) {
+                return yield* insecure(configDirectory, 'config directory mode is not 700', new Error('Invalid directory mode'));
+            }
+            if (file.exists) {
+                const fileInfo = yield* fs
+                    .stat(configPath)
+                    .pipe(Effect.mapError((error) => insecure(configPath, 'could not inspect credential file mode', error)));
+                if ((fileInfo.mode & 0o7777) !== 0o600) {
+                    return yield* insecure(configPath, 'credential file mode is not 600', new Error('Invalid file mode'));
+                }
+            }
+            return yield* Effect.void;
+        });
+        const ensureSecureStorage = Effect.fn('ConfigManager.ensureSecureStorage')(function* () {
+            yield* fs
+                .makeDirectory(configDirectory, { recursive: true, mode: 0o700 })
+                .pipe(Effect.mapError((error) => insecure(configDirectory, 'could not create the config directory', error)));
+            const directory = yield* inspectPath(configDirectory);
+            if (!directory.exists || directory.type !== 'Directory') {
+                return yield* insecure(configDirectory, 'config directory is not a regular directory', new Error('Invalid config directory'));
+            }
+            const exists = yield* fs
+                .exists(configPath)
+                .pipe(Effect.mapError((error) => insecure(configPath, 'could not inspect the credential file', error)));
+            if (!exists) {
+                const creation = yield* Effect.either(fs.writeFileString(configPath, '{}', { flag: 'wx', mode: 0o600 }));
+                if (Either.isLeft(creation) &&
+                    (!(creation.left instanceof PlatformError.SystemError) || creation.left.reason !== 'AlreadyExists')) {
+                    return yield* insecure(configPath, 'could not create the credential file', creation.left);
+                }
+            }
+            yield* inspectParentAndFile(configPath);
+            if (process.platform === 'win32') {
+                const targets = [configDirectory, configPath];
+                const before = yield* Effect.forEach(targets, (targetPath) => inspectPath(targetPath));
+                yield* ensureWindowsAcl(targets);
+                const after = yield* Effect.forEach(targets, (targetPath) => inspectPath(targetPath));
+                yield* Effect.forEach(targets, (targetPath, index) => assertStable(targetPath, before[index] ?? { exists: false }, after[index] ?? { exists: false }), { discard: true });
+            }
+            else {
+                yield* ensurePosixMode(configDirectory, 0o700, 'Directory');
+                yield* ensurePosixMode(configPath, 0o600, 'File');
+            }
+            return yield* Effect.void;
+        });
+        const atomicWriteConfig = Effect.fnUntraced(function* (encoded) {
+            yield* ensureSecureStorage();
+            const before = yield* inspectParentAndFile(configPath);
+            const nonce = yield* Random.nextIntBetween(0, 0x7fffffff);
+            const temporaryPath = path.join(configDirectory, `.config.json.${process.pid}.${nonce.toString(16)}.tmp`);
+            const cleanupTemporary = Effect.fnUntraced(function* (created, operationError) {
+                const inspected = yield* Effect.either(inspectParentAndFile(temporaryPath));
+                if (Either.isLeft(inspected)) {
+                    return yield* new ConfigCleanupError({
+                        path: configPath,
+                        temporaryPath,
+                        error: inspected.left,
+                        operationError,
+                    });
+                }
+                if (!sameIdentity(before.parent, inspected.right.parent)) {
+                    return yield* new ConfigCleanupError({
+                        path: configPath,
+                        temporaryPath,
+                        error: new Error('Config temp parent identity changed; refusing cleanup'),
+                        operationError,
+                    });
+                }
+                if (!matchesCreatedFile(created, inspected.right.file)) {
+                    return yield* new ConfigCleanupError({
+                        path: configPath,
+                        temporaryPath,
+                        error: new Error('Config temp identity changed or disappeared; refusing cleanup'),
+                        operationError,
+                    });
+                }
+                const removed = yield* Effect.either(fs.remove(temporaryPath));
+                if (Either.isLeft(removed)) {
+                    return yield* new ConfigCleanupError({
+                        path: configPath,
+                        temporaryPath,
+                        error: removed.left,
+                        operationError,
+                    });
+                }
+            });
+            const creation = yield* createExclusiveFile(fs, temporaryPath, encoded, 0o600).pipe(Effect.mapError(() => new ConfigNotWritable({ path: temporaryPath })));
+            if (Exit.isFailure(creation.writeExit)) {
+                const primary = new ConfigNotWritable({ path: temporaryPath });
+                yield* cleanupTemporary(creation.identity, primary);
+                return yield* primary;
+            }
+            if (!creation.pathMatchesHandle) {
+                const primary = new ConfigNotWritable({ path: temporaryPath });
+                yield* cleanupTemporary(creation.identity, primary);
+                return yield* primary;
+            }
+            const installResult = yield* Effect.either(Effect.gen(function* () {
+                const temporary = yield* inspectParentAndFile(temporaryPath);
+                yield* assertStable(before.parentPath, before.parent, temporary.parent);
+                if (!matchesCreatedFile(creation.identity, temporary.file)) {
+                    return yield* insecure(temporaryPath, 'config temp identity differs from its creating handle', new Error('Config temp replacement detected'));
+                }
+                if (process.platform === 'win32') {
+                    yield* ensureWindowsAcl([temporaryPath]);
+                    const hardened = yield* inspectParentAndFile(temporaryPath);
+                    yield* assertStable(before.parentPath, before.parent, hardened.parent);
+                    if (!matchesCreatedFile(creation.identity, hardened.file)) {
+                        return yield* insecure(temporaryPath, 'config temp changed while applying its ACL', new Error('Config temp replacement detected'));
+                    }
+                }
+                else {
+                    const info = yield* fs
+                        .stat(temporaryPath)
+                        .pipe(Effect.mapError((error) => insecure(temporaryPath, 'could not verify config temp mode', error)));
+                    if ((info.mode & 0o7777) !== 0o600) {
+                        return yield* insecure(temporaryPath, 'config temp mode is not 600', new Error('Invalid config temp mode'));
+                    }
+                }
+                const current = yield* inspectParentAndFile(configPath);
+                yield* assertStable(before.parentPath, before.parent, current.parent);
+                yield* assertStable(configPath, before.file, current.file);
+                yield* fs
+                    .rename(temporaryPath, configPath)
+                    .pipe(Effect.mapError(() => new ConfigNotWritable({ path: configPath })));
+            }));
+            if (Either.isLeft(installResult)) {
+                yield* cleanupTemporary(creation.identity, installResult.left);
+                return yield* installResult.left;
+            }
+            const installed = yield* inspectParentAndFile(configPath);
+            yield* assertStable(before.parentPath, before.parent, installed.parent);
+            if (!matchesCreatedFile(creation.identity, installed.file)) {
+                return yield* insecure(configPath, 'atomic credential installation identity could not be verified', new Error('Installed file identity mismatch'));
+            }
+        });
+        const ConfigFileFromDisk = Effect.gen(function* () {
             const exists = yield* fs.exists(configPath);
             if (!exists) {
-                return ExpandCliConfig.make({});
+                const empty = { config: ExpandCliConfig.make({}), raw: {} };
+                return empty;
             }
-            const string = yield* fs.readFileString(configPath);
-            return yield* Schema.decode(ExpandCliConfig.Json)(string).pipe(Effect.mapError((error) => new ConfigParseError({ path: configPath, error })));
+            const string = yield* readCredentialFile(configPath);
+            const raw = yield* Schema.decode(RawConfigJson)(string).pipe(Effect.mapError((error) => new ConfigParseError({ path: configPath, error })));
+            const config = yield* Schema.decodeUnknown(ExpandCliConfig)(raw).pipe(Effect.mapError((error) => new ConfigParseError({ path: configPath, error })));
+            const contents = { config, raw };
+            return contents;
         });
+        const EnvironmentFromConfigFile = ConfigFileFromDisk.pipe(Effect.map(({ config }) => config));
         const loadConfig = Effect.fn('loadConfig')(function* () {
             const env = yield* Environment;
             const file = yield* EnvironmentFromConfigFile;
@@ -84,8 +512,23 @@ export class ConfigManager extends Effect.Service()('@expandai/cli/Config/Config
                 file: Option.fromNullable(file.authMethod),
             };
             yield* Effect.logWarning(`EXPAND_API_URL overrides apiUrl from ${configPath}`).pipe(Effect.when(() => Option.zipWith(apiUrl.env, apiUrl.file, (env, file) => env.toString() !== file.toString()).pipe(Option.getOrElse(() => false))));
-            yield* Effect.logWarning(`EXPAND_API_KEY overrides the auth method stored in ${configPath}`).pipe(Effect.when(() => Option.isSome(authMethod.env) && Option.isSome(authMethod.file)));
-            return yield* Option.match(Option.orElse(authMethod.env, () => authMethod.file), {
+            // Credentials signed in through Expand's own authorization flow win over
+            // an ambient `EXPAND_API_KEY`. Someone who just approved this machine in
+            // a browser means those credentials; the environment variable is a
+            // default for shells and CI, and it is frequently exported machine-wide
+            // by tooling nobody is thinking about at the time. It still beats an API
+            // key stored in the file, which is the same kind of credential.
+            // Usable, not merely present. A stored OAuth credential that expired with
+            // no refresh token can never succeed, and outranking the environment with
+            // it left `EXPAND_API_KEY` permanently shadowed on exactly the CI and
+            // agent machines this is meant to serve, with `expandai logout` the only
+            // way out.
+            const now = yield* DateTime.now;
+            const storedOAuth = authMethod.file.pipe(Option.filter((method) => method._tag === 'OAuth' && isAuthMethodLocallyUsable(method, now)));
+            const effectiveAuthMethod = Option.firstSomeOf([storedOAuth, authMethod.env, authMethod.file]);
+            yield* Effect.logWarning(`EXPAND_API_KEY is set but ${configPath} holds credentials from \`expandai login\` or agent setup, which take precedence. Unset EXPAND_API_KEY to silence this, or run \`expandai logout\` to use the API key.`).pipe(Effect.when(() => Option.isSome(authMethod.env) && Option.isSome(storedOAuth)));
+            yield* Effect.logWarning(`EXPAND_API_KEY overrides the API key stored in ${configPath}`).pipe(Effect.when(() => Option.isSome(authMethod.env) && Option.isSome(authMethod.file) && Option.isNone(storedOAuth)));
+            return yield* Option.match(effectiveAuthMethod, {
                 onNone: () => Effect.fail(new NotAuthenticated()),
                 onSome: (authMethod) => Effect.succeed({
                     apiUrl: Option.firstSomeOf([apiUrl.env, apiUrl.file]).pipe(Option.getOrElse(() => new URL(DEFAULT_API_URL))),
@@ -94,25 +537,46 @@ export class ConfigManager extends Effect.Service()('@expandai/cli/Config/Config
             });
         });
         const saveConfig = Effect.fn('saveConfig')(function* (config) {
-            yield* fs
-                .makeDirectory(path.dirname(configPath), { recursive: true })
-                .pipe(Effect.mapError(() => new ConfigNotWritable({ path: configPath })));
             const encoded = yield* Schema.encode(ExpandCliConfig.Json)(config);
-            yield* fs
-                .writeFileString(configPath, encoded, { mode: 0o600 })
-                .pipe(Effect.mapError(() => new ConfigNotWritable({ path: configPath })));
-            // `mode` only applies on creation; chmod handles a pre-existing file.
-            // Failures are non-fatal (e.g. chmod is a no-op on Windows, or the file
-            // is owned by another user) but surfaced at debug level so they're
-            // inspectable when DEBUG=true.
-            yield* fs.chmod(configPath, 0o600).pipe(Effect.tapErrorCause((cause) => Effect.logDebug(`chmod 0o600 ${configPath} failed (file mode may not enforce 0600)`).pipe(Effect.annotateLogs({ cause }))), Effect.ignore);
+            yield* atomicWriteConfig(encoded);
         });
+        // Propagates ConfigParseError: merging onto an empty fallback would
+        // serialize `{}` over a file that failed to decode (corrupt, or written
+        // by a newer CLI version) and destroy the credentials stored in it. No
+        // write may ever follow a parse failure.
         const updateConfig = Effect.fn('updateConfig')(function* (patch) {
-            const existing = yield* EnvironmentFromConfigFile.pipe(Effect.orElseSucceed(() => ExpandCliConfig.make({})));
-            yield* saveConfig(ExpandCliConfig.make({ ...existing, ...patch }));
+            const existing = yield* ConfigFileFromDisk;
+            const updated = ExpandCliConfig.make({ ...existing.config, ...patch });
+            const known = yield* Schema.encode(ExpandCliConfig.Json)(updated).pipe(Effect.flatMap(Schema.decode(RawConfigJson)));
+            const encoded = yield* Schema.encode(RawConfigJson)(mergeRawConfig(existing.raw, known));
+            yield* atomicWriteConfig(encoded);
+        });
+        // The config file alone, without the env overrides or the NotAuthenticated
+        // failure of loadConfig — telemetry settings must be readable before the
+        // user has ever logged in. An unreadable or undecodable file is tolerated
+        // but surfaced via `parseFailed` so callers never mistake it for an empty
+        // one (and never write over it).
+        const readConfigFile = Effect.fn('readConfigFile')(function* () {
+            return yield* ConfigFileFromDisk.pipe(Effect.map(({ config }) => ({ config, parseFailed: false })), Effect.orElseSucceed(() => ({ config: ExpandCliConfig.make({}), parseFailed: true })));
         });
+        // Clears only authentication state: telemetry preferences (an explicit
+        // opt-out, the distinct id, the notice flag) and a configured apiUrl
+        // survive logout. An undecodable file is deleted instead of rewritten —
+        // nothing in it can be preserved, and writing `{}` would break the
+        // no-write-after-parse-failure rule updateConfig upholds.
         const clearConfig = Effect.fn('clearConfig')(function* () {
-            yield* saveConfig(ExpandCliConfig.make({}));
+            const result = yield* Effect.either(ConfigFileFromDisk);
+            if (Either.isLeft(result)) {
+                if (!(result.left instanceof ConfigParseError))
+                    return yield* result.left;
+                yield* Effect.logWarning(`Could not parse ${configPath}; removing it. Telemetry preferences and apiUrl were not preserved.`);
+                yield* fs.remove(configPath).pipe(Effect.mapError(() => new ConfigNotWritable({ path: configPath })));
+                return;
+            }
+            const raw = { ...result.right.raw };
+            delete raw.authMethod;
+            const encoded = yield* Schema.encode(RawConfigJson)(raw);
+            yield* atomicWriteConfig(encoded);
         });
         const getApiUrl = Effect.fn('getApiUrl')(function* () {
             const env = yield* Environment;
@@ -123,6 +587,12 @@ export class ConfigManager extends Effect.Service()('@expandai/cli/Config/Config
             };
             return Option.firstSomeOf([apiUrl.env, apiUrl.file]).pipe(Option.getOrElse(() => new URL(DEFAULT_API_URL)));
         });
+        // Web app origin for guide links the CLI hands to an agent. Reads `EXPAND_APP_URL` — the
+        // counterpart to `EXPAND_API_URL` — so a local or self-hosted stack points agents at the
+        // app actually serving `/start.md` instead of production.
+        const getAppUrl = Effect.fn('getAppUrl')(function* () {
+            return yield* Config.string('EXPAND_APP_URL').pipe(Config.withDefault(DEFAULT_APP_URL));
+        });
         // Public playground host for citation links. Reads `EXPAND_PLAYGROUND_HOST` — the same env
         // var the API / cdp-server bake into `meta.playground` — so local/staging set one host for
         // both server and CLI. The fetch path prefers the server-resolved `meta.playground` origin;
@@ -132,11 +602,15 @@ export class ConfigManager extends Effect.Service()('@expandai/cli/Config/Config
         });
         return {
             configPath,
+            inspectSecureStorage,
+            ensureSecureStorage,
             loadConfig,
             saveConfig,
             updateConfig,
             clearConfig,
+            readConfigFile,
             getApiUrl,
+            getAppUrl,
             getPlaygroundHost,
         };
     }),