@nebutra/tenant 0.1.0 → 0.1.1

package/dist/isolation.js

@@ -0,0 +1,319 @@
+import { logger } from "@nebutra/logger";
+import { TenantIsolationError } from "./types";
+const DEFAULT_TENANT_COLUMN = "tenant_id";
+const DEFAULT_POLICY_PREFIX = "tenant_isolation";
+const DEFAULT_TENANT_EXPRESSION = "current_setting('app.current_tenant_id', true)";
+function assertNonEmptyIdentifier(value, label) {
+    if (typeof value !== "string" || value.trim().length === 0 || value.includes("\0")) {
+        throw new TenantIsolationError(`Invalid ${label} for RLS policy generation`, "shared_schema");
+    }
+}
+function quoteIdentifier(identifier) {
+    assertNonEmptyIdentifier(identifier, "identifier");
+    return `"${identifier.replaceAll('"', '""')}"`;
+}
+function tableReference(table, schema) {
+    assertNonEmptyIdentifier(table, "table name");
+    if (!schema) {
+        return quoteIdentifier(table);
+    }
+    assertNonEmptyIdentifier(schema, "schema name");
+    return `${quoteIdentifier(schema)}.${quoteIdentifier(table)}`;
+}
+function policyPredicate(tenantColumn, tenantExpression) {
+    assertNonEmptyIdentifier(tenantColumn, "tenant column");
+    if (tenantExpression.trim().length === 0 || tenantExpression.includes("\0")) {
+        throw new TenantIsolationError("Invalid tenant expression for RLS policy generation", "shared_schema");
+    }
+    return `${quoteIdentifier(tenantColumn)} = ${tenantExpression}`;
+}
+/**
+ * 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 function generateRlsPolicySql(options) {
+    const { command = "ALL", forceRls = true, policyPrefix = DEFAULT_POLICY_PREFIX, schema, tables, tenantColumn = DEFAULT_TENANT_COLUMN, tenantExpression = DEFAULT_TENANT_EXPRESSION, } = options;
+    if (!Array.isArray(tables) || tables.length === 0) {
+        throw new TenantIsolationError("At least one table is required for RLS policy generation", "shared_schema");
+    }
+    assertNonEmptyIdentifier(policyPrefix, "policy prefix");
+    const normalizedCommand = command.toUpperCase();
+    if (!["ALL", "SELECT", "INSERT", "UPDATE", "DELETE"].includes(normalizedCommand)) {
+        throw new TenantIsolationError(`Unsupported RLS policy command: ${command}`, "shared_schema");
+    }
+    const predicate = policyPredicate(tenantColumn, tenantExpression);
+    const sortedTables = [...new Set(tables)].sort((a, b) => a.localeCompare(b));
+    return sortedTables
+        .map((table) => {
+        const target = tableReference(table, schema);
+        const policyName = quoteIdentifier(`${policyPrefix}_${table}`);
+        const statements = [`ALTER TABLE ${target} ENABLE ROW LEVEL SECURITY;`];
+        if (forceRls) {
+            statements.push(`ALTER TABLE ${target} FORCE ROW LEVEL SECURITY;`);
+        }
+        statements.push(`DROP POLICY IF EXISTS ${policyName} ON ${target};`);
+        const createPolicyLines = [`CREATE POLICY ${policyName} ON ${target}`];
+        if (normalizedCommand !== "ALL") {
+            createPolicyLines[0] += ` FOR ${normalizedCommand}`;
+        }
+        if (normalizedCommand !== "INSERT") {
+            createPolicyLines.push(`  USING (${predicate})`);
+        }
+        if (["ALL", "INSERT", "UPDATE"].includes(normalizedCommand)) {
+            const prefix = createPolicyLines.length > 1 ? "  WITH CHECK" : "  WITH CHECK";
+            createPolicyLines.push(`${prefix} (${predicate})`);
+        }
+        statements.push(`${createPolicyLines.join("\n")};`);
+        return statements.join("\n");
+    })
+        .join("\n\n");
+}
+// =============================================================================
+// Database Isolation Helpers
+// =============================================================================
+/**
+ * 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 function withRls(prisma, tenantId) {
+    try {
+        // Check if Prisma client supports $extends (v5+)
+        if (typeof prisma.$extends === "function") {
+            // Create a Prisma client extension that sets RLS context on each query
+            const extended = prisma.$extends({
+                query: {
+                    $allOperations: {
+                        async $before() {
+                            // Execute SET command to set application variable
+                            if (typeof prisma.$executeRaw === "function") {
+                                await prisma.$executeRaw `SELECT set_config('app.current_tenant_id', ${tenantId}, false)`;
+                            }
+                            logger.debug("RLS context set", { tenantId });
+                        },
+                    },
+                },
+            });
+            return extended;
+        }
+        logger.debug("withRls: Prisma client does not support $extends, returning original client", {
+            tenantId,
+        });
+        return prisma;
+    }
+    catch (err) {
+        logger.error("Failed to apply RLS extension", err, { tenantId });
+        throw new TenantIsolationError(`Failed to apply RLS isolation for tenant ${tenantId}`, "shared_schema");
+    }
+}
+/**
+ * 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 function getTenantSchema(tenantId) {
+    if (!tenantId || typeof tenantId !== "string") {
+        throw new TenantIsolationError("Invalid tenant ID for schema generation", "schema_per_tenant");
+    }
+    // Convert tenant ID to safe schema name
+    // Replace hyphens and special chars with underscores
+    const safe = tenantId
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "_")
+        .replace(/^[0-9]+/, "org_");
+    // Ensure doesn't conflict with reserved schemas
+    const reserved = ["public", "pg_", "information_schema", "pg_catalog"];
+    if (reserved.some((r) => safe.startsWith(r))) {
+        return `org_${safe}`;
+    }
+    return `${safe}_public`;
+}
+/**
+ * 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 function getTenantDatabaseUrl(tenantId, baseUrl) {
+    const url = baseUrl || process.env.DATABASE_URL;
+    if (!url) {
+        throw new TenantIsolationError("No base database URL available for tenant database resolution", "database_per_tenant");
+    }
+    try {
+        const parsedUrl = new URL(url);
+        // Convert tenant ID to safe database name
+        const dbName = `nebutra_${tenantId.toLowerCase().replace(/[^a-z0-9]+/g, "_")}`;
+        // Replace pathname (database name)
+        parsedUrl.pathname = `/${dbName}`;
+        logger.debug("Tenant database URL constructed", { tenantId, dbName });
+        return parsedUrl.toString();
+    }
+    catch (err) {
+        logger.error("Failed to construct tenant database URL", err, { tenantId });
+        throw new TenantIsolationError(`Failed to construct database URL for tenant ${tenantId}`, "database_per_tenant");
+    }
+}
+/**
+ * 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 class TenantAwarePrismaClient {
+    prisma;
+    tenantId;
+    constructor(prisma, tenantId) {
+        this.prisma = prisma;
+        this.tenantId = tenantId;
+        logger.debug("TenantAwarePrismaClient initialized", { tenantId });
+    }
+    /**
+     * Get the underlying Prisma client with RLS context applied.
+     */
+    get client() {
+        return withRls(this.prisma, this.tenantId);
+    }
+    /**
+     * Get the schema name for this tenant (schema-per-tenant strategy).
+     */
+    getSchema() {
+        return getTenantSchema(this.tenantId);
+    }
+    /**
+     * Get the database URL for this tenant (database-per-tenant strategy).
+     */
+    getDatabaseUrl(baseUrl) {
+        return getTenantDatabaseUrl(this.tenantId, baseUrl);
+    }
+    /**
+     * Execute a raw SQL query with tenant context.
+     */
+    async executeRaw(query) {
+        try {
+            logger.debug("Executing raw query with tenant context", {
+                tenantId: this.tenantId,
+                queryLength: query.length,
+            });
+            const client = this.client;
+            if (!client.$executeRaw) {
+                throw new TenantIsolationError("Prisma client does not support $executeRaw", "shared_schema");
+            }
+            return await client.$executeRaw `${query}`;
+        }
+        catch (err) {
+            logger.error("Failed to execute raw query", err, { tenantId: this.tenantId });
+            throw new TenantIsolationError(`Failed to execute query for tenant ${this.tenantId}`, "shared_schema");
+        }
+    }
+    /**
+     * Execute a raw query and return results.
+     */
+    async queryRaw(query) {
+        try {
+            logger.debug("Executing query with tenant context", {
+                tenantId: this.tenantId,
+                queryLength: query.length,
+            });
+            const client = this.client;
+            if (!client.$queryRaw) {
+                throw new TenantIsolationError("Prisma client does not support $queryRaw", "shared_schema");
+            }
+            return await client.$queryRaw `${query}`;
+        }
+        catch (err) {
+            logger.error("Failed to execute query", err, { tenantId: this.tenantId });
+            throw new TenantIsolationError(`Failed to query tenant data for ${this.tenantId}`, "shared_schema");
+        }
+    }
+}
+/**
+ * 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 function createTenantPrismaProxy(prisma, tenantId, strategy = "shared_schema") {
+    logger.debug("Creating tenant Prisma proxy", { tenantId, strategy });
+    switch (strategy) {
+        case "shared_schema":
+            // Apply RLS extension
+            return withRls(prisma, tenantId);
+        case "schema_per_tenant":
+            // Wrap with schema awareness
+            return new TenantAwarePrismaClient(prisma, tenantId).client;
+        case "database_per_tenant":
+            // Wrap with database URL awareness
+            return new TenantAwarePrismaClient(prisma, tenantId).client;
+        default:
+            throw new TenantIsolationError(`Unknown isolation strategy: ${strategy}`);
+    }
+}

package/dist/middleware.d.ts

@@ -0,0 +1,106 @@
+import type { TenantConfig } from "./types";
+/** Minimal Hono-like context — matches Hono's `Context` without importing it. */
+interface HonoLikeContext {
+    req: {
+        raw: {
+            headers: Headers;
+        };
+        url: string;
+        header: (name: string) => string | undefined;
+    };
+    json: (body: unknown, status: number) => Response;
+}
+/**
+ * Create a Hono middleware that extracts tenant from request and sets context.
+ *
+ * - Resolves tenant ID using configured strategy (header, subdomain, path, JWT, API key)
+ * - Wraps handler execution with AsyncLocalStorage context
+ * - Returns 400 if tenant is required but not resolved
+ *
+ * @param config Tenant configuration
+ * @returns A Hono middleware function
+ *
+ * @example
+ * ```ts
+ * import { Hono } from "hono";
+ * import { tenantMiddleware } from "@nebutra/tenant/middleware";
+ *
+ * const app = new Hono();
+ *
+ * app.use(
+ *   tenantMiddleware({
+ *     headerName: "x-tenant-id",
+ *     requireTenant: true,
+ *   })
+ * );
+ *
+ * app.get("/api/data", (c) => {
+ *   const tenant = getCurrentTenant();
+ *   return c.json({ tenantId: tenant.id });
+ * });
+ *
+ * export default app;
+ * ```
+ */
+export declare function tenantMiddleware(config?: Partial<TenantConfig>): (c: HonoLikeContext, next: () => Promise<Response>) => Promise<Response>;
+/**
+ * Wrap a Next.js API route handler to extract and set tenant context.
+ *
+ * Uses the same resolver logic as Hono middleware but for Next.js.
+ *
+ * @param handler The API route handler
+ * @param config Tenant configuration
+ * @returns Wrapped handler that sets tenant context
+ *
+ * @example
+ * ```ts
+ * // pages/api/data.ts
+ * import { withTenant } from "@nebutra/tenant/middleware";
+ * import { getCurrentTenant } from "@nebutra/tenant";
+ * import type { NextApiRequest, NextApiResponse } from "next";
+ *
+ * export default withTenant(
+ *   async (req: NextApiRequest, res: NextApiResponse) => {
+ *     const tenant = getCurrentTenant();
+ *     res.json({ tenantId: tenant.id });
+ *   },
+ *   { headerName: "x-tenant-id" }
+ * );
+ * ```
+ */
+export declare function withTenant<T extends any[], R>(handler: (...args: T) => Promise<R> | R, config?: Partial<TenantConfig>): (...args: T) => Promise<R>;
+/**
+ * Wrap a Next.js Server Action to extract and set tenant context.
+ *
+ * Server Actions don't have direct access to request headers, so tenant ID
+ * should be passed explicitly or resolved from authentication context.
+ *
+ * @param handler The server action handler
+ * @param getTenantId Function to extract tenant ID (e.g., from auth context)
+ * @returns Wrapped handler that sets tenant context
+ *
+ * @example
+ * ```ts
+ * // lib/actions.ts
+ * "use server";
+ * import { withServerAction } from "@nebutra/tenant/middleware";
+ * import { getSession } from "@/lib/auth";
+ *
+ * export const getUserData = withServerAction(
+ *   async (userId: string) => {
+ *     const tenant = getCurrentTenant();
+ *     const user = await db.user.findUnique({
+ *       where: { id: userId, tenantId: tenant.id },
+ *     });
+ *     return user;
+ *   },
+ *   async () => {
+ *     const session = await getSession();
+ *     return session?.tenantId || null;
+ *   }
+ * );
+ * ```
+ */
+export declare function withServerAction<T extends any[], R>(handler: (...args: T) => Promise<R> | R, getTenantId: () => Promise<string | null> | string | null): (...args: T) => Promise<R>;
+export {};
+//# sourceMappingURL=middleware.d.ts.map

package/dist/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAkB,MAAM,SAAS,CAAC;AAO5D,iFAAiF;AACjF,UAAU,eAAe;IACvB,GAAG,EAAE;QACH,GAAG,EAAE;YAAE,OAAO,EAAE,OAAO,CAAA;SAAE,CAAC;QAC1B,GAAG,EAAE,MAAM,CAAC;QACZ,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;KAC9C,CAAC;IACF,IAAI,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,KAAK,QAAQ,CAAC;CACnD;AAYD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,GAAE,OAAO,CAAC,YAAY,CAAM,IAuBnD,GAAG,eAAe,EAAE,MAAM,MAAM,OAAO,CAAC,QAAQ,CAAC,uBAyDhE;AAMD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,GAAG,EAAE,EAAE,CAAC,EAC3C,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,EACvC,MAAM,GAAE,OAAO,CAAC,YAAY,CAAM,IAQpB,GAAG,MAAM,CAAC,KAAG,OAAO,CAAC,CAAC,CAAC,CAsDtC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,GAAG,EAAE,EAAE,CAAC,EACjD,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,EACvC,WAAW,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,MAAM,GAAG,IAAI,IAE3C,GAAG,MAAM,CAAC,KAAG,OAAO,CAAC,CAAC,CAAC,CAiBtC"}

package/dist/middleware.js

@@ -0,0 +1,247 @@
+import { logger } from "@nebutra/logger";
+import { runWithTenant } from "./context";
+import { fromHeader, fromJwtClaim, fromPath, fromSubdomain } from "./resolvers";
+import { TenantRequiredError } from "./types";
+// =============================================================================
+// Hono Middleware for Multi-Tenant Context
+// =============================================================================
+/**
+ * Create a Hono middleware that extracts tenant from request and sets context.
+ *
+ * - Resolves tenant ID using configured strategy (header, subdomain, path, JWT, API key)
+ * - Wraps handler execution with AsyncLocalStorage context
+ * - Returns 400 if tenant is required but not resolved
+ *
+ * @param config Tenant configuration
+ * @returns A Hono middleware function
+ *
+ * @example
+ * ```ts
+ * import { Hono } from "hono";
+ * import { tenantMiddleware } from "@nebutra/tenant/middleware";
+ *
+ * const app = new Hono();
+ *
+ * app.use(
+ *   tenantMiddleware({
+ *     headerName: "x-tenant-id",
+ *     requireTenant: true,
+ *   })
+ * );
+ *
+ * app.get("/api/data", (c) => {
+ *   const tenant = getCurrentTenant();
+ *   return c.json({ tenantId: tenant.id });
+ * });
+ *
+ * export default app;
+ * ```
+ */
+export function tenantMiddleware(config = {}) {
+    const mergedConfig = {
+        headerName: "x-tenant-id",
+        requireTenant: true,
+        ...config,
+    };
+    // Determine which resolver to use
+    let resolver;
+    if (mergedConfig.resolver) {
+        resolver = mergedConfig.resolver;
+    }
+    else if (mergedConfig.subdomainPattern) {
+        resolver = fromSubdomain(mergedConfig.subdomainPattern);
+    }
+    else if (mergedConfig.pathPrefix) {
+        resolver = fromPath(mergedConfig.pathPrefix);
+    }
+    else if (mergedConfig.jwtClaimName) {
+        resolver = fromJwtClaim(mergedConfig.jwtClaimName);
+    }
+    else {
+        // Default: header-based resolution
+        resolver = fromHeader(mergedConfig.headerName);
+    }
+    return async (c, next) => {
+        try {
+            // Extract tenant ID from request
+            const honoHeaders = {};
+            const rawHeaders = c.req.raw.headers;
+            rawHeaders.forEach((value, key) => {
+                honoHeaders[key.toLowerCase()] = value;
+            });
+            const resolverInput = {
+                headers: honoHeaders,
+                url: c.req.url,
+            };
+            const authHeader = c.req.header("Authorization");
+            if (authHeader)
+                resolverInput.token = authHeader.replace(/^Bearer\s+/i, "");
+            const apiKeyHeader = c.req.header("X-API-Key");
+            if (apiKeyHeader)
+                resolverInput.apiKey = apiKeyHeader;
+            const tenantId = await Promise.resolve(resolver(resolverInput));
+            if (!tenantId) {
+                if (mergedConfig.requireTenant) {
+                    logger.warn("Tenant context required but not resolved", {
+                        url: c.req.url,
+                    });
+                    return c.json({
+                        error: "Tenant context required",
+                        message: "No valid tenant ID found in request",
+                    }, 400);
+                }
+                // Tenant is optional, proceed without context
+                logger.debug("Tenant context not resolved (optional)");
+                return next();
+            }
+            logger.debug("Tenant resolved in middleware", { tenantId });
+            // Execute handler within tenant context
+            return await runWithTenant({ id: tenantId }, async () => {
+                return next();
+            });
+        }
+        catch (err) {
+            logger.error("Tenant middleware error", err);
+            return c.json({
+                error: "Internal server error",
+                message: "Failed to process tenant context",
+            }, 500);
+        }
+    };
+}
+// =============================================================================
+// Next.js API Route / Server Action Wrapper
+// =============================================================================
+/**
+ * Wrap a Next.js API route handler to extract and set tenant context.
+ *
+ * Uses the same resolver logic as Hono middleware but for Next.js.
+ *
+ * @param handler The API route handler
+ * @param config Tenant configuration
+ * @returns Wrapped handler that sets tenant context
+ *
+ * @example
+ * ```ts
+ * // pages/api/data.ts
+ * import { withTenant } from "@nebutra/tenant/middleware";
+ * import { getCurrentTenant } from "@nebutra/tenant";
+ * import type { NextApiRequest, NextApiResponse } from "next";
+ *
+ * export default withTenant(
+ *   async (req: NextApiRequest, res: NextApiResponse) => {
+ *     const tenant = getCurrentTenant();
+ *     res.json({ tenantId: tenant.id });
+ *   },
+ *   { headerName: "x-tenant-id" }
+ * );
+ * ```
+ */
+export function withTenant(handler, config = {}) {
+    const mergedConfig = {
+        headerName: "x-tenant-id",
+        requireTenant: true,
+        ...config,
+    };
+    return async (...args) => {
+        // Extract req from args (Next.js convention: req is first arg)
+        const req = args[0];
+        if (!req || !req.headers) {
+            logger.warn("withTenant: No request object found");
+            if (mergedConfig.requireTenant) {
+                throw new TenantRequiredError("No request context available");
+            }
+            return handler(...args);
+        }
+        // Determine resolver
+        let resolver;
+        if (mergedConfig.resolver) {
+            resolver = mergedConfig.resolver;
+        }
+        else if (mergedConfig.subdomainPattern) {
+            resolver = fromSubdomain(mergedConfig.subdomainPattern);
+        }
+        else if (mergedConfig.pathPrefix) {
+            resolver = fromPath(mergedConfig.pathPrefix);
+        }
+        else if (mergedConfig.jwtClaimName) {
+            resolver = fromJwtClaim(mergedConfig.jwtClaimName);
+        }
+        else {
+            resolver = fromHeader(mergedConfig.headerName);
+        }
+        // Resolve tenant ID
+        const withTenantInput = {
+            headers: req.headers,
+        };
+        if (req.url)
+            withTenantInput.url = `${req.headers.host || ""}${req.url}`;
+        const authorization = req.headers.authorization;
+        if (authorization)
+            withTenantInput.token = authorization.replace(/^Bearer\s+/i, "");
+        const apiKey = req.headers["x-api-key"];
+        if (apiKey)
+            withTenantInput.apiKey = apiKey;
+        const tenantId = await Promise.resolve(resolver(withTenantInput));
+        if (!tenantId) {
+            if (mergedConfig.requireTenant) {
+                logger.warn("withTenant: Tenant required but not resolved");
+                throw new TenantRequiredError("No tenant context found in request");
+            }
+            logger.debug("withTenant: Tenant context not resolved (optional)");
+            return handler(...args);
+        }
+        logger.debug("withTenant: Tenant resolved", { tenantId });
+        // Execute handler within tenant context
+        return runWithTenant({ id: tenantId }, () => handler(...args));
+    };
+}
+/**
+ * Wrap a Next.js Server Action to extract and set tenant context.
+ *
+ * Server Actions don't have direct access to request headers, so tenant ID
+ * should be passed explicitly or resolved from authentication context.
+ *
+ * @param handler The server action handler
+ * @param getTenantId Function to extract tenant ID (e.g., from auth context)
+ * @returns Wrapped handler that sets tenant context
+ *
+ * @example
+ * ```ts
+ * // lib/actions.ts
+ * "use server";
+ * import { withServerAction } from "@nebutra/tenant/middleware";
+ * import { getSession } from "@/lib/auth";
+ *
+ * export const getUserData = withServerAction(
+ *   async (userId: string) => {
+ *     const tenant = getCurrentTenant();
+ *     const user = await db.user.findUnique({
+ *       where: { id: userId, tenantId: tenant.id },
+ *     });
+ *     return user;
+ *   },
+ *   async () => {
+ *     const session = await getSession();
+ *     return session?.tenantId || null;
+ *   }
+ * );
+ * ```
+ */
+export function withServerAction(handler, getTenantId) {
+    return async (...args) => {
+        try {
+            const tenantId = await Promise.resolve(getTenantId());
+            if (!tenantId) {
+                logger.warn("withServerAction: Tenant ID not available");
+                throw new TenantRequiredError("No tenant context available in server action");
+            }
+            logger.debug("withServerAction: Tenant resolved", { tenantId });
+            return runWithTenant({ id: tenantId }, () => handler(...args));
+        }
+        catch (err) {
+            logger.error("withServerAction: Error setting tenant context", err);
+            throw err;
+        }
+    };
+}