@pattern-stack/codegen 0.7.8 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pattern-stack/codegen",
-  "version": "0.7.8",
+  "version": "0.8.0",
   "description": "Entity-driven code generation for full-stack TypeScript applications",
   "license": "MIT",
   "type": "module",

package/runtime/base-classes/base-repository.ts

@@ -9,10 +9,15 @@
  *
  * NOT @Injectable — concrete repositories are @Injectable and inject DRIZZLE.
  */
-import { eq, inArray, isNull, sql } from 'drizzle-orm';
+import { and, eq, inArray, isNull, sql } from 'drizzle-orm';
 import type { PgTableWithColumns, PgColumn } from 'drizzle-orm/pg-core';
 import type { SQL } from 'drizzle-orm';
 import type { DrizzleClient, DrizzleTx } from '../types/drizzle';
+import {
+  requireRequester,
+  tryGetRequester,
+  type RequesterScope,
+} from './tenant-context';
 
 // ============================================================================
 // Interfaces
@@ -59,6 +64,21 @@ export abstract class BaseRepository<TEntity> {
     userTracking: false,
   };
 
+  /**
+   * Ambient tenant-scope enforcement for `userTracking` repos (see
+   * `scopePredicate`). Only has effect when `behaviors.userTracking === true`.
+   *
+   * - `'lenient'` (default): when no ambient requester context is active,
+   *   reads/writes are NOT scoped — preserves pre-scoping behavior, so adopting
+   *   ambient scoping is additive. Scoping kicks in automatically once a
+   *   boundary installs `withRequester(...)`.
+   * - `'strict'`: a missing ambient context throws (`requireRequester`),
+   *   making a forgotten boundary fail loud instead of silently returning
+   *   cross-tenant rows. Recommended for new multi-tenant consumers — override
+   *   in a concrete repo or a family base class.
+   */
+  protected readonly scopeEnforcement: 'lenient' | 'strict' = 'lenient';
+
   protected readonly db: DrizzleClient;
 
   constructor(db: DrizzleClient) {
@@ -85,9 +105,7 @@ export abstract class BaseRepository<TEntity> {
    * Returns null if not found (or soft-deleted when softDelete=true).
    */
   async findById(id: string): Promise<TEntity | null> {
-    const rows = await this.baseQuery()
-      .where(eq(this.table['id'], id))
-      .limit(1);
+    const rows = await this.baseQuery(eq(this.table['id'], id)).limit(1);
     return (rows[0] as TEntity) ?? null;
   }
 
@@ -97,7 +115,7 @@ export abstract class BaseRepository<TEntity> {
    */
   async findByIds(ids: string[]): Promise<TEntity[]> {
     if (ids.length === 0) return [];
-    const rows = await this.baseQuery().where(inArray(this.table['id'], ids));
+    const rows = await this.baseQuery(inArray(this.table['id'], ids));
     return rows as TEntity[];
   }
 
@@ -105,11 +123,8 @@ export abstract class BaseRepository<TEntity> {
    * List entities with optional filtering, pagination, and ordering.
    */
   async list(options?: ListOptions): Promise<TEntity[]> {
-    let query = this.baseQuery();
+    let query = this.baseQuery(options?.where);
 
-    if (options?.where) {
-      query = query.where(options.where) as typeof query;
-    }
     if (options?.orderBy) {
       query = query.orderBy(options.orderBy as SQL) as typeof query;
     }
@@ -137,6 +152,10 @@ export abstract class BaseRepository<TEntity> {
     if (this.behaviors.softDelete) {
       conditions.push(isNull(this.table['deletedAt']));
     }
+    const scope = this.scopePredicate();
+    if (scope) {
+      conditions.push(scope);
+    }
     if (where) {
       conditions.push(where);
     }
@@ -144,8 +163,6 @@ export abstract class BaseRepository<TEntity> {
     if (conditions.length === 1) {
       query = query.where(conditions[0]) as typeof query;
     } else if (conditions.length > 1) {
-      // Combine with AND by building the condition inline
-      const { and } = await import('drizzle-orm');
       query = query.where(and(...conditions)) as typeof query;
     }
 
@@ -186,7 +203,7 @@ export abstract class BaseRepository<TEntity> {
     const rows = await this.runner(tx)
       .update(this.table)
       .set(data as any) // eslint-disable-line @typescript-eslint/no-explicit-any
-      .where(eq(this.table['id'], id))
+      .where(this.scopeAnd(eq(this.table['id'], id)))
       .returning();
     return rows[0] as TEntity;
   }
@@ -202,11 +219,11 @@ export abstract class BaseRepository<TEntity> {
       await runner
         .update(this.table)
         .set({ deletedAt: new Date() } as any) // eslint-disable-line @typescript-eslint/no-explicit-any
-        .where(eq(this.table['id'], id));
+        .where(this.scopeAnd(eq(this.table['id'], id)));
     } else {
       await runner
         .delete(this.table)
-        .where(eq(this.table['id'], id));
+        .where(this.scopeAnd(eq(this.table['id'], id)));
     }
   }
 
@@ -224,15 +241,74 @@ export abstract class BaseRepository<TEntity> {
   // ============================================================================
 
   /**
-   * Base SELECT query that automatically excludes soft-deleted rows
-   * when softDelete behavior is enabled.
+   * Base SELECT query that automatically applies the ambient guards —
+   * soft-delete exclusion (when `softDelete`) and tenant scope (when
+   * `userTracking` + an active requester context) — combined with an optional
+   * caller `extra` predicate into a SINGLE `WHERE`.
+   *
+   * Pass the leaf predicate as `extra` rather than chaining a second
+   * `.where(...)`: Drizzle's `.where()` OVERRIDES (does not AND) a prior
+   * `.where()` on a `$dynamic()` query, so a chained call would silently drop
+   * the soft-delete and scope guards. `baseQuery(extra)` is the safe form.
    */
-  protected baseQuery() {
+  protected baseQuery(extra?: SQL) {
     const query = this.db.select().from(this.table).$dynamic();
-    if (this.behaviors.softDelete) {
-      return query.where(isNull(this.table['deletedAt']));
+    const where = this.scopeAnd(extra, { softDelete: this.behaviors.softDelete });
+    return where ? query.where(where) : query;
+  }
+
+  /**
+   * Build the ambient tenant-scope predicate for this repo's table.
+   *
+   * Returns `undefined` (no scoping) when:
+   *   - `behaviors.userTracking` is false (repo is not user-owned), or
+   *   - no ambient requester context is active AND `scopeEnforcement` is
+   *     `'lenient'` (the default — preserves pre-scoping behavior).
+   *
+   * When a requester context is active, scopes by `user_id` per the ambient
+   * scope: `'user'` → `user_id = ctx.userId`; `'org'` → `user_id IN
+   * ctx.orgUserIds` (empty list matches nothing — fail-closed); `'superuser'`
+   * → no filter. See `tenant-context.ts` for the boundary-install contract.
+   */
+  protected scopePredicate(): SQL | undefined {
+    if (!this.behaviors.userTracking) return undefined;
+    const ctx =
+      this.scopeEnforcement === 'strict'
+        ? requireRequester()
+        : tryGetRequester();
+    if (!ctx) return undefined;
+    const scope: RequesterScope = ctx.scope ?? 'user';
+    switch (scope) {
+      case 'superuser':
+        return undefined;
+      case 'org':
+        return ctx.orgUserIds && ctx.orgUserIds.length > 0
+          ? inArray(this.table['userId'], ctx.orgUserIds as string[])
+          : sql`false`;
+      case 'user':
+      default:
+        return eq(this.table['userId'], ctx.userId);
     }
-    return query;
+  }
+
+  /**
+   * Combine the ambient scope predicate (and, optionally, the soft-delete
+   * guard) with a caller `extra` predicate into one `SQL`. Returns `undefined`
+   * when nothing applies. Used by read + by-id write paths so a single
+   * `.where(...)` carries every guard.
+   */
+  protected scopeAnd(
+    extra?: SQL,
+    opts?: { softDelete?: boolean },
+  ): SQL | undefined {
+    const conditions: SQL[] = [];
+    if (opts?.softDelete) conditions.push(isNull(this.table['deletedAt']));
+    const scope = this.scopePredicate();
+    if (scope) conditions.push(scope);
+    if (extra) conditions.push(extra);
+    if (conditions.length === 0) return undefined;
+    if (conditions.length === 1) return conditions[0];
+    return and(...conditions);
   }
 
   /**

package/runtime/base-classes/index.ts

@@ -4,6 +4,19 @@
 export { BaseRepository } from './base-repository';
 export type { BehaviorConfig, ListOptions } from './base-repository';
 
+// Ambient tenant scope (AsyncLocalStorage) — read by BaseRepository.scopePredicate,
+// set at request/worker boundaries via withRequester/withUserScope/etc.
+export {
+  withRequester,
+  requireRequester,
+  tryGetRequester,
+  requireRequesterScope,
+  withUserScope,
+  withOrgScope,
+  withSuperuserScope,
+} from './tenant-context';
+export type { RequesterContext, RequesterScope } from './tenant-context';
+
 export { BaseService } from './base-service';
 export type { IBaseRepository } from './base-service';
 

package/runtime/base-classes/tenant-context.ts

@@ -0,0 +1,175 @@
+/**
+ * Ambient requester context — AsyncLocalStorage-backed tenant scope.
+ *
+ * The alternative to threading `userId`/`organizationId` through every
+ * repository/service signature. Set ONCE at each boundary the generated app
+ * owns, read implicitly inside `BaseRepository` (see `scopePredicate`).
+ *
+ * ## Where to set it (boundaries)
+ *
+ *   - HTTP / tRPC handlers — from the authenticated `ctx.user`
+ *   - OAuth callback controllers — from the authenticated session
+ *   - Queue/worker `process()` — from the job's owning user after the
+ *     job's record is loaded
+ *
+ * Each boundary wraps the rest of the request in `withRequester({ userId,
+ * organizationId }, () => ...)`. The context propagates through every `await`
+ * to all downstream repo/service calls without being passed explicitly.
+ *
+ * ## Where to read it
+ *
+ *   - `BaseRepository.scopePredicate()` reads it (via `tryGetRequester` in
+ *     lenient mode, `requireRequester` in strict mode) and filters every read
+ *     by the ambient scope when the repo declares `userTracking: true`.
+ *
+ * ## Why AsyncLocalStorage over an explicit parameter
+ *
+ * Threading `userId` (and later `organizationId`) through dozens of method
+ * signatures is pure parameter pollution. Ambient context also lets a repo
+ * make the "I forgot to scope" mistake impossible at runtime: in strict mode
+ * `requireRequester()` throws when no context is active, surfacing a missing
+ * boundary call loudly rather than silently leaking cross-tenant data.
+ *
+ * ## Not-found semantics
+ *
+ * When a row exists but belongs to a different requester, scoped reads return
+ * `null`/`[]` — identical to "truly doesn't exist". No existence oracle;
+ * callers throw NotFound uniformly. Standard security practice.
+ *
+ * ## Testing
+ *
+ * Tests that exercise scoped repos must wrap the call in `withRequester(...)`.
+ * In strict mode an unwrapped call hitting `requireRequester()` throws — by
+ * design. In lenient mode (the default) an unwrapped call is simply unscoped.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+/**
+ * Data-visibility scope. The auth layer decides which scope a request is
+ * allowed to claim; the repo trusts whatever the ambient context says.
+ *
+ * - `'user'`: filter every read by `user_id = ctx.userId`. Default.
+ * - `'org'`: filter every read by membership in the requester's org, resolved
+ *   via `user_id IN (ctx.orgUserIds)` rather than via a per-entity
+ *   `organization_id` column. Works for every user-owned table and keeps repos
+ *   single-table — the org member list is pre-resolved at the boundary.
+ * - `'superuser'`: no scope filter. Engineering / internal-tools only.
+ *
+ * AUTHORIZATION (who is allowed to claim each scope) lives in boundary
+ * middleware, not in the repo. The repo trusts the ambient context — same
+ * trust model as a threaded `userId`.
+ */
+export type RequesterScope = 'user' | 'org' | 'superuser';
+
+export interface RequesterContext {
+  /**
+   * The user making the request. Always present — even in `'org'` and
+   * `'superuser'` scopes it is the audit-trail "who actually did this".
+   */
+  readonly userId: string;
+  /**
+   * The organization the requester belongs to. Required when
+   * `scope === 'org'`; may be null for `'user'` (users with no org) and for
+   * `'superuser'` (cross-org reads).
+   */
+  readonly organizationId: string | null;
+  /**
+   * Data-visibility scope. Defaults to `'user'` when omitted.
+   */
+  readonly scope?: RequesterScope;
+  /**
+   * For `scope === 'org'`: the list of user IDs in the requester's org,
+   * pre-resolved by the boundary middleware that established the `'org'`
+   * scope (one `SELECT users.id WHERE organization_id = X` at the trust
+   * boundary). Repos use this as a literal `IN (...)` filter — they never
+   * JOIN to `users` themselves. Required when `scope === 'org'`.
+   */
+  readonly orgUserIds?: readonly string[];
+}
+
+const als = new AsyncLocalStorage<RequesterContext>();
+
+/**
+ * Set the ambient requester context for the duration of `fn`. The context
+ * propagates through `await` boundaries to all downstream calls. Nesting is
+ * fine — an inner `withRequester` overrides the outer for its callback.
+ */
+export function withRequester<T>(
+  ctx: RequesterContext,
+  fn: () => Promise<T>,
+): Promise<T> {
+  return als.run(ctx, fn);
+}
+
+/**
+ * Read the ambient requester context. Throws if no context is active — by
+ * design. Used by repos in strict scope-enforcement mode; an unwrapped call
+ * site is a missing boundary.
+ */
+export function requireRequester(): RequesterContext {
+  const ctx = als.getStore();
+  if (!ctx) {
+    throw new Error(
+      'No requester context active. Wrap the entry point in ' +
+        'withRequester({ userId, organizationId }, fn). See tenant-context.ts.',
+    );
+  }
+  return ctx;
+}
+
+/**
+ * Read the ambient requester context without throwing. Returns `undefined`
+ * when no context is active. Used by repos in lenient scope-enforcement mode
+ * (the default) and by code paths that legitimately run outside a request.
+ */
+export function tryGetRequester(): RequesterContext | undefined {
+  return als.getStore();
+}
+
+/**
+ * Resolve the effective scope for the ambient context, defaulting to `'user'`.
+ */
+export function requireRequesterScope(): RequesterScope {
+  return requireRequester().scope ?? 'user';
+}
+
+/**
+ * Convenience helpers for setting scope explicitly. All three preserve
+ * `userId` in the context (audit trail) regardless of scope.
+ *
+ * - `withUserScope`: regular end-user requests. Most call sites.
+ * - `withOrgScope`: admin / org-shared resource access. The caller MUST verify
+ *   the requester's role permits `'org'` before calling — the helper does not
+ *   enforce authorization. `orgUserIds` is pre-resolved at the boundary.
+ * - `withSuperuserScope`: engineering scripts / internal tools. `organizationId`
+ *   is null (cross-org is the point). Same authorization caveat applies.
+ */
+export function withUserScope<T>(
+  userId: string,
+  organizationId: string | null,
+  fn: () => Promise<T>,
+): Promise<T> {
+  return withRequester({ userId, organizationId, scope: 'user' }, fn);
+}
+
+export function withOrgScope<T>(
+  userId: string,
+  organizationId: string,
+  orgUserIds: readonly string[],
+  fn: () => Promise<T>,
+): Promise<T> {
+  return withRequester(
+    { userId, organizationId, scope: 'org', orgUserIds },
+    fn,
+  );
+}
+
+export function withSuperuserScope<T>(
+  userId: string,
+  fn: () => Promise<T>,
+): Promise<T> {
+  return withRequester(
+    { userId, organizationId: null, scope: 'superuser' },
+    fn,
+  );
+}