intra-tenant-scope-architect

name

intra-tenant-scope-architect

description

Design a second mandatory data-scoping axis BELOW the tenant (location / site / region / org-unit / business-unit) for a multi-tenant SaaS — the per-user scope-grant model, the composite row-filter predicate on every scoped table (tenant_id AND scope), which roles are scope-restricted vs tenant-wide, server-derived propagation through app and edge layers, and the migration to add the axis to a live per-tenant schema. Presupposes the tenant boundary; this is a sub-tenant dimension inside ONE tenant, not a new tenant. Use when users in a tenant must see only a subset of its data by an org dimension (a store manager sees one store; a regional lead sees a region; admins see all). Do NOT use for tenant SEMANTICS or tenant hierarchy (tenant-modeler), tenant_id-axis storage strategy (multi-tenant-data-architect), or roles×permissions authz (authorization-matrix-designer). Reshapes live schema — DESIGNS the migration, does not run it.

Intra-Tenant Scope Architect

Purpose

Design a second mandatory scoping axis below the tenant — a location, site, region, org-unit, or business-unit dimension by which users inside a single tenant see only a subset of that tenant's data. The deliverable is the scope model, a per-user scope-grant model, a classification of roles into scope-restricted vs tenant-wide, the composite row-filter predicate that every scoped table carries (tenant_id = current_tenant AND (scope in granted_scopes OR user is tenant-wide)), the server-side propagation contract through app and edge layers, and the migration to add the axis to a live per-tenant schema. The discipline mirrors tenant scoping one level down: deny-by-default on scope, scope derived server-side from a grant model, never from the client. This presupposes the tenant boundary already works — it adds a dimension inside a tenant, it does not define or replace the tenant.

Use When

• Use when: within one tenant, users must be restricted to a SUBSET of that tenant's data along a stable organizational dimension — a store manager sees one store, a regional lead sees a region, HQ/tenant-admins see everything.
• Use when: retrofitting a site/region/org-unit filter onto an existing per-tenant schema where today every member of a tenant sees all of it.
• Use when: deciding which roles are scope-restricted vs tenant-wide and how a user's scope set is assigned and propagated to every query.
• Do NOT use when: the question is what a tenant IS, or a parent/child tenant hierarchy — that is tenant-modeler; a child tenant is a separate tenant with its own boundary, whereas a scope is a filter WITHIN one tenant.
• Do NOT use when: designing the tenant-scoped data layer around tenant_id itself (per-store pooled/siloed strategy, the tenant propagation contract) — that is multi-tenant-data-architect; this skill adds a subordinate axis and presupposes that layer.
• Do NOT use when: designing roles × permissions × resources — what a role CAN do, object-level authz — that is authorization-matrix-designer; a scope is a propagated ROW-FILTER dimension, not a permission. The same role can be held by two users with different scopes.
• Do NOT use when: the "scope" is really an ad-hoc share of one record with a colleague (share-link-access-architect / member sharing), not a standing organizational axis.

Inputs to Inspect

1. The tenant model (tenant-modeler output): confirm the org dimension is a sub-tenant axis, not a separate tenant — and whether it already exists.
2. The existing per-tenant schema: which tables hold tenant data, where tenant_id enforcement lives today, and whether a site/unit column exists.
3. The role model: which roles should be scope-restricted (see only granted scopes) vs tenant-wide (see the whole tenant — admin, owner, auditor).
4. How a user is associated with a site/region/unit today, if at all — the raw material for the scope-grant model.
5. The app and edge layers that build queries (middleware, ORMs, an edge/gateway that constructs filters) — every place scope must propagate.
6. Reference/shared data within the tenant that is deliberately tenant-wide (not scoped) — so the predicate isn't wrongly applied to it.

Workflow

1. Confirm the axis is real, mandatory, and organizational. It must be a stable dimension (site/region/unit), not an ad-hoc filter. If it is a separate legal/data boundary, it is a child TENANT (tenant-modeler); if it is "share this one record with a colleague," it is a sharing grant (share-link-access-architect/authorization-matrix-designer). Stop and reroute if either is true.
2. Model the scope dimension. The scope entity (site/region/unit), its relationship to the tenant (a scope belongs to exactly one tenant), and whether scopes nest (region → site) — nesting changes the predicate.
3. Design the per-user scope-grant model. A user is granted one or more scope values within their tenant; state how a new user gets a default scope and how grants are added/revoked. This grant set is the source of truth the predicate reads — it is not stored on the client.
4. Classify roles. Split roles into scope-restricted (filtered to granted scopes) vs tenant-wide (bypass the scope filter — admin/owner/auditor). This exception is load-bearing; name it explicitly and keep the tenant-wide set small and audited.
5. Write the composite row-filter predicate. Every scoped table carries the scope key and enforces tenant_id = current_tenant AND (scope_id = ANY(current_user_scopes) OR current_user_is_tenant_wide) — deny-by-default on scope exactly as tenant scoping is deny-by-default on tenant. List which tables are scoped vs deliberately tenant-wide.
6. Define server-side propagation. The user's scope set is derived server-side from the grant model, bound once per request/job like tenant context, and carried to every query — including any edge/gateway layer that builds filters. A client-supplied scope value is the intra-tenant IDOR; forbid it by contract.
7. Plan the live migration. Add the scope column (nullable → backfill → NOT NULL), assign existing users a scope set, add the composite predicate in shadow, verify per-scope counts, then enforce. This reshapes a live schema — this skill DESIGNS the migration; it does not run it. Defer the RLS policy SQL correctness to rls-policy-auditor; here the axis and predicate SHAPE are the deliverable.

Output Format

INTRA-TENANT SCOPE DESIGN — <product/tenant model>
Axis confirmed: <site/region/unit; NOT a child tenant, NOT a sharing grant>
Scope model: <scope entity → belongs to one tenant; nesting? region→site>
Per-user scope-grant model: <how users are granted scopes; default; revoke>
Role classification: <scope-restricted roles | tenant-wide (bypass) roles>
Composite predicate (every scoped table): tenant_id = current_tenant AND
  (scope_id = ANY(current_user_scopes) OR current_user_is_tenant_wide)
Scoped vs tenant-wide tables: <which carry the scope key; which don't and why>
Propagation contract: <scope set derived server-side, bound once, carried to
  app + edge queries; client-supplied scope forbidden>
Live migration: <add column → backfill → assign scopes → shadow predicate →
  verify per-scope counts → enforce — DESIGNED, not executed>
Open questions / risks: <each with risk-if-wrong / who answers>

Validation Checklist

• The axis is confirmed a sub-tenant organizational dimension, not a child tenant and not an ad-hoc share.
• Every scoped table carries the scope key and the composite predicate; tenant-wide/reference tables are explicitly listed as not scoped.
• The predicate is deny-by-default on scope; tenant-wide roles bypass it through a named, small, audited exception — not an implicit hole.
• The user's scope set is derived server-side from the grant model and bound once per request; no query trusts a client-supplied scope value.
• Propagation reaches the edge/gateway layer too, not just the app layer.
• The migration is expand → backfill → shadow → verify → enforce, each step reversible; it is designed, not executed.
• RLS policy SQL correctness is deferred to rls-policy-auditor; this delivers the axis and predicate shape.

Tenant Isolation Rules

• The scope axis is SUBORDINATE to the tenant axis — it filters within a tenant and never crosses one. The predicate always keeps tenant_id = current_tenant as the outer condition; scope is the inner one.
• Scope, like tenant, is derived server-side from the authenticated principal's grants — never from request bodies, query params, or headers.
• Deny-by-default on scope: a scoped row with no matching grant is invisible, the same posture as an out-of-tenant row.
• Tenant-wide bypass is an enumerated exception, not a default: the roles that see the whole tenant are listed, kept minimal, and their broad reads audited.
• A missed scoped table is an intra-tenant leak — the isolation test matrix covers every scoped table, mirroring the tenant-layer matrix one level down.

Gotchas

• The tenant-wide exception is forgotten in the predicate, so admins get locked out of their own tenant — or it is written too broadly and every role bypasses scope. Get this one clause exactly right.
• One scoped table is missed and it becomes the intra-tenant leak — the same failure mode as an unscoped store at the tenant layer, one level down.
• A client-supplied scope value is trusted "because the UI already filters" — that is the intra-tenant IDOR in its purest form.
• Scopes that should nest (a region contains sites) but are modeled flat, so a regional lead can't see their own sites without a grant per site.
• Confusing a scope (a filter inside one tenant) with a child tenant (a separate boundary) — the two have opposite data-sharing defaults.
• The edge/gateway layer builds a query without the scope filter because propagation stopped at the app layer — every query-building layer must carry it.

Stop Conditions

• The axis turns out to be a child TENANT (separate legal/data boundary) → stop; route to tenant-modeler. It is not a scope.
• The axis turns out to be an ad-hoc share of specific records → route to share-link-access-architect or member sharing in authorization-matrix-designer; a scope is a standing organizational axis.
• The migration must run against a live schema (add NOT NULL column, backfill, flip the predicate) → this skill DESIGNS it; executing follows human-approval-boundary. Do not run it.
• The tenant boundary itself is undefined or contested → tenant-modeler first; a subordinate axis on an undefined boundary is confident nonsense.

Supporting Files

• evals/evals.json — behavior cases: the add-a-site-axis design, the child-tenant-not-a-scope refusal, the tenant-wide-bypass edge, and the client-supplied-scope IDOR catch.
• evals/trigger-evals.json — discrimination against tenant-modeler (tenant semantics/hierarchy), multi-tenant-data-architect (tenant_id-axis storage strategy), and authorization-matrix-designer (roles×permissions vs a row-filter dimension).
• No references/ — the grant model, predicate, and migration above are the complete procedure; detail lives in the produced artifacts.