Bare Docs

bare-directory

Capability based directory access for Bare

Documented against v0.1.0
experimental

bare-directory — Capability based directory access for Bare. It is a native addon.

npm i bare-directory

Usage

const { Directory } = require('bare-directory')

const root = await Directory.open('/srv/data')

const file = await root.openFile('notes.txt', { read: true, write: true, create: true })

await file.write(Buffer.from('hello'))

const images = (await root.openDirectory('images')).restrict(['list', 'lookup', 'read'])

for (const { name, type } of await images.list()) console.log(name, type)

DirectorySync and FileSync provide the same API synchronously. See the API below for the full API and Rights for the available rights.

API

Directory

Directory.close(): void

Close the directory. Operations already in progress finish first, and later ones fail with EBADF. Handles are also closed when garbage collected.

createDirectory(name: string): Promise<void>

Create the directory name. Needs create.

Parameters

ParameterTypeDefaultDescription
namestring——

Directory.open(path: string, opts?: OpenOptions): Promise<Directory>

Open the directory at path. This is the only operation that takes a path, and is meant for whoever hands out the capabilities.

Parameters

ParameterTypeDefaultDescription
pathstring——
opts?OpenOptions——

list(): Promise<Entry[]>

List the entries of the directory. Needs list. Fails with EILSEQ if a name isn't valid UTF-8.

openDirectory(name: string): Promise<Directory>

Open the directory name with the rights of this one. Needs lookup.

Parameters

ParameterTypeDefaultDescription
namestring——

openFile(name: string, opts?: OpenFileOptions): Promise<File>

Open the regular file name. Needs lookup, and the right of the same name for read, write, append, create and truncate. The file gets the rights it was opened for, plus setTimes, and truncate if opened for writing, where this directory has them. Symbolic links fail with ELOOP, and anything that isn't a regular file with EISDIR or ENOTSUP.

Parameters

ParameterTypeDefaultDescription
namestring——
opts?OpenFileOptions——

readLink(name: string): Promise<string>

Read the target of the symbolic link name as text. Needs lookup. Fails with EILSEQ if the target isn't valid UTF-8.

Parameters

ParameterTypeDefaultDescription
namestring——

removeDirectory(name: string): Promise<void>

Remove the empty directory name. Needs remove.

Parameters

ParameterTypeDefaultDescription
namestring——

removeFile(name: string): Promise<void>

Remove the entry name, which must not be a directory. Needs remove.

Parameters

ParameterTypeDefaultDescription
namestring——

Directory.rename

rename(name: string, directory: Directory | DirectorySync, target?: string, opts?: RenameOptions): Promise<void>

Move the entry name to target, defaulting to name, in directory, which may be this one. Needs rename on both directories.

Parameters

ParameterTypeDefaultDescription
namestring——
directoryDirectory | DirectorySync——
target?string——
opts?RenameOptions——

restrict(rights: Right[]): Directory

Get a new handle to the directory with only those rights that this one has.

Parameters

ParameterTypeDefaultDescription
rightsRight[]——

Directory.rights: Right[]

The rights of the directory.

Directory.setTimes(atime: bigint | null, mtime: bigint | null): Promise<void>

Set the access and modification times of the directory, leaving either unchanged if null. Needs setTimes.

Parameters

ParameterTypeDefaultDescription
atimebigint | null——
mtimebigint | null——

stat(name?: string): Promise<Stat>

Get the metadata of the entry name, or of the directory itself if name is omitted. Needs lookup for an entry.

Parameters

ParameterTypeDefaultDescription
name?string——

DirectorySync

DirectorySync.close(): void

Close the directory. Handles are also closed when garbage collected.

createDirectory(name: string): void

Create the directory name. Needs create.

Parameters

ParameterTypeDefaultDescription
namestring——

DirectorySync.open(path: string, opts?: OpenOptions): DirectorySync

Open the directory at path. This is the only operation that takes a path, and is meant for whoever hands out the capabilities.

Parameters

ParameterTypeDefaultDescription
pathstring——
opts?OpenOptions——

list(): Entry[]

List the entries of the directory. Needs list. Fails with EILSEQ if a name isn't valid UTF-8.

openDirectory(name: string): DirectorySync

Open the directory name with the rights of this one. Needs lookup.

Parameters

ParameterTypeDefaultDescription
namestring——

openFile(name: string, opts?: OpenFileOptions): FileSync

Open the regular file name. Needs lookup, and the right of the same name for read, write, append, create and truncate. The file gets the rights it was opened for, plus setTimes, and truncate if opened for writing, where this directory has them. Symbolic links fail with ELOOP, and anything that isn't a regular file with EISDIR or ENOTSUP.

Parameters

ParameterTypeDefaultDescription
namestring——
opts?OpenFileOptions——

readLink(name: string): string

Read the target of the symbolic link name as text. Needs lookup. Fails with EILSEQ if the target isn't valid UTF-8.

Parameters

ParameterTypeDefaultDescription
namestring——

removeDirectory(name: string): void

Remove the empty directory name. Needs remove.

Parameters

ParameterTypeDefaultDescription
namestring——

removeFile(name: string): void

Remove the entry name, which must not be a directory. Needs remove.

Parameters

ParameterTypeDefaultDescription
namestring——

DirectorySync.rename

rename(name: string, directory: Directory | DirectorySync, target?: string, opts?: RenameOptions): void

Move the entry name to target, defaulting to name, in directory, which may be this one. Needs rename on both directories.

Parameters

ParameterTypeDefaultDescription
namestring——
directoryDirectory | DirectorySync——
target?string——
opts?RenameOptions——

restrict(rights: Right[]): DirectorySync

Get a new handle to the directory with only those rights that this one has.

Parameters

ParameterTypeDefaultDescription
rightsRight[]——

DirectorySync.rights: Right[]

The rights of the directory.

DirectorySync.setTimes(atime: bigint | null, mtime: bigint | null): void

Set the access and modification times of the directory, leaving either unchanged if null. Needs setTimes.

Parameters

ParameterTypeDefaultDescription
atimebigint | null——
mtimebigint | null——

stat(name?: string): Stat

Get the metadata of the entry name, or of the directory itself if name is omitted. Needs lookup for an entry.

Parameters

ParameterTypeDefaultDescription
name?string——

File

File.close(): void

Close the file. Operations already in progress finish first, and later ones fail with EBADF. Handles are also closed when garbage collected.

read(buffer: Uint8Array, position?: number): Promise<number>

Read into buffer from position, defaulting to 0, and resolve with the number of bytes read. Needs read.

Parameters

ParameterTypeDefaultDescription
bufferUint8Array——
position?number——

restrict(rights: Right[]): File

Get a new handle to the file with only those rights that this one has.

Parameters

ParameterTypeDefaultDescription
rightsRight[]——

File.rights: Right[]

The rights of the file.

File.setTimes(atime: bigint | null, mtime: bigint | null): Promise<void>

Set the access and modification times of the file, leaving either unchanged if null. Needs setTimes.

Parameters

ParameterTypeDefaultDescription
atimebigint | null——
mtimebigint | null——

stat(): Promise<Stat>

Get the metadata of the file.

sync(): Promise<void>

Flush the file to storage.

truncate(size: number): Promise<void>

Truncate the file to size bytes. Needs truncate.

Parameters

ParameterTypeDefaultDescription
sizenumber——

write(buffer: Uint8Array, position?: number): Promise<number>

Write buffer at position, defaulting to 0, and resolve with the number of bytes written. A file opened only for appending always writes at its end. Needs write or append.

Parameters

ParameterTypeDefaultDescription
bufferUint8Array——
position?number——

FileSync

FileSync.close(): void

Close the file. Handles are also closed when garbage collected.

read(buffer: Uint8Array, position?: number): number

Read into buffer from position, defaulting to 0, and return the number of bytes read. Needs read.

Parameters

ParameterTypeDefaultDescription
bufferUint8Array——
position?number——

restrict(rights: Right[]): FileSync

Get a new handle to the file with only those rights that this one has.

Parameters

ParameterTypeDefaultDescription
rightsRight[]——

FileSync.rights: Right[]

The rights of the file.

FileSync.setTimes(atime: bigint | null, mtime: bigint | null): void

Set the access and modification times of the file, leaving either unchanged if null. Needs setTimes.

Parameters

ParameterTypeDefaultDescription
atimebigint | null——
mtimebigint | null——

stat(): Stat

Get the metadata of the file.

sync(): void

Flush the file to storage.

truncate(size: number): void

Truncate the file to size bytes. Needs truncate.

Parameters

ParameterTypeDefaultDescription
sizenumber——

write(buffer: Uint8Array, position?: number): number

Write buffer at position, defaulting to 0, and return the number of bytes written. A file opened only for appending always writes at its end. Needs write or append.

Parameters

ParameterTypeDefaultDescription
bufferUint8Array——
position?number——

Constants and variables

rights: Right[]

The names of all rights.

Types

type Right = | 'list'
  | 'lookup'
  | 'create'
  | 'remove'
  | 'rename'
  | 'read'
  | 'write'
  | 'append'
  | 'truncate'
  | 'setTimes'

A right of a directory or file handle:

  • list: list the entries of a directory.
  • lookup: open entries, get their metadata, and read symbolic links.
  • create: create files and directories.
  • remove: remove entries, including replacing one by renaming.
  • rename: move entries between directories. Both directories need it.
  • read: read files.
  • write: write files anywhere.
  • append: write files only at their end.
  • truncate: truncate files.
  • setTimes: set the access and modification times.

Operations without the right they need fail with ENOTCAPABLE.

Stat

interface Stat {
  type: 'file' | 'directory' | 'symlink' | 'other'
  size: bigint
  ino: bigint
  nlink: bigint
  atime: bigint
  mtime: bigint
  ctime: bigint
}

The metadata of an entry. Times are in nanoseconds since the Unix epoch.

Entry

interface Entry {
  name: string
  type: Stat['type']
}

An entry of a directory.

Rights

Directory and File run their operations on the thread pool and return promises, except close() and restrict(), which are synchronous, and DirectorySync and FileSync are their synchronous counterparts. Names are single path components, and names and rights are checked before an operation starts.

A handle carries a set of rights. open() takes them from opts.rights and defaults to all of them, openDirectory() passes on the rights of its parent, and restrict() returns a handle with fewer. An operation without the right it needs fails with ENOTCAPABLE. The type comment of Right says remove is needed to replace an entry by renaming, but rename() needs it on the target directory whenever replace is true, even when nothing is replaced.

RightNeeded by
listlist()
lookupopenDirectory(), openFile(), stat(name), and readLink()
createcreateDirectory(), and openFile() with create
removeremoveFile() and removeDirectory(), and rename() on the target directory unless opts.replace is false, even when no entry is replaced
renamerename(), on both directories
readopenFile() with read, then read() on the file
writeopenFile() with write, then write() anywhere in the file
appendopenFile() with append, then write() at the end of the file
truncateopenFile() with truncate, and truncate() on a file opened with write
setTimessetTimes()

A file opened from a directory gets only the rights its open flags ask for, plus setTimes, and truncate when it is opened for writing, each only if the directory has it.

Options

The .d.ts declares these option types without exporting them.

OpenOptions

Options for Directory.open() and DirectorySync.open().

OptionDefaultDescription
rightsAll rightsThe rights of the directory. See Rights.

OpenFileOptions

Options for openFile().

OptionDefaultDescription
readtrue unless write or append is setOpen the file for reading.
writefalseOpen the file for writing anywhere.
appendfalseOpen the file for writing only at its end.
createfalseCreate the file if it doesn't exist.
exclusivefalseFail with EEXIST if the file exists. Without create, fails with EINVAL.
truncatefalseTruncate the file to empty. Without write, fails with EINVAL.

RenameOptions

Options for rename().

OptionDefaultDescription
replacetrueReplace an existing target. With false, an existing target fails with EEXIST. While it is true, rename() needs remove on the target directory, even when no entry is replaced.

Security model

Only opening a directory by path needs ambient authority. It's meant for whoever hands out the capabilities, such as an embedder. Every other operation is relative to an open handle.

  • A name is a single path component. Empty names, ., .., names with / or NUL, and names longer than 255 bytes fail with EINVAL. On Windows, so do names with \ : " * ? < > | or control characters, names ending in a dot or space, and device names like CON, NUL.txt, or COM followed by a superscript digit.
  • Symbolic links are never followed. Opening one fails with ELOOP, and readLink() returns its target as text.
  • Only regular files and directories can be opened. Devices, FIFOs, and sockets fail with ENOTSUP and are never opened, so opening them has no side effects. On Windows, the same goes for reparse points that aren't links, such as cloud file placeholders.
  • A directory that is moved while open still refers to the same directory.
  • Rights can only be narrowed. Anything opened from a directory gets at most its rights, and restrict() can only remove rights. An operation without the right it needs fails with ENOTCAPABLE.
  • list() and readLink() fail with EILSEQ on names that aren't valid UTF-8, as these can't be represented as strings.

Names are checked in JavaScript and again in native code. If an invalid name reaches native code, the JavaScript checks were bypassed, and the process is aborted instead of risking an escape.

The kernel also enforces the confinement, as far as each platform allows:

PlatformEnforcement
Linuxopenat2() of a single name with RESOLVE_BENEATH, RESOLVE_NO_SYMLINKS, and RESOLVE_NO_MAGICLINKS from Linux 5.6, otherwise openat() with O_NOFOLLOW.
Androidopenat() of a single name with O_NOFOLLOW. openat2() is never used, as Android kills apps that call it.
macOSopenat() of a single name with O_NOFOLLOW_ANY.
iOSopenat() of a single name with O_NOFOLLOW_ANY.
WindowsNtCreateFile() of a single name relative to the directory handle, without following reparse points. Requires Windows 10 1809 or later.

See also

  • bare-wasi — HostDirectory exposes a DirectorySync to a WebAssembly guest.
  • bare-fs — path-based file system access with the ambient authority of the process.
  • Bare modules — the full bare-* catalog.
  • Bare runtime API — the runtime these modules extend.

Last updated on

Was this helpful?

On this page

UsageAPIDirectoryDirectory.close(): voidcreateDirectory(name: string): Promise<void>Directory.open(path: string, opts?: OpenOptions): Promise<Directory>list(): Promise<Entry[]>openDirectory(name: string): Promise<Directory>openFile(name: string, opts?: OpenFileOptions): Promise<File>readLink(name: string): Promise<string>removeDirectory(name: string): Promise<void>removeFile(name: string): Promise<void>Directory.renamerestrict(rights: Right[]): DirectoryDirectory.rights: Right[]Directory.setTimes(atime: bigint | null, mtime: bigint | null): Promise<void>stat(name?: string): Promise<Stat>DirectorySyncDirectorySync.close(): voidcreateDirectory(name: string): voidDirectorySync.open(path: string, opts?: OpenOptions): DirectorySynclist(): Entry[]openDirectory(name: string): DirectorySyncopenFile(name: string, opts?: OpenFileOptions): FileSyncreadLink(name: string): stringremoveDirectory(name: string): voidremoveFile(name: string): voidDirectorySync.renamerestrict(rights: Right[]): DirectorySyncDirectorySync.rights: Right[]DirectorySync.setTimes(atime: bigint | null, mtime: bigint | null): voidstat(name?: string): StatFileFile.close(): voidread(buffer: Uint8Array, position?: number): Promise<number>restrict(rights: Right[]): FileFile.rights: Right[]File.setTimes(atime: bigint | null, mtime: bigint | null): Promise<void>stat(): Promise<Stat>sync(): Promise<void>truncate(size: number): Promise<void>write(buffer: Uint8Array, position?: number): Promise<number>FileSyncFileSync.close(): voidread(buffer: Uint8Array, position?: number): numberrestrict(rights: Right[]): FileSyncFileSync.rights: Right[]FileSync.setTimes(atime: bigint | null, mtime: bigint | null): voidstat(): Statsync(): voidtruncate(size: number): voidwrite(buffer: Uint8Array, position?: number): numberConstants and variablesrights: Right[]TypesRightStatEntryRightsOptionsOpenOptionsOpenFileOptionsRenameOptionsSecurity modelSee also