Capabilities and permissions

Shipped — public-stable

The capability model — expandCapabilities, the capability hierarchy, and PermissionError — is part of the first-release shipped surface.

Capabilities are intent, not a security boundary

Capabilities are an intent declaration, a best-effort, in-memory audit, and an accident-prevention layer. They are not a sandbox, isolation, or security guarantee. Obsidian provides no sandbox, and the documented global handle is admin-scoped and ungated, so a consumer can bypass capability scoping entirely. Never market or rely on this model as “secure”, “sandboxed”, or “isolated”.

The capability set

Capabilities are declared when you connect(). The live set has six members:

Capability	Grants
read-state	Read reactive state.
read-document	Read the open document (implies read-state).
write-annotations	Create/modify annotations (implies read-document, read-state).
write-bookmarks	Create/modify bookmarks (implies read-state).
write-library	Modify the library (implies read-state).
admin	Everything above.

Tokens outside this set (for example collections:read, export:execute, modes:read) are not part of the live capability set and cannot be granted today.

Note

write-bookmarks and write-library gate the commands.bookmarks and commands.library command surfaces, which are currently experimental. The capability tokens are part of the shipped six-member set, but the command surfaces they gate are not yet shipped — a shipped capability token is not a shipped command surface.

Hierarchy

Capabilities expand hierarchically — granting a higher capability implies the lower ones:

admin
 ├─ write-library      ─┐
 ├─ write-bookmarks    ─┤─→ read-state
 ├─ write-annotations  ─→ read-document ─→ read-state
 ├─ read-document      ─→ read-state
 └─ read-state

expandCapabilities

expandCapabilities(capabilities: Capability[]): Capability[]

Expands a list of requested capabilities into the full implied set. Granting ['write-annotations'] expands to ['write-annotations', 'read-document', 'read-state']. This is the function that determines what a scoped handle is allowed to do.

PermissionError

When a capability-gated method is called without the required capability, the facade throws a PermissionError. Handle it where you call gated methods:

try {
  await scoped.commands.mupdf.createAnnotation(/* ... */);
} catch (err) {
  if (err instanceof PermissionError) {
    // The scoped handle was not granted write-annotations.
  }
}

PermissionError is the deterministic signal that a gated call was not permitted for an honest caller routed through a facade. It does not constrain a consumer who reaches underlying services directly — that is the accident-prevention, not security-boundary, framing above.

What capabilities each shipped surface needs

Surface	Typical capability
commands.notes reads	read-state
commands.notes writes	write-annotations
commands.links reads	read-state
commands.links writes	write-annotations
commands.mupdf reads (text/region/page)	read-document
commands.mupdf annotate	write-annotations

Related

• Guide: Connect to the Amnesia API
• Access the API — where connect() and the global are documented.

_{Reference verified as of 2026-06-28.}