Graphden documentation

The tenancy seam

🔧 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:

Context

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).

Capability seams (fine-grained)

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:

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.

User identity (owner / author keys)

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).

Notifications

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 seam

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.

Addon config manifest

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.

Storage & schema seams

Route-collection seam

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.

Effect gate

The runtime sandbox mechanism is entirely in core (executor/compile_runtime.clj); the addon only sets policy values.

Execute guard

: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.

Packages channel

: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.

What the addon provides

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.