@nebutra/tenant 0.1.0 → 0.1.2

package/dist/context.d.ts

@@ -0,0 +1,87 @@
+import type { TenantContext } from "./types";
+/**
+ * Execute a function with a tenant context set.
+ *
+ * All async operations within `fn` will have access to the same tenant context
+ * via `getCurrentTenant()` without passing it as a parameter.
+ *
+ * @param context The tenant context to set
+ * @param fn The function to execute
+ * @returns The return value of `fn`
+ *
+ * @example
+ * ```ts
+ * const result = await runWithTenant({ id: "org_123" }, async () => {
+ *   const tenant = getCurrentTenant();
+ *   await doSomething(tenant.id);
+ * });
+ * ```
+ */
+export declare function runWithTenant<T>(context: TenantContext, fn: () => Promise<T> | T): Promise<T>;
+/**
+ * Get the current tenant context from AsyncLocalStorage.
+ *
+ * Throws `TenantRequiredError` if no tenant context is set.
+ *
+ * @throws TenantRequiredError if tenant context is not available
+ * @returns The current tenant context
+ *
+ * @example
+ * ```ts
+ * const tenant = getCurrentTenant();
+ * console.log(tenant.id); // "org_123"
+ * ```
+ */
+export declare function getCurrentTenant(): TenantContext;
+/**
+ * Get the current tenant context, or null if not set.
+ *
+ * Useful for optional tenant contexts (public routes, webhooks, etc).
+ *
+ * @returns The current tenant context, or null if not set
+ *
+ * @example
+ * ```ts
+ * const tenant = getTenantOrNull();
+ * if (tenant) {
+ *   console.log(`Processing for tenant: ${tenant.id}`);
+ * } else {
+ *   console.log("Public route, no tenant");
+ * }
+ * ```
+ */
+export declare function getTenantOrNull(): TenantContext | null;
+/**
+ * Assertion helper that ensures a tenant context is present.
+ *
+ * Throws a structured error if tenant is missing. Useful as a safety
+ * check at the start of tenant-specific handlers.
+ *
+ * @param tenant The tenant context (or null)
+ * @param context Optional context message for the error
+ * @throws TenantRequiredError if tenant is null or undefined
+ *
+ * @example
+ * ```ts
+ * const tenant = getTenantOrNull();
+ * requireTenant(tenant, "DELETE /api/documents/:id");
+ * // Safe to use tenant.id from here on
+ * ```
+ */
+export declare function requireTenant(tenant: TenantContext | null | undefined, context?: string): asserts tenant is TenantContext;
+/**
+ * Get the current tenant ID as a shorthand.
+ *
+ * Throws if tenant context is not set.
+ *
+ * @returns The current tenant's ID
+ * @throws TenantRequiredError if tenant context is not available
+ */
+export declare function getCurrentTenantId(): string;
+/**
+ * Get the current tenant ID, or null if not set.
+ *
+ * @returns The current tenant's ID, or null
+ */
+export declare function getTenantIdOrNull(): string | null;
+//# 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":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAW7C;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,EAAE,aAAa,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAS7F;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,IAAI,aAAa,CAWhD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,IAAI,aAAa,GAAG,IAAI,CAEtD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,aAAa,GAAG,IAAI,GAAG,SAAS,EACxC,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,IAAI,aAAa,CASjC;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,GAAG,IAAI,CAEjD"}

package/dist/context.js

@@ -0,0 +1,125 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { logger } from "@nebutra/logger";
+import { TenantRequiredError } from "./types";
+/**
+ * AsyncLocalStorage-based tenant context — request-scoped, zero-copy across async boundaries.
+ *
+ * Each incoming request gets its own isolated context, even across await boundaries.
+ * No risk of tenant data leaking between requests or threads.
+ */
+const tenantStorage = new AsyncLocalStorage();
+/**
+ * Execute a function with a tenant context set.
+ *
+ * All async operations within `fn` will have access to the same tenant context
+ * via `getCurrentTenant()` without passing it as a parameter.
+ *
+ * @param context The tenant context to set
+ * @param fn The function to execute
+ * @returns The return value of `fn`
+ *
+ * @example
+ * ```ts
+ * const result = await runWithTenant({ id: "org_123" }, async () => {
+ *   const tenant = getCurrentTenant();
+ *   await doSomething(tenant.id);
+ * });
+ * ```
+ */
+export function runWithTenant(context, fn) {
+    return tenantStorage.run(context, () => {
+        // Support both sync and async functions
+        const result = fn();
+        if (result instanceof Promise) {
+            return result;
+        }
+        return Promise.resolve(result);
+    });
+}
+/**
+ * Get the current tenant context from AsyncLocalStorage.
+ *
+ * Throws `TenantRequiredError` if no tenant context is set.
+ *
+ * @throws TenantRequiredError if tenant context is not available
+ * @returns The current tenant context
+ *
+ * @example
+ * ```ts
+ * const tenant = getCurrentTenant();
+ * console.log(tenant.id); // "org_123"
+ * ```
+ */
+export function getCurrentTenant() {
+    const context = tenantStorage.getStore();
+    if (!context) {
+        logger.warn("getCurrentTenant() called without active tenant context");
+        throw new TenantRequiredError("No tenant context found. Ensure middleware called runWithTenant().");
+    }
+    return context;
+}
+/**
+ * Get the current tenant context, or null if not set.
+ *
+ * Useful for optional tenant contexts (public routes, webhooks, etc).
+ *
+ * @returns The current tenant context, or null if not set
+ *
+ * @example
+ * ```ts
+ * const tenant = getTenantOrNull();
+ * if (tenant) {
+ *   console.log(`Processing for tenant: ${tenant.id}`);
+ * } else {
+ *   console.log("Public route, no tenant");
+ * }
+ * ```
+ */
+export function getTenantOrNull() {
+    return tenantStorage.getStore() ?? null;
+}
+/**
+ * Assertion helper that ensures a tenant context is present.
+ *
+ * Throws a structured error if tenant is missing. Useful as a safety
+ * check at the start of tenant-specific handlers.
+ *
+ * @param tenant The tenant context (or null)
+ * @param context Optional context message for the error
+ * @throws TenantRequiredError if tenant is null or undefined
+ *
+ * @example
+ * ```ts
+ * const tenant = getTenantOrNull();
+ * requireTenant(tenant, "DELETE /api/documents/:id");
+ * // Safe to use tenant.id from here on
+ * ```
+ */
+export function requireTenant(tenant, context) {
+    if (!tenant) {
+        const message = context
+            ? `Tenant context required for: ${context}`
+            : "Tenant context is required";
+        logger.warn(message);
+        throw new TenantRequiredError(message);
+    }
+}
+/**
+ * Get the current tenant ID as a shorthand.
+ *
+ * Throws if tenant context is not set.
+ *
+ * @returns The current tenant's ID
+ * @throws TenantRequiredError if tenant context is not available
+ */
+export function getCurrentTenantId() {
+    return getCurrentTenant().id;
+}
+/**
+ * Get the current tenant ID, or null if not set.
+ *
+ * @returns The current tenant's ID, or null
+ */
+export function getTenantIdOrNull() {
+    return getTenantOrNull()?.id ?? null;
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { getCurrentTenant, getCurrentTenantId, getTenantIdOrNull, getTenantOrNull, requireTenant, runWithTenant, } from "./context";
+export { compose, fromApiKey, fromHeader, fromJwtClaim, fromPath, fromSubdomain, } from "./resolvers";
+export type { AuthSessionLike, SessionGetter } from "./resolvers/from-auth-session";
+export { fromAuthSession } from "./resolvers/from-auth-session";
+export type { IsolationStrategy, PlanTier, TenantConfig, TenantContext, TenantInfo, TenantResolver, } from "./types";
+export { TenantConfigSchema, TenantContextSchema, TenantInfoSchema, TenantIsolationError, TenantRequiredError, } from "./types";
+export type { RlsPolicyCommand, RlsPolicySqlOptions } from "./isolation";
+export { createTenantPrismaProxy, generateRlsPolicySql, getTenantDatabaseUrl, getTenantSchema, TenantAwarePrismaClient, withRls, } from "./isolation";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,aAAa,GACd,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,OAAO,EACP,UAAU,EACV,UAAU,EACV,YAAY,EACZ,QAAQ,EACR,aAAa,GACd,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AACpF,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAEhE,YAAY,EACV,iBAAiB,EACjB,QAAQ,EACR,YAAY,EACZ,aAAa,EACb,UAAU,EACV,cAAc,GACf,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,SAAS,CAAC;AAKjB,YAAY,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAEzE,OAAO,EACL,uBAAuB,EACvB,oBAAoB,EACpB,oBAAoB,EACpB,eAAe,EACf,uBAAuB,EACvB,OAAO,GACR,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,13 @@
+// =============================================================================
+// @nebutra/tenant — Multi-tenancy context and isolation
+// =============================================================================
+// Re-export context functions
+export { getCurrentTenant, getCurrentTenantId, getTenantIdOrNull, getTenantOrNull, requireTenant, runWithTenant, } from "./context";
+// Re-export resolvers
+export { compose, fromApiKey, fromHeader, fromJwtClaim, fromPath, fromSubdomain, } from "./resolvers";
+export { fromAuthSession } from "./resolvers/from-auth-session";
+export { TenantConfigSchema, TenantContextSchema, TenantInfoSchema, TenantIsolationError, TenantRequiredError, } from "./types";
+// Re-export isolation helpers
+export { createTenantPrismaProxy, generateRlsPolicySql, getTenantDatabaseUrl, getTenantSchema, TenantAwarePrismaClient, withRls, } from "./isolation";
+// Re-export React hooks (as subpath export ./react)
+// These are exported via package.json "exports" for tree-shaking

package/dist/isolation.d.ts

@@ -0,0 +1,157 @@
+import type { IsolationStrategy } from "./types";
+/** Minimal Prisma-like client interface for RLS extension support. */
+interface PrismaLikeClient {
+    $extends?: (extension: unknown) => unknown;
+    $executeRaw?: (query: TemplateStringsArray, ...values: unknown[]) => Promise<number>;
+    $queryRaw?: (query: TemplateStringsArray, ...values: unknown[]) => Promise<unknown[]>;
+}
+export type RlsPolicyCommand = "ALL" | "SELECT" | "INSERT" | "UPDATE" | "DELETE";
+export interface RlsPolicySqlOptions {
+    /** Tables that contain the tenant discriminator column. Sorted for deterministic output. */
+    tables: string[];
+    /** Optional schema qualifier. Defaults to unqualified table names. */
+    schema?: string;
+    /** Tenant discriminator column name. */
+    tenantColumn?: string;
+    /** PostgreSQL policy name prefix. Policy names are generated as `${prefix}_${table}`. */
+    policyPrefix?: string;
+    /** Policy command. Defaults to ALL for read/write tenant isolation. */
+    command?: RlsPolicyCommand;
+    /** Tenant expression used by generated policies. */
+    tenantExpression?: string;
+    /** Emit FORCE ROW LEVEL SECURITY after enabling RLS. Defaults to true. */
+    forceRls?: boolean;
+}
+/**
+ * Generate deterministic PostgreSQL Row-Level Security DDL for shared-schema tenancy.
+ *
+ * The generated SQL is intentionally migration-tool friendly: stable table sorting,
+ * explicit policy replacement, and no database connection side effects.
+ */
+export declare function generateRlsPolicySql(options: RlsPolicySqlOptions): string;
+/**
+ * Apply Prisma client extension that sets RLS (Row-Level Security) context.
+ *
+ * Works with PostgreSQL RLS policies that check `app.current_tenant_id`.
+ * This is the standard pattern for shared-schema multi-tenancy.
+ *
+ * The Prisma client middleware intercepts all queries and sets the
+ * application-level variable before executing.
+ *
+ * @param prisma The Prisma client to extend
+ * @param tenantId The tenant ID to set in RLS context
+ * @returns The extended Prisma client
+ *
+ * @example
+ * ```ts
+ * import { PrismaClient } from "@prisma/client";
+ * import { withRls } from "@nebutra/tenant/isolation";
+ * import { getCurrentTenant } from "@nebutra/tenant";
+ *
+ * const prisma = new PrismaClient();
+ *
+ * // In a request handler:
+ * const tenant = getCurrentTenant();
+ * const client = withRls(prisma, tenant.id);
+ *
+ * // All queries now include RLS enforcement:
+ * const users = await client.user.findMany();
+ * // SQL: SELECT * FROM users WHERE current_setting('app.current_tenant_id') = user.tenant_id
+ * ```
+ */
+export declare function withRls<P extends PrismaLikeClient>(prisma: P, tenantId: string): P;
+/**
+ * Get the PostgreSQL schema name for schema-per-tenant strategy.
+ *
+ * Converts a tenant ID to a safe PostgreSQL schema name.
+ * Schema names must start with a letter and contain only alphanumerics and underscores.
+ *
+ * @param tenantId The tenant ID
+ * @returns The schema name (e.g., "org_acme_corp_public")
+ * @throws TenantIsolationError if tenant ID is invalid
+ *
+ * @example
+ * ```ts
+ * const schemaName = getTenantSchema("acme-corp");
+ * // Returns: "org_acme_corp_public"
+ * ```
+ */
+export declare function getTenantSchema(tenantId: string): string;
+/**
+ * Get the PostgreSQL connection string for database-per-tenant strategy.
+ *
+ * Constructs a connection URL with the tenant-specific database name.
+ * Assumes the base connection URL is available and tenant databases follow
+ * a naming pattern (e.g., `nebutra_acme_corp`).
+ *
+ * @param tenantId The tenant ID
+ * @param baseUrl Optional base connection URL (defaults to process.env.DATABASE_URL)
+ * @returns The tenant-specific database URL
+ * @throws TenantIsolationError if base URL is invalid
+ *
+ * @example
+ * ```ts
+ * const dbUrl = getTenantDatabaseUrl("acme-corp");
+ * // Returns: "postgresql://user:pass@localhost/nebutra_acme_corp"
+ * ```
+ */
+export declare function getTenantDatabaseUrl(tenantId: string, baseUrl?: string): string;
+/**
+ * Wrapper for a Prisma client that automatically applies tenant filtering.
+ *
+ * This is useful for schema-per-tenant or database-per-tenant strategies
+ * where you want to ensure tenant isolation at the client level.
+ *
+ * @example
+ * ```ts
+ * import { TenantAwarePrismaClient } from "@nebutra/tenant/isolation";
+ * import { getCurrentTenant } from "@nebutra/tenant";
+ *
+ * export function getTenantPrisma() {
+ *   const tenant = getCurrentTenant();
+ *   return new TenantAwarePrismaClient(prisma, tenant.id);
+ * }
+ * ```
+ */
+export declare class TenantAwarePrismaClient {
+    private prisma;
+    private tenantId;
+    constructor(prisma: PrismaLikeClient, tenantId: string);
+    /**
+     * Get the underlying Prisma client with RLS context applied.
+     */
+    get client(): PrismaLikeClient;
+    /**
+     * Get the schema name for this tenant (schema-per-tenant strategy).
+     */
+    getSchema(): string;
+    /**
+     * Get the database URL for this tenant (database-per-tenant strategy).
+     */
+    getDatabaseUrl(baseUrl?: string): string;
+    /**
+     * Execute a raw SQL query with tenant context.
+     */
+    executeRaw(query: string): Promise<number>;
+    /**
+     * Execute a raw query and return results.
+     */
+    queryRaw(query: string): Promise<unknown[]>;
+}
+/**
+ * Create a tenant-aware Prisma proxy that applies isolation based on strategy.
+ *
+ * @param prisma The base Prisma client
+ * @param tenantId The tenant ID
+ * @param strategy The isolation strategy (default: "shared_schema")
+ * @returns A proxy or wrapper for the Prisma client
+ *
+ * @example
+ * ```ts
+ * const prisma = createTenantPrismaProxy(client, "acme-corp", "shared_schema");
+ * const users = await prisma.user.findMany(); // Filtered by RLS
+ * ```
+ */
+export declare function createTenantPrismaProxy(prisma: PrismaLikeClient, tenantId: string, strategy?: IsolationStrategy): PrismaLikeClient;
+export {};
+//# sourceMappingURL=isolation.d.ts.map

package/dist/isolation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"isolation.d.ts","sourceRoot":"","sources":["../src/isolation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAOjD,sEAAsE;AACtE,UAAU,gBAAgB;IACxB,QAAQ,CAAC,EAAE,CAAC,SAAS,EAAE,OAAO,KAAK,OAAO,CAAC;IAC3C,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrF,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;CACvF;AAED,MAAM,MAAM,gBAAgB,GAAG,KAAK,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEjF,MAAM,WAAW,mBAAmB;IAClC,4FAA4F;IAC5F,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,sEAAsE;IACtE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,yFAAyF;IACzF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uEAAuE;IACvE,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,oDAAoD;IACpD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAyCD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,mBAAmB,GAAG,MAAM,CA2DzE;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,OAAO,CAAC,CAAC,SAAS,gBAAgB,EAAE,MAAM,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,CAAC,CAiClF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAmBxD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CA6B/E;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,uBAAuB;IAEhC,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,QAAQ;gBADR,MAAM,EAAE,gBAAgB,EACxB,QAAQ,EAAE,MAAM;IAK1B;;OAEG;IACH,IAAI,MAAM,qBAET;IAED;;OAEG;IACH,SAAS,IAAI,MAAM;IAInB;;OAEG;IACH,cAAc,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM;IAIxC;;OAEG;IACG,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAwBhD;;OAEG;IACG,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;CAoBlD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,gBAAgB,EACxB,QAAQ,EAAE,MAAM,EAChB,QAAQ,GAAE,iBAAmC,GAC5C,gBAAgB,CAmBlB"}