@aiquants/authz-react-router 0.7.2 → 0.8.0

package/README.md

@@ -45,10 +45,20 @@ const authz = createAuthz({
   appKey: "myapp",
   // request → your user id (or null → checked against "@anonymous" permissions)
   resolveUserId: async (request) => (await getSessionUser(request))?.id ?? null,
+  // request → the tenant this request acts within (subdomain / header / session). REQUIRED.
+  // Fail fast: `?? "default"` would authorize a session-less request inside the default tenant.
+  resolveTenantId: async (request) => {
+    const user = await getSessionUser(request)
+    if (!user?.tenantId) throw new Response("tenant unresolved", { status: 400 })
+    return user.tenantId
+  },
+  // request + tenant → may this caller act AS that tenant? REQUIRED, and never `() => true`:
+  // resolveTenantId only says WHICH tenant was named, which on every transport the client can influence.
+  assertTenantMembership: async (request, tenantId) => (await getSessionUser(request))?.tenantId === tenantId,
   // load + merge this user's grants for MANY resources in one round-trip
   getEffectivePermissions: (args) => getEffectivePermissionsMany(db, authzTables, args),
-  // optional: lets `getMyPermissions(request)` report on every registered resource
-  listResourceKeys: () => listResourceKeys(db, authzTables, "myapp"),
+  // optional: lets `getMyPermissions(request)` report on every registered resource of that tenant
+  listResourceKeys: (_request, tenantId) => listResourceKeys(db, authzTables, "myapp", tenantId),
 })
 
 export const { requirePermission, getMyPermissions } = authz
@@ -56,6 +66,24 @@ export const { requirePermission, getMyPermissions } = authz
 
 > If your DB pool can be cold at the first request (serverless / lazy connect), have `resolveUserId` and `getEffectivePermissions` await a connection-ready guard first — otherwise a cold-start DB error can surface as a misleading 403 instead of a 500.
 
+> **Tenancy is not optional.** Every check happens inside exactly one tenant, so `resolveTenantId` is a required port and
+> its result must be a non-empty string. Returning `""` / `null` raises `AuthzTenantError` **before** the permission port
+> is consulted — it never degrades into "no filter", which would hand the caller every tenant's grants. The guard also
+> verifies that the permission it received was issued for the requested tenant and denies (`reason: "tenant-mismatch"`)
+> when it was not, so a store that forgets its predicate cannot turn into cross-tenant access.
+>
+> **Naming a tenant is not the same as belonging to it.** `resolveTenantId` answers *which* tenant the request named, and
+> on every transport that name is ultimately client-influenced (a header, a sub-domain, a cookie). `assertTenantMembership`
+> is therefore also required, with no permissive default: without it a user of tenant A is authorized inside tenant B by
+> simply naming tenant B — B's `@authenticated` grants apply, and every tenant check still passes because the permission
+> genuinely belongs to B. It is consulted **before** any permission is loaded and denies with `reason:
+> "not-a-tenant-member"`. `userId` is `null` for an anonymous caller; a tenant's `@anonymous` grants are public by
+> construction, so returning `true` there is the usual answer.
+>
+> Do **not** substitute a fallback tenant (`?? "default"`). A request that cannot name its tenant is a request that must
+> not be authorized — substituting one silently moves the missing-tenant-means-all-tenants inversion out of the library
+> and into every consumer.
+
 **Step 2 — guard a loader/action, apply scope, and render the badge.** On allow you get `{ userId, scope, permission }` from a **single** evaluation, so you can authorize, narrow the data, *and* tell the user what they may do — without asking the database a second time.
 
 ```ts
@@ -84,7 +112,7 @@ export async function loader({ request }: { request: Request }) {
 **Step 3 — register the resource + grant.** Insert a `TMResource('myapp','report')` and a `TDRolePermission` for the role(s) that should see it. Either run SQL, or build a tiny admin screen with the CRUD helpers (see the host app's admin guide). Example grant: "role `viewer` may `read` report, rows where dept ∈ {A}, hiding the amount column":
 
 ```sql
--- row_scope / column_scope are the §3.2 JSON from @aiquants/authz-core
+-- row_scope / column_scope are the scope-contract JSON from @aiquants/authz-core
 INSERT INTO dbo_authz.TDRolePermission (role_id, resource_id, action, row_scope, column_scope)
 SELECT r.id, res.id, 'read',
        N'{"filters":[{"field":"dept","op":"in","values":["A"]}]}',
@@ -122,7 +150,7 @@ import { MyPermissionIndicator, MyPermissionStatus } from "@aiquants/authz-react
 > ⚠️ Unlike the admin shell's `labels`, these two components ship **Japanese** defaults (`"あなたの権限"`, `"閲覧"` /
 > `"編集"` / `"削除"`, `"部分制限"`, and the `対象リソース: …` tooltip). Pass `prefixLabel` and `labels` to localize them.
 
-## Scope cheat-sheet (§3.2)
+## Scope cheat-sheet (row / column scope contract)
 
 The JSON you put in `row_scope` / `column_scope` (full contract in `@aiquants/authz-core`):
 
@@ -137,12 +165,14 @@ Multiple roles **union** (wider wins): rows OR'd (any `NULL` ⇒ all rows); colu
 
 ## API
 
-- `createAuthz({ appKey, resolveUserId, resolveGroupIds?, getEffectivePermissions, listResourceKeys?, onDeny? })` → `{ requirePermission, getMyPermissions }`.
-- `getEffectivePermissions({ userId, groupIds?, appKey, resourceKeys })` → `Record<resourceKey, EffectivePermission | null>`. **One call, many resources** — pair it with `getEffectivePermissionsMany` from `@aiquants/authz-drizzle` and N resources cost one round-trip. Keys the port omits are treated as "no permission" (fail-close).
-- `listResourceKeys(request)` → every resource key registered for the app. Optional; configuring it is what makes the no-argument `getMyPermissions(request)` legal. Without it that call throws `AuthzUsageError` naming both remedies instead of guessing.
-- `resolveGroupIds(request)` → the acting user's group ids. Forwarded automatically to `getEffectivePermissions` by both `requirePermission` and `getMyPermissions`, so group-granted roles count toward effective permissions. Returning `null`/`undefined` (or omitting the port) sends no `groupIds` at all.
+- `createAuthz({ appKey, resolveUserId, resolveTenantId, assertTenantMembership, resolveGroupIds?, getEffectivePermissions, listResourceKeys?, onDeny? })` → `{ requirePermission, getMyPermissions }`.
+- `resolveTenantId(request)` → the tenant id this request acts within. **Required, non-empty**; forwarded to every `getEffectivePermissions` call and returned by `requirePermission`. A blank result throws `AuthzTenantError`.
+- `assertTenantMembership(request, tenantId, userId)` → may this caller act **as** that tenant? **Required**, no permissive default; consulted before any permission is loaded, and `false` denies with `reason: "not-a-tenant-member"` (and reports no permissions at all from `getMyPermissions`).
+- `getEffectivePermissions({ userId, tenantId, groupIds?, appKey, resourceKeys })` → `Record<resourceKey, EffectivePermission | null>`. **One call, many resources** — pair it with `getEffectivePermissionsMany` from `@aiquants/authz-drizzle` and N resources cost one round-trip. Keys the port omits are treated as "no permission" (fail-close).
+- `listResourceKeys(request, tenantId)` → every resource key registered for the app **within that tenant**. Optional; configuring it is what makes the no-argument `getMyPermissions(request)` legal. Without it that call throws `AuthzUsageError` naming both remedies instead of guessing. The tenant arrives already resolved and validated, so a host never derives it a second time.
+- `resolveGroupIds(request, tenantId)` → the acting user's group ids within that tenant. Forwarded automatically to `getEffectivePermissions` by both `requirePermission` and `getMyPermissions`, so group-granted roles count toward effective permissions. Returning `null`/`undefined` (or omitting the port) sends no `groupIds` at all.
   ⚠️ Without this port, roles assigned to groups in the admin UI have **no runtime effect** — the store writes succeed and the UI looks correct, so the failure is silent. Cover the wiring with a test.
-- `requirePermission(request, {resourceKey, action}, options?)` → `{ userId, scope, permission }` on allow: the scope for row WHERE / column mask, **and** the `PermissionView` derived from the very same evaluation (no second lookup, so the guard and the badge can never disagree). Denies throw `AuthzDeniedError` (403), or `throw redirect(options.failureRedirect)` when set. A malformed query (blank `resourceKey`, unknown `action`, or the derived `"write"`) throws `AuthzUsageError` before anything is loaded — a mistake surfaces as a 500 you can read, never as a mysterious 403.
+- `requirePermission(request, {resourceKey, action}, options?)` → `{ userId, tenantId, scope, permission }` on allow: the scope for row WHERE / column mask, **and** the `PermissionView` derived from the very same evaluation (no second lookup, so the guard and the badge can never disagree). Denies throw `AuthzDeniedError` (403), or `throw redirect(options.failureRedirect)` when set. A malformed query (blank `resourceKey`, unknown `action`, or the derived `"write"`) throws `AuthzUsageError` before anything is loaded — a mistake surfaces as a 500 you can read, never as a mysterious 403.
 - `getMyPermissions(request, {resourceKeys})` → `Record<K, PermissionView>` where `K` is the literal union of the keys you passed, so an unrequested key is a **compile error** rather than a runtime `undefined`. `getMyPermissions(request)` reports on every registered resource (requires `listResourceKeys`). Duplicate keys collapse; an empty list asks the database nothing.
   ⚠️ The no-argument form's result **keys are your app's resource inventory**. Every value is still evaluated fail-closed (an unauthenticated caller gets all-false views), but do not hand the whole map to an unauthenticated client if the resource names themselves are sensitive — name the resources you actually render instead.
 - `AuthzUsageError` — thrown for API misuse (missing/ill-typed arguments, missing port). Deliberately distinct from `AuthzDeniedError`: misuse must not masquerade as a denial.
@@ -174,7 +204,11 @@ Two rules make the whole surface predictable, and both exist because their absen
 | `requireAndGetPermission(request, query)` | `requirePermission(request, query)` — it already returns `permission` |
 | `getEffectivePermissions: (args) => …(args.resourceKey)` (one resource) | `getEffectivePermissions: (args) => …(args.resourceKeys)` returning a record (many resources) |
 | `createAuthzAdminApp({ …, getMyPermissions })` | port removed — the admin shell reads its badge off the guard |
-| `createAuthzAdminApp({ requirePermission })` resolving to `{ userId }` | must now resolve to `{ userId, permission }` — pass `createAuthz`'s `requirePermission` directly, or add `permission` to a hand-rolled guard |
+| `createAuthzAdminApp({ requirePermission })` resolving to `{ userId }` | must now resolve to `{ userId, tenantId, permission }` — pass `createAuthz`'s `requirePermission` directly, or add both fields to a hand-rolled guard |
+| `createAuthz({ … })` without `resolveTenantId` | the port is **required**; omitting it throws `AuthzUsageError` at factory time |
+| `createAuthz({ … })` without `assertTenantMembership` | also **required**; naming a tenant never proves membership in it, so omitting it throws `AuthzUsageError` at factory time |
+| `getEffectivePermissions({ userId, appKey, resourceKeys })` | `tenantId` is now always present and non-empty — scope your query by it (never treat its absence as "all tenants") |
+| `AuthzAdminStore` methods called without a tenant (`listRoles()`, `deleteRole(id)`, …) | every method takes a required `tenantId` first (`listRoles(tenantId)`, `deleteRole(tenantId, id)`); `RoleInput` / `RoleUpdate` / `ResourceInput` / `GrantInput` also name their target tenant |
 | `usePermission(view)` → `{ canRead, canWrite, canDelete, …States }` | adds `canCreate` / `canUpdate`, so it is a superset of the view's booleans |
 | `expectedResourceKey?: string` on the indicator components | now `NoInfer<K>` — bound to the permission's own key, so a mismatch is a compile error (0.6.x code that deliberately passed a different key stops compiling) |
 | `createAuthzAdminServer(...).loadMyPermissions` | removed — `layoutGuard` returns `{ userId, myPermissions }` from the guard it already runs |
@@ -200,6 +234,21 @@ The splat-mounted admin app (`createAuthzAdminApp`) serves `roles`, `resources`,
 
 Reads require `read` on the admin resource; writes require the verb matching their effect (`create` / `update` / `delete`).
 
+### Tenancy in the admin UI
+
+The whole screen is scoped to the tenant `resolveTenantId` returned for the request — the shell shows it
+(`data-testid="authz-tenant-badge"`), every table has a tenant column, and the create-role / create-resource /
+create-grant forms carry a `tenantId` field prefilled with it.
+
+Two rules make that more than decoration:
+
+- **The form's tenant never widens the request's.** A submitted `tenantId` states which tenant the payload targets; it is
+  compared with the guard's tenant and a mismatch is refused with 403. Neither side is preferred.
+- **Every mutation re-checks ownership server-side.** Ids arrive from a form, so before writing, the target row is loaded
+  within the tenant and its **own** `tenantId` compared. A filtered list is not an authorization check: if the store ever
+  dropped its predicate, every id in the database would look owned. A row that is absent *or* foreign is refused
+  identically (403), so the screen cannot be used to probe which ids exist in another tenant.
+
 ## Demo App
 
 This package contains an interactive React Router 7 SPA demo in the `demo/` subdirectory. The demo app runs completely in the browser, using `localStorage` to mock database storage.