import { buckyos, createAppInstanceId, parseSessionTokenClaims, VerifyHubClient, } from 'buckyos/node' import { type Environment, readEnvironment, type ResolvedConfig } from './config.ts' import { type DevelopmentModeDecision, type DevelopmentModeReader, readTargetDevelopmentMode, } from './development_mode.ts' import { EXIT_AUTH, sanitizeMessage, ToolError } from './errors.ts' import { IDENTITY_CANDIDATE_LIMIT, IDENTITY_REJECTION_CODES, type IdentityCandidate, type IdentityMaterial, resolveIdentityMaterial, scanIdentityCandidates, } from './identity.ts' import { resolveServiceUrl } from './runtime.ts' import { getHost } from '../runtime/host.ts' type AuthTarget = | { kind: 'app'; app_instance_id: string } | { kind: 'system'; service_id: string } export type AuthenticationKind = | 'session-token' | 'session-token-file' | 'environment' | 'identity' | 'password' | 'mock' export interface ResolvedPrincipal { id: string appId: string appInstanceId?: string authentication: AuthenticationKind tokenExpiresAt?: string } export interface AuthenticatedSession { token: string principal: ResolvedPrincipal claims: Record renewable: boolean } export interface AuthenticationTransport { loginByJwt(url: string, jwt: string, target: AuthTarget, timeoutMs: number): Promise loginByPassword( url: string, username: string, password: string, target: AuthTarget, timeoutMs: number, ): Promise } export interface AuthenticationDependencies { transport?: AuthenticationTransport readPassword?: (prompt: string) => Promise readUsername?: (prompt: string) => Promise readDevelopmentMode?: DevelopmentModeReader now?: () => number } export interface SessionController { readonly config: ResolvedConfig connect(): Promise ensureValid(): Promise reconnect(): Promise current(): AuthenticatedSession status(): Record } const LOGIN_APP_ID = 'buckycli' const LOGIN_TOKEN_TTL_SECONDS = 10 * 60 export class AuthenticationSession implements SessionController { readonly config: ResolvedConfig readonly #environment: Environment readonly #transport: AuthenticationTransport readonly #readPassword: (prompt: string) => Promise readonly #readUsername: (prompt: string) => Promise readonly #readDevelopmentMode: DevelopmentModeReader readonly #now: () => number #session?: AuthenticatedSession #acceptedIdentity?: IdentityMaterial #developmentMode?: DevelopmentModeDecision #identityAttempts: Array<{ identity: string; code: string; message: string }> = [] constructor( config: ResolvedConfig, environment: Environment = readEnvironment(), dependencies: AuthenticationDependencies = {}, ) { this.config = config this.#environment = environment this.#transport = dependencies.transport ?? new SdkAuthenticationTransport() this.#readPassword = dependencies.readPassword ?? readSecret this.#readUsername = dependencies.readUsername ?? readVisible this.#readDevelopmentMode = dependencies.readDevelopmentMode ?? readTargetDevelopmentMode this.#now = dependencies.now ?? Date.now } async connect(): Promise { if (this.#session) return this.#session this.#session = await this.#authenticate(false) return this.#session } async ensureValid(): Promise { const session = await this.connect() const exp = numberClaim(session.claims.exp) const nowSeconds = Math.floor(this.#now() / 1_000) if (exp === undefined || exp > nowSeconds + 15) return session if (!session.renewable) { throw new ToolError( 'SESSION_EXPIRED', 'the externally supplied session token has expired', EXIT_AUTH, ) } this.#session = await this.#authenticate(true) return this.#session } async reconnect(): Promise { this.#session = await this.#authenticate(true) return this.#session } current(): AuthenticatedSession { if (!this.#session) { throw new ToolError('AUTH_REQUIRED', 'session is not initialized', EXIT_AUTH) } return this.#session } status(): Record { const session = this.current() const expiresAt = session.principal.tokenExpiresAt const exp = numberClaim(session.claims.exp) const remainingSeconds = exp === undefined ? null : Math.max(0, exp - Math.floor(this.#now() / 1_000)) return { authenticated: true, principal: session.principal.id, appid: session.principal.appId, app_instance_id: session.principal.appInstanceId ?? null, authentication: session.principal.authentication, renewable: session.renewable, expires_at: expiresAt ?? null, remaining_seconds: remainingSeconds, developer_mode: this.#developmentMode?.state ?? null, identity_attempts: this.#identityAttempts, } } async #authenticate(reconnect: boolean): Promise { if (this.config.sessionToken) { const source = this.config.sources.session_token === 'environment' ? 'environment' : 'session-token' return externalSession(this.config.sessionToken, source, this.#now()) } if (this.config.sessionTokenFile) { let token: string try { token = (await getHost().readTextFile(this.config.sessionTokenFile)).trim() } catch (error) { throw new ToolError( 'SESSION_TOKEN_FILE_ERROR', `failed to read session token file: ${ error instanceof Error ? error.message : String(error) }`, EXIT_AUTH, ) } if (!token) { throw new ToolError('INVALID_SESSION_TOKEN', 'session token file is empty', EXIT_AUTH) } return externalSession(token, 'session-token-file', this.#now()) } const injected = this.#environment.BUCKYOS_APPCLIENT_SESSION_TOKEN?.trim() if (injected) return externalSession(injected, 'environment', this.#now()) if (this.#acceptedIdentity) { if (this.#acceptedIdentity.source === 'buckycli-home') { await this.#requireDeveloperIdentityAccess() } return await this.#loginWithIdentity(this.#acceptedIdentity) } if (this.config.identity) { const material = await this.#resolveExplicitIdentity(this.config.identity) const session = await this.#loginWithIdentity(material) this.#acceptedIdentity = material return session } this.#identityAttempts = [] const operations = await scanIdentityCandidates(this.config, this.#environment) const operationsSession = await this.#tryIdentityCandidates(operations.candidates) if (operationsSession) return operationsSession const developmentMode = await this.#checkDevelopmentMode() if ( developmentMode.state === 'enabled' && operations.candidates.length < IDENTITY_CANDIDATE_LIMIT ) { const operationsDids = new Set( operations.candidates.map((candidate) => candidate.material.did), ) const developer = await scanIdentityCandidates(this.config, this.#environment, { includeOperations: false, includeDeveloper: true, }) const remaining = IDENTITY_CANDIDATE_LIMIT - operations.candidates.length const candidates = developer.candidates.filter((candidate) => !operationsDids.has(candidate.material.did) ).slice(0, remaining) const developerSession = await this.#tryIdentityCandidates(candidates) if (developerSession) return developerSession } if (this.#identityAttempts.length > 0) { throw new ToolError( 'IDENTITY_CANDIDATES_REJECTED', `all ${this.#identityAttempts.length} identity candidates were rejected`, EXIT_AUTH, false, { attempts: this.#identityAttempts }, ) } if (this.config.nonInteractive) { throw new ToolError( 'AUTH_REQUIRED', 'no session token or usable identity is available in non-interactive mode', EXIT_AUTH, ) } const username = this.config.identity?.startsWith('did:') ? await this.#readUsername('Username: ') : this.config.identity ?? await this.#readUsername('Username: ') if (!username.trim()) throw new ToolError('AUTH_REQUIRED', 'username is required', EXIT_AUTH) const password = await this.#readPassword(reconnect ? 'Password (reconnect): ' : 'Password: ') const token = await this.#transport.loginByPassword( resolveServiceUrl(this.config, 'verify-hub'), username.trim(), password, appAuthTarget(username.trim()), this.config.timeoutMs, ) return authenticatedSession(token, 'password', true, this.#now()) } async #resolveExplicitIdentity(selectedIdentity: string): Promise { if (this.config.implicitDeviceIdentity) { return await resolveIdentityMaterial(selectedIdentity, this.config, this.#environment) } try { return await resolveIdentityMaterial(selectedIdentity, this.config, this.#environment) } catch (error) { if (!(error instanceof ToolError) || error.code !== 'IDENTITY_NOT_FOUND') throw error } await this.#requireDeveloperIdentityAccess() return await resolveIdentityMaterial(selectedIdentity, this.config, this.#environment, { includeOperations: false, includeDeveloper: true, }) } async #tryIdentityCandidates( candidates: readonly IdentityCandidate[], ): Promise { for (const candidate of candidates) { try { const session = await this.#loginWithIdentity(candidate.material) this.#acceptedIdentity = candidate.material return session } catch (error) { if (!isIdentityRejection(error)) throw error this.#identityAttempts.push({ identity: candidate.material.did, code: error.code, message: sanitizeMessage(error.message), }) } } return undefined } async #loginWithIdentity(material: IdentityMaterial): Promise { const loginJwt = await createLoginJwt( material.subject, material.issuer, material.privateKeyPem, this.#now(), ) const token = await this.#transport.loginByJwt( resolveServiceUrl(this.config, 'verify-hub'), loginJwt, identityAuthTarget(material.principalKind, material.subject), this.config.timeoutMs, ) return authenticatedSession(token, 'identity', true, this.#now()) } async #checkDevelopmentMode(): Promise { this.#developmentMode = await this.#readDevelopmentMode(this.config) return this.#developmentMode } async #requireDeveloperIdentityAccess(): Promise { const decision = await this.#checkDevelopmentMode() if (decision.state === 'enabled') return this.#acceptedIdentity = undefined if (decision.state === 'disabled') { throw new ToolError( 'DEVELOPER_IDENTITY_DISABLED', 'the target Zone has developer mode disabled; local developer identities are unavailable', EXIT_AUTH, ) } throw new ToolError( 'DEVELOPER_MODE_UNAVAILABLE', 'the target Zone developer-mode configuration could not be verified', EXIT_AUTH, true, { reason: sanitizeMessage(decision.reason) }, ) } } function isIdentityRejection(error: unknown): error is ToolError { return error instanceof ToolError && IDENTITY_REJECTION_CODES.includes(error.code) } export class SdkAuthenticationTransport implements AuthenticationTransport { async loginByJwt( url: string, jwt: string, target: AuthTarget, timeoutMs: number, ): Promise { const client = new buckyos.kRPCClient(url) const response = await withLocalTimeout( new VerifyHubClient(client).loginByJwt({ jwt, target }), timeoutMs, ) if (!response.session_token) throw new Error('verify-hub returned no session token') return response.session_token } async loginByPassword( url: string, username: string, password: string, target: AuthTarget, timeoutMs: number, ): Promise { const client = new buckyos.kRPCClient(url) const verifyHub = new VerifyHubClient(client) const nonce = Date.now() verifyHub.setSeq(nonce) const response = await withLocalTimeout( verifyHub.loginByPassword({ username, password: (buckyos.hashPassword as unknown as ( username: string, password: string, nonce?: number | null, ) => string)(username, password, nonce), target, login_nonce: nonce, }), timeoutMs, ) if (!response.session_token) throw new Error('verify-hub returned no session token') return response.session_token } } function identityAuthTarget( principalKind: 'user' | 'device', subject: string, ): AuthTarget { return principalKind === 'device' ? { kind: 'system', service_id: LOGIN_APP_ID } : appAuthTarget(subject) } function appAuthTarget(ownerUserId: string): AuthTarget { return { kind: 'app', app_instance_id: createAppInstanceId(LOGIN_APP_ID, ownerUserId), } } export function authenticatedSession( token: string, authentication: AuthenticationKind, renewable: boolean, nowMs = Date.now(), ): AuthenticatedSession { const claims = parseClaims(token) const exp = numberClaim(claims.exp) const nowSeconds = Math.floor(nowMs / 1_000) if (exp !== undefined && exp <= nowSeconds) { throw new ToolError('SESSION_EXPIRED', 'the session token has expired', EXIT_AUTH) } const id = stringClaim(claims.sub) ?? stringClaim(claims.userid) const appId = stringClaim(claims.appid) ?? stringClaim(claims.aud) if (!id || !appId) { throw new ToolError( 'INVALID_SESSION_TOKEN', 'session token is missing principal or appid claims', EXIT_AUTH, ) } const appInstanceId = stringClaim(claims.app_instance_id) ?? stringClaim((claims.extra as Record | undefined)?.app_instance_id) return { token, claims, renewable, principal: { id, appId, appInstanceId, authentication, tokenExpiresAt: exp === undefined ? undefined : new Date(exp * 1_000).toISOString(), }, } } function externalSession( token: string, authentication: Extract< AuthenticationKind, 'session-token' | 'session-token-file' | 'environment' >, nowMs: number, ): AuthenticatedSession { return authenticatedSession(token, authentication, false, nowMs) } function parseClaims(token: string): Record { const claims = parseSessionTokenClaims(token) if (!claims) { throw new ToolError('INVALID_SESSION_TOKEN', 'session token is not a valid JWT', EXIT_AUTH) } return claims as Record } async function createLoginJwt( subject: string, issuer: string, privateKeyPem: string, nowMs: number, ): Promise { const now = Math.floor(nowMs / 1_000) const header = { alg: 'EdDSA', kid: issuer, typ: 'JWT' } const payload = { token_type: 'Normal', appid: LOGIN_APP_ID, jti: crypto.randomUUID(), session: now, sub: subject, userid: subject, iss: issuer, exp: now + LOGIN_TOKEN_TTL_SECONDS, sudo: false, extra: {}, } const signingInput = `${base64Url(JSON.stringify(header))}.${base64Url(JSON.stringify(payload))}` const keyBytes = pemBytes(privateKeyPem) let key: CryptoKey try { key = await crypto.subtle.importKey( 'pkcs8', keyBytes.slice().buffer as ArrayBuffer, { name: 'Ed25519' }, false, ['sign'], ) } catch { throw new ToolError( 'INVALID_PRIVATE_KEY', 'identity authentication key is not a valid Ed25519 PKCS8 key', EXIT_AUTH, ) } const signature = await crypto.subtle.sign('Ed25519', key, new TextEncoder().encode(signingInput)) return `${signingInput}.${base64Url(new Uint8Array(signature))}` } function pemBytes(pem: string): Uint8Array { const encoded = pem.replace(/-----[^-]+-----/g, '').replaceAll(/\s/g, '') const binary = atob(encoded) return Uint8Array.from(binary, (character) => character.charCodeAt(0)) } function base64Url(value: string | Uint8Array): string { const bytes = typeof value === 'string' ? new TextEncoder().encode(value) : value let binary = '' for (const byte of bytes) binary += String.fromCharCode(byte) return btoa(binary).replaceAll('+', '-').replaceAll('/', '_').replaceAll('=', '') } function stringClaim(value: unknown): string | undefined { return typeof value === 'string' && value.trim() ? value.trim() : undefined } function numberClaim(value: unknown): number | undefined { return typeof value === 'number' && Number.isFinite(value) ? value : undefined } async function withLocalTimeout(promise: Promise, timeoutMs: number): Promise { let timer: ReturnType | undefined const timeout = new Promise((_, reject) => { timer = setTimeout( () => reject(new ToolError('TIMEOUT', 'authentication timed out', 8, true)), timeoutMs, ) }) try { return await Promise.race([promise, timeout]) } finally { if (timer !== undefined) clearTimeout(timer) } } async function readVisible(prompt: string): Promise { return (await getHost().readLine(prompt))?.trim() ?? '' } async function readSecret(prompt: string): Promise { if (!getHost().inputIsTerminal()) { throw new ToolError( 'INTERACTIVE_AUTH_UNAVAILABLE', 'password input requires a terminal', EXIT_AUTH, ) } try { return await getHost().readSecret(prompt) } catch (error) { throw new ToolError( 'INTERACTIVE_AUTH_UNAVAILABLE', error instanceof Error ? error.message : String(error), EXIT_AUTH, ) } }