@pattern-stack/codegen 0.7.8 → 0.8.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pattern-stack/codegen",
-  "version": "0.7.8",
+  "version": "0.8.1",
   "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,
+  );
+}

package/runtime/subsystems/auth/index.ts

@@ -112,5 +112,13 @@ export {
 // Controller
 export { AuthController } from './controllers/auth.controller';
 
+// Middleware — RequesterContext boundary (bridges auth → ambient tenant scope)
+export {
+  installRequesterContext,
+  makeRequesterContextMiddleware,
+  resolveRequesterContext,
+  type RequesterContextOptions,
+} from './middleware/requester-context';
+
 // Module
 export { AuthModule, type AuthModuleOptions } from './auth.module';

package/runtime/subsystems/auth/middleware/requester-context.ts

@@ -0,0 +1,141 @@
+/**
+ * RequesterContext boundary install — bridges authentication to ambient
+ * tenant scoping.
+ *
+ * This is the missing link that makes `BaseRepository`'s ambient scoping
+ * (see `base-classes/tenant-context.ts`) actually engage on HTTP requests:
+ * it reads the requester off each request (via the consumer-bound
+ * `IUserContext`) and runs the rest of the request inside `withRequester(...)`,
+ * so every downstream repository read/write is automatically scoped — no
+ * threaded `userId`.
+ *
+ * ## Wiring (one line in your bootstrap)
+ *
+ * In `main.ts`, after `NestFactory.create`:
+ *
+ * ```ts
+ * import { installRequesterContext } from './shared/subsystems/auth/middleware/requester-context';
+ * const app = await NestFactory.create(AppModule);
+ * installRequesterContext(app); // no-op + warn if AUTH_USER_CONTEXT is unbound
+ * ```
+ *
+ * `installRequesterContext` resolves `AUTH_USER_CONTEXT` from the root DI
+ * container (so it sees the binding the consumer provides in AppModule) and
+ * registers a global Express middleware. Pairs with Swagger's `@ApiBearerAuth`
+ * "Authorize" button: paste a token there and every request it sends now flows
+ * through this boundary into a scoped repository call.
+ *
+ * ## Trust + failure model
+ *
+ * - The middleware TRUSTS whatever `IUserContext` returns — authentication and
+ *   authorization (validating the token, deciding which scope a requester may
+ *   claim) are the `IUserContext` implementation's job, exactly as for a
+ *   hand-threaded `userId`.
+ * - When the requester cannot be resolved (no/invalid credentials — e.g. a
+ *   public route, or the OAuth callback itself), the request proceeds WITHOUT
+ *   an ambient context (`onUnresolved: 'unscoped'`, the default). A
+ *   `userTracking` repo in lenient mode then runs unscoped; in strict mode it
+ *   throws downstream — which is correct: unauthenticated callers must not
+ *   reach scoped data. Set `onUnresolved: 'reject'` to fail the request at the
+ *   boundary instead.
+ */
+import type { INestApplication } from '@nestjs/common';
+import {
+  withRequester,
+  type RequesterContext,
+} from '../../../base-classes/tenant-context';
+import { AUTH_USER_CONTEXT } from '../auth.tokens';
+import type { IUserContext } from '../protocols/user-context';
+
+/** Minimal Express-style middleware signature (avoids an `express` dep). */
+type NextFn = (err?: unknown) => void;
+type RequestHandler = (req: unknown, res: unknown, next: NextFn) => void;
+
+export interface RequesterContextOptions {
+  /**
+   * What to do when `IUserContext` cannot resolve a requester (throws, or
+   * returns no `userId`).
+   * - `'unscoped'` (default): proceed without a context — public routes work;
+   *   scoped repos run unscoped (lenient) or throw downstream (strict).
+   * - `'reject'`: fail the request at the boundary (`next(error)`).
+   */
+  onUnresolved?: 'unscoped' | 'reject';
+}
+
+/**
+ * Resolve the ambient context for a request: prefer the richer
+ * `resolveRequester` (org/superuser), else derive plain `'user'` scope from
+ * `getCurrentUserId`. Returns `undefined` when no requester can be determined.
+ */
+export async function resolveRequesterContext(
+  userContext: IUserContext,
+  req: unknown,
+): Promise<RequesterContext | undefined> {
+  if (typeof userContext.resolveRequester === 'function') {
+    const ctx = await userContext.resolveRequester(req);
+    return ctx?.userId ? ctx : undefined;
+  }
+  const userId = await userContext.getCurrentUserId(req);
+  return userId ? { userId, organizationId: null } : undefined;
+}
+
+/**
+ * Build the global middleware. Runs the remainder of the request inside
+ * `withRequester(...)` so the ambient context propagates through every `await`
+ * to downstream repositories.
+ */
+export function makeRequesterContextMiddleware(
+  userContext: IUserContext,
+  options: RequesterContextOptions = {},
+): RequestHandler {
+  const onUnresolved = options.onUnresolved ?? 'unscoped';
+  return (req, _res, next) => {
+    resolveRequesterContext(userContext, req).then(
+      (ctx) => {
+        if (!ctx) {
+          next();
+          return;
+        }
+        // als.run executes its callback synchronously; Express dispatches the
+        // rest of the pipeline inside next(), so all downstream handlers (and
+        // their awaits) inherit this context.
+        withRequester(ctx, async () => {
+          next();
+        });
+      },
+      (err) => {
+        if (onUnresolved === 'reject') {
+          next(err);
+          return;
+        }
+        next();
+      },
+    );
+  };
+}
+
+/**
+ * Register the requester-context boundary on a Nest app. Resolves
+ * `AUTH_USER_CONTEXT` from the root container (so it sees the consumer's
+ * AppModule binding) and installs the global middleware. No-ops with a warning
+ * when `AUTH_USER_CONTEXT` is not bound, so calling it unconditionally in
+ * bootstrap is safe.
+ */
+export function installRequesterContext(
+  app: INestApplication,
+  options: RequesterContextOptions = {},
+): void {
+  const userContext = app.get<IUserContext>(AUTH_USER_CONTEXT, {
+    strict: false,
+  });
+  if (!userContext) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      '[auth] installRequesterContext: AUTH_USER_CONTEXT is not bound — ' +
+        'request scoping NOT installed. Provide an IUserContext under ' +
+        'AUTH_USER_CONTEXT in your AppModule to enable ambient tenant scoping.',
+    );
+    return;
+  }
+  app.use(makeRequesterContextMiddleware(userContext, options));
+}

package/runtime/subsystems/auth/protocols/user-context.ts

@@ -17,6 +17,23 @@
  * dependency on `express` / `fastify` / NestJS request types. The concrete
  * adapter narrows it (e.g. via a `Request` import).
  */
+import type { RequesterContext } from '../../../base-classes/tenant-context';
+
 export interface IUserContext {
   getCurrentUserId(req: unknown): Promise<string>;
+  /**
+   * Optional richer resolution of the full ambient requester context — the
+   * org/superuser dimensions on top of `userId`. When implemented, the
+   * `RequesterContextMiddleware` (see `../middleware/requester-context`) uses
+   * it verbatim to scope reads/writes; when omitted, the middleware falls back
+   * to `{ userId: await getCurrentUserId(req), organizationId: null }` (plain
+   * `'user'` scope).
+   *
+   * Implement this when the app supports org-shared (`'org'`) or admin
+   * (`'superuser'`) data visibility — resolve `organizationId` + the
+   * `orgUserIds` member list here, at the trust boundary, so repositories stay
+   * single-table. AUTHORIZATION (which scope a requester may claim) is the
+   * implementation's responsibility; the repo trusts what this returns.
+   */
+  resolveRequester?(req: unknown): Promise<RequesterContext>;
 }