@keeper-security/keeper-sdk-javascript 0.1.0

package/src/auth/ConsoleLogin.ts

@@ -0,0 +1,351 @@
+import readline from 'readline/promises'
+import type { AuthUI3 } from '@keeper-security/keeperapi'
+import { KeeperVault } from '../vault/KeeperVault'
+import {
+    logger,
+    extractResultCode,
+    extractErrorMessage,
+    KeeperSdkError,
+    SdkDefaults,
+    AuthDefaults,
+    ResultCodes,
+    KEEPER_PUBLIC_HOSTS,
+} from '../utils'
+import { ConsoleAuthUI } from './ConsoleAuthUI'
+import { FileConfigLoader } from './SessionManager'
+import type { KeeperJsonConfig } from './SessionManager'
+
+const DEFAULT_REGION = 'US'
+const MASK_CHAR = '*'
+const NOOP_WRITE = (() => true) as typeof process.stdout.write
+
+enum CliCharAction {
+    Submit,
+    Cancel,
+    Backspace,
+    Append,
+}
+
+type ConsoleHandlers = {
+    log: typeof console.log
+    warn: typeof console.warn
+    debug: typeof console.debug
+    error: typeof console.error
+    stdoutWrite: typeof process.stdout.write
+    stderrWrite: typeof process.stderr.write
+}
+
+const defaultConfigLoader = new FileConfigLoader()
+
+let rlManager: ReadlineManager | null = null
+let suppressionDepth = 0
+let originals: ConsoleHandlers | null = null
+
+function captureConsoleHandlers(): ConsoleHandlers {
+    return {
+        log: console.log,
+        warn: console.warn,
+        debug: console.debug,
+        error: console.error,
+        stdoutWrite: process.stdout.write.bind(process.stdout),
+        stderrWrite: process.stderr.write.bind(process.stderr),
+    }
+}
+
+function applyConsoleHandlers(h: ConsoleHandlers): void {
+    console.log = h.log
+    console.warn = h.warn
+    console.debug = h.debug
+    console.error = h.error
+    process.stdout.write = h.stdoutWrite
+    process.stderr.write = h.stderrWrite
+}
+
+function classifyInputChar(ch: string): CliCharAction {
+    if (ch === '\n' || ch === '\r') return CliCharAction.Submit
+    if (ch === '\u0003') return CliCharAction.Cancel
+    if (ch === '\u007F' || ch === '\b') return CliCharAction.Backspace
+    return CliCharAction.Append
+}
+
+class ReadlineManager {
+    private rl: readline.Interface | null = null
+
+    private getOrCreate(): readline.Interface {
+        if (!this.rl) {
+            this.rl = readline.createInterface({
+                input: process.stdin,
+                output: process.stdout,
+            })
+        }
+        return this.rl
+    }
+
+    public async question(query: string): Promise<string> {
+        const rl = this.getOrCreate()
+        const answer = await rl.question(query)
+        return answer.trim()
+    }
+
+    public close(): void {
+        if (this.rl) {
+            this.rl.close()
+            this.rl = null
+        }
+    }
+}
+
+function getReadlineManager(): ReadlineManager {
+    if (!rlManager) {
+        rlManager = new ReadlineManager()
+    }
+    return rlManager
+}
+
+export function prompt(question: string, masked = false): Promise<string> {
+    const mgr = getReadlineManager()
+    if (!masked) {
+        return mgr.question(question)
+    }
+
+    return new Promise((resolve, reject) => {
+        mgr.close()
+        process.stdout.write(question)
+        let buf = ''
+        process.stdin.setRawMode(true)
+        process.stdin.resume()
+        process.stdin.setEncoding('utf8')
+
+        function exitRawMode() {
+            process.stdout.write('\n')
+            process.stdin.setRawMode(false)
+            process.stdin.pause()
+            process.stdin.removeListener('data', onData)
+        }
+
+        const onData = (str: string) => {
+            for (const ch of str) {
+                switch (classifyInputChar(ch)) {
+                    case CliCharAction.Submit:
+                        exitRawMode()
+                        resolve(buf.trim())
+                        return
+                    case CliCharAction.Cancel:
+                        exitRawMode()
+                        reject(new KeeperSdkError('Operation cancelled by user.', ResultCodes.USER_CANCELLED))
+                        return
+                    case CliCharAction.Backspace:
+                        if (buf.length > 0) {
+                            buf = buf.slice(0, -1)
+                            process.stdout.write('\b \b')
+                        }
+                        break
+                    case CliCharAction.Append:
+                        buf += ch
+                        process.stdout.write(MASK_CHAR)
+                        break
+                }
+            }
+        }
+
+        process.stdin.on('data', onData)
+    })
+}
+
+export async function loadKeeperConfig(preloaded?: KeeperJsonConfig): Promise<KeeperJsonConfig> {
+    if (preloaded) return preloaded
+    return defaultConfigLoader.load()
+}
+
+export async function resolveServer(username?: string, preloadedConfig?: KeeperJsonConfig): Promise<string> {
+    const config = await loadKeeperConfig(preloadedConfig)
+    const configServer = config.last_server || config.server
+
+    if (username) {
+        const users = config.users || []
+        const userEntry = users.find((u) => u.user?.toLowerCase() === username.toLowerCase())
+        if (userEntry?.server) return userEntry.server
+    }
+
+    if (configServer) return configServer
+
+    logger.info('Select server region:')
+    const entries = Object.entries(KEEPER_PUBLIC_HOSTS)
+    entries.forEach(([region, host], i) => {
+        logger.info(`  ${i + 1}. ${region} (${host})`)
+    })
+    logger.info(`  Or enter a hostname directly (e.g. dev.keepersecurity.com)`)
+
+    const choice = await prompt(`Region [1 = ${DEFAULT_REGION}]: `)
+    if (!choice) return KEEPER_PUBLIC_HOSTS[DEFAULT_REGION]
+
+    const idx = parseInt(choice, 10) - 1
+    if (idx >= 0 && idx < entries.length) return entries[idx][1]
+
+    return KEEPER_PUBLIC_HOSTS[choice.toUpperCase()] || choice
+}
+
+export function suppressLogs(): () => void {
+    if (suppressionDepth === 0) {
+        originals = captureConsoleHandlers()
+        applyConsoleHandlers({
+            log: () => {},
+            warn: () => {},
+            debug: () => {},
+            error: () => {},
+            stdoutWrite: NOOP_WRITE,
+            stderrWrite: NOOP_WRITE,
+        })
+    }
+    suppressionDepth++
+
+    let restored = false
+    return () => {
+        if (restored) return
+        restored = true
+        suppressionDepth--
+        if (suppressionDepth === 0 && originals) {
+            applyConsoleHandlers(originals)
+            originals = null
+        }
+    }
+}
+
+async function withSuppressedOutput<T>(fn: () => Promise<T>): Promise<T> {
+    const restore = suppressLogs()
+    try {
+        return await fn()
+    } finally {
+        restore()
+    }
+}
+
+function unsuppressLogs(): () => void {
+    if (suppressionDepth === 0 || !originals) return () => {}
+
+    const overrides = captureConsoleHandlers()
+    applyConsoleHandlers(originals)
+
+    let restored = false
+    return () => {
+        if (restored) return
+        restored = true
+        applyConsoleHandlers(overrides)
+    }
+}
+
+function unsuppressedAuthUI(): AuthUI3 {
+    const ui = new ConsoleAuthUI()
+    const wrap = <A extends unknown[], R>(fn: (...args: A) => Promise<R>) =>
+        async (...args: A): Promise<R> => {
+            const restore = unsuppressLogs()
+            try {
+                return await fn(...args)
+            } finally {
+                restore()
+            }
+        }
+    return {
+        waitForDeviceApproval: wrap(ui.waitForDeviceApproval.bind(ui)),
+        waitForTwoFactorCode: wrap(ui.waitForTwoFactorCode.bind(ui)),
+        getPassword: wrap(ui.getPassword.bind(ui)),
+    }
+}
+
+export async function login(): Promise<KeeperVault> {
+    const config = await loadKeeperConfig()
+    const defaultUsername = config.last_login || config.user || ''
+
+    const host = defaultUsername ? await resolveServer(defaultUsername, config) : undefined
+
+    if (defaultUsername && host) {
+        const vault = await tryPersistentLogin(host, defaultUsername)
+        if (vault) return vault
+    }
+
+    let username: string
+    if (defaultUsername) {
+        logger.info(`Enter master password for ${defaultUsername}`)
+        username = defaultUsername
+    } else {
+        username = await prompt('Username (email): ')
+    }
+
+    if (!username) {
+        throw new KeeperSdkError('Username is required.', ResultCodes.MISSING_USERNAME)
+    }
+
+    const resolvedHost = host || (await resolveServer(username, config))
+    return await interactiveLogin(resolvedHost, username)
+}
+
+async function tryPersistentLogin(host: string, username: string): Promise<KeeperVault | null> {
+    const vault = new KeeperVault({
+        host,
+        clientVersion: SdkDefaults.CLIENT_VERSION,
+        authUI: unsuppressedAuthUI(),
+    })
+    try {
+        await withSuppressedOutput(() => vault.resumeSession())
+        logger.info(`Logging in to Keeper as ${username}`)
+        logger.info('Successfully authenticated with Persistent Login')
+        return await syncVault(vault)
+    } catch (err) {
+        logger.debug('Persistent login failed:', extractErrorMessage(err))
+        vault.disconnect()
+        return null
+    }
+}
+
+async function interactiveLogin(host: string, username: string): Promise<KeeperVault> {
+    const vault = new KeeperVault({
+        host,
+        clientVersion: SdkDefaults.CLIENT_VERSION,
+        authUI: unsuppressedAuthUI(),
+    })
+
+    for (let attempt = 1; attempt <= AuthDefaults.MAX_LOGIN_ATTEMPTS; attempt++) {
+        const password = await prompt('Password: ', true)
+
+        if (!password) {
+            throw new KeeperSdkError('Password is required.', ResultCodes.MISSING_PASSWORD)
+        }
+
+        try {
+            await withSuppressedOutput(() => vault.login(username, password))
+            logger.info('Successfully authenticated with Master Password\n')
+            return await syncVault(vault)
+        } catch (err) {
+            const resultCode = extractResultCode(err)
+            if (resultCode === ResultCodes.INVALID_CREDENTIALS) {
+                const remaining = AuthDefaults.MAX_LOGIN_ATTEMPTS - attempt
+                if (remaining > 0) {
+                    logger.warn(`Invalid credentials (${remaining} attempt${remaining === 1 ? '' : 's'} remaining)`)
+                    continue
+                }
+                throw new KeeperSdkError(
+                    `Maximum login attempts (${AuthDefaults.MAX_LOGIN_ATTEMPTS}) exceeded.`,
+                    ResultCodes.MAX_ATTEMPTS_EXCEEDED
+                )
+            }
+            throw KeeperSdkError.from(err)
+        }
+    }
+
+    throw new KeeperSdkError(
+        `Maximum login attempts (${AuthDefaults.MAX_LOGIN_ATTEMPTS}) exceeded.`,
+        ResultCodes.MAX_ATTEMPTS_EXCEEDED
+    )
+}
+
+async function syncVault(vault: KeeperVault): Promise<KeeperVault> {
+    logger.info('Syncing vault...')
+    await withSuppressedOutput(() => vault.sync())
+    logger.info(`Vault synced. ${vault.getSummary().recordCount} records loaded.\n`)
+    return vault
+}
+
+export function cleanup(vault: KeeperVault): void {
+    vault.disconnect()
+    getReadlineManager().close()
+}

package/src/auth/SessionManager.ts

@@ -0,0 +1,293 @@
+import fs from 'fs/promises'
+import path from 'path'
+import os from 'os'
+import {
+    normal64Bytes,
+    type DeviceConfig,
+    type SessionStorage,
+    type KeeperHost,
+    type SessionParams,
+} from '@keeper-security/keeperapi'
+import { logger, extractErrorMessage, SdkDefaults } from '../utils'
+import type { Nullable } from '../utils'
+
+export type ConfigurationUser = {
+    user?: string
+    server?: string
+    last_device?: { device_token?: string }
+}
+
+export type ConfigurationServerConfig = {
+    server?: string
+    clone_code?: string
+}
+
+export type ConfigurationDeviceConfig = {
+    device_token?: string
+    private_key?: string
+    server_info?: Array<ConfigurationServerConfig>
+}
+
+export type KeeperJsonConfig = {
+    last_login?: string
+    last_server?: string
+    user?: string
+    server?: string
+    device_token?: string
+    private_key?: string
+    clone_code?: string
+    users?: Array<ConfigurationUser>
+    devices?: Array<ConfigurationDeviceConfig>
+}
+
+type ResolvedDevice = {
+    deviceToken: Uint8Array
+    privateKey: Uint8Array
+    serverInfo: Array<Required<ConfigurationServerConfig>>
+}
+
+type DeviceCacheEntry = {
+    username: string
+    device: Nullable<ResolvedDevice>
+}
+
+export interface ConfigLoader {
+    load(): Promise<KeeperJsonConfig>
+    save(config: KeeperJsonConfig): Promise<void>
+    readonly configDir: string
+}
+
+export class FileConfigLoader implements ConfigLoader {
+    public readonly configDir: string
+
+    constructor(configDir?: string) {
+        this.configDir = configDir || path.join(os.homedir(), SdkDefaults.CONFIG_DIR)
+    }
+
+    async load(): Promise<KeeperJsonConfig> {
+        const configPath = path.join(this.configDir, 'config.json')
+        try {
+            const content = await fs.readFile(configPath, 'utf-8')
+            const parsed: unknown = JSON.parse(content)
+            if (SessionManager.isValidKeeperConfig(parsed)) {
+                return parsed
+            }
+        } catch (err) {
+            logger.debug('Failed to load keeper config:', extractErrorMessage(err))
+        }
+        return {}
+    }
+
+    async save(config: KeeperJsonConfig): Promise<void> {
+        const configPath = path.join(this.configDir, 'config.json')
+        await fs.writeFile(configPath, JSON.stringify(config, null, 2), {
+            mode: 0o600,
+        })
+    }
+}
+
+export class SessionManager implements SessionStorage {
+    private readonly configLoader: ConfigLoader
+    private sessionParams: Nullable<SessionParams> = null
+    private _lastUsername?: string
+    private _keeperConfig: Nullable<KeeperJsonConfig> = null
+    private _deviceCache: Nullable<DeviceCacheEntry> = null
+    private sessionDevices = new Map<string, DeviceConfig>()
+    private sessionCloneCodes = new Map<string, Uint8Array>()
+
+    constructor(configDir?: string)
+    constructor(loader: ConfigLoader)
+    constructor(configDirOrLoader?: string | ConfigLoader) {
+        if (typeof configDirOrLoader === 'string' || configDirOrLoader === undefined) {
+            this.configLoader = new FileConfigLoader(configDirOrLoader as string | undefined)
+        } else {
+            this.configLoader = configDirOrLoader
+        }
+    }
+
+    public get configDir(): string {
+        return this.configLoader.configDir
+    }
+
+    public get lastUsername(): string | undefined {
+        return this._lastUsername
+    }
+
+    public async getLastUsername(): Promise<string | undefined> {
+        if (this._lastUsername) return this._lastUsername
+        const keeperConfig = await this.loadKeeperConfig()
+        return keeperConfig.last_login || keeperConfig.user || undefined
+    }
+
+    public async getDeviceConfig(host: string): Promise<DeviceConfig> {
+        const username = await this.getLastUsername()
+        if (username) {
+            const device = await this.findDeviceInKeeperConfig(username)
+            if (device) {
+                return {
+                    deviceToken: device.deviceToken,
+                    privateKey: device.privateKey,
+                }
+            }
+        }
+
+        return this.sessionDevices.get(host) || {}
+    }
+
+    public createOnDeviceConfig(host: string): (deviceConfig: DeviceConfig) => Promise<void> {
+        return async (deviceConfig: DeviceConfig) => {
+            this.sessionDevices.set(host, { ...deviceConfig })
+        }
+    }
+
+    private cloneCodeKey(host: KeeperHost, username: string): string {
+        return `${host}::${username}`
+    }
+
+    public async getCloneCode(host: KeeperHost, username: string): Promise<Nullable<Uint8Array>> {
+        const hostStr = String(host)
+
+        const key = this.cloneCodeKey(host, username)
+        const sessionCode = this.sessionCloneCodes.get(key)
+        if (sessionCode) return sessionCode
+
+        const device = await this.findDeviceInKeeperConfig(username)
+        if (device) {
+            const serverInfo = device.serverInfo.find((entry) => entry.server === hostStr)
+            if (serverInfo) {
+                return normal64Bytes(serverInfo.clone_code)
+            }
+        }
+
+        return null
+    }
+
+    public async saveCloneCode(host: KeeperHost, username: string, cloneCode: Uint8Array): Promise<void> {
+        const key = this.cloneCodeKey(host, username)
+        this.sessionCloneCodes.set(key, cloneCode)
+        await this.updateKeeperConfigCloneCode(String(host), username, cloneCode)
+    }
+
+    private async updateKeeperConfigCloneCode(host: string, username: string, cloneCode: Uint8Array): Promise<void> {
+        try {
+            const parsed = await this.configLoader.load()
+            if (!parsed || Object.keys(parsed).length === 0) return
+
+            let updated = false
+            const encodedCloneCode = Buffer.from(cloneCode).toString('base64url')
+
+            const server = parsed.last_server || parsed.server
+            if (parsed.user?.toLowerCase() === username.toLowerCase() && server === host) {
+                parsed.clone_code = encodedCloneCode
+                updated = true
+            }
+
+            const user = (parsed.users || []).find(
+                (configUser) => configUser.user?.toLowerCase() === username.toLowerCase()
+            )
+            if (user?.last_device?.device_token) {
+                const device = (parsed.devices || []).find(
+                    (configDevice) => configDevice.device_token === user.last_device.device_token
+                )
+                if (device?.server_info) {
+                    const serverInfo = device.server_info.find((entry) => entry.server === host)
+                    if (serverInfo) {
+                        serverInfo.clone_code = encodedCloneCode
+                        updated = true
+                    }
+                }
+            }
+
+            if (updated) {
+                await this.configLoader.save(parsed)
+                this._keeperConfig = null
+                this._deviceCache = null
+            }
+        } catch (err) {
+            logger.warn('Failed to update keeper config clone code:', extractErrorMessage(err))
+        }
+    }
+
+    public async getSessionParameters(): Promise<Nullable<SessionParams>> {
+        return this.sessionParams
+    }
+
+    public async saveSessionParameters(params: Partial<SessionParams>): Promise<void> {
+        this.sessionParams = { ...this.sessionParams, ...params } as SessionParams
+        if (params.username) {
+            this._lastUsername = params.username
+        }
+    }
+
+    public setLastUsername(username: string): void {
+        this._lastUsername = username
+    }
+
+    private async loadKeeperConfig(): Promise<KeeperJsonConfig> {
+        if (this._keeperConfig) return this._keeperConfig
+        this._keeperConfig = await this.configLoader.load()
+        return this._keeperConfig
+    }
+
+    private async findDeviceInKeeperConfig(username: string): Promise<Nullable<ResolvedDevice>> {
+        const normalizedUsername = username.toLowerCase()
+        if (this._deviceCache?.username === normalizedUsername) {
+            return this._deviceCache.device
+        }
+
+        const device = await this.lookupDeviceInKeeperConfig(normalizedUsername)
+        this._deviceCache = { username: normalizedUsername, device }
+        return device
+    }
+
+    private async lookupDeviceInKeeperConfig(normalizedUsername: string): Promise<Nullable<ResolvedDevice>> {
+        const keeperConfig = await this.loadKeeperConfig()
+
+        if (keeperConfig.users && keeperConfig.devices) {
+            const user = keeperConfig.users.find(
+                (configUser) => configUser.user?.toLowerCase() === normalizedUsername
+            )
+            if (user?.last_device?.device_token) {
+                const deviceTokenStr = user.last_device.device_token
+                const device = keeperConfig.devices.find((configDevice) => configDevice.device_token === deviceTokenStr)
+                if (device?.private_key) {
+                    return {
+                        deviceToken: normal64Bytes(deviceTokenStr),
+                        privateKey: normal64Bytes(device.private_key),
+                        serverInfo: (device.server_info || []).filter(
+                            (entry): entry is Required<ConfigurationServerConfig> =>
+                                !!entry.server && !!entry.clone_code
+                        ),
+                    }
+                }
+            }
+        }
+
+        if (
+            keeperConfig.device_token &&
+            keeperConfig.private_key &&
+            keeperConfig.user?.toLowerCase() === normalizedUsername
+        ) {
+            const serverInfo: Array<Required<ConfigurationServerConfig>> = []
+            const server = keeperConfig.last_server || keeperConfig.server
+            if (server && keeperConfig.clone_code) {
+                serverInfo.push({ server, clone_code: keeperConfig.clone_code })
+            }
+            return {
+                deviceToken: normal64Bytes(keeperConfig.device_token),
+                privateKey: normal64Bytes(keeperConfig.private_key),
+                serverInfo,
+            }
+        }
+
+        return null
+    }
+
+    public static isValidKeeperConfig(value: unknown): value is KeeperJsonConfig {
+        if (typeof value !== 'object' || value === null) return false
+        const obj = value as Record<string, unknown>
+        if (obj.users !== undefined && !Array.isArray(obj.users)) return false
+        if (obj.devices !== undefined && !Array.isArray(obj.devices)) return false
+        return true
+    }
+}