expandai 0.0.2 → 0.0.3

package/src/Config.ts

@@ -1,17 +1,46 @@
 /**
  * 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 { type CreatedFileIdentity, 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: string) =>
+	Config.string(name).pipe(
+		Config.option,
+		Config.map(
+			Option.match({
+				onNone: () => false,
+				onSome: (value) => value !== '' && value !== '0' && value !== 'false',
+			}),
+		),
+	)
+
+export const envLiteral = <A extends string>(name: string, schema: Schema.Schema<A, A>) =>
+	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 })
@@ -19,15 +48,109 @@ 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>('ExpandCliConfig')({
 	apiUrl: Schema.optional(Schema.URL),
 	authMethod: Schema.optional(Schema.Union(ApiKeyConfig, OAuthConfig)),
+	telemetry: Schema.optional(TelemetrySettings),
 }) {
 	static readonly Json = Schema.parseJson(ExpandCliConfig)
 }
 
+export type AuthMethod = typeof ApiKeyConfig.Type | typeof OAuthConfig.Type
+
+/**
+ * How a stored credential stands right now.
+ *
+ * `refresh_required` is deliberately distinct from `healthy`: an expired access
+ * token with a refresh token on disk is only a credential we *could* renew, and
+ * renewal can fail. Reporting it as healthy told agents a machine was authorized
+ * when the next call would fail.
+ */
+export type AuthMethodState = 'healthy' | 'refresh_required' | 'unusable'
+
+export function authMethodState(authMethod: AuthMethod, now: DateTime.Utc): AuthMethodState {
+	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: AuthMethod, now: DateTime.Utc): boolean {
+	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: typeof RawConfigRecord.Type,
+	known: typeof RawConfigRecord.Type,
+): typeof RawConfigRecord.Type {
+	return { ...existing, ...known }
+}
+
+interface ConfigFileContents {
+	readonly config: ExpandCliConfig
+	readonly raw: typeof RawConfigRecord.Type
+}
+
+interface PathIdentity {
+	readonly exists: boolean
+	readonly dev?: number
+	readonly ino?: number
+	readonly realPath?: string
+	readonly type?: FileSystem.File.Type
+}
+
+function isErrnoCode(input: unknown, code: string): boolean {
+	return typeof input === 'object' && input !== null && 'code' in input && input.code === code
+}
+
+function powerShellLiteral(value: string): string {
+	return `'${value.replaceAll("'", "''")}'`
+}
+
+function scriptWithTargetPaths(script: string, targetPaths: ReadonlyArray<string>): string {
+	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: PathIdentity, right: PathIdentity): boolean {
+	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>()('ConfigNotWritable', {
 	path: Schema.String,
 }) {
@@ -36,6 +159,17 @@ export class ConfigNotWritable extends Schema.TaggedError<ConfigNotWritable>()('
 	}
 }
 
+export class ConfigCleanupError extends Schema.TaggedError<ConfigCleanupError>()('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>()('ConfigParseError', {
 	path: Schema.String,
 	error: Schema.Defect,
@@ -45,6 +179,16 @@ export class ConfigParseError extends Schema.TaggedError<ConfigParseError>()('Co
 	}
 }
 
+export class CredentialStoreInsecure extends Schema.TaggedError<CredentialStoreInsecure>()('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>()('NotAuthenticated', {}) {
 	get message() {
 		return 'Not authenticated. Run `expandai login` to authenticate.'
@@ -70,28 +214,478 @@ const Environment = Effect.gen(function* () {
 })
 
 export class ConfigManager extends Effect.Service<ConfigManager>()('@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 configPath = path.join(yield* xdgConfigDirectory, 'expandai', 'config.json')
+		const configDirectory = path.dirname(configPath)
+
+		const insecure = (targetPath: string, reason: string, error: unknown) =>
+			new CredentialStoreInsecure({ path: targetPath, reason, error })
+
+		const assertNotSymbolicLink = Effect.fnUntraced(function* (targetPath: string) {
+			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: string) {
+			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: PathIdentity = { 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: PathIdentity = {
+				exists: true,
+				dev: info.dev,
+				ino: Option.getOrUndefined(info.ino),
+				realPath,
+				type: info.type,
+			}
+			return identity
+		})
+
+		const assertStable = (targetPath: string, before: PathIdentity, after: PathIdentity) =>
+			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: string) {
+			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) } as const
+		})
+
+		const readCredentialFile = Effect.fnUntraced(function* (targetPath: string) {
+			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 EnvironmentFromConfigFile = Effect.gen(function* () {
+		const ensurePosixMode = Effect.fnUntraced(function* (
+			targetPath: string,
+			mode: number,
+			expectedType: 'Directory' | 'File',
+		) {
+			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: ReadonlyArray<string>) {
+			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: ReadonlyArray<string>) {
+			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: string) {
+			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: CreatedFileIdentity, operationError: unknown) {
+				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: ConfigFileContents = { config: ExpandCliConfig.make({}), raw: {} }
+				return empty
 			}
 
-			const string = yield* fs.readFileString(configPath)
-			return yield* Schema.decode(ExpandCliConfig.Json)(string).pipe(
+			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: ConfigFileContents = { 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
@@ -112,54 +706,94 @@ export class ConfigManager extends Effect.Service<ConfigManager>()('@expandai/cl
 					),
 				),
 			)
-			yield* Effect.logWarning(`EXPAND_API_KEY overrides the auth method stored in ${configPath}`).pipe(
-				Effect.when(() => Option.isSome(authMethod.env) && Option.isSome(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])
 
-			return yield* Option.match(
-				Option.orElse(authMethod.env, () => authMethod.file),
-				{
-					onNone: () => Effect.fail(new NotAuthenticated()),
-					onSome: (authMethod) =>
-						Effect.succeed({
-							apiUrl: Option.firstSomeOf([apiUrl.env, apiUrl.file]).pipe(
-								Option.getOrElse(() => new URL(DEFAULT_API_URL)),
-							),
-							authMethod,
-						}),
-				},
+			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)),
+						),
+						authMethod,
+					}),
+			})
 		})
 
 		const saveConfig = Effect.fn('saveConfig')(function* (config: ExpandCliConfig) {
-			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: Partial<ExpandCliConfig>) {
-			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* () {
@@ -174,6 +808,13 @@ export class ConfigManager extends Effect.Service<ConfigManager>()('@expandai/cl
 			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;
@@ -184,11 +825,15 @@ export class ConfigManager extends Effect.Service<ConfigManager>()('@expandai/cl
 
 		return {
 			configPath,
+			inspectSecureStorage,
+			ensureSecureStorage,
 			loadConfig,
 			saveConfig,
 			updateConfig,
 			clearConfig,
+			readConfigFile,
 			getApiUrl,
+			getAppUrl,
 			getPlaygroundHost,
 		} as const
 	}),