Graphden documentation

Security model

For a customer or self-hoster evaluating how Graphden isolates tenants and handles their code and secrets. It describes the isolation architecture and its boundaries — it is not an exhaustive threat enumeration, and it does not publish exploit paths. Report vulnerabilities privately through the channel in SECURITY.md, never a public issue.

(Contributor view: the multi-tenant policy is an optional addon from the private graphden-tenancy repo; the core seams it plugs into are documented in TENANCY_SEAM.md.)

Trust model

Isolation layers (defense in depth)

A tenant graph on the shared cloud is contained by several independent layers, so a gap in one does not by itself cross tenants:

  1. Application-layer scoping — OrgScopedStorage stamps and filters every entity by the caller’s org; a tenant reads and writes only its own rows (plus the shared, read-only public library). Within an org, per-namespace grants — to a user, to a role (a team: its members hold the grant), or to the whole org — gate WHO edits WHAT, and a branch’s write-policy (protected branches — owner / org admins) gates writes and merges per branch (VERSIONING.md § Protected branches). The same owner/admin gate covers ALL of a branch’s protection knobs — write-policy, require-merge?, and the review policy (required-approvals / approver-ids / allow-self-approval?) — so a plain org member can’t lower a colleague’s review bar (the :branch authz arm keys on the whole protection set, not just write-policy). Review authz: who may APPROVE a merge = a restrictive approver-ids allow-list when the target sets one (∪ org-admins), otherwise the target’s write-policy roles — enforced when the approval row is written. Each approval is bound to the target it was authorized for (target-branch-id); the merge gate counts an approval only when it matches the ACTUAL merge target AND (when set) the current allow-list, so approvals gathered on a proposal off an open decoy branch can’t be redirected to clear a protected branch’s requirement, and a tightened policy isn’t satisfied by a now-unauthorized approval. Who may COMMENT = anyone who can resolve the (org-scoped) branch, and a comment is deletable only by its author.
  2. Database-layer RLS — Postgres Row-Level Security (FORCE) filters every row by the connection’s graphden.current_org, so even a raw-SQL path that bypassed the decorator stays confined. Strict by default: the app must connect as a non-superuser role or the boot fails (DEPLOYMENT.md § non-superuser DB role).
  3. Capability gate (effects) — every base-fn declares its side effects (db / network / io / process / …); a two-layer effect gate bounds what a tenant graph may do, by tier. The locked anonymous (demo) tier allows only db / state / time / random; the registered free tier and up add metered network (outbound HTTP + your own external DB, egress- guarded); process is dedicated-tier only; raw-sql (arbitrary SQL on the platform database) is never granted to any tenant (PLANS.md).
  4. Fairness quotas — per-org row caps (fns, list items), a fleet-wide concurrent-execution cap, an outbound egress rate-limit and response byte-cap, and a wall-clock execution deadline.
  5. Egress guard (SSRF) — a tenant’s outbound network call is validated against a fail-closed classifier that rejects internal / private / loopback / cloud-metadata targets (and names that resolve to them) before dialing — and again at connect time for EVERY connection, so neither a DNS rebind nor a redirect hop (to a name or an IP literal) reaches an internal address. This covers both outbound HTTP and a tenant’s connection to its own external database (web/sql): the JDBC host is checked the same way, the platform’s own DB is refused as a target (no cross-tenant reach), and a restricted query runs under a statement timeout and server-side row cap so a slow or huge query can’t pin the shared executor.
  6. Secret information-flow marker — values read from the vault are typed [:secret T], tracked through composition, and hidden at execution sinks (the Run pane). This is best-effort taint-tracking, not a proven non-interference guarantee — read SECRETS.md § Scope.
  7. Package-write guard — fn rows written by the boot package sync (base-fns, first-party fn-defs, primitives) are read-only through the editor API: binding / list-item / fn-slot writes whose owner is package-synced, and deletes of the package rows themselves, answer 403 (crud/package_guard.clj over the packages.owned boot registry). One stray write onto a shared parent like :add propagates to every descendant in the installation through inheritance and is silently reverted by the next sync — the guard makes that class impossible for ANY principal; the legitimate paths are extending into a child fn or editing the package’s fns.edn. Renaming or re-describing the package fn itself is refused for the same reason. The 403 holds on EVERY write surface: the generic entity create/update, sequence append / update / move / remove, the record-type compound update (PUT /api/types/record, which would otherwise re-shape the fn’s own slots) and the inline secret bind (POST /api/secret-bindings); a slot shared by several fns is guarded if ANY fn declaring it is package-synced. The editor mirrors the rule client-side (package-owned rides out on each fn row): no + placeholder, no rename/delete, and the edit-block reason says to extend instead — so the affordance is absent rather than failing.
  8. Marketplace gates (MARKETPLACE.md) — the shared catalog is the one surface where tenants meet. A tenant’s public listing is moderated on the cloud: it lands pending, invisible to other orgs until the platform-admin approves it, and both the queue and the decision are gated on the platform-admin right at the base-fn, not the route. A public name is first come, first served registry-wide — another org’s publish under it is refused. Reviews are author-owned (the addon stamps the author, a foreign edit or delete is refused, the generic entity route included), install counts are platform-write-only, and preferences are owner-scoped (a user’s theme / keymap is neither readable nor writable by anyone else). The anonymous storefront renders public + approved rows only and mutates nothing.
  9. Namespace read + impl concealment — private tenant fns default-deny discovery and signature reads. A :read grant shows a fn’s signature; :view-impl also shows its internal composition and implies :read, while :write implies both. :execute remains independent. Public/shared fns stay discoverable. The addon’s graph-read filter is applied to graph projections and the rich-type snapshot; its view-impl filter (crud.entities/view-impl-filter) is then applied on every surface that reads composition: the graph dumps and MCP reads (signature only), Explorer views (no uses match through it), usages, the inspector and the return-type-rule popover, bound values and provenance read by binding id, the whole-graph export (the fn is left out), execution traces (its frame is a leaf, nothing beneath it ships), the canvas layout (its card is its signature — no parents, no bindings, nothing drawn beneath it), the graph lint (it lints as a leaf, so no finding names its chain or matches its internals), the rich-types registry read by id (its bindings / primary parent / rule owner are dropped), a branch-local seed or rule owner reached through it (left unnamed), and its version history (no composition hash, no base-fn), and the raw rows a BYO executor loads (GET /api/export/graph-rows: the fn ships signature-only, marked :concealed? true, the anonymous helpers only it is built from are left out, and the executor refuses to run it — or anything built on it — with :execution-error/fn-concealed). The registry’s by-id index and the :fn-version log carry no org, so a request-facing read by id first asks the viewer’s own storage for the fn: another org’s private fn has no entry and no history for them (the history endpoint answers 404, as for a fn that never existed). The executor still runs the full graph server-side.
  10. Resource isolation — see below.

Resource isolation: shared vs dedicated

The shared tier isolates tenants by data and capability and bounds them for fairness, but co-located tenants share the pod’s CPU / heap / threads — a noisy or OOMing neighbour can degrade others (SCALING.md § Tenant isolation). A tenant that needs a hard resource boundary uses the dedicated tier: its own cgroup-limited shard. Always-on tenant services are, for this reason, a dedicated-tier feature only.

Secrets

Secrets live in Vault / OpenBao. The platform holds the root token as infrastructure configuration, never exposed to a tenant graph; a tenant reaches a secret only through the :vault-get base-fn, whose result is typed [:secret :text]. The KV mount is one flat namespace on that token, so the vault client confines every tenant-context op to the org’s own org/<org-id>/ prefix and refuses paths that could leave the mount (SECRETS.md § Per-org vault paths). In a tenant’s restricted execution :vault-get — the resolver a secret binding reads through — is the one vault base-fn allowed, and only with a tenant org in scope (so the client’s prefix check applies); the raw write / delete / metadata ops stay operator-only. A tenant cannot even STORE a secret binding naming a path outside its prefix (every write route refuses it), and the tombstone GC’s vault reclaim — a platform thread — deletes each path under the org owning its binding, so the client’s prefix check applies there too. See SECRETS.md.

API-token scopes (least privilege for MCP / CLI)

A self-serve API bearer (ACCOUNTS.md § session) can carry scopes and an expiry, picked at mint time on the /account panel. Semantics are a ceiling: the token’s effective rights are the account’s grants ∩ its scopes — a token can only ever narrow, never widen. The accounts module stores scopes and surfaces them on the principal (:api-token? / :token-scopes); the tenancy layer enforces them, so on a single-tenant self-host without the addon a bearer is as powerful as its account (same as a browser session there). Two rules are categorical on the enforced (cloud) surface, independent of scopes: an API token can never reach user/org/platform management (invites, grants, roles, members, registration), and can never mint or revoke API tokens (/api/my-tokens/* requires a browser session).

Preview surfaces (typed reprs, /preview, /__preview)

Three related surfaces render graph-authored content, each on a different trust footing:

Your responsibility (self-host)

Graphden provides the isolation layers above; the deployment perimeter is yours: Postgres HA / backups / point-in-time recovery, the non-superuser DB role, the network perimeter and TLS termination, and OS / container patching. See DEPLOYMENT.md.

Reporting

Please report suspected security issues privately via the org SECURITY policy, not a public issue or PR.