Engineering decisions
Decision
Schema per tenant (ADR-0001)
ProposedContext
Schema per tenant (ADR-0001)
Tenants are enterprises that expect strong isolation, per-tenant export and erasure, and a credible answer to whether another customer's bug can read their data.
Rationale
Schema per tenant (ADR-0001)
Each tenant gets schema fk_{slug}, created from a template schema. Requests run on a QueryRunner whose search_path points at the tenant schema, carried in AsyncLocalStorage behind a DataSource proxy. tenant_id columns and filters stay as a second layer.
Consequences
Schema per tenant (ADR-0001)
Per-tenant backup, export and drop become schema operations. Migrations must update template and every fk_* schema, and code outside a request (cron, queues, CLI) must set tenant context explicitly. The pinned per-request connection limits concurrency and is tracked as P1-9.
Decision
Global owner modules for stateful services (ADR-0002)
ProposedContext
Global owner modules for stateful services (ADR-0002)
Shared services were listed in the providers of many feature modules, and Nest creates one instance per listing. That produced 7 Redis connections, 3 JwksService instances racing to generate platform keys, two RBAC caches that disagreed after role changes, and boot failures when a module used @Protected() without importing DatabaseModule.
Rationale
Global owner modules for stateful services (ADR-0002)
Three @Global modules own every cross-cutting stateful service: DatabaseModule (DataSource, TenantContextService, SessionRepository, CORS refresh), SharedServicesModule (Redis, security events, sessions, JWKS, refresh tokens) and GuardsModule (auth guards, RBAC services and cache). Feature modules never re-provide them.
Consequences
Global owner modules for stateful services (ADR-0002)
One instance per process and boot no longer depends on import order. New cross-cutting services go into one of these modules, never into a feature's providers.
Decision
Cookie-only access tokens (ADR-0003)
ProposedContext
Cookie-only access tokens (ADR-0003)
Login and refresh also returned accessToken in the JSON body so the SDK could send bearer tokens. A body copy is readable by any script on the page, which removes the XSS protection httpOnly cookies provide.
Rationale
Cookie-only access tokens (ADR-0003)
Cookie-only delivery for browsers, applied everywhere with no opt-in header. The listed endpoints return expiresIn and non-secret session claims instead. The SDK tracks an authenticated boolean, drops getAccessToken, and always tries one silent refresh and retry on a 401. /oauth/token is unaffected because RFC 6749 requires body delivery there.
Consequences
Cookie-only access tokens (ADR-0003)
Breaking change to the SDK public API. It also fixed a latent bug where four SDK methods threw 'No access token in response' on every call because those endpoints never returned one.
Decision
Per-tenant signing keys with scheduled rotation (ADR-0004)
ProposedContext
Per-tenant signing keys with scheduled rotation (ADR-0004)
The lookup, rotation and retired-key verification code already preferred a tenant key, but provisioning never created one, so every tenant silently shared the platform key, including for SAML assertions.
Rationale
Per-tenant signing keys with scheduled rotation (ADR-0004)
Generate a real RSA key when a tenant is provisioned and rotate on a schedule with a grace period (KEY_ACTIVE_TTL_DAYS 90, KEY_ROTATION_GRACE_DAYS 7). KeyRotationService runs daily per tenant under a cluster-wide advisory lock and backfills tenants created earlier.
Consequences
Per-tenant signing keys with scheduled rotation (ADR-0004)
JWTs, OAuth tokens and SAML assertions no longer share key material across tenants. Review follow-ups fixed before merge: platform-key rotation now runs under the lock (two replicas could create two active keys), the signing-key cache revalidates every 5 minutes, and failed registrations delete the key they provisioned.
Decision
No foreign keys from tenant schemas to public.tenants (ADR-0005)
ProposedContext
No foreign keys from tenant schemas to public.tenants (ADR-0005)
Every cloned table carried an ON DELETE CASCADE foreign key to public.tenants, so deleting a tenant had to visit the referencing table in every tenant schema. At about 700 accumulated schemas Postgres failed with out of shared memory and deletion could not run at all.
Rationale
No foreign keys from tenant schemas to public.tenants (ADR-0005)
Drop the cross-schema foreign keys and delete a tenant by dropping its schema explicitly. A migration removes the constraints per schema and is safe to re-run; recreateForeignKeys now only recreates intra-tenant keys. tenant_id columns stay.
Consequences
No foreign keys from tenant schemas to public.tenants (ADR-0005)
Lock cost scales with the tenant being deleted, not the number of tenants. New per-tenant tables must use a plain tenant_id column and migrations must apply to template and every fk_* schema.
Decision
Per-tenant CORS origins (ADR-0006)
ProposedContext
Per-tenant CORS origins (ADR-0006)
CORS was one global allow-list, so a page on tenant A's registered origin could make credentialed browser calls against tenant B's API.
Rationale
Per-tenant CORS origins (ADR-0006)
A per-request CORS delegate checks the Origin against CORS_ORIGINS or the allow-list of the tenant the request resolves to, using the same priority as the tenant resolver. Tenant admins manage their own list through GET and PUT /tenants/current/allowed-origins.
Consequences
Per-tenant CORS origins (ADR-0006)
Deployments that relied on one tenant's origin working everywhere must now list it per tenant. Edits apply immediately on the handling instance and within 60 seconds on others. Preflights that cannot identify a tenant are answered from the union, but the real request is re-checked.
Decision
One-time link tokens and number-matched magic links (ADR-0007)
ProposedContext
One-time link tokens and number-matched magic links (ADR-0007)
Password reset only emailed a 6-digit code, and verify-email and magic link answered one generic error for expired, used and unknown links. A bare polling nonce for cross-device magic links is device-code phishing: an attacker requests a link for the victim and polls for the session.
Rationale
One-time link tokens and number-matched magic links (ADR-0007)
LinkTokenService issues 256-bit tokens, stores only the SHA-256, and claims with an atomic SET NX so concurrent use has one winner; inspect never consumes, so scanners are safe. Distinct codes LINK_EXPIRED, LINK_ALREADY_USED and LINK_WRONG_ACCOUNT. Cross-device sign-in needs a 6-digit match code shown only on the requesting device, and step-up must be as strong as sign-in.
Consequences
One-time link tokens and number-matched magic links (ADR-0007)
Reset links live in Redis, so a flush invalidates them. A user who is socially engineered into typing an attacker's code is the standard number-matching limit. A side fix removed a schema pin that made every required-MFA policy lookup fail silently as not enforced.
Decision
PKCE: S256 only, explicit, mandatory for public clients
ProposedContext
PKCE: S256 only, explicit, mandatory for public clients
PKCE is what protects a public client's authorization code from interception, so the accepted method and the requirement had to be unambiguous rather than best-effort.
Rationale
PKCE: S256 only, explicit, mandatory for public clients
Only code_challenge_method=S256 is accepted and it must be sent explicitly. Public clients must always use PKCE. Verification is constant-time, and codes issued with plain are rejected.
Consequences
PKCE: S256 only, explicit, mandatory for public clients
A breaking change recorded in the changelog and covered by a dedicated PKCE spec. Discovery advertises only the code response type.
Decision
Tenant-aware background jobs (TenantJobRunner)
ProposedContext
Tenant-aware background jobs (TenantJobRunner)
Cron jobs ran with no tenant context, so with schema-per-tenant they could not see tenant tables at all, and multiple replicas would each run the same job.
Rationale
Tenant-aware background jobs (TenantJobRunner)
TenantJobRunner runs work per active tenant inside a tenant QueryRunner, behind a cluster-wide Postgres advisory lock. Hourly token cleanup and 15-minute session cleanup use it, and key rotation reuses runExclusive for the platform key.
Consequences
Tenant-aware background jobs (TenantJobRunner)
Expired sessions in a tenant schema are purged and verified live. Any new background job must go through the runner, which is now a stated rule for contributors.
Decision
Mail through a queue, events after commit
ProposedContext
Mail through a queue, events after commit
Sending mail inline makes login latency depend on a provider, and publishing events inside a transaction lets listeners react to state that is later rolled back.
Rationale
Mail through a queue, events after commit
MailService only enqueues a BullMQ job (three attempts, exponential backoff); a processor renders React Email templates and picks SES, then SMTP, then Console. Services publish DomainEvents after the transaction commits, and the SecurityNotifier turns them into emails.
Consequences
Mail through a queue, events after commit
Notification failures never fail the originating request. Redis becomes a hard dependency for mail as well as sessions and rate limits, and the Console provider is refused in production.
Decision
LDAP: checked egress and a deactivation safety valve
ProposedContext
LDAP: checked egress and a deactivation safety valve
An LDAP connection takes a customer-supplied host, which is an SSRF vector, yet on-premise directories legitimately live on private ranges. A broken filter or empty directory could also look like everyone leaving.
Rationale
LDAP: checked egress and a deactivation safety valve
Resolve the host once, check every address, and dial the checked IP while keeping the hostname for TLS verification, so DNS rebinding cannot swap targets. Private ranges are denied unless listed in LDAP_ALLOWED_PRIVATE_CIDRS; loopback and link-local metadata ranges are always denied. Sync deactivates but never deletes, and aborts before changing anything if more than 20 percent of provisioned users would be deactivated.
Consequences
LDAP: checked egress and a deactivation safety valve
Directory sync is safe to run unattended. Operators must list their private CIDRs explicitly, and a malformed CIDR list stops the service at startup.
Decision
The SDK and portal never fake a missing contract
ProposedContext
The SDK and portal never fake a missing contract
The Figma plan covered 47 design families, but several had no backend contract (billing, provisioning history, connected applications). Faking them with sample data would make the console look finished when it is not.
Rationale
The SDK and portal never fake a missing contract
The SDK wraps only what exists and branches results as discriminated unions. Capabilities without a contract are feature-flagged off and render a Planned shell with a written handoff: purpose, persona, contract, permissions, audit events and acceptance. A gaps document tracks each open flow.
Consequences
The SDK and portal never fake a missing contract
The console is honest about its scope. Closing a gap means shipping the contract and flipping one flag in the same change.