@keeper-security/keeper-sdk-javascript 0.1.0

package/src/folders/FolderManager.ts

@@ -0,0 +1,174 @@
+import type { Auth } from '@keeper-security/keeperapi'
+import { InMemoryStorage } from '../storage/InMemoryStorage'
+import { KeeperSdkError, ResultCodes } from '../utils'
+import { addFolder, mkdir } from './addFolder'
+import type { AddFolderInput, AddFolderResult, MkdirOptions } from './addFolder'
+import {
+    changeDirectory,
+    createVaultFolderSession,
+    findParentFolderUid,
+    getWorkingFolderDisplayName,
+    resolveSingleFolder,
+    splitPathComponents,
+    tryResolvePath,
+} from './changeDirectory'
+import type { ChangeDirectoryResult, TryResolvePathResult, VaultFolderSession } from './changeDirectory'
+import { buildFolderDeleteObject, deleteFolder, resolveRmdirPatternsToFolderUids, rmdir } from './deleteFolder'
+import type { DeleteFolderResult, RmdirOptions } from './deleteFolder'
+import { buildFolderTree, folderTreeAscii, renderFolderTreeAscii } from './folderTree'
+import type { FolderTreeBuildOptions, FolderTreeResult } from './folderTree'
+import { findFolder, getFolder } from './getFolder'
+import type { FoundFolder, GetFolderOptions, GetFolderResult } from './getFolder'
+import { findFolderUidByNameOrUid, listFolder, listRootUserFolders, listVaultRootFolders } from './listFolder'
+import type { ListFolderFolderSimple, ListFolderOptions, ListFolderResult } from './listFolder'
+import { renameFolder, updateFolder, updateSharedFolderPermissions } from './updateFolder'
+import type { RenameFolderResult, UpdateFolderInput, UpdateFolderResult } from './updateFolder'
+
+export type AuthProvider = () => Auth
+
+export type SharedFolderPermissionsInput = {
+    manageUsers?: boolean | null
+    manageRecords?: boolean | null
+    canShare?: boolean | null
+    canEdit?: boolean | null
+}
+
+export class FolderManager {
+    private readonly storage: InMemoryStorage
+    private readonly session: VaultFolderSession
+    private readonly authProvider: AuthProvider
+
+    constructor(storage: InMemoryStorage, session: VaultFolderSession, authProvider: AuthProvider) {
+        this.storage = storage
+        this.session = session
+        this.authProvider = authProvider
+    }
+
+    public static createSession(): VaultFolderSession {
+        return createVaultFolderSession()
+    }
+
+    public static splitPathComponents(path: string): string[] {
+        return splitPathComponents(path)
+    }
+
+    public getSession(): VaultFolderSession {
+        return this.session
+    }
+
+    public getCurrentFolderUid(): string | null {
+        return this.session.currentFolderUid
+    }
+
+    public getWorkingFolderDisplayName(): string {
+        return getWorkingFolderDisplayName(this.storage, this.session.currentFolderUid)
+    }
+
+    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 async listFolder(options: ListFolderOptions = {}): Promise<ListFolderResult> {
+        return listFolder(this.storage, options)
+    }
+
+    public listRootUserFolders() {
+        return listRootUserFolders(this.storage)
+    }
+
+    public async listVaultRootFolders(): Promise<{
+        rows: ListFolderFolderSimple[]
+        promotedRootSharedUids: Set<string>
+    }> {
+        return listVaultRootFolders(this.storage)
+    }
+
+    public findFolderUidByNameOrUid(nameOrUid: string): string | undefined {
+        return findFolderUidByNameOrUid(this.storage, nameOrUid)
+    }
+
+    public findFolder(nameOrUid: string): FoundFolder | undefined {
+        return findFolder(this.storage, nameOrUid)
+    }
+
+    public async findParentFolderUid(folderUid: string): Promise<string | null> {
+        return findParentFolderUid(this.storage, folderUid)
+    }
+
+    public async getFolder(uidOrName: string, options: GetFolderOptions = {}): Promise<GetFolderResult> {
+        return getFolder(this.storage, uidOrName, options)
+    }
+
+    public async changeDirectory(path: string): Promise<ChangeDirectoryResult> {
+        return changeDirectory(this.storage, this.session, path)
+    }
+
+    public async tryResolvePath(path: string): Promise<TryResolvePathResult> {
+        return tryResolvePath(this.storage, this.session, path)
+    }
+
+    public async resolveSingleFolder(folderName: string): Promise<ChangeDirectoryResult> {
+        return resolveSingleFolder(this.storage, this.session, folderName)
+    }
+
+    public async addFolder(input: AddFolderInput): Promise<AddFolderResult> {
+        return addFolder(this.requireAuth(), this.storage, input)
+    }
+
+    public async mkdir(
+        path: string,
+        options: MkdirOptions = {}
+    ): Promise<{ folderUid: string; success: boolean; message?: string }> {
+        return mkdir(this.requireAuth(), this.storage, this.session, path, options)
+    }
+
+    public async updateFolder(input: UpdateFolderInput): Promise<UpdateFolderResult> {
+        return updateFolder(this.requireAuth(), this.storage, input)
+    }
+
+    public async renameFolder(folderPath: string, newName: string): Promise<RenameFolderResult> {
+        return renameFolder(this.requireAuth(), this.storage, this.session, folderPath, newName)
+    }
+
+    public async updateSharedFolderPermissions(
+        sharedFolderUid: string,
+        permissions: SharedFolderPermissionsInput
+    ): Promise<UpdateFolderResult> {
+        return updateSharedFolderPermissions(this.requireAuth(), this.storage, sharedFolderUid, permissions)
+    }
+
+    public async deleteFolder(
+        folderRefs: string[],
+        confirm?: (summary: string) => boolean | Promise<boolean>
+    ): Promise<DeleteFolderResult> {
+        return deleteFolder(this.requireAuth(), this.storage, folderRefs, confirm)
+    }
+
+    public async rmdir(patterns: string[], options: RmdirOptions = {}): Promise<DeleteFolderResult> {
+        return rmdir(this.requireAuth(), this.storage, this.session, patterns, options)
+    }
+
+    public async resolveRmdirPatternsToFolderUids(pattern: string): Promise<Set<string>> {
+        return resolveRmdirPatternsToFolderUids(this.storage, this.session, pattern)
+    }
+
+    public async buildFolderDeleteObject(folderUid: string) {
+        return buildFolderDeleteObject(this.storage, folderUid)
+    }
+
+    public async buildFolderTree(options: FolderTreeBuildOptions = {}): Promise<FolderTreeResult> {
+        return buildFolderTree(this.storage, this.session, options)
+    }
+
+    public async folderTreeAscii(options: FolderTreeBuildOptions = {}): Promise<string> {
+        return folderTreeAscii(this.storage, this.session, options)
+    }
+
+    public renderFolderTreeAscii(tree: FolderTreeResult): string {
+        return renderFolderTreeAscii(tree)
+    }
+}

package/src/folders/addFolder.ts

@@ -0,0 +1,294 @@
+import type { Auth, FolderAddRequest } from '@keeper-security/keeperapi'
+import {
+    encryptForStorage,
+    encryptObjectForStorage,
+    folderAddCommand,
+    generateEncryptionKey,
+    generateUid,
+    platform,
+} from '@keeper-security/keeperapi'
+import type { DSharedFolder, DSharedFolderFolder, DUserFolder } from '@keeper-security/keeperapi'
+import { InMemoryStorage } from '../storage/InMemoryStorage'
+import { isBoolean, KeeperSdkError, extractErrorMessage } from '../utils'
+import { listFolder } from './listFolder'
+import { tryResolvePath, splitPathComponents, type VaultFolderSession } from './changeDirectory'
+import { FolderKind, FolderResultStatus, ParentFolderKind } from './folderHelpers'
+
+type NewFolderKind = FolderKind
+
+export type AddFolderInput = {
+    folderName: string
+    isSharedFolder?: boolean
+    parentUid?: string | null
+    manageUsers?: boolean
+    manageRecords?: boolean
+    canShare?: boolean
+    canEdit?: boolean
+}
+
+export type AddFolderResult = {
+    folderUid: string
+    success: boolean
+    message?: string
+}
+
+export type MkdirOptions = {
+    sharedFolder?: boolean
+    userFolder?: boolean
+    grantAll?: boolean
+    manageUsers?: boolean
+    manageRecords?: boolean
+    canShare?: boolean
+    canEdit?: boolean
+}
+
+type ParentContext = {
+    kind: ParentFolderKind
+    sharedScopeUid: string | null
+}
+
+function resolveParentContext(storage: InMemoryStorage, parentUid: string | null): ParentContext {
+    if (parentUid === null || parentUid === '') {
+        return { kind: ParentFolderKind.VirtualRoot, sharedScopeUid: null }
+    }
+    if (storage.getByUid<DUserFolder>(FolderKind.UserFolder, parentUid)) {
+        return { kind: ParentFolderKind.UserFolder, sharedScopeUid: null }
+    }
+    const sharedFolder = storage.getByUid<DSharedFolder>(FolderKind.SharedFolder, parentUid)
+    if (sharedFolder) {
+        return { kind: ParentFolderKind.SharedFolder, sharedScopeUid: sharedFolder.uid }
+    }
+    const sharedFolderFolder = storage.getByUid<DSharedFolderFolder>(FolderKind.SharedFolderFolder, parentUid)
+    if (sharedFolderFolder) {
+        return {
+            kind: ParentFolderKind.SharedFolderFolder,
+            sharedScopeUid: sharedFolderFolder.sharedFolderUid,
+        }
+    }
+    throw new KeeperSdkError(`Parent folder "${parentUid}" not found`, 'folder_not_found')
+}
+
+function decideNewFolderType(parent: ParentContext, isSharedFolder: boolean): NewFolderKind {
+    if (isSharedFolder) {
+        if (parent.kind !== ParentFolderKind.UserFolder && parent.kind !== ParentFolderKind.VirtualRoot) {
+            throw new KeeperSdkError(
+                'Shared folders cannot be nested inside other shared folders.',
+                'shared_folder_nested'
+            )
+        }
+        return FolderKind.SharedFolder
+    }
+    if (parent.kind === ParentFolderKind.VirtualRoot || parent.kind === ParentFolderKind.UserFolder) {
+        return FolderKind.UserFolder
+    }
+    return FolderKind.SharedFolderFolder
+}
+
+async function getEncryptionKeyForNewFolder(
+    auth: Auth,
+    storage: InMemoryStorage,
+    folderType: NewFolderKind,
+    sharedScopeUid: string | null
+): Promise<Uint8Array> {
+    if (folderType === FolderKind.SharedFolderFolder) {
+        if (!sharedScopeUid) {
+            throw new KeeperSdkError('Shared folder scope could not be resolved.', 'shared_folder_scope_missing')
+        }
+        const sharedFolderKey = await storage.getKeyBytes(sharedScopeUid)
+        if (!sharedFolderKey) {
+            throw new KeeperSdkError(
+                'Shared folder encryption key not available. Sync the vault and try again.',
+                'shared_folder_key_missing'
+            )
+        }
+        return sharedFolderKey
+    }
+    if (!auth.dataKey) {
+        throw new KeeperSdkError('Data key not available. Ensure you are logged in.', 'data_key_missing')
+    }
+    return auth.dataKey
+}
+
+async function findChildFolderUidByName(
+    storage: InMemoryStorage,
+    parentUid: string | null,
+    name: string
+): Promise<string | undefined> {
+    const result = await listFolder(storage, {
+        folderUid: parentUid === null ? undefined : parentUid,
+        showFolders: true,
+        showRecords: false,
+    })
+    const trimmedName = name.trim()
+    const lowerName = trimmedName.toLowerCase()
+    for (const folder of result.folders) {
+        if (folder.uid === trimmedName) return folder.uid
+        if (folder.name.trim() === trimmedName) return folder.uid
+        if (folder.name.trim().toLowerCase() === lowerName) return folder.uid
+    }
+    return undefined
+}
+
+export async function addFolder(auth: Auth, storage: InMemoryStorage, input: AddFolderInput): Promise<AddFolderResult> {
+    const name = input.folderName?.trim()
+    if (!name) {
+        throw new KeeperSdkError('Folder name cannot be empty.', 'folder_name_required')
+    }
+
+    const parentUid = input.parentUid === undefined || input.parentUid === '' ? null : input.parentUid
+    const parent = resolveParentContext(storage, parentUid)
+
+    const isShared = input.isSharedFolder === true
+    const folderType = decideNewFolderType(parent, isShared)
+
+    const folderUid = generateUid()
+    const folderKey = generateEncryptionKey()
+
+    const sharedScope = folderType === FolderKind.SharedFolderFolder ? parent.sharedScopeUid : null
+
+    const encryptionKey = await getEncryptionKeyForNewFolder(auth, storage, folderType, sharedScope)
+
+    const request: FolderAddRequest = {
+        folder_uid: folderUid,
+        folder_type: folderType,
+        key: await encryptForStorage(folderKey, encryptionKey),
+        data: await encryptObjectForStorage({ name, title: name }, folderKey),
+        link: false,
+    }
+
+    if (parentUid) {
+        request.parent_uid = parentUid
+    }
+    if (folderType === FolderKind.SharedFolderFolder && sharedScope) {
+        request.shared_folder_uid = sharedScope
+    }
+
+    if (folderType === FolderKind.SharedFolder) {
+        request.name = await encryptForStorage(platform.stringToBytes(name), folderKey)
+        request.manage_users = isBoolean(input.manageUsers) ? input.manageUsers : false
+        request.manage_records = isBoolean(input.manageRecords) ? input.manageRecords : false
+        request.can_edit = isBoolean(input.canEdit) ? input.canEdit : false
+        request.can_share = isBoolean(input.canShare) ? input.canShare : false
+    }
+
+    try {
+        const response = await auth.executeRestCommand(folderAddCommand(request))
+        const succeeded =
+            response.result === FolderResultStatus.Success || response.result_code === FolderResultStatus.Success
+        if (!succeeded) {
+            const reason =
+                response.message ||
+                response.result_code ||
+                `folder_add failed for "${name}" (uid=${folderUid}, type=${folderType}): server returned no message or result_code`
+            return {
+                folderUid,
+                success: false,
+                message: reason,
+            }
+        }
+        return { folderUid, success: true }
+    } catch (err) {
+        return {
+            folderUid,
+            success: false,
+            message: `folder_add failed for "${name}" (uid=${folderUid}, type=${folderType}): ${extractErrorMessage(err)}`,
+        }
+    }
+}
+
+export async function mkdir(
+    auth: Auth,
+    storage: InMemoryStorage,
+    session: VaultFolderSession,
+    path: string,
+    options: MkdirOptions = {}
+): Promise<{ folderUid: string; success: boolean; message?: string }> {
+    const trimmed = path.trim()
+    if (!trimmed) {
+        throw new KeeperSdkError('Folder path cannot be empty.', 'folder_path_required')
+    }
+
+    if (options.sharedFolder && options.userFolder) {
+        throw new KeeperSdkError('Use only one of sharedFolder (-sf) or userFolder (-uf).', 'mkdir_flags_conflict')
+    }
+
+    const { folderUid: baseUid, remaining } = await tryResolvePath(storage, session, trimmed)
+    if (!remaining.trim()) {
+        throw new KeeperSdkError(`Folder "${trimmed}" already exists.`, 'folder_already_exists')
+    }
+
+    const grantAll = options.grantAll === true
+    let manageUsers = isBoolean(options.manageUsers) ? options.manageUsers : false
+    let manageRecords = isBoolean(options.manageRecords) ? options.manageRecords : false
+    let canShare = isBoolean(options.canShare) ? options.canShare : false
+    let canEdit = isBoolean(options.canEdit) ? options.canEdit : false
+    if (grantAll) {
+        manageUsers = true
+        manageRecords = true
+        canShare = true
+        canEdit = true
+    }
+
+    const segments = splitPathComponents(remaining)
+        .map((segment) => segment.trim())
+        .filter((segment) => segment !== '' && segment !== '.')
+
+    if (segments.length === 0) {
+        throw new KeeperSdkError(`Folder "${trimmed}" already exists.`, 'folder_already_exists')
+    }
+
+    let currentParent: string | null = baseUid
+    let lastResult: AddFolderResult = {
+        folderUid: '',
+        success: false,
+        message: 'not run',
+    }
+
+    for (let segmentIndex = 0; segmentIndex < segments.length; segmentIndex++) {
+        const segment = segments[segmentIndex]
+        const isLastSegment = segmentIndex === segments.length - 1
+        const existingChildUid = await findChildFolderUidByName(storage, currentParent, segment)
+        if (existingChildUid) {
+            if (isLastSegment) {
+                throw new KeeperSdkError(`Folder "${segment}" already exists.`, 'folder_already_exists')
+            }
+            currentParent = existingChildUid
+            continue
+        }
+
+        const createAsSharedFolder = isLastSegment && options.sharedFolder === true
+
+        const parentContext = resolveParentContext(storage, currentParent)
+        if (
+            createAsSharedFolder &&
+            parentContext.kind !== ParentFolderKind.UserFolder &&
+            parentContext.kind !== ParentFolderKind.VirtualRoot
+        ) {
+            throw new KeeperSdkError(
+                'Shared folders can only be created under a personal folder.',
+                'shared_folder_invalid_parent'
+            )
+        }
+
+        lastResult = await addFolder(auth, storage, {
+            folderName: segment,
+            parentUid: currentParent,
+            isSharedFolder: createAsSharedFolder,
+            manageUsers: isLastSegment && createAsSharedFolder ? manageUsers : undefined,
+            manageRecords: isLastSegment && createAsSharedFolder ? manageRecords : undefined,
+            canShare: isLastSegment && createAsSharedFolder ? canShare : undefined,
+            canEdit: isLastSegment && createAsSharedFolder ? canEdit : undefined,
+        })
+
+        if (!lastResult.success) {
+            return {
+                folderUid: lastResult.folderUid,
+                success: false,
+                message: lastResult.message,
+            }
+        }
+        currentParent = lastResult.folderUid
+    }
+
+    return { folderUid: lastResult.folderUid, success: true }
+}

package/src/folders/changeDirectory.ts

@@ -0,0 +1,217 @@
+import type { DSharedFolder, DSharedFolderFolder, DUserFolder } from '@keeper-security/keeperapi'
+import { InMemoryStorage } from '../storage/InMemoryStorage'
+import { KeeperSdkError } from '../utils'
+import { listFolder, listRootUserFolders } from './listFolder'
+import type { ListFolderFolderSimple } from './listFolder'
+import { FolderKind, VaultObjectKind, sharedFolderFolderName, sharedFolderName, userFolderName } from './folderHelpers'
+
+const VAULT_ROOT_DISPLAY_NAME = 'My Vault'
+
+const ESCAPED_SEPARATOR_PLACEHOLDER = '\x00'
+
+export type VaultFolderSession = {
+    currentFolderUid: string | null
+}
+
+export type ChangeDirectoryResult = {
+    folderUid: string | null
+    name: string
+}
+
+export function createVaultFolderSession(): VaultFolderSession {
+    return { currentFolderUid: null }
+}
+
+function getFolderEntryByUid(storage: InMemoryStorage, uid: string): ListFolderFolderSimple | undefined {
+    const userFolder = storage.getByUid<DUserFolder>(FolderKind.UserFolder, uid)
+    if (userFolder) {
+        return { uid: userFolder.uid, name: userFolderName(userFolder), folderKind: FolderKind.UserFolder }
+    }
+    const sharedFolder = storage.getByUid<DSharedFolder>(FolderKind.SharedFolder, uid)
+    if (sharedFolder) {
+        return {
+            uid: sharedFolder.uid,
+            name: sharedFolderName(sharedFolder),
+            folderKind: FolderKind.SharedFolder,
+        }
+    }
+    const sharedFolderFolder = storage.getByUid<DSharedFolderFolder>(FolderKind.SharedFolderFolder, uid)
+    if (sharedFolderFolder) {
+        return {
+            uid: sharedFolderFolder.uid,
+            name: sharedFolderFolderName(sharedFolderFolder),
+            folderKind: FolderKind.SharedFolderFolder,
+        }
+    }
+    return undefined
+}
+
+export async function findParentFolderUid(storage: InMemoryStorage, folderUid: string): Promise<string | null> {
+    const rootFolderUids = new Set((await listRootUserFolders(storage)).map((folder) => folder.uid))
+    if (rootFolderUids.has(folderUid)) return null
+
+    const parentKinds = [
+        FolderKind.UserFolder,
+        FolderKind.SharedFolder,
+        FolderKind.SharedFolderFolder,
+        VaultObjectKind.Team,
+    ] as const
+    for (const kind of parentKinds) {
+        for (const candidate of storage.getAll(kind)) {
+            const candidateUid = (candidate as { uid: string }).uid
+            const dependencies = (await storage.getDependencies(candidateUid)) || []
+            for (const dependency of dependencies) {
+                if (dependency.uid !== folderUid) continue
+                if (
+                    dependency.kind === FolderKind.UserFolder ||
+                    dependency.kind === FolderKind.SharedFolder ||
+                    dependency.kind === FolderKind.SharedFolderFolder
+                ) {
+                    return candidateUid
+                }
+            }
+        }
+    }
+
+    return null
+}
+
+async function listFolderChildrenForCd(
+    storage: InMemoryStorage,
+    parentUid: string | null
+): Promise<ListFolderFolderSimple[]> {
+    const result = await listFolder(storage, {
+        folderUid: parentUid === null ? undefined : parentUid,
+        showFolders: true,
+        showRecords: false,
+    })
+    return result.folders
+}
+
+function findChildFolder(
+    children: ListFolderFolderSimple[],
+    component: string
+): ListFolderFolderSimple | undefined {
+    const trimmedComponent = component.trim()
+    if (!trimmedComponent) return undefined
+    const matchByUid = children.find((child) => child.uid === trimmedComponent)
+    if (matchByUid) return matchByUid
+    const exactNameMatch = children.find((child) => child.name.trim() === trimmedComponent)
+    if (exactNameMatch) return exactNameMatch
+    const lowerComponent = trimmedComponent.toLowerCase()
+    return children.find((child) => child.name.trim().toLowerCase() === lowerComponent)
+}
+
+export function splitPathComponents(path: string): string[] {
+    const escaped = path.replace(/\/\//g, ESCAPED_SEPARATOR_PLACEHOLDER)
+    return escaped.split('/').map((segment) => segment.replace(/\x00/g, '/'))
+}
+
+export type TryResolvePathResult = {
+    folderUid: string | null
+    remaining: string
+}
+
+export async function tryResolvePath(
+    storage: InMemoryStorage,
+    session: VaultFolderSession,
+    path: string
+): Promise<TryResolvePathResult> {
+    const trimmed = path.trim()
+    if (!trimmed) {
+        return { folderUid: session.currentFolderUid, remaining: '' }
+    }
+
+    const direct = getFolderEntryByUid(storage, trimmed)
+    if (direct) {
+        return { folderUid: direct.uid, remaining: '' }
+    }
+
+    const absolute = trimmed.startsWith('/') && !trimmed.startsWith('//')
+    const pathToWalk = absolute ? trimmed.slice(1) : trimmed
+    const components = splitPathComponents(pathToWalk)
+
+    let folderUid: string | null = absolute ? null : session.currentFolderUid || null
+
+    if (!absolute && folderUid !== null) {
+        if (!getFolderEntryByUid(storage, folderUid)) {
+            folderUid = null
+        }
+    }
+
+    let componentIndex = 0
+    while (componentIndex < components.length) {
+        const component = components[componentIndex]
+        componentIndex++
+
+        if (component === '' || component === '.') {
+            continue
+        }
+
+        if (component === '..') {
+            if (folderUid === null) {
+                continue
+            }
+            folderUid = await findParentFolderUid(storage, folderUid)
+            continue
+        }
+
+        const children = await listFolderChildrenForCd(storage, folderUid)
+        const match = findChildFolder(children, component)
+        if (match) {
+            folderUid = match.uid
+        } else {
+            const remaining = [component, ...components.slice(componentIndex)].join('/')
+            return { folderUid, remaining }
+        }
+    }
+
+    return { folderUid, remaining: '' }
+}
+
+export async function resolveSingleFolder(
+    storage: InMemoryStorage,
+    session: VaultFolderSession,
+    folderName: string
+): Promise<ChangeDirectoryResult> {
+    const trimmed = folderName.trim()
+    if (!trimmed) {
+        throw new KeeperSdkError('Folder cannot be empty.', 'folder_required')
+    }
+
+    const direct = getFolderEntryByUid(storage, trimmed)
+    if (direct) {
+        return { folderUid: direct.uid, name: direct.name }
+    }
+
+    const { folderUid, remaining } = await tryResolvePath(storage, session, trimmed)
+    if (remaining) {
+        throw new KeeperSdkError(`Folder "${folderName}" not found`, 'folder_not_found')
+    }
+
+    if (folderUid === null) {
+        return { folderUid: null, name: VAULT_ROOT_DISPLAY_NAME }
+    }
+
+    const entry = getFolderEntryByUid(storage, folderUid)
+    if (!entry) {
+        throw new KeeperSdkError(`Folder "${folderName}" not found`, 'folder_not_found')
+    }
+    return { folderUid: entry.uid, name: entry.name }
+}
+
+export async function changeDirectory(
+    storage: InMemoryStorage,
+    session: VaultFolderSession,
+    path: string
+): Promise<ChangeDirectoryResult> {
+    const resolved = await resolveSingleFolder(storage, session, path)
+    session.currentFolderUid = resolved.folderUid
+    return resolved
+}
+
+export function getWorkingFolderDisplayName(storage: InMemoryStorage, currentFolderUid: string | null): string {
+    if (currentFolderUid === null) return VAULT_ROOT_DISPLAY_NAME
+    const entry = getFolderEntryByUid(storage, currentFolderUid)
+    return entry?.name || VAULT_ROOT_DISPLAY_NAME
+}