Org controls
admin_write is a second Postgres role your buyer-facing tenant-isolation policy never matches, so your own operator control plane can write across every tenant without the app role ever gaining that reach.
What it is
org-controls is the cross-tenant admin-write RLS layer carved out of the open tenancy-rls floor, plus the org-plan surfaces around it: WorkOS SSO sign-in, a Clerk session-verification driver, and the owner-gated multi-user membership surface. The free tenancy-rls package still enforces the buyer app role's fail-closed single-tenant isolation; this paid layer adds the separate admin_write role your own operator control plane mutates through.
What ships in the module
Browser-safe entry point
Import @caisson/org-controls/browser inside a client bundle for assertCanManageMembers, so your UI can show and hide owner-only controls using the exact gate the server enforces rather than a second copy of the rule. The main entry keeps the full surface, and every browser-entry export is also on it.
Cross-tenant write policy, DB-separated on purpose
buildAdminWritePolicySql grants SELECT/INSERT/UPDATE (no DELETE) to admin_write and adds a role-scoped TO admin_write USING (true) WITH CHECK (true) permissive policy alongside the table's existing app tenant-isolation policy, RLS OR-combines them by role, so admin_write reaches every tenant while app never matches this policy. buildAdminSelectPolicySql is the narrower read-only twin for tables the control plane only ever reads.
withAdminWrite, the one seam every mutation writes through
withAdminWrite opens a transaction, runs the same fail-closed SUPERUSER/BYPASSRLS role pre-flight withTenant uses (deliberately duplicated here per ADR-0257 §1.3 rather than widening the open tenancy-rls surface), then SET LOCAL ROLE admin_write for the transaction's life, never the connection pool directly.
Owner-gated multi-user membership
assertCanManageMembers gates addAccountMember and removeAccountMember to the owner role, a seat cannot manage members or billing. removeAccountMember additionally refuses self-removal and refuses removing a second owner, so this control can never lock an account's owner out or let one owner unilaterally eject a co-owner.
WorkOS SSO sign-in
createWorkosSsoProvider builds the AuthKit/SSO authorization URL and exchanges the callback code for a Zod-strict-validated {userId, email} profile over api.workos.com, a framework-agnostic transport seam apps/site wires into better-auth. A failed exchange never echoes the response body, since it can carry the client secret or user PII.
Clerk session-verification driver
createClerkSessionVerifier verifies a Clerk session JWT (networkless when jwtKey is supplied, live JWKS fetch otherwise) and clerkClaimsToSessionContext maps its claims onto the kernel's SessionContext. An active Organization with no role claim maps to the least-privileged seat, never the owner default, closing a privilege-escalation path a reshaped custom token could otherwise open.
Fail-closed entitlement gate
holdsOrgControls is the predicate the /dashboard/members surfaces gate through: an empty active-entitlement set denies by default, and it accepts either the bare org-controls purchase id or the full @caisson/org-controls module id, correct whichever form a standalone purchase or bundle grant carries.
/**
* SQL that lets the `admin_write` role INSERT/UPDATE/SELECT every row of `table` cross-tenant,
* WITHOUT widening what any other role sees. Emitted ALONGSIDE the table's existing
* `buildTenantPolicySql` output (which stays the `app` tenant-isolation floor): a
* `GRANT SELECT, INSERT, UPDATE ... TO admin_write` (no DELETE — the mutation surface soft-revokes,
* never hard-deletes) plus a `TO admin_write USING (true) WITH CHECK (true)` policy. RLS
* OR-combines permissive policies, but each is role-scoped, so `admin_write` sees/writes every
* tenant while `app` never matches this policy and stays isolated. Applied to the production
* database at deploy time, mirroring the read-only counterpart policy builder.
*/
export function buildAdminWritePolicySql(
table: string,
{ role = ADMIN_WRITE_ROLE }: AdminWritePolicyOptions = {},
): string {
return [
// Idempotent so re-running DEPLOY provisioning never errors: GRANT is a no-op when already held,
// and DROP POLICY IF EXISTS clears any prior policy before CREATE (Postgres has no
// CREATE POLICY IF NOT EXISTS). The policy body is fixed, so drop-then-create is safe to repeat.
`GRANT SELECT, INSERT, UPDATE ON ${table} TO ${role};`,
`DROP POLICY IF EXISTS ${table}_admin_write ON ${table};`,
`CREATE POLICY ${table}_admin_write ON ${table}`,
` TO ${role}`,
` USING (true)`,
` WITH CHECK (true);`,
].join("\n");
}- USING (true) WITH CHECK (true) is scoped TO admin_write only, RLS OR-combines permissive policies, so this cross-tenant grant never widens what the app role's own tenant-isolation policy already sees.
- GRANT SELECT, INSERT, UPDATE deliberately omits DELETE, the operator mutation surface this policy backs soft-revokes a row, it never hard-deletes through admin_write.
- DROP POLICY IF EXISTS runs before CREATE POLICY so buildAdminWritePolicySql is safe to re-run at every DEPLOY, Postgres has no CREATE POLICY IF NOT EXISTS.