expandai 0.0.2 → 0.0.3

package/src/Auth/Pkce.ts

@@ -0,0 +1,26 @@
+import { createHash, randomBytes } from 'node:crypto'
+import { Redacted } from 'effect'
+
+/**
+ * RFC 7636 requires 43–128 characters of unreserved alphabet; 32 random bytes
+ * encode to 43 base64url characters, which is also what the API's
+ * `^[A-Za-z0-9_-]{43}$` challenge check expects.
+ */
+const VERIFIER_BYTES = 32
+
+/** PKCE code verifier. Redacted so it cannot reach a log or a JSON result. */
+export function createCodeVerifier(): Redacted.Redacted<string> {
+	return Redacted.make(randomBytes(VERIFIER_BYTES).toString('base64url'))
+}
+
+export function codeChallengeFor(verifier: Redacted.Redacted<string>): string {
+	return createHash('sha256').update(Redacted.value(verifier)).digest('base64url')
+}
+
+/**
+ * Opaque high-entropy value for non-PKCE uses such as the OAuth `state`
+ * parameter. Same entropy and encoding, different purpose.
+ */
+export function createHighEntropySecret(): string {
+	return randomBytes(VERIFIER_BYTES).toString('base64url')
+}

package/src/Auth/SetupGrantAuthorization.ts

@@ -0,0 +1,116 @@
+import { Effect, Redacted, Schema } from 'effect'
+import { ConfigManager } from '../Config.js'
+import {
+	ManualAuthorization,
+	ManualAuthorizationCredentialSaveFailed,
+	ManualAuthorizationDenied,
+	ManualAuthorizationRefused,
+} from './ManualAuthorization.js'
+
+interface SetupGrantAuthorizationInput {
+	readonly setupToken: Redacted.Redacted<string>
+	readonly harness: 'agent-harnesses'
+	readonly scope: 'project' | 'global'
+}
+
+export class SetupGrantAuthorizationError extends Schema.TaggedError<SetupGrantAuthorizationError>()(
+	'SetupGrantAuthorizationError',
+	{
+		code: Schema.Literal(
+			'invalid_or_expired',
+			'stored_credential_conflict',
+			'request_failed',
+			'denied',
+			'credential_save_failed',
+			'refused',
+			'config_unreadable',
+		),
+		recoverable: Schema.Boolean,
+	},
+) {
+	get message() {
+		switch (this.code) {
+			// Checked before redemption, so the token is untouched and the user can
+			// retry with the same one after clearing the stored credential.
+			case 'stored_credential_conflict':
+				return 'An Expand API key is already stored on this machine, and completing this setup would replace it with no way to recover it. Nothing was changed and your setup prompt is still valid. Run `expandai logout` to clear the stored key, then run this setup command again.'
+			case 'request_failed':
+				return 'Could not reach Expand to redeem the setup token. Nothing was sent, so the same token is still good — check the network and try again.'
+			case 'denied':
+				return 'This setup authorization was denied. Copy a fresh setup prompt from the Expand dashboard.'
+			// Checked before redemption, so like stored_credential_conflict the token is
+			// untouched and the same prompt works once the file is dealt with.
+			case 'config_unreadable':
+				return 'The Expand config file on this machine could not be read, so setup cannot tell whether completing it would overwrite an existing API key. Nothing was redeemed and your setup prompt is still valid. Run `expandai whoami` to see which file it is, fix or delete it, then run this setup command again.'
+			// Server-side misconfiguration: a fresh prompt is refused identically.
+			case 'refused':
+				return 'Expand refused to redeem this setup token for a reason a fresh prompt cannot fix — most likely an OAuth client, resource, or scope misconfiguration on the server. Do not request another prompt; report this.'
+			// The token redeemed — it is spent — but the credentials could not be
+			// written locally. A fresh prompt hits the same wall until the local
+			// storage problem is fixed, so say that instead of blaming the token.
+			case 'credential_save_failed':
+				return 'The setup token was redeemed, but the credentials could not be saved on this machine. Fix credential storage — run `expandai whoami` to see the path it uses, and check its permissions — then copy a fresh setup prompt from the Expand dashboard.'
+			default:
+				return 'The setup token is invalid, expired, or already used. Copy a fresh setup prompt from the Expand dashboard.'
+		}
+	}
+}
+
+function setupGrantError(code: typeof SetupGrantAuthorizationError.fields.code.Type): SetupGrantAuthorizationError {
+	return new SetupGrantAuthorizationError({
+		code,
+		recoverable: code !== 'denied' && code !== 'credential_save_failed' && code !== 'refused',
+	})
+}
+
+/**
+ * Dashboard-minted setup: the "token" in the prompt is a pre-approved RFC 8628
+ * device code, already bound to the minting user and pinned to their
+ * organization server-side. Redeeming is a single poll of the OAuth token
+ * endpoint — better-auth owns generation, expiry and the single-use burn, so
+ * there is no redemption protocol of ours left to get wrong.
+ */
+export class SetupGrantAuthorization extends Effect.Service<SetupGrantAuthorization>()(
+	'@expandai/cli/Auth/SetupGrantAuthorization',
+	{
+		dependencies: [ConfigManager.Default, ManualAuthorization.Default],
+		effect: Effect.gen(function* () {
+			const configManager = yield* ConfigManager
+			const manualAuthorization = yield* ManualAuthorization
+			const authorize = Effect.fn('SetupGrantAuthorization.authorize')(function* (input: SetupGrantAuthorizationInput) {
+				// The *file*, specifically. `loadConfig` collapses env and file into one
+				// value, so it cannot tell an ambient `EXPAND_API_KEY` — which must
+				// never block setup — from a key written by `expandai login`, which
+				// saving new credentials would overwrite with no way to recover it.
+				//
+				// Refused before redemption: nothing has been spent, so the same prompt
+				// still works once the user clears the stored key.
+				// `readConfigFile` never fails — it reports an unreadable file through
+				// `parseFailed` and hands back an empty config — so `Effect.either` here was
+				// always Right and the ApiKey check silently passed on a corrupt file. That
+				// matters: redemption is single-use, so proceeding would spend the token and
+				// *then* fail to save. Refuse first, while the prompt is still good.
+				const storedFile = yield* configManager.readConfigFile()
+				if (storedFile.parseFailed) return yield* setupGrantError('config_unreadable')
+				if (storedFile.config.authMethod?._tag === 'ApiKey') {
+					return yield* setupGrantError('stored_credential_conflict')
+				}
+				yield* Effect.annotateCurrentSpan({ harness: input.harness, scope: input.scope })
+				yield* manualAuthorization.redeemPreApproved(input.setupToken).pipe(
+					Effect.mapError((error) => {
+						if (error instanceof ManualAuthorizationDenied) return setupGrantError('denied')
+						if (error instanceof ManualAuthorizationCredentialSaveFailed) {
+							return setupGrantError('credential_save_failed')
+						}
+						if (error instanceof ManualAuthorizationRefused) return setupGrantError('refused')
+						if (error._tag === 'ManualAuthorizationApiError' && error.kind === 'request_failed') {
+							return setupGrantError('request_failed')
+						}
+						return setupGrantError('invalid_or_expired')
+					}),
+				)
+			})
+			return { authorize } as const
+		}),
+	},
+) {}

package/src/Authentication.ts

@@ -2,10 +2,13 @@ import { Command, Prompt } from '@effect/cli'
 import { Console, DateTime, Duration, Effect, Either, Match, Schema, String } from 'effect'
 import open from 'open'
 import { BrowserOAuthService } from './BrowserOAuth.js'
-import { ApiKey, ApiKeyConfig, ConfigManager, OAuthConfig } from './Config.js'
-import { Uninstall } from './Install/Uninstall.js'
+import { ApiKey, ApiKeyConfig, type AuthMethod, ConfigManager, isAuthMethodLocallyUsable } from './Config.js'
+
+// Re-exported: these moved to Config.ts, where the credential types live, so
+// that credential precedence can consult usability without a cycle.
+export { type AuthMethodState, authMethodState, isAuthMethodLocallyUsable } from './Config.js'
 
-type AuthMethod = typeof ApiKeyConfig.Type | typeof OAuthConfig.Type
+import { Uninstall } from './Install/Uninstall.js'
 
 /** Render a user-facing description of the current auth state. Pure given DateTime.now. */
 export const formatAuthStatus = Effect.fn('Authentication.formatAuthStatus')(function* (authMethod: AuthMethod) {
@@ -32,6 +35,17 @@ export class Authentication extends Effect.Service<Authentication>()('@expandai/
 		const browserOAuth = yield* BrowserOAuthService
 		const uninstall = yield* Uninstall
 
+		const hasLocallyUsableCredentials = Effect.fn('Authentication.hasLocallyUsableCredentials')(function* () {
+			yield* configManager.ensureSecureStorage()
+			const loaded = yield* Effect.either(configManager.loadConfig())
+			if (Either.isLeft(loaded)) {
+				if (loaded.left._tag === 'NotAuthenticated') return false
+				return yield* Effect.fail(loaded.left)
+			}
+			const now = yield* DateTime.now
+			return isAuthMethodLocallyUsable(loaded.right.authMethod, now)
+		})
+
 		const apiKeyLogin = Effect.fn('Authentication.apiKeyLogin')(function* () {
 			const apiKey = yield* Prompt.password({ message: 'Enter your API Key' })
 			yield* configManager.updateConfig({
@@ -40,13 +54,41 @@ export class Authentication extends Effect.Service<Authentication>()('@expandai/
 			yield* Console.log('API key saved successfully!')
 		})
 
-		const oauthLogin = Effect.fn('Authentication.oauthLogin')(function* () {
+		const browserLogin = Effect.fnUntraced(function* <R>(
+			showAuthorizeUrl: (authorizeUrl: URL) => Effect.Effect<void, unknown, R>,
+		) {
 			yield* Console.log(
 				String.stripMargin(`
 					|
 					|Starting browser authorization...`),
 			)
-			yield* browserOAuth.login((authorizeUrl) =>
+			yield* browserOAuth.login(showAuthorizeUrl)
+			yield* Console.log(
+				String.stripMargin(`
+					|
+					|Successfully authenticated!`),
+			)
+		})
+
+		const printAuthorizeUrl = Effect.fnUntraced(function* (authorizeUrl: URL) {
+			yield* Console.log(
+				String.stripMargin(`
+					|
+					|Open this URL in a browser:
+					|  ${authorizeUrl.toString()}
+					|
+					|Waiting for browser authorization...`),
+			)
+		})
+
+		// `init` already asks for harness and scope. Keep browser login on the
+		// existing loopback OAuth path without introducing a third Prompt choice.
+		const loginWithBrowser = Effect.fn('Authentication.loginWithBrowser')(function* () {
+			yield* browserLogin(printAuthorizeUrl)
+		})
+
+		const oauthLogin = Effect.fn('Authentication.oauthLogin')(function* () {
+			yield* browserLogin((authorizeUrl) =>
 				Effect.gen(function* () {
 					yield* Console.log(
 						String.stripMargin(`
@@ -70,14 +112,10 @@ export class Authentication extends Effect.Service<Authentication>()('@expandai/
 					)
 				}),
 			)
-			yield* Console.log(
-				String.stripMargin(`
-					|
-					|Successfully authenticated!`),
-			)
 		})
 
 		const login = Effect.fn('Authentication.login')(function* () {
+			yield* configManager.ensureSecureStorage()
 			const existing = yield* Effect.either(configManager.loadConfig())
 
 			if (Either.isRight(existing)) {
@@ -144,7 +182,7 @@ export class Authentication extends Effect.Service<Authentication>()('@expandai/
 			yield* Console.log('Logged out.')
 		})
 
-		return { login, whoami, logout } as const
+		return { hasLocallyUsableCredentials, loginWithBrowser, login, whoami, logout } as const
 	}),
 }) {}
 

package/src/BrowserOAuth.ts

@@ -1,8 +1,8 @@
-import { createHash, randomBytes } from 'node:crypto'
 import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http'
 import { HttpClient, HttpClientRequest, HttpClientResponse } from '@effect/platform'
 import { NodeHttpClient } from '@effect/platform-node'
 import { DateTime, Duration, Effect, Inspectable, Redacted, Schema } from 'effect'
+import { codeChallengeFor, createHighEntropySecret } from './Auth/Pkce.js'
 import { ConfigManager, OAuthConfig } from './Config.js'
 
 const CLIENT_ID = 'expandai-cli'
@@ -107,16 +107,8 @@ interface LoopbackServer {
 	readonly close: Effect.Effect<void>
 }
 
-function base64Url(bytes: Uint8Array): string {
-	return Buffer.from(bytes).toString('base64').replaceAll('+', '-').replaceAll('/', '_').replaceAll('=', '')
-}
-
-function createHighEntropySecret(): string {
-	return base64Url(randomBytes(32))
-}
-
 export const createCodeChallenge = Effect.fn('BrowserOAuth.createCodeChallenge')(function* (codeVerifier: string) {
-	return base64Url(createHash('sha256').update(codeVerifier).digest())
+	return codeChallengeFor(Redacted.make(codeVerifier))
 })
 
 export const buildAuthorizeUrl = Effect.fn('BrowserOAuth.buildAuthorizeUrl')(function* ({
@@ -253,6 +245,7 @@ export class BrowserOAuthService extends Effect.Service<BrowserOAuthService>()('
 		const exchangeToken = Effect.fn('BrowserOAuthService.exchangeToken')(function* (
 			form: ReadonlyArray<readonly [string, string]>,
 		) {
+			yield* configManager.ensureSecureStorage()
 			const apiUrl = yield* configManager.getApiUrl()
 			const resource = apiUrl.toString()
 			const request = HttpClientRequest.post(new URL(OAUTH_TOKEN_ENDPOINT, apiUrl)).pipe(
@@ -301,10 +294,13 @@ export class BrowserOAuthService extends Effect.Service<BrowserOAuthService>()('
 			])
 		})
 
-		const refreshToken = Effect.fn('BrowserOAuthService.refreshToken')(function* (refreshToken: string) {
+		const refreshToken = Effect.fn('BrowserOAuthService.refreshToken')(function* (
+			refreshToken: string,
+			clientId: string = CLIENT_ID,
+		) {
 			return yield* exchangeToken([
 				['grant_type', 'refresh_token'],
-				['client_id', CLIENT_ID],
+				['client_id', clientId],
 				['refresh_token', refreshToken],
 			])
 		})
@@ -319,6 +315,7 @@ export class BrowserOAuthService extends Effect.Service<BrowserOAuthService>()('
 					refreshToken:
 						tokenResponse.refresh_token === undefined ? undefined : Redacted.make(tokenResponse.refresh_token),
 					expiresAt,
+					clientId: CLIENT_ID,
 				}),
 			})
 		})
@@ -326,6 +323,7 @@ export class BrowserOAuthService extends Effect.Service<BrowserOAuthService>()('
 		const login = Effect.fn('BrowserOAuthService.login')(function* <R>(
 			openAuthorizeUrl: (authorizeUrl: URL) => Effect.Effect<void, unknown, R>,
 		) {
+			yield* configManager.ensureSecureStorage()
 			const codeVerifier = createHighEntropySecret()
 			const state = createHighEntropySecret()
 			const codeChallenge = yield* createCodeChallenge(codeVerifier)

package/src/CommandPath.ts

@@ -0,0 +1,30 @@
+/**
+ * Telemetry-safe command-path extraction. Only tokens that sit in legal
+ * command-path positions of the tree below are ever reported — never
+ * free-form args, URLs, or queries. The walk stops at the first token that
+ * isn't a subcommand of the current node, so positional user input can't
+ * leak even when it happens to equal a command word
+ * (`expandai search snap_abc login` reports just `search`). Choice-arg
+ * values (hosts, scopes) are positional data and deliberately absent.
+ */
+const COMMAND_TREE = new Map<string, ReadonlySet<string>>([
+	['fetch', new Set()],
+	['search', new Set()],
+	['login', new Set()],
+	['whoami', new Set()],
+	['logout', new Set()],
+	['init', new Set()],
+	['status', new Set()],
+	['uninstall', new Set()],
+	['mcp', new Set(['run', 'install', 'uninstall'])],
+	['skill', new Set(['install', 'uninstall'])],
+	['hook', new Set(['claude-code', 'opencode', 'install', 'uninstall'])],
+	['telemetry', new Set(['status', 'enable', 'disable'])],
+])
+
+export function commandFromArgv(argv: readonly string[]): string {
+	const [first, second] = argv.slice(2)
+	const subcommands = first === undefined ? undefined : COMMAND_TREE.get(first)
+	if (first === undefined || subcommands === undefined) return '(none)'
+	return second !== undefined && subcommands.has(second) ? `${first} ${second}` : first
+}

package/src/Commands/Fetch.ts

@@ -2,7 +2,9 @@ import { Args, Command, HelpDoc, Options } from '@effect/cli'
 import { DEFAULT_PLAYGROUND_HOST, resolvePlaygroundHost } from '@expandai/sdk/Playground'
 import { Console, Effect, Match, Option, Schema, String } from 'effect'
 import { ApiClient } from '../ApiClient.js'
-import { renderSnippets } from '../Snippets.js'
+import { withCitationFooter } from '../Hook/SnapshotNote.js'
+import { highlightMarkdownAnsi, shouldColorizeMarkdown } from '../MarkdownAnsi.js'
+import { renderSnippets, withCitationUrls } from '../Snippets.js'
 
 export class MarkdownUnavailable extends Schema.TaggedError<MarkdownUnavailable>()('MarkdownUnavailable', {
 	url: Schema.String,
@@ -121,15 +123,21 @@ export const FetchCommand: Command.Command<'fetch', never, unknown, FetchCommand
 
 			const output =
 				format === 'text' && query === undefined
-					? yield* client
-							.fetchFetch(fetchRequest)
-							.pipe(
-								Effect.flatMap((markdown) =>
-									String.isNonEmpty(markdown)
-										? Effect.succeed(markdown)
-										: Effect.fail(new MarkdownUnavailable({ url: url.toString() })),
-								),
-							)
+					? yield* client.fetchFetch(fetchRequest).pipe(
+							Effect.flatMap((markdown) =>
+								String.isNonEmpty(markdown)
+									? Effect.succeed(markdown)
+									: Effect.fail(new MarkdownUnavailable({ url: url.toString() })),
+							),
+							// Interactive terminals get ANSI-highlighted markdown. Piped output is
+							// being read by an agent, so it also carries the citation contract —
+							// this is the third fetch path (with the hook and the MCP tools) and
+							// was the only one that shipped evidence ids without telling anyone
+							// to use them.
+							Effect.map((markdown) =>
+								shouldColorizeMarkdown() ? highlightMarkdownAnsi(markdown) : withCitationFooter(markdown),
+							),
+						)
 					: yield* client.fetchFetchResult(fetchRequest).pipe(
 							Effect.flatMap((fetched) =>
 								Match.value(format).pipe(
@@ -145,7 +153,30 @@ export const FetchCommand: Command.Command<'fetch', never, unknown, FetchCommand
 													),
 												)
 									}),
-									Match.when('json', () => Schema.encode(Schema.parseJson(Schema.Unknown, { space: 2 }))(fetched)),
+									Match.when('json', () => {
+										// Snippets carry a citation link in every other output path
+										// (text here, and both MCP tools). Without it a JSON consumer
+										// cannot cite what it just searched.
+										const search = fetched.data?.search
+										const cited =
+											search == null
+												? fetched
+												: {
+														...fetched,
+														data: {
+															...fetched.data,
+															search: {
+																...search,
+																snippets: withCitationUrls(
+																	fetched.meta.snapshotId,
+																	resolvePlaygroundHost(fetched.meta.playground, DEFAULT_PLAYGROUND_HOST),
+																	search.snippets,
+																),
+															},
+														},
+													}
+										return Schema.encode(Schema.parseJson(Schema.Unknown, { space: 2 }))(cited)
+									}),
 									Match.exhaustive,
 								),
 							),