🔧 Internal engineering record — not user documentation. The reader-facing view of tenant isolation is SECURITY_MODEL.md; the tier/quota surface is PLANS.md.
Multi-tenancy is an optional Integrant addon, not a fork and not a
graph-package. This repo (the open core) ships every mechanism the addon
needs — the seams below — plus one namespace of shared context
(graphden.tenancy.context). The multi-tenant policy (OrgScoped storage,
RLS, grants/authz, plans, users, the app-router, domains, the tenancy-admin
package) lives in the private graphden-tenancy repo and plugs into these
seams via config. Without the addon the system is single-tenant: one implicit
org, unrestricted effects, single-token (or open) auth — every seam is an
identity pass-through.
Why an addon (decision guard). A security boundary cannot be implemented
by the thing it restricts: tenant graphs execute inside the executor, so if
isolation or the effect gate were themselves graph-packages, composition could
circumvent them. Enforcement therefore lives below the graph. But it must
neither fork “cloud vs self-hosted” nor bloat the base binary — so it is a
core-level optional dependency, reusing bones the core already has (storage
decorators, Integrant, schema extend-builder, the two-channel package
model). Cloud vs self-hosted is a mode, not code: one binary; “cloud” =
addon wired + restriction policy. A self-hoster who wants multi-user installs
the same addon — they are not “cloud”.
What holds the seam in place. Most of the vars the addon reaches here
have no caller in this repo — they exist for the addon — so a rename or a
move can pass every graphden test and only break at pin-bump time, in a repo
this CI cannot see. tools/open-core-seam.edn lists every var the addon
reaches (generated from its own requires) and
test/graphden/open_core_seam_test.clj resolves each one, so the break
lands where the change is made. It proves the NAME resolves, not the
contract — an arity or semantic change still needs the addon’s own suite.
The seams, in wiring order:
graphden.tenancy.context — the one tenancy namespace that stays in core,
because core code must be able to ask about tenancy without depending on the
policy. Holds the *current-org* thread-local (bound per-request by the
addon; unbound = platform/single-tenant), platform-tier? /
platform-admin? predicates, and the BYO execution-mode resolution
(GRAPHDEN_BYO_EXECUTOR / :org.execution-mode).
Beyond the yes/no predicates above, context.clj carries two
installable capability seams — policy lives in the addon, core keeps
only the hook; both are default-deny without the addon:
install-platform-cap-fn! /
current-has-platform-cap? cap: admits a delegate holding one
platform right (:view-all-stats, :manage-orgs, …) without the
whole :platform-admin umbrella. The addon’s predicate returns
true for the umbrella too, so an operator passes every gate.install-org-cap-fn! / current-has-org-cap? cap:
the same shape scoped to the current org (:manage-users,
:publish-packages, …); the addon implements grants + role
bundles + owner-implies-all.The namespace discovery seam is a graph transformation rather than a
capability predicate: install-graph-read-filter! /
apply-graph-read-filter lets the addon remove function signatures and
namespace names the current principal cannot read. Its default is identity,
so single-tenant installs keep their full graph. Core uses it for both the
graph projections and the rich-type snapshot; tenancy applies :read grants.
Because both default to deny, a gate in core/packages MUST pair the
capability check with a current-platform-tier? short-circuit to
stay open on single-tenant / operator installs — the shape
(or (current-platform-tier?) (current-has-org-cap? :publish-packages))
guarding publish-package-apply (registry/impls.clj) and the
:view-all-stats gate in app/execution/impls.clj are the two
precedents.
tenancy.context/current-user-id — the accounts principal’s :user-id,
"anonymous" without per-user identity — and current-user-label (a
public-safe display label) are the seam the marketplace’s per-user rows key
on: :ui-pref (owner-scoped) and :package-review (author-owned writes).
The addon’s decorator classifies both (owner-scoped-entities /
author-owned-entities) and stamps / filters them; core only exposes the
identity (MARKETPLACE.md § 2).
install-notify-fn! / notify! event payload — the same install-a-hook
shape pointed the other way: core raises a domain event and the addon
decides who is told and over what channel (it owns the accounts Mailer,
the org → owner lookup and the trusted link origin). Without an addon the
event is dropped; the sink’s result is returned to the caller and never
inspected, so an installed sink must not throw — a mail failure is the
sender’s to log, not the domain write’s to undo. Events raised today:
| Event | Payload | Raised by | The addon’s sink |
|---|---|---|---|
:package-submitted |
the created :package-version row that landed pending |
publish-package-apply (registry/registry/impls.clj) |
:tenancy/notifications — emails every platform-admin (MARKETPLACE.md § 8) |
:package-moderated |
the updated :package-version row (status, moderation-note, org-id, publisher-id, …) |
moderate-package-version! (registry/marketplace/impls.clj) |
:tenancy/notifications — emails the publisher, else the publishing org’s owner |
Auth is provider-driven, never hardcoded. Core defines
graphden.auth.provider/AuthProvider and a default single-token
implementation behind the :auth/provider Integrant key
(system/init/exec.clj); the graph reaches the decision through the
:authenticate-request seam in web/ring-adapter. Blank AUTH_TOKEN = no
provider = the instance runs open (self-hosted no-login mode); a set token or
the addon’s session/user provider turns auth on, and then reads are gated too.
The addon overrides :auth/provider with token→{:user :org} resolution.
graphden.system.config/read-config deep-merges Aero fragments listed in
GRAPHDEN_ADDON_CONFIGS (comma-separated classpath resources) over the core
config; a fragment’s :graphden/require vector loads the addon’s init-key
namespaces first. An addon fragment overrides indirection keys
(:auth/provider, :app/storage, …) and adds its own components. Unset env
= no-op = single-tenant.
:app/storage (system/init/storage.clj) is
an identity pass-through under VersionedStorage, so the addon’s
OrgScoped decorator sits where vs/unwrap cannot bypass it:
Versioned(OrgScoped(Postgres)).
The decorator keeps the storage it wraps under :base (or
:base-storage) and has no :pool of its own: that is the convention
graphden.storage.tx walks to find the pool and to bind a whole stack to
one transaction connection (tx/in-transaction rebuilds each decorator
around the bound backend, so every write in the transaction still passes
the decorator’s guards). A decorator that hid its inner storage under
another field would silently put every versioned write back on
autocommit, without its collision locks. RLS holds inside the
transaction because its connection comes from the org-aware pool on the
request thread.storage.graph-writer/call-with-write holds
PostgreSQL transaction advisory locks across validation and the entire outer
commit or rollback. Public, raw and unknown writers take an exclusive global
lock. A trusted private writer takes that lock shared and its organization
lock exclusive, so separate organizations can edit their private graph rows
concurrently. These locks precede branch, row, identity and collision locks;
compilation and whole-graph type checks run after they are released.
GraphWriterAdmission/writer-scope-for classifies the identities a mutation
changes, including the identity behind a version row. A private actor can
have an authorized write to a public identity; that operation still needs
global admission. Classification repeats after waiting, and a changed owner
refuses the operation without upgrading a held lock. Namespace and row
authorization still run through the actual decorators under the lock.
VersionedStorage explicitly forwards admission and preview authorization.
Unknown decorators use global admission and cannot advertise writable
previews. A transaction token only permits physical storage calls to join
the same active context and exact connection; caller metadata grants no
authority. Compound inheritance apply rejects foreign JDBC transactions
whose commit boundary it does not own. It invalidates and publishes only
after the actual commit; publication failures report committed success with
warnings and preserve the new function UUID.:db/schema {:extensions […]} lets the addon add
entities (:org, :user, :grant, :role, :domain, :token, …)
without editing core schemas.:datasource-wrap seam lets the addon wrap the
:db/postgres pool to set_config the current org on every borrow (the
RLS session variable). The wrap MUST delegate the JDBC Wrapper methods
(isWrapperFor / unwrap): that is how halt reaches the Hikari pool
behind it (pool/close-pool unwraps instead of casting — the cast threw
out of the shutdown hook in production, 2026-09-03).org-id column is core, not addon (decision guard): it sits on the
graph entities at the identity level (NULL ≡ public, not versioned) so
core queries work in both modes. A tenant is a legitimate cross-cutting
field, not graph semantics — the addon enables enforcement, not the
column.graphden.system.route-collection — a JVM-wide ordered collection of
fall-through routers consulted by branch_router/dispatch inside
request-scope (so an addon control-plane panel runs with *current-org*
bound; a boot-frozen router could not be org-scoped). The addon installs its
router via install-router!; without the addon the collection is empty and
dispatch passes through byte-for-byte. The frontend half:
api-routes-js/install-from-routers! regenerates the window.API cache from
the union of the main router and any installed collections, so addon routes
reach editor JS without hardcoded paths. Note: the optional first-party
registry / mcp packages deliberately do NOT use this seam — they need
per-branch freshness and are served via branch_router handler slots instead.
The runtime sandbox mechanism is entirely in core
(executor/compile_runtime.clj); the addon only sets policy values.
record-effect!; with
*allowed-effects* bound to a set, a category outside it throws
:execution/forbidden-effect. nil = unrestricted = zero overhead.cloud-forbidden-effects = #{:env :io :network :process :raw-sql :cross-org}.
:raw-sql exists because :db must stay allowed (tenants need org-scoped
storage) while the raw HoneySQL escape hatches would ride on :db past
org-scope and RLS — they record :raw-sql additionally.
:cross-org marks the platform-only dispatch primitives that run a fn
under ANOTHER org’s *current-org* scope (the cloud domain-router’s
:execute-in-org) — safe on the operator plan, forbidden on every
tenant plan.:raw-sql-recording
primitives):
cloud-request-allowed-effects
(safe set + :raw-sql) around tenant requests;cloud-allowed-effects-for (plan-resolved via the
cloud-allowed-effects-resolver seam, falling back to the locked
default-cloud-allowed-effects = #{:db :state :time :random}).
The platform ctx stays unrestricted; the restriction is a property of
executing a user graph, not a wrapper around the platform.cr/capture-conveyed-bindings on the starting thread
→ with-bindings on the other; the addon registers *current-org* via
cr/register-conveyed-var!): :future, :with-timeout,
:with-heartbeat, each :http-server request (http-kit worker threads —
fixed 2026-09-24; a tenant service’s requests used to run unscoped), and
:sse-stream ticks (bound-fn*). A new such base-fn must do the same.record-effect!, or it is a sandbox hole. A new sensitive category goes in
both types.core/known-effect-categories and cloud-forbidden-effects./partials/*,
/api/* in the app package): the handler’s effect closure must stay
inside cloud-request-allowed-effects, because on the cloud it runs
under that set for every tenant session — a closure that reaches :env
or :network answers 403 for every tenant, exactly as the branch popover
(GRAPHDEN_HUB_URL via :env) and the feedback probe + intake did in
production, 2026-08-28 → 09-02. Two sanctioned shapes:
:exec/deploy-config in the system config and read through the
:deploy-config base-fn — a boot-time snapshot in the platform process,
:effects #{} (CONFIGURATION § :exec/deploy-config).
Declaring a key is the operator’s statement that the value is public;
a secret never goes there (vault / Clojure-side config), and nothing
outside the declared map exists in the snapshot.:shipped-asset — cached per process, allow-listed to asset kinds
under packages/, :effects #{} — so serving the editor needs no
:io and the addon has no per-path exception to maintain. A
CALLER-chosen classpath path (/api/assets/baseline,
/partials/asset-edit) stays on :read-resource-or-nil (:io):
operator-only by the gate, which is what keeps cloud/prod.edn
unreadable through it.
tenant_effect_budget_test pins every app route’s closure against the
set, with an explicit ledger for the operator-only exceptions.:execute-guard on the ExecutionContext — an injectable
(fn [ctx fn-id]) admission check cr/execute consults once at
top-level (the *execute-authorized* flag keeps it off the hot sub-fn
path), throwing :authz/forbidden. The addon installs per-namespace
:execute authorization here; core installs nothing.
:app/packages {:extra-package-names […]} (system/init/packages.clj) —
the addon ships its control-plane UI as an ordinary fns-package
(tenancy-admin) loaded only when the addon is active, without rewriting the
core package list.
Everything above is a socket. The plugs — OrgScopedStorage (own+public
read / own write / org stamping / tenant-forbidden privileged entities),
Postgres RLS policies, grants + roles + per-namespace authz, plans/tiers +
quotas, users + sessions, the FaaS app-router (tenant apps = handler-fns, not
owned services; the OPERATOR org’s own apps run in the platform ctx —
:operator-org — so the landing can, e.g., serve its own images through
:read-resource-bytes), domains + DNS verification, demo-org GC, operator
bootstrap —
live in the private graphden-tenancy repo (see its docs/PLATFORM_NOTES.md
for the design rationale) and reach production through the graphden-cloud
build.