feat(tenancy): add multi-tenancy primitives (@quatrain/tenancy) #45

Merged
crapougnax merged 7 commits from feat/tenancy into develop 2026-11-14 17:13:21 +00:00
Member

Summary

New package @quatrain/tenancy (1.0.0-beta.0) for an instance shared by several customers:

  • Tenant registry: Tenant and Membership models stored through any backend adapter by TenancyRepository, an in-memory store, and the TenantStoreInterface port. Slugs and (tenant, user) pairs are unique.
  • Request resolution from the path, the subdomain or a header.
  • Checked scopes: granted only for an existing, active tenant and, for a user, a member. The actor is always explicit (user or system process).
  • Async tenant scope (currentTenant()) that refuses to switch tenant inside a unit of work, and an envelope to carry the scope through a queue.
  • TenantResources: one lazily built resource per tenant, rebuilt when what it is built from changes.
  • Export and import of a tenant registry entry.

The package knows nothing about HTTP frameworks or authentication. Data isolation is enforced where the data lives.

Depends on #33 and on #44

This branch is built on feat/backend-postgres-row-isolation, itself built on feat/backend-unique-properties. Until both are merged, the diff also shows their commits; merge them first, in that order.

Tests

Unit tests run without a database. PostgresIsolation.test.ts covers the PostgreSQL set-up end to end (registry and data in one database, restricted role, rows isolated per tenant) and is skipped without a database.

To decide

  • Tests sit next to the sources in src/, so they are published with the package.
  • First version is 1.0.0-beta.0.

Closes #43

🤖 Generated with Claude Code

## Summary New package `@quatrain/tenancy` (`1.0.0-beta.0`) for an instance shared by several customers: - **Tenant registry**: `Tenant` and `Membership` models stored through any backend adapter by `TenancyRepository`, an in-memory store, and the `TenantStoreInterface` port. Slugs and (tenant, user) pairs are unique. - **Request resolution** from the path, the subdomain or a header. - **Checked scopes**: granted only for an existing, active tenant and, for a user, a member. The actor is always explicit (user or system process). - **Async tenant scope** (`currentTenant()`) that refuses to switch tenant inside a unit of work, and an envelope to carry the scope through a queue. - **`TenantResources`**: one lazily built resource per tenant, rebuilt when what it is built from changes. - **Export and import** of a tenant registry entry. The package knows nothing about HTTP frameworks or authentication. Data isolation is enforced where the data lives. ## Depends on #33 and on #44 This branch is built on `feat/backend-postgres-row-isolation`, itself built on `feat/backend-unique-properties`. Until both are merged, the diff also shows their commits; merge them first, in that order. ## Tests Unit tests run without a database. `PostgresIsolation.test.ts` covers the PostgreSQL set-up end to end (registry and data in one database, restricted role, rows isolated per tenant) and is skipped without a database. ## To decide - Tests sit next to the sources in `src/`, so they are published with the package. - First version is `1.0.0-beta.0`. Closes #43 🤖 Generated with [Claude Code](https://claude.com/claude-code)
feat(identifiers): add slug, UUID, prefixed identifier and URI helpers
Some checks failed
Quatrain Core Sovereign CI / Monorepo Build, Tests & Quality Audit (push) Successful in 6m16s
Quatrain Core Sovereign CI / Publish Changed Packages to npm (push) Has been skipped
Quatrain Core Sovereign CI / Monorepo Build, Tests & Quality Audit (pull_request) Has been cancelled
Quatrain Core Sovereign CI / Publish Changed Packages to npm (pull_request) Has been cancelled
1aeed6db03
New package @quatrain/identifiers, without dependency:

- slugify, isSlug, assertSlug: slugs valid in a path, a file name and a
  DNS label;
- uniqueSlug: first free slug with a counter suffix;
- uuid, isUuid, prefixedId, isPrefixedId: generated identifiers;
- isOpaqueId, assertOpaqueId: sanity check of identifiers issued by
  another system;
- isUri: absolute URI, optionally restricted to allowed schemes.

Uniqueness itself stays a storage concern.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
A property can now be declared `unique: true`. Backends able to do so
refuse a second record of the collection holding the same value, at
creation and at update, including under concurrent writes.

- core: `unique` option and getter on properties;
- types: ConflictError, for writes colliding with the current state;
- backend: UniqueConstraintError (collection, property) and
  uniquePropertyNames(); the mock adapter enforces the rule;
- backend-postgres, backend-sqlite: UNIQUE column in created tables and
  generated migrations, constraint violations mapped to
  UniqueConstraintError.

Missing values may repeat. Soft-deleted records keep their value: it is
not reusable. Tables that already exist are not altered: add the
constraint with a migration. Adapters that do not implement the option
(Firestore, REST) ignore it.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
fix(backend-sqlite): report a record identifier already taken as a unique violation
Some checks failed
Quatrain Core Sovereign CI / Monorepo Build, Tests & Quality Audit (push) Has started running
Quatrain Core Sovereign CI / Publish Changed Packages to npm (push) Has been cancelled
15e1604b67
Creating a record with an explicit identifier that already exists threw
a generic BackendError on SQLite, and a UniqueConstraintError on
PostgreSQL. Both adapters now throw UniqueConstraintError, without a
property name since the collision is on the identifier.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
feat(backend-postgres): isolate rows per owner with row-level security
Some checks failed
Quatrain Core Sovereign CI / Monorepo Build, Tests & Quality Audit (push) Has started running
Quatrain Core Sovereign CI / Publish Changed Packages to npm (push) Has been cancelled
28ba299323
One database can now hold the data of several owners (tenants) that
never see each other's rows, including when a query forgets its filter.

- config.sessionSettings: function returning settings applied to each
  statement for one transaction only, so pooled connections never keep
  them;
- rowIsolationSql(): DDL enabling and forcing row-level security on a
  table, comparing its owner column with a session setting;
- assertRowSecurityRole(): start-up check that the role does not bypass
  policies.

Without an owner, protected tables look empty and refuse writes. The
adapter behaves as before when sessionSettings is absent.

A restricted role cannot create tables: automatic table creation does
not apply to it, tables come from migrations. Documented in the README
and in a new HOWTO.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
feat(tenancy): add multi-tenancy primitives
Some checks failed
Quatrain Core Sovereign CI / Monorepo Build, Tests & Quality Audit (push) Failing after 7m2s
Quatrain Core Sovereign CI / Publish Changed Packages to npm (push) Has been skipped
a1339f972d
New package @quatrain/tenancy for an instance shared by several
customers:

- tenant registry: Tenant and Membership models stored through any
  backend adapter by TenancyRepository, an in-memory store, and the
  TenantStoreInterface port; slugs and (tenant, user) pairs are unique;
- request resolution from the path, the subdomain or a header;
- checked scopes: granted only for an existing, active tenant and, for a
  user, a member; the actor is always explicit (user or system process);
- async tenant scope (currentTenant) that refuses to switch tenant inside
  a unit of work, and an envelope to carry the scope through a queue;
- TenantResources: one lazily built resource per tenant, rebuilt when
  what it is built from changes, in place of process-wide singletons;
- export and import of a tenant registry entry.

Data isolation is enforced where the data lives. An end-to-end test
covers the PostgreSQL set-up: registry and data in one database, a
restricted application role, rows isolated per tenant through the
adapter's session settings. It needs a database and is skipped without
one.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
test(backend-postgres): create the complete users table whichever test runs first
Some checks failed
Quatrain Core Sovereign CI / Monorepo Build, Tests & Quality Audit (push) Successful in 5m56s
Quatrain Core Sovereign CI / Publish Changed Packages to npm (push) Has been skipped
Quatrain Core Sovereign CI / Monorepo Build, Tests & Quality Audit (pull_request) Has been cancelled
Quatrain Core Sovereign CI / Publish Changed Packages to npm (pull_request) Has been cancelled
214f52a14e
On an empty database, a test whose model only refers to users made the
adapter create a placeholder users table with a single column; the tests
running afterwards then failed on missing columns. The shared test setup
now registers the User class, so the table is created complete.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
test(backend-postgres): register the User class in the row isolation test
Some checks failed
Quatrain Core Sovereign CI / Monorepo Build, Tests & Quality Audit (push) Successful in 6m25s
Quatrain Core Sovereign CI / Publish Changed Packages to npm (push) Has been skipped
Quatrain Core Sovereign CI / Monorepo Build, Tests & Quality Audit (pull_request) Failing after 18m2s
Quatrain Core Sovereign CI / Publish Changed Packages to npm (pull_request) Has been cancelled
d058ad3c8e
Same cause as the shared setup: run first on an empty database, the test
made the adapter create a placeholder users table that broke the tests
running afterwards.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
test(tenancy): register the User class in the PostgreSQL isolation test
Some checks failed
Quatrain Core Sovereign CI / Monorepo Build, Tests & Quality Audit (push) Successful in 6m17s
Quatrain Core Sovereign CI / Publish Changed Packages to npm (push) Has been skipped
Quatrain Core Sovereign CI / Monorepo Build, Tests & Quality Audit (pull_request) Has started running
Quatrain Core Sovereign CI / Publish Changed Packages to npm (pull_request) Has been cancelled
17467c791c
Run first on an empty database, the test made the adapter create a
placeholder users table that broke the tests running afterwards.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Merge branch 'develop' into feat/tenancy
All checks were successful
Quatrain Core CI / Monorepo Build, Tests & Quality Audit (push) Successful in 6m20s
Quatrain Core CI / Publish Changed Packages to npm (push) Has been skipped
Quatrain Core CI / Monorepo Build, Tests & Quality Audit (pull_request) Successful in 6m32s
Quatrain Core CI / Publish Changed Packages to npm (pull_request) Has been skipped
909494edca
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Merge branch 'develop' into feat/backend-postgres-row-isolation
All checks were successful
Quatrain Core CI / Monorepo Build, Tests & Quality Audit (push) Successful in 4m25s
Quatrain Core CI / Monorepo Build, Tests & Quality Audit (pull_request) Successful in 4m32s
Quatrain Core CI / Publish Changed Packages to npm (pull_request) Has been skipped
Quatrain Core CI / Publish Changed Packages to npm (push) Has been skipped
160cf0e752
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Merge branch 'develop' into feat/backend-postgres-row-isolation
Some checks failed
Quatrain Core CI / Monorepo Build, Tests & Quality Audit (push) Successful in 8m14s
Quatrain Core CI / Publish Changed Packages to npm (push) Has been skipped
Quatrain Core CI / Monorepo Build, Tests & Quality Audit (pull_request) Failing after 16m46s
Quatrain Core CI / Publish Changed Packages to npm (pull_request) Has been cancelled
bb35d0bdf2
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Merge branch 'feat/backend-postgres-row-isolation' into feat/tenancy
All checks were successful
Quatrain Core CI / Monorepo Build, Tests & Quality Audit (push) Successful in 8m12s
Quatrain Core CI / Publish Changed Packages to npm (push) Has been skipped
Quatrain Core CI / Monorepo Build, Tests & Quality Audit (pull_request) Successful in 8m18s
Quatrain Core CI / Publish Changed Packages to npm (pull_request) Has been skipped
a1b5b600fc
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Merge branch 'develop' into feat/tenancy
All checks were successful
Quatrain Core CI / Monorepo Build, Tests & Quality Audit (push) Successful in 6m5s
Quatrain Core CI / Monorepo Build, Tests & Quality Audit (pull_request) Successful in 6m24s
Quatrain Core CI / Publish Changed Packages to npm (push) Has been skipped
Quatrain Core CI / Publish Changed Packages to npm (pull_request) Has been skipped
b994d8717f
crapougnax merged commit eb3e37ca84 into develop 2026-11-14 17:13:21 +00:00
crapougnax deleted branch feat/tenancy 2026-11-14 17:13:21 +00:00
Sign in to join this conversation.
No description provided.