@keeper-security/keeper-sdk-javascript 0.1.0

package/src/records/RecordUtils.ts

@@ -0,0 +1,282 @@
+import type { DRecord } from '@keeper-security/keeperapi'
+import { getTotpCode } from './Totp'
+
+enum FieldType {
+    Login = 'login',
+    Password = 'password',
+    Url = 'url',
+    Note = 'note',
+    Text = 'text',
+}
+
+export enum RecordVersion {
+    Legacy = 2,
+    Typed = 3,
+}
+
+const TOTP_FIELD_TYPES = new Set<string>(['totp', 'oneTimeCode', 'otp'])
+const MASKED_VALUE = '********'
+const RECORD_SEPARATOR = '-'.repeat(50)
+
+type RecordField = {
+    type: string
+    value: any[]
+    label?: string
+    required?: boolean
+    privacyScreen?: boolean
+    enforceGeneration?: boolean
+    complexity?: {
+        length?: number
+        caps?: number
+        lowercase?: number
+        digits?: number
+        special?: number
+    }
+}
+
+type LegacyExtraField = {
+    type?: string
+    field_type?: string
+    value?: unknown
+    data?: unknown
+    label?: string
+    field_title?: string
+}
+
+function toFieldValueArray(v: unknown): any[] {
+    if (v == null) return []
+    return Array.isArray(v) ? v : [v]
+}
+
+function getLegacyExtraFields(record: DRecord): RecordField[] {
+    const raw = record.extra
+    if (raw == null) return []
+    let extra: { fields?: LegacyExtraField[] }
+    if (typeof raw === 'string') {
+        try {
+            extra = JSON.parse(raw)
+        } catch {
+            return []
+        }
+    } else if (typeof raw === 'object') {
+        extra = raw
+    } else {
+        return []
+    }
+    if (!Array.isArray(extra.fields)) return []
+    const out: RecordField[] = []
+    for (const f of extra.fields) {
+        const typeName = f.type || f.field_type || FieldType.Text
+        const rawVal = f.value !== undefined && f.value !== null ? f.value : f.data
+        out.push({
+            type: typeName,
+            value: toFieldValueArray(rawVal),
+            label: f.label || f.field_title,
+        })
+    }
+    return out
+}
+
+export function getRecordTitle(record: DRecord): string {
+    if (!record.data) return '(no data)'
+    if (typeof record.data === 'string') {
+        try {
+            const parsed = JSON.parse(record.data)
+            return parsed.title || '(untitled)'
+        } catch {
+            return '(parse error)'
+        }
+    }
+    return record.data.title || '(untitled)'
+}
+
+export function getRecordType(record: DRecord): string {
+    if (record.version <= RecordVersion.Legacy) return 'legacy'
+    if (!record.data) return 'unknown'
+    return record.data.type || 'unknown'
+}
+
+export function getRecordFields(record: DRecord): RecordField[] {
+    if (!record.data) return []
+
+    if (record.version <= RecordVersion.Legacy) {
+        const fields: RecordField[] = []
+        const d = record.data
+        if (d.secret1) fields.push({ type: FieldType.Login, value: [d.secret1] })
+        if (d.secret2) fields.push({ type: FieldType.Password, value: [d.secret2] })
+        if (d.link) fields.push({ type: FieldType.Url, value: [d.link] })
+        if (d.notes) fields.push({ type: FieldType.Note, value: [d.notes] })
+        if (Array.isArray(d.custom)) {
+            for (const c of d.custom) {
+                if (!c) continue
+                fields.push({
+                    type: c.type || FieldType.Text,
+                    value: c.value != null && c.value !== '' ? [c.value] : [],
+                    label: c.name,
+                })
+            }
+        }
+        const extraFields = getLegacyExtraFields(record)
+        fields.push(...extraFields)
+        return fields
+    }
+
+    const fields: RecordField[] = []
+    if (Array.isArray(record.data.fields)) {
+        for (const f of record.data.fields) {
+            fields.push({
+                type: f.type || FieldType.Text,
+                value: Array.isArray(f.value) ? f.value : [f.value],
+                label: f.label,
+                required: f.required,
+                privacyScreen: f.privacyScreen,
+                enforceGeneration: f.enforceGeneration,
+                complexity: f.complexity,
+            })
+        }
+    }
+    if (Array.isArray(record.data.custom)) {
+        for (const f of record.data.custom) {
+            fields.push({
+                type: f.type || FieldType.Text,
+                value: Array.isArray(f.value) ? f.value : [f.value],
+                label: f.label,
+                required: f.required,
+                privacyScreen: f.privacyScreen,
+                enforceGeneration: f.enforceGeneration,
+                complexity: f.complexity,
+            })
+        }
+    }
+    return fields
+}
+
+export type RecordSummary = {
+    login?: string
+    password?: string
+    url?: string
+    fields: RecordField[]
+}
+
+export function getRecordSummary(record: DRecord): RecordSummary {
+    const fields = getRecordFields(record)
+    if (record.version <= RecordVersion.Legacy) {
+        return {
+            login: record.data?.secret1,
+            password: record.data?.secret2,
+            url: record.data?.link,
+            fields,
+        }
+    }
+
+    let login: string | undefined
+    let password: string | undefined
+    let url: string | undefined
+
+    for (const f of fields) {
+        if (!login && f.type === FieldType.Login && f.value.length > 0) {
+            login = String(f.value[0])
+        } else if (!password && f.type === FieldType.Password && f.value.length > 0) {
+            password = String(f.value[0])
+        } else if (!url && f.type === FieldType.Url && f.value.length > 0) {
+            const val = f.value[0]
+            url = typeof val === 'string' ? val : val?.value || val?.url
+        }
+    }
+
+    return { login, password, url, fields }
+}
+
+export function getRecordTotpUrl(record: DRecord): string | undefined {
+    for (const field of getRecordFields(record)) {
+        if (!TOTP_FIELD_TYPES.has(field.type)) continue
+        for (const v of field.value) {
+            if (typeof v === 'string' && v.trim()) return v.trim()
+        }
+    }
+    return undefined
+}
+
+export function getRecordPassword(record: DRecord): string | undefined {
+    return getRecordSummary(record).password
+}
+
+export function getRecordLogin(record: DRecord): string | undefined {
+    return getRecordSummary(record).login
+}
+
+export function getRecordUrl(record: DRecord): string | undefined {
+    return getRecordSummary(record).url
+}
+
+const wordCache = new WeakMap<DRecord, string[]>()
+
+export function searchRecords(records: DRecord[], criteria: string): DRecord[] {
+    if (!criteria.trim()) return records
+
+    const searchWords = criteria.toLowerCase().split(/\s+/)
+
+    return records.filter((record) => {
+        let words = wordCache.get(record)
+        if (!words) {
+            words = collectRecordWords(record)
+            wordCache.set(record, words)
+        }
+        return searchWords.every((sw) => words!.some((w) => w.includes(sw)))
+    })
+}
+
+function collectRecordWords(record: DRecord): string[] {
+    const words: string[] = []
+    const title = getRecordTitle(record)
+    if (title) words.push(...title.toLowerCase().split(/\s+/))
+
+    for (const field of getRecordFields(record)) {
+        if (field.label) words.push(field.label.toLowerCase())
+        for (const v of field.value) {
+            if (typeof v === 'string') {
+                words.push(...v.toLowerCase().split(/\s+/))
+            } else if (v && typeof v === 'object') {
+                for (const val of Object.values(v)) {
+                    if (typeof val === 'string') {
+                        words.push(...val.toLowerCase().split(/\s+/))
+                    }
+                }
+            }
+        }
+    }
+
+    words.push(record.uid)
+    return words
+}
+
+export function formatRecord(record: DRecord, showDetails = false): string {
+    const summary = getRecordSummary(record)
+    const lines: string[] = [
+        RECORD_SEPARATOR,
+        `Title: ${getRecordTitle(record)}`,
+        `Record UID: ${record.uid}`,
+        `Record Type: ${getRecordType(record)}`,
+    ]
+
+    if (summary.login) lines.push(`Username: ${summary.login}`)
+    if (summary.url) lines.push(`URL: ${summary.url}`)
+
+    if (showDetails) {
+        for (const field of summary.fields) {
+            if (field.type === FieldType.Login || field.type === FieldType.Url) continue
+            const isTotp = TOTP_FIELD_TYPES.has(field.type)
+            const isSensitive = field.type === FieldType.Password || isTotp
+            const label = isTotp ? 'TOTP URL' : field.label || field.type
+            lines.push(`${label}: ${isSensitive ? MASKED_VALUE : field.value.join(', ')}`)
+        }
+
+        const totpUrl = getRecordTotpUrl(record)
+        const code = totpUrl ? getTotpCode(totpUrl) : null
+        if (code) {
+            lines.push(`Two Factor Code: ${code.code}    valid for ${code.secondsRemaining} sec`)
+        }
+    }
+
+    return lines.join('\n')
+}

package/src/records/Totp.ts

@@ -0,0 +1,119 @@
+import { createHmac } from 'crypto'
+
+export type TotpAlgorithm = 'SHA1' | 'SHA256' | 'SHA512'
+
+export type TotpParams = {
+    secret: string
+    algorithm: TotpAlgorithm
+    digits: number
+    period: number
+}
+
+export type TotpCode = {
+    code: string
+    secondsRemaining: number
+    period: number
+}
+
+const BASE32_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567'
+const DEFAULT_DIGITS = 6
+const DEFAULT_PERIOD = 30
+const DEFAULT_ALGORITHM: TotpAlgorithm = 'SHA1'
+const UINT32_MAX = 0x100000000
+
+function decodeBase32(input: string): Uint8Array {
+    const noWhitespace = input.replace(/\s+/g, '')
+    let endIndex = noWhitespace.length
+    while (endIndex > 0 && noWhitespace.charCodeAt(endIndex - 1) === 0x3d) endIndex--
+    const cleaned = noWhitespace.slice(0, endIndex).toUpperCase()
+    const out: number[] = []
+    let buffer = 0
+    let bits = 0
+    for (const ch of cleaned) {
+        const idx = BASE32_ALPHABET.indexOf(ch)
+        if (idx < 0) throw new Error(`Invalid base32 character "${ch}" in TOTP secret`)
+        buffer = (buffer << 5) | idx
+        bits += 5
+        if (bits >= 8) {
+            bits -= 8
+            out.push((buffer >> bits) & 0xff)
+        }
+    }
+    return Uint8Array.from(out)
+}
+
+function normalizeAlgorithm(value: string | null | undefined): TotpAlgorithm {
+    const upper = (value || DEFAULT_ALGORITHM).toUpperCase()
+    return upper === 'SHA256' || upper === 'SHA512' ? upper : DEFAULT_ALGORITHM
+}
+
+function parsePositiveInt(value: string | null, fallback: number): number {
+    const parsed = parseInt(value || '', 10)
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback
+}
+
+export function parseTotpUrl(url: string): TotpParams | null {
+    if (!url?.trim()) return null
+    let params: URLSearchParams
+    try {
+        if (url.startsWith('otpauth://')) {
+            const u = new URL(url)
+            if (u.hostname.toLowerCase() !== 'totp') return null
+            params = u.searchParams
+        } else {
+            params = new URLSearchParams(url)
+        }
+    } catch {
+        return null
+    }
+    const secret = (params.get('secret') || '').trim()
+    if (!secret) return null
+    return {
+        secret,
+        algorithm: normalizeAlgorithm(params.get('algorithm')),
+        digits: parsePositiveInt(params.get('digits'), DEFAULT_DIGITS),
+        period: parsePositiveInt(params.get('period'), DEFAULT_PERIOD),
+    }
+}
+
+function counterToBuffer(counter: number): Buffer {
+    const buf = Buffer.alloc(8)
+    buf.writeUInt32BE(Math.floor(counter / UINT32_MAX), 0)
+    buf.writeUInt32BE(counter % UINT32_MAX, 4)
+    return buf
+}
+
+export function getTotpCode(urlOrParams: string | TotpParams, now: number = Date.now()): TotpCode | null {
+    const params = typeof urlOrParams === 'string' ? parseTotpUrl(urlOrParams) : urlOrParams
+    if (!params) return null
+    if (!Number.isFinite(params.period) || params.period <= 0) return null
+    if (!Number.isFinite(params.digits) || params.digits <= 0) return null
+
+    let key: Uint8Array
+    try {
+        key = decodeBase32(params.secret)
+    } catch {
+        return null
+    }
+    if (key.length === 0) return null
+
+    const seconds = Math.floor(now / 1000)
+    const counter = Math.floor(seconds / params.period)
+    const secondsRemaining = params.period - (seconds % params.period)
+
+    const digest = createHmac(params.algorithm.toLowerCase(), Buffer.from(key))
+        .update(counterToBuffer(counter))
+        .digest()
+
+    if (digest.length === 0) return null
+    const offset = digest[digest.length - 1] & 0x0f
+    if (offset + 3 >= digest.length) return null
+    const binary =
+        ((digest[offset] & 0x7f) << 24) |
+        ((digest[offset + 1] & 0xff) << 16) |
+        ((digest[offset + 2] & 0xff) << 8) |
+        (digest[offset + 3] & 0xff)
+
+    const code = (binary % 10 ** params.digits).toString().padStart(params.digits, '0')
+    return { code, secondsRemaining, period: params.period }
+}

package/src/sharedFolders/SharedFolderManager.ts

@@ -0,0 +1,57 @@
+import type { Auth } from '@keeper-security/keeperapi'
+import { InMemoryStorage } from '../storage/InMemoryStorage'
+import { KeeperSdkError, ResultCodes } from '../utils'
+import {
+    formatSharedFoldersTable,
+    listSharedFolders,
+    renderSharedFoldersAsciiTable,
+} from './listSharedFolders'
+import type {
+    FormattedSharedFoldersTable,
+    ListSharedFolderRow,
+    ListSharedFoldersOptions,
+} from './listSharedFolders'
+import { shareFolder } from './shareFolder'
+import type { ShareFolderInput, ShareFolderResult } from './shareFolder'
+
+export type AuthProvider = () => Auth
+
+export class SharedFolderManager {
+    private readonly storage: InMemoryStorage
+    private readonly authProvider: AuthProvider
+
+    constructor(storage: InMemoryStorage, authProvider: AuthProvider) {
+        this.storage = storage
+        this.authProvider = authProvider
+    }
+
+    private requireAuth(): Auth {
+        const auth = this.authProvider()
+        if (!auth) {
+            throw new KeeperSdkError('Not logged in. Call login() first.', ResultCodes.NOT_LOGGED_IN)
+        }
+        return auth
+    }
+
+    public listSharedFolders(options: ListSharedFoldersOptions = {}): ListSharedFolderRow[] {
+        return listSharedFolders(this.storage, options)
+    }
+
+    public formatSharedFoldersTable(
+        rows: ListSharedFolderRow[],
+        options: { verbose?: boolean; columnWidth?: number } = {}
+    ): FormattedSharedFoldersTable {
+        return formatSharedFoldersTable(rows, options)
+    }
+
+    public renderSharedFoldersAsciiTable(
+        table: FormattedSharedFoldersTable,
+        options: { minColWidth?: number } = {}
+    ): string {
+        return renderSharedFoldersAsciiTable(table, options)
+    }
+
+    public async shareFolder(input: ShareFolderInput): Promise<ShareFolderResult> {
+        return shareFolder(this.requireAuth(), this.storage, input)
+    }
+}

package/src/sharedFolders/listSharedFolders.ts

@@ -0,0 +1,173 @@
+import type {
+    DSharedFolder,
+    DSharedFolderRecord,
+    DSharedFolderTeam,
+    DSharedFolderUser,
+} from '@keeper-security/keeperapi'
+import { InMemoryStorage } from '../storage/InMemoryStorage'
+import { TOKEN_SEPARATOR_PATTERN } from '../utils'
+import { FolderKind, VaultObjectKind } from '../folders/folderHelpers'
+
+export type ListSharedFoldersOptions = {
+    pattern?: string | null
+    verbose?: boolean
+    includeDetails?: boolean
+}
+
+export type ListSharedFolderRow = {
+    shared_folder_uid: string
+    name: string
+    team_count?: number
+    user_count?: number
+    record_count?: number
+    default_manage_records?: boolean
+    default_manage_users?: boolean
+    default_can_edit?: boolean
+    default_can_share?: boolean
+}
+
+const DEFAULT_COLUMN_WIDTH = 40
+const MIN_TRUNCATE_PREFIX = 3
+
+function sharedFolderDisplayName(folder: DSharedFolder): string {
+    return (folder.name || folder.uid).trim() || folder.uid
+}
+
+function findSharedFolders(storage: InMemoryStorage, pattern: string): DSharedFolder[] {
+    const searchWords = tokenize(pattern.toLowerCase())
+    const matches: DSharedFolder[] = []
+    for (const sharedFolder of storage.getAll<DSharedFolder>(FolderKind.SharedFolder)) {
+        const uid = sharedFolder.uid
+        const name = sharedFolderDisplayName(sharedFolder).toLowerCase()
+        const entityWords = tokenize(`${uid} ${name}`)
+        if (matchEntity(entityWords, searchWords)) {
+            matches.push(sharedFolder)
+        }
+    }
+    return matches
+}
+
+function matchEntity(entityWords: string[], searchWords: string[]): boolean {
+    if (!searchWords || searchWords.length === 0) return true
+    if (!entityWords || entityWords.length === 0) return false
+    for (const entityWord of entityWords) {
+        for (const searchWord of searchWords) {
+            if (searchWord.length <= entityWord.length && entityWord.includes(searchWord)) {
+                return true
+            }
+        }
+    }
+    return false
+}
+
+function tokenize(text: string): string[] {
+    return text.split(TOKEN_SEPARATOR_PATTERN).filter((token) => token.length > 0)
+}
+
+function countBySharedFolderUid<T extends { sharedFolderUid: string }>(items: T[], sharedFolderUid: string): number {
+    let count = 0
+    for (const item of items) {
+        if (item.sharedFolderUid === sharedFolderUid) count += 1
+    }
+    return count
+}
+
+function countTeamsForFolder(storage: InMemoryStorage, sharedFolderUid: string): number {
+    return countBySharedFolderUid(storage.getAll<DSharedFolderTeam>(VaultObjectKind.SharedFolderTeam), sharedFolderUid)
+}
+
+function countUsersForFolder(storage: InMemoryStorage, sharedFolderUid: string): number {
+    return countBySharedFolderUid(storage.getAll<DSharedFolderUser>(VaultObjectKind.SharedFolderUser), sharedFolderUid)
+}
+
+function countRecordsForFolder(storage: InMemoryStorage, sharedFolderUid: string): number {
+    return countBySharedFolderUid(
+        storage.getAll<DSharedFolderRecord>(VaultObjectKind.SharedFolderRecord),
+        sharedFolderUid
+    )
+}
+
+export function listSharedFolders(
+    storage: InMemoryStorage,
+    options: ListSharedFoldersOptions = {}
+): ListSharedFolderRow[] {
+    const { pattern, includeDetails = false } = options
+    const sharedFolders: DSharedFolder[] = pattern
+        ? findSharedFolders(storage, pattern)
+        : storage.getAll<DSharedFolder>(FolderKind.SharedFolder)
+
+    return sharedFolders.map((sharedFolder) => {
+        const shared_folder_uid = sharedFolder.uid
+        const name = sharedFolderDisplayName(sharedFolder)
+        const row: ListSharedFolderRow = { shared_folder_uid, name }
+        if (includeDetails) {
+            row.record_count = countRecordsForFolder(storage, shared_folder_uid)
+            row.user_count = countUsersForFolder(storage, shared_folder_uid)
+            row.team_count = countTeamsForFolder(storage, shared_folder_uid)
+            row.default_manage_records = sharedFolder.defaultManageRecords
+            row.default_manage_users = sharedFolder.defaultManageUsers
+            row.default_can_edit = sharedFolder.defaultCanEdit
+            row.default_can_share = sharedFolder.defaultCanShare
+        }
+        return row
+    })
+}
+
+export type FormattedSharedFoldersTable = {
+    headers: string[]
+    rows: string[][]
+}
+
+function truncateText(text: string, maxLength: number): string {
+    if (!text) return ''
+    if (text.length <= maxLength) return text
+    if (maxLength <= MIN_TRUNCATE_PREFIX) return text.slice(0, maxLength)
+    return `${text.slice(0, maxLength - MIN_TRUNCATE_PREFIX)}...`
+}
+
+export function formatSharedFoldersTable(
+    rows: ListSharedFolderRow[],
+    options: { verbose?: boolean; columnWidth?: number } = {}
+): FormattedSharedFoldersTable {
+    const { verbose = false, columnWidth = DEFAULT_COLUMN_WIDTH } = options
+    const maxWidth = verbose ? null : columnWidth
+    const headers = ['#', 'Shared Folder UID', 'Name']
+    const outRows: string[][] = rows.map((row, rowIndex) => {
+        const uid = maxWidth == null ? row.shared_folder_uid : truncateText(row.shared_folder_uid, maxWidth)
+        const name = maxWidth == null ? row.name : truncateText(row.name, maxWidth)
+        return [String(rowIndex + 1), uid, name]
+    })
+    return { headers, rows: outRows }
+}
+
+export function renderSharedFoldersAsciiTable(
+    table: FormattedSharedFoldersTable,
+    options: { minColWidth?: number } = {}
+): string {
+    const { minColWidth = 2 } = options
+    const { headers, rows } = table
+    const columnCount = headers.length
+    const columnWidths: number[] = new Array(columnCount).fill(0)
+    for (let columnIndex = 0; columnIndex < columnCount; columnIndex += 1) {
+        columnWidths[columnIndex] = Math.max(headers[columnIndex].length, minColWidth)
+    }
+    for (const row of rows) {
+        for (let columnIndex = 0; columnIndex < columnCount; columnIndex += 1) {
+            const cell = row[columnIndex] || ''
+            columnWidths[columnIndex] = Math.max(columnWidths[columnIndex], cell.length, minColWidth)
+        }
+    }
+    const padCell = (cell: string, columnIndex: number) =>
+        cell + ' '.repeat(columnWidths[columnIndex] - cell.length)
+    const formatRow = (cells: string[]) => cells.map((cell, columnIndex) => padCell(cell, columnIndex)).join('  ')
+    const ruleRow = Array.from({ length: columnCount }, (_unused, columnIndex) =>
+        '-'.repeat(columnWidths[columnIndex])
+    )
+        .map((dashes, columnIndex) => padCell(dashes, columnIndex))
+        .join('  ')
+    const lines: string[] = [formatRow(headers), ruleRow]
+    for (const row of rows) {
+        lines.push(formatRow(row))
+    }
+    return lines.join('\n')
+}