Multi-Tenancy & Business Isolation

​

The three scoping identifiers

Naming trap. @CurrentTenant() is a legacy alias for @TenantId() — it returns the validated tenant id, not a workspace id, even though many call-sites bind it to a parameter named workspaceId. Prefer @TenantId() in new code. (See tenant/decorators/current-tenant.decorator.ts.)

​

How tenant id is resolved (and why the header is not enough)

1. JWT tenant_id claim (snake_case, legacy)
2. JWT tenantId claim (camelCase, newer issuers)
3. request.tenantId set by AdminApiKeyGuard after it validates the admin API key — the only path where a raw X-Tenant-Id header is honored
4. (admin-key callers only) raw X-Tenant-Id header

​

The AccountingWorkspaceGuard (the front door)

Validate that workspace_id resolves to an active accounting book owned by the caller’s tenant, and — when X-Business-Id is supplied — that the book belongs to that business.

• Reads and writes are covered. It extracts workspaceId from both the query and the body (extractWorkspaceId). Reading the query alone would let a body-routed write (POST/PUT) move workspaceId into the JSON body and skip the consistency check entirely.
• X-Business-Id is required when a workspace is present. The guard calls WorkspaceBusinessScopeService.assertWorkspaceInBusiness({ …, requireLinkedBusiness: true }). With requireLinkedBusiness: true, an absent X-Business-Id header is a deny (ForbiddenException), not “any business of the tenant.” This closes the old hole where an unscoped finance role could read across every business by omitting the header.
• No workspace → pass. Endpoints that don’t route by workspaceId (bridge, settings, some list endpoints) return true from the guard; those controllers enforce business-id consistency themselves.
• No tenant → pass to downstream. A missing tenant id means a pre-auth state; the guard defers to the auth layers rather than guessing.

​

The fail-closed core: WorkspaceBusinessScopeService

​

Per-business books: AccountingRoutingService

• resolve({ tenantId, businessId, productKey?, bookId? }) — validates the business belongs to the tenant, then picks the target book:
  1. an explicit bookId (must belong to that business, else NotFoundException)
  2. the business’s defaultBookId
  3. exactly one active book (auto-adopt with a warning)
  4. zero active books → NotFoundException; more than one active book with no default → BadRequestException code: 'BOOK_ROUTING_AMBIGUOUS' (“Refusing to guess”).
• resolveBusinessIdForWorkspace({ tenantId, workspaceId }) — the reverse direction, used by modules that already hold a workspaceId (e.g. JournalService.postWithCurrentPipeline). Throws if the book is unlinked to a business.
• resolveByProduct(...) is intentionally a hard rejection — after the multi-business cutover every adapter must pass an explicit businessId. resolveContextByProduct(...) is the narrow exception for products with no businessId at all (e.g. personal-finance reimbursements): it routes only when exactly one business is enrolled in the product, otherwise returns null so the caller degrades (skips GL) instead of mis-routing money.

​

The @BusinessCtx() decorator (the cross-module pattern)

interface RequestBusinessContext {
  tenantId: string | null;   // signed JWT claim (or admin-key path)
  businessId: string | null; // X-Business-Id header
  productKey: string | null; // X-Product-Key header
}

• requireTenantId(ctx) → UnauthorizedException('Tenant context required') if null.
• requireBusinessId(ctx) → UnauthorizedException('X-Business-Id header is required …') if null — use this on routes that are always scoped to a single business.

Native accounting CRUD controllers (invoices, bills, payments, …) instead compose TenantAuthGuard + AccountingWorkspaceGuard + @CurrentTenant() (= @TenantId()) and route by workspaceId. The two patterns coexist: workspace-routed endpoints get their business check from AccountingWorkspaceGuard; bridge/settings/HR endpoints get theirs from @BusinessCtx() + requireBusinessId().

​

The gotcha: reads, lists and mutations must all be scoped

// reads / lists
await repo.find({ where: { tenantId, workspaceId, isDeleted: false } });

// mutations re-scope in the WHERE clause, never trust the id alone
`UPDATE accounting_ledger_entries SET account_id = $1
   WHERE account_id = $2 AND workspace_id = $3 AND tenant_id = $4`

If you add a handler, scope the read, the list, the update, and the delete — not just the insert. A row lookup by id alone (findOne({ where: { id } })) is a cross-tenant/cross-business leak waiting to happen; always include tenantId (and workspaceId/businessId where the entity carries it).

​

Quick checklist for a new accounting endpoint

1. Guard with TenantAuthGuard + AccountingWorkspaceGuard (workspace-routed) or read @BusinessCtx() + requireBusinessId() (business-routed).
2. Take the tenant from @CurrentTenant()/@TenantId() (the signed claim) — never from a header for a normal user.
3. Pass tenantId + workspaceId (and businessId where applicable) into every repository call — find, findOne, update, softDelete.
4. For inbound product postings, resolve the book via AccountingRoutingService with an explicit businessId; let BOOK_ROUTING_AMBIGUOUS surface rather than guessing a book.

​

Gaps / notes for reviewers

• business_id is a real column on a subset of master/internal tables (tax_codes, withholding_codes, withholding_balances, payment_terms, journal_entry_templates, and the posting-internals accounting_intent_outbox / accounting_source_links / accounting_posting_profiles). Transactional rows (invoices, bills, payments, journal entries, ledger entries) do not carry business_id; their owning business is derived from the book via AccountingRoutingService. Confirm the entity’s columns before assuming a businessId filter is available on a given table.
• Row-level scoping is enforced by convention in service/repository code, not by a Postgres RLS policy. There is no database-level tenant guarantee — the application predicates are the guarantee.