@happyvertical/smrt-tenancy 0.30.0

package/dist/context.d.ts

@@ -0,0 +1,435 @@
+import { DatabaseInterface } from '@happyvertical/sql';
+/**
+ * Full data stored in tenant context for the current async execution scope.
+ *
+ * Created by `withTenant()` / `enterTenantContext()` and read by `getCurrentTenant()`,
+ * `getTenantId()`, and the interceptor hooks. All fields except `tenantId` and
+ * `permissions` are optional and may be populated lazily by higher-level packages
+ * (e.g., `smrt-users`).
+ *
+ * @see withTenant
+ * @see MinimalTenantContext
+ */
+export interface TenantContextData {
+    /** Current tenant ID (required) */
+    tenantId: string;
+    /** Current tenant object (lazy-loaded if smrt-users is available) */
+    tenant?: unknown;
+    /** Current user ID (optional) */
+    userId?: string;
+    /** Current user object (lazy-loaded if smrt-users is available) */
+    user?: unknown;
+    /** Resolved permissions for this user in this tenant */
+    permissions: Set<string>;
+    /** Database connection for this tenant (if database-per-tenant strategy) */
+    database?: DatabaseInterface;
+    /** Super admin bypass enabled - allows cross-tenant operations */
+    superAdminBypass?: boolean;
+    /** Custom metadata for application-specific data */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Minimal context accepted by `withTenant()` and `withTenantSync()` when only a
+ * tenant ID is known.
+ *
+ * `permissions` defaults to an empty `Set` when omitted. Use `TenantContextData`
+ * when you also need to carry user info, database handles, or resolved permissions.
+ *
+ * @see TenantContextData
+ * @see withTenant
+ */
+export interface MinimalTenantContext {
+    /** Tenant identifier. */
+    tenantId: string;
+    /** Resolved permissions; defaults to an empty Set when omitted. */
+    permissions?: Set<string>;
+    /** When `true`, tenant auto-filtering is skipped for classes that allow super admin bypass. */
+    superAdminBypass?: boolean;
+    /** Arbitrary application-specific metadata to carry through the context. */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Get the current tenant context for this async execution scope.
+ *
+ * Returns `undefined` when called outside any tenant scope or inside a
+ * `withSystemContext()` block (the system context marker is treated as "no
+ * tenant data").  Prefer `requireTenant()` when a context is mandatory.
+ *
+ * @returns The active `TenantContextData`, or `undefined` if none is set.
+ *
+ * @example
+ * ```typescript
+ * const ctx = getCurrentTenant();
+ * if (ctx) {
+ *   console.log('Current tenant:', ctx.tenantId);
+ * }
+ * ```
+ *
+ * @see requireTenant
+ * @see hasTenantContext
+ */
+export declare function getCurrentTenant(): TenantContextData | undefined;
+/**
+ * Get the current tenant context or throw if one is not available.
+ *
+ * Use this in business-logic code that must run inside a tenant scope.
+ * For a non-throwing alternative use `getCurrentTenant()`.
+ *
+ * @returns The active `TenantContextData`.
+ * @throws {TenantContextError} When no tenant context is set (code is outside
+ *   any `withTenant()` call or the enclosing middleware has not run).
+ *
+ * @example
+ * ```typescript
+ * const { tenantId, permissions } = requireTenant();
+ * ```
+ *
+ * @see getCurrentTenant
+ * @see requireTenantId
+ */
+export declare function requireTenant(): TenantContextData;
+/**
+ * Get the current tenant ID or throw if no tenant context is available.
+ *
+ * Shorthand for `requireTenant().tenantId`.
+ *
+ * @returns The active tenant ID string.
+ * @throws {TenantContextError} When no tenant context is set.
+ *
+ * @example
+ * ```typescript
+ * const tenantId = requireTenantId();
+ * const rows = await db.query(`SELECT * FROM docs WHERE tenant_id = ?`, [tenantId]);
+ * ```
+ *
+ * @see getTenantId
+ * @see requireTenant
+ */
+export declare function requireTenantId(): string;
+/**
+ * Get the current tenant ID without throwing.
+ *
+ * Returns `undefined` when called outside any tenant scope or inside a
+ * `withSystemContext()` block.  Use `requireTenantId()` when a missing context
+ * should be treated as an error.
+ *
+ * @returns The active tenant ID, or `undefined` if none is set.
+ *
+ * @example
+ * ```typescript
+ * const tenantId = getTenantId();
+ * if (tenantId) {
+ *   // Optional tenant-scoped logic
+ * }
+ * ```
+ *
+ * @see requireTenantId
+ * @see hasTenantContext
+ */
+export declare function getTenantId(): string | undefined;
+/**
+ * Check whether the current async execution scope has an active tenant context.
+ *
+ * Returns `false` both when there is no context at all and when code is running
+ * inside `withSystemContext()` (the system marker is not a tenant context).
+ *
+ * @returns `true` if a `TenantContextData` is active, `false` otherwise.
+ *
+ * @example
+ * ```typescript
+ * if (hasTenantContext()) {
+ *   console.log('Tenant:', getTenantId());
+ * }
+ * ```
+ *
+ * @see getTenantId
+ * @see isSystemContext
+ */
+export declare function hasTenantContext(): boolean;
+/**
+ * Check whether the current async execution scope was entered via `withSystemContext()`.
+ *
+ * A system context is explicitly set to bypass all tenant checks; it is distinct
+ * from "no context" (undefined store).  When the store is undefined the
+ * interceptor enforces tenant requirements; when it holds the system marker the
+ * interceptor skips all checks.
+ *
+ * @returns `true` if inside a `withSystemContext()` call, `false` otherwise.
+ *
+ * @see withSystemContext
+ * @see hasTenantContext
+ */
+export declare function isSystemContext(): boolean;
+/**
+ * Check whether the super admin bypass flag is set in the current tenant context.
+ *
+ * When `true`, the interceptor skips tenant auto-filtering for classes that have
+ * `allowSuperAdminBypass: true` in their `@TenantScoped()` config.  Returns
+ * `false` inside a system context (no tenant data is available).
+ *
+ * @returns `true` if super admin bypass is active, `false` otherwise.
+ *
+ * @see withSuperAdminBypass
+ * @see TenantScopedOptions.allowSuperAdminBypass
+ */
+export declare function isSuperAdminBypass(): boolean;
+/**
+ * Run code within a tenant context (async version)
+ *
+ * @param context - Tenant context data (at minimum, tenantId)
+ * @param fn - Async function to run within the tenant context
+ * @returns Promise resolving to the function's return value
+ *
+ * @example
+ * ```typescript
+ * await withTenant({ tenantId: 'tenant-123' }, async () => {
+ *   const id = requireTenantId();  // 'tenant-123'
+ *   await doSomething();
+ * });
+ * ```
+ */
+export declare function withTenant<T>(context: TenantContextData | MinimalTenantContext, fn: () => Promise<T>): Promise<T>;
+/**
+ * Run synchronous code within a tenant context.
+ *
+ * Prefer `withTenant()` for async code.  Use this variant only when the
+ * callback must be synchronous (e.g., initializing a module-level value that
+ * is consumed synchronously downstream).
+ *
+ * @param context - Tenant context data (at minimum, `tenantId`).
+ * @param fn - Synchronous function to run within the tenant context.
+ * @returns The return value of `fn`.
+ *
+ * @example
+ * ```typescript
+ * const result = withTenantSync({ tenantId: 'tenant-123' }, () => {
+ *   return computeSomethingSync();
+ * });
+ * ```
+ *
+ * @see withTenant
+ */
+export declare function withTenantSync<T>(context: TenantContextData | MinimalTenantContext, fn: () => T): T;
+/**
+ * Enter tenant context for the remainder of the current async execution
+ *
+ * This uses AsyncLocalStorage.enterWith() to establish context that persists
+ * until the async resource completes. Useful for Express middleware where
+ * the route handler executes after the middleware returns.
+ *
+ * @param context - Tenant context data
+ *
+ * @example Express middleware
+ * ```typescript
+ * app.use((req, res, next) => {
+ *   const tenantId = req.headers['x-tenant-id'] as string;
+ *   enterTenantContext({ tenantId });
+ *   next();  // Route handlers now have tenant context
+ * });
+ * ```
+ */
+export declare function enterTenantContext(context: TenantContextData | MinimalTenantContext): void;
+/**
+ * Run code in system context (bypasses tenant checks)
+ *
+ * Use this for:
+ * - Migration scripts
+ * - Admin tools that need cross-tenant access
+ * - Background jobs that process multiple tenants
+ *
+ * System context is explicitly different from "no context" - it signals
+ * that tenant checks should be bypassed, while no context means the
+ * interceptor should enforce tenant requirements.
+ *
+ * @param fn - Async function to run without tenant context
+ *
+ * @example
+ * ```typescript
+ * await withSystemContext(async () => {
+ *   // No tenant context - can access all data
+ *   const allDocuments = await documentCollection.list({});
+ * });
+ * ```
+ */
+export declare function withSystemContext<T>(fn: () => Promise<T>): Promise<T>;
+/**
+ * Run async code with the super admin bypass flag enabled on the current
+ * tenant context.
+ *
+ * Unlike `withSystemContext()`, this does **not** remove the tenant context —
+ * the caller's `tenantId` remains intact.  The interceptor skips
+ * auto-filtering only for classes that have `allowSuperAdminBypass: true` in
+ * their `@TenantScoped()` config.
+ *
+ * A tenant context must already be active (i.e., this must be called from
+ * within a `withTenant()` scope).  Use `withSystemContext()` if no tenant
+ * context is available at all.
+ *
+ * @param fn - Async function to run with super admin bypass enabled.
+ * @returns Promise resolving to the return value of `fn`.
+ * @throws {TenantContextError} If called outside any tenant context.
+ *
+ * @example
+ * ```typescript
+ * await withTenant({ tenantId: 'admin-tenant' }, async () => {
+ *   await withSuperAdminBypass(async () => {
+ *     // Can read any tenant's AuditLog (if allowSuperAdminBypass: true)
+ *     const logs = await auditLogCollection.list({});
+ *   });
+ * });
+ * ```
+ *
+ * @see withSystemContext
+ * @see isSuperAdminBypass
+ */
+export declare function withSuperAdminBypass<T>(fn: () => Promise<T>): Promise<T>;
+/**
+ * Namespace object providing advanced tenant context utilities.
+ *
+ * Contains helpers for binding callbacks, inspecting context state, and
+ * running code with the context stored in a queued job payload.  These
+ * utilities supplement the standalone exported functions for situations where
+ * async context might otherwise be lost (e.g., `setTimeout`, event emitters,
+ * message queue consumers).
+ *
+ * @example
+ * ```typescript
+ * import { TenantContext } from '@happyvertical/smrt-tenancy';
+ *
+ * // Preserve context across a setTimeout
+ * setTimeout(TenantContext.bind(() => {
+ *   console.log(getTenantId()); // context is intact
+ * }), 500);
+ *
+ * // Process a queued job
+ * await TenantContext.runWithJobContext(job, async () => {
+ *   await processJob(job);
+ * });
+ * ```
+ */
+export declare const TenantContext: {
+    /**
+     * Bind a callback to the current tenant context
+     *
+     * Use this when passing callbacks to setTimeout, event emitters,
+     * or other APIs that might lose the async context.
+     *
+     * @param fn - Function to bind to current context
+     * @returns Wrapped function that will run in the original context
+     *
+     * @example
+     * ```typescript
+     * // Without bind - context is lost
+     * setTimeout(() => {
+     *   console.log(getTenantId());  // undefined!
+     * }, 1000);
+     *
+     * // With bind - context is preserved
+     * setTimeout(TenantContext.bind(() => {
+     *   console.log(getTenantId());  // 'tenant-123'
+     * }), 1000);
+     * ```
+     */
+    bind<T extends (...args: unknown[]) => unknown>(fn: T): T;
+    /**
+     * Get the current context data (or undefined for system/no context)
+     */
+    readonly current: TenantContextData | undefined;
+    /**
+     * Check if we're in system context
+     */
+    readonly isSystem: boolean;
+    /**
+     * Run code with context from a job/message payload
+     *
+     * Useful for processing queued jobs that include tenant metadata.
+     *
+     * @param job - Job object with tenantId in metadata
+     * @param fn - Function to run in the job's tenant context
+     *
+     * @example
+     * ```typescript
+     * const job = await queue.pop();
+     * await TenantContext.runWithJobContext(job, async () => {
+     *   await processJob(job);
+     * });
+     * ```
+     */
+    runWithJobContext<T>(job: {
+        metadata?: {
+            tenantId?: string;
+        };
+        tenantId?: string;
+    }, fn: () => Promise<T>): Promise<T>;
+};
+/**
+ * Error thrown when a tenant context is required but not available.
+ *
+ * Raised by `requireTenant()`, `requireTenantId()`, and the tenant interceptor
+ * when a `@TenantScoped({ mode: 'required' })` operation is attempted outside
+ * any `withTenant()` scope.
+ *
+ * The `code` property is always `'TENANT_CONTEXT_REQUIRED'` and can be used for
+ * programmatic error handling.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const tenantId = requireTenantId();
+ * } catch (err) {
+ *   if (err instanceof TenantContextError) {
+ *     // err.code === 'TENANT_CONTEXT_REQUIRED'
+ *   }
+ * }
+ * ```
+ *
+ * @see requireTenant
+ * @see requireTenantId
+ * @see TenantIsolationError
+ */
+export declare class TenantContextError extends Error {
+    /** Stable error code; always `'TENANT_CONTEXT_REQUIRED'`. */
+    readonly code = "TENANT_CONTEXT_REQUIRED";
+    constructor(message: string);
+}
+/**
+ * Error thrown when a tenant isolation boundary is crossed.
+ *
+ * Raised by the tenant interceptor when:
+ * - A `list()` or `get()` query explicitly filters by a tenant ID that does not
+ *   match the current context tenant.
+ * - A `save()` or `delete()` is attempted on an object whose `tenantId` field
+ *   belongs to a different tenant than the current context.
+ * - A raw SQL query is executed against a tenant-scoped class without an
+ *   explicit bypass (when `rawQueryPolicy` is `'throw'`).
+ *
+ * The `code` property is always `'TENANT_ISOLATION_VIOLATION'`.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await collection.list({ where: { tenantId: 'other-tenant' } });
+ * } catch (err) {
+ *   if (err instanceof TenantIsolationError) {
+ *     // err.tenantId          — context tenant
+ *     // err.attemptedTenantId — tenant that was attempted
+ *   }
+ * }
+ * ```
+ *
+ * @see TenantContextError
+ * @see createTenantInterceptor
+ */
+export declare class TenantIsolationError extends Error {
+    /** Stable error code; always `'TENANT_ISOLATION_VIOLATION'`. */
+    readonly code = "TENANT_ISOLATION_VIOLATION";
+    /** The tenant ID that is active in the current context. */
+    readonly tenantId?: string;
+    /** The tenant ID that was attempted (and rejected). */
+    readonly attemptedTenantId?: string;
+    constructor(message: string, details?: {
+        tenantId?: string;
+        attemptedTenantId?: string;
+    });
+}
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"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"}

package/dist/decorators.d.ts

@@ -0,0 +1,126 @@
+import { CompatiblePropertyDecorator } from '@happyvertical/smrt-core';
+import { TenantIdFieldOptions } from './fields.js';
+/**
+ * Options accepted by the `@TenantScoped()` class decorator.
+ *
+ * All fields are optional; defaults match the most restrictive safe behaviour
+ * (required mode, auto-filter and auto-populate enabled, no super-admin bypass).
+ *
+ * @see TenantScoped
+ * @see TenantScopedConfig
+ */
+export interface TenantScopedOptions {
+    /**
+     * Tenancy mode for this class
+     * - 'required': Must have tenant context for all operations (default)
+     * - 'optional': Works with or without tenant context
+     */
+    mode?: 'required' | 'optional';
+    /**
+     * Field name containing tenant ID
+     * @default 'tenantId'
+     */
+    field?: string;
+    /**
+     * Auto-filter all queries by tenant
+     * @default true
+     */
+    autoFilter?: boolean;
+    /**
+     * Auto-populate tenant ID from context on create
+     * @default true
+     */
+    autoPopulate?: boolean;
+    /**
+     * Allow super admin bypass for this class
+     * @default false - must be explicitly enabled
+     */
+    allowSuperAdminBypass?: boolean;
+}
+/**
+ * Mark a class as tenant-scoped
+ *
+ * This decorator registers the class with the tenancy system so that:
+ * - list()/get() queries are automatically filtered by tenant
+ * - save() validates tenant ID matches current context
+ * - delete() validates tenant ownership
+ * - Raw SQL queries trigger policy enforcement
+ *
+ * @param options - Configuration options
+ *
+ * @example Basic usage (required tenancy)
+ * ```typescript
+ * @smrt()
+ * @TenantScoped()
+ * class Document extends SmrtObject {
+ *   @tenantId()
+ *   tenantId: string = '';
+ *
+ *   title: string = '';
+ * }
+ * ```
+ *
+ * @example With super admin bypass enabled
+ * ```typescript
+ * @smrt()
+ * @TenantScoped({ allowSuperAdminBypass: true })
+ * class AuditLog extends SmrtObject {
+ *   @tenantId()
+ *   tenantId: string = '';
+ *
+ *   action: string = '';
+ * }
+ * ```
+ *
+ * @example Optional tenancy (works with or without context)
+ * ```typescript
+ * @smrt()
+ * @TenantScoped({ mode: 'optional' })
+ * class GlobalConfig extends SmrtObject {
+ *   @tenantId({ nullable: true })
+ *   tenantId: string | null = null;  // null = global, string = tenant-specific
+ *
+ *   key: string = '';
+ *   value: string = '';
+ * }
+ * ```
+ */
+export declare function TenantScoped(options?: TenantScopedOptions): <T extends Function>(target: T, decoratorContext?: ClassDecoratorContext) => T;
+/**
+ * Tenant ID property decorator
+ *
+ * Marks a property as the tenant identifier field. This decorator registers
+ * the field metadata with ObjectRegistry, keeping the property value clean
+ * (no descriptor objects that could be accidentally saved to the database).
+ *
+ * @param options - Field options (nullable, autoFilter, autoPopulate, etc.)
+ * @returns Property decorator
+ *
+ * @example Basic usage (required tenancy)
+ * ```typescript
+ * @smrt()
+ * @TenantScoped()
+ * class Document extends SmrtObject {
+ *   @tenantId()
+ *   tenantId: string = '';
+ *
+ *   title: string = '';
+ * }
+ * ```
+ *
+ * @example Nullable tenant ID (for global resources)
+ * ```typescript
+ * @smrt()
+ * @TenantScoped({ mode: 'optional' })
+ * class GlobalConfig extends SmrtObject {
+ *   @tenantId({ nullable: true })
+ *   tenantId: string | null = null;  // null = global, string = tenant-specific
+ *
+ *   key: string = '';
+ * }
+ * ```
+ *
+ * @see https://github.com/happyvertical/smrt/issues/829 - Why decorators over field helpers
+ */
+export declare function tenantId(options?: TenantIdFieldOptions): CompatiblePropertyDecorator;
+//# sourceMappingURL=decorators.d.ts.map

package/dist/decorators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorators.d.ts","sourceRoot":"","sources":["../src/decorators.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAEL,KAAK,2BAA2B,EAKjC,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAMxD;;;;;;;;GAQG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,IAAI,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;IAE/B;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB;;;OAGG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE,mBAAwB,IACpD,CAAC,SAAS,QAAQ,EACxB,QAAQ,CAAC,EACT,mBAAmB,qBAAqB,KACvC,CAAC,CAoBL;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,QAAQ,CAAC,OAAO,GAAE,oBAAyB,GA8BnD,2BAA2B,CAClC"}

package/dist/enabled-state.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared tenancy-enabled flag.
+ *
+ * Holds the single boolean toggled by `enableTenancy()` / `disableTenancy()`.
+ * It lives in its own leaf module (importing nothing from the package) so that
+ * both `interceptor.ts` and `entry-point.ts` can read it without forming a
+ * circular import: `interceptor.ts` imports `runTenantScopedEntryPoint` from
+ * `entry-point.ts`, and `entry-point.ts` needs the enabled flag — routing the
+ * flag through here keeps that dependency one-directional.
+ */
+/**
+ * Set the global tenancy-enabled flag. Internal — called by `enableTenancy()` /
+ * `disableTenancy()` in `interceptor.ts`.
+ *
+ * @param value - `true` to mark tenancy enabled, `false` to clear it.
+ */
+export declare function setTenancyEnabled(value: boolean): void;
+/**
+ * Return `true` if tenant enforcement is currently active.
+ *
+ * @returns Whether `enableTenancy()` has been called without a later
+ *   `disableTenancy()`.
+ */
+export declare function isTenancyEnabled(): boolean;
+//# sourceMappingURL=enabled-state.d.ts.map

package/dist/enabled-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enabled-state.d.ts","sourceRoot":"","sources":["../src/enabled-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAEtD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAE1C"}

package/dist/entry-point.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Fail-closed tenant-context establishment for non-web entry points (#1554).
+ *
+ * The SvelteKit/Express adapters establish tenant context from the authenticated
+ * request principal, so the web surface of a `@TenantScoped({ mode: 'optional' })`
+ * model never reads across tenants without an active context. The generated
+ * **CLI** and **MCP** entry points have no request principal, so an invocation
+ * with no active context would fall through the interceptor's optional-mode
+ * pass-through and return rows across **all** tenants.
+ *
+ * `runTenantScopedEntryPoint()` closes that gap. It is the single fail-closed
+ * gate both generated surfaces wrap their per-command/per-tool execution in.
+ *
+ * @see createCliContext for the richer CLI runner (resolveTenantId, super-admin).
+ */
+/**
+ * Inputs for {@link runTenantScopedEntryPoint}.
+ *
+ * Provide **either** `className` (the gate resolves tenant-scoping from the
+ * authoritative tenancy registry — the same source the interceptor uses, so it
+ * covers both `@TenantScoped` and `@smrt({ tenantScoped })` registrations) or an
+ * explicit `tenantScoped` boolean (when the caller already resolved it, e.g. a
+ * build-time generated surface). An explicit boolean wins when both are given.
+ */
+export interface TenantEntryPointOptions {
+    /**
+     * Class name of the target model. When provided, tenant-scoping is resolved
+     * via `isTenantScopedClass(className)`.
+     */
+    className?: string;
+    /**
+     * Explicit tenant-scoping decision. Overrides `className` resolution when set.
+     * Non-scoped models always pass through unchanged — the gate is a no-op.
+     */
+    tenantScoped?: boolean;
+    /**
+     * Explicit operator-provided tenant selector (CLI `--tenant <id>`, MCP
+     * `context.tenantId`). When present (and no context is already active) the
+     * function runs inside this tenant's context.
+     */
+    tenantId?: string | null;
+    /**
+     * Explicit operator opt-in to cross-tenant / system access (CLI
+     * `--all-tenants`, an MCP host that trusts the caller as an operator). When
+     * set the function runs in system context, bypassing tenant filtering.
+     *
+     * @default false
+     */
+    allowCrossTenant?: boolean;
+    /**
+     * Human-facing surface name used in the fail-closed error message, e.g.
+     * `'CLI'` or `'MCP'`.
+     *
+     * @default 'entry point'
+     */
+    surface?: string;
+}
+/**
+ * Run `fn` inside an appropriate tenant context for a generated CLI/MCP entry
+ * point, failing closed for tenant-scoped models when no authorized context can
+ * be established.
+ *
+ * Resolution order (tenant-scoped models only):
+ * 1. A tenant context is already active, or an explicit `withSystemContext()`
+ *    bypass is in effect (e.g. `runAsSystem()`, migrations) → run as-is.
+ * 2. `allowCrossTenant` was explicitly set → run in system context. Checked
+ *    before `tenantId` so an explicit cross-tenant opt-in wins over a default
+ *    principal/host tenant rather than being silently scoped.
+ * 3. An explicit `tenantId` was provided → run inside that tenant.
+ * 4. Tenancy is enabled but none of the above → **throw** `TenantContextError`
+ *    (the fail-closed branch — never silently read across tenants).
+ * 5. Tenancy is disabled (single-/no-tenant deployment) → pass through.
+ *
+ * Non-tenant-scoped models always pass straight through.
+ *
+ * @param options - {@link TenantEntryPointOptions}.
+ * @param fn - The command/tool body to execute.
+ * @returns The resolved value of `fn`.
+ * @throws {TenantContextError} When a tenant-scoped model is reached with
+ *   tenancy enabled and no tenant/cross-tenant selector.
+ */
+export declare function runTenantScopedEntryPoint<T>(options: TenantEntryPointOptions, fn: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=entry-point.d.ts.map

package/dist/entry-point.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry-point.d.ts","sourceRoot":"","sources":["../src/entry-point.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAYH;;;;;;;;GAQG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAEzB;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAE3B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,yBAAyB,CAAC,CAAC,EAC/C,OAAO,EAAE,uBAAuB,EAChC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAgDZ"}