@nebutra/tenant 0.1.0 → 0.1.2

package/dist/resolvers.js

@@ -0,0 +1,253 @@
+import { logger } from "@nebutra/logger";
+function isRequest(req) {
+    return typeof Request !== "undefined" && req instanceof Request;
+}
+function getHeader(headers, headerName) {
+    if (!headers)
+        return null;
+    if (headers instanceof Headers) {
+        return headers.get(headerName);
+    }
+    const normalizedHeaderName = headerName.toLowerCase();
+    const entry = Object.entries(headers).find(([name]) => name.toLowerCase() === normalizedHeaderName);
+    const value = entry?.[1];
+    if (typeof value === "string")
+        return value;
+    if (Array.isArray(value))
+        return value[0] ?? null;
+    return null;
+}
+function getUrlString(req) {
+    const url = req.url;
+    if (!url)
+        return null;
+    return url instanceof URL ? url.toString() : url;
+}
+function getJwtToken(req) {
+    const explicitToken = isRequest(req) ? null : req.token;
+    if (explicitToken)
+        return explicitToken;
+    const authorization = getHeader(req.headers, "authorization");
+    const match = authorization?.match(/^Bearer\s+(.+)$/i);
+    return match?.[1]?.trim() || null;
+}
+function decodeJwtPayload(token) {
+    const parts = token.split(".");
+    if (parts.length !== 3 || !parts[1])
+        return null;
+    return JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8"));
+}
+/**
+ * Extract tenant ID from an HTTP header.
+ *
+ * Default strategy for API gateways. Header name is configurable.
+ *
+ * @param headerName The header name to look for (default: "x-tenant-id")
+ * @returns A resolver function
+ *
+ * @example
+ * ```ts
+ * const resolver = fromHeader("x-tenant-id");
+ * const tenantId = await resolver({ headers: { "x-tenant-id": "org_123" } });
+ * ```
+ */
+export function fromHeader(headerName = "x-tenant-id") {
+    return (req) => {
+        const value = getHeader(req.headers, headerName);
+        if (typeof value === "string") {
+            logger.debug("Tenant resolved from header", { headerName, tenantId: value });
+            return value;
+        }
+        return null;
+    };
+}
+/**
+ * Extract tenant ID from a subdomain using a regex pattern.
+ *
+ * Useful for SaaS products with tenant subdomains (e.g., `acme.app.nebutra.com`).
+ *
+ * @param pattern A regex pattern with a capture group for tenant ID
+ * @returns A resolver function
+ *
+ * @example
+ * ```ts
+ * // Extract "acme" from "acme.app.nebutra.com"
+ * const resolver = fromSubdomain("^([a-z0-9-]+)\\.app\\.nebutra\\.com$");
+ * const tenantId = await resolver({ url: "https://acme.app.nebutra.com/api" });
+ * ```
+ */
+export function fromSubdomain(pattern) {
+    const regex = new RegExp(pattern, "i");
+    return (req) => {
+        const urlString = getUrlString(req);
+        if (!urlString)
+            return null;
+        try {
+            const url = new URL(urlString);
+            const hostname = url.hostname;
+            const match = hostname.match(regex);
+            if (match?.[1]) {
+                logger.debug("Tenant resolved from subdomain", { hostname, tenantId: match[1] });
+                return match[1];
+            }
+        }
+        catch (_err) {
+            logger.warn("Failed to parse URL for subdomain extraction", { url: urlString });
+        }
+        return null;
+    };
+}
+/**
+ * Extract tenant ID from a URL path prefix.
+ *
+ * Useful for multi-tenant apps with path-based routing (e.g., `/org/acme/...`).
+ *
+ * @param prefix The path prefix pattern (e.g., "/org/:tenantId" or "/org/([^/]+)")
+ * @returns A resolver function
+ *
+ * @example
+ * ```ts
+ * // Extract tenant ID from "/org/acme/..."
+ * const resolver = fromPath("/org/:tenantId");
+ * const tenantId = await resolver({ url: "https://app.nebutra.com/org/acme/dashboard" });
+ * ```
+ */
+export function fromPath(prefix) {
+    // Convert Next.js-style `:tenantId` to regex capture group
+    const pattern = prefix.replace(/:tenantId/g, "([^/?]+)");
+    const regex = new RegExp(`^${pattern}`);
+    return (req) => {
+        const urlString = getUrlString(req);
+        if (!urlString)
+            return null;
+        try {
+            const url = new URL(urlString);
+            const pathname = url.pathname;
+            const match = pathname.match(regex);
+            if (match?.[1]) {
+                logger.debug("Tenant resolved from path", { pathname, tenantId: match[1] });
+                return match[1];
+            }
+        }
+        catch (_err) {
+            logger.warn("Failed to parse URL for path extraction", { url: urlString });
+        }
+        return null;
+    };
+}
+/**
+ * Extract tenant ID from a JWT token claim.
+ *
+ * Useful for authentication services that embed tenant info in the token.
+ *
+ * @param claimName The JWT claim name (e.g., "tenant_id", "org_id")
+ * @returns A resolver function
+ *
+ * @example
+ * ```ts
+ * // Extract from decoded JWT { sub: "user_123", tenant_id: "org_456" }
+ * const resolver = fromJwtClaim("tenant_id");
+ * const tenantId = await resolver({ token: "eyJhbGc..." });
+ * ```
+ */
+export function fromJwtClaim(claimName) {
+    return (req) => {
+        const token = getJwtToken(req);
+        if (!token)
+            return null;
+        try {
+            // Decode JWT without verification (signature should be verified upstream)
+            const payload = decodeJwtPayload(token);
+            if (!payload)
+                return null;
+            const value = payload[claimName];
+            if (typeof value === "string") {
+                logger.debug("Tenant resolved from JWT claim", { claimName, tenantId: value });
+                return value;
+            }
+        }
+        catch (_err) {
+            logger.warn("Failed to extract JWT claim", { claimName });
+        }
+        return null;
+    };
+}
+/**
+ * Resolve tenant ID from an API key by looking it up in a function (e.g., database).
+ *
+ * Useful for service-to-service authentication or API clients.
+ *
+ * @param lookupFn Async function that takes an API key and returns the tenant ID
+ * @returns A resolver function
+ *
+ * @example
+ * ```ts
+ * // Look up API key in database
+ * const resolver = fromApiKey(async (apiKey) => {
+ *   const key = await db.apiKey.findUnique({ where: { key: apiKey } });
+ *   return key?.tenantId ?? null;
+ * });
+ * const tenantId = await resolver({ apiKey: "sk_123" });
+ * ```
+ */
+export function fromApiKey(lookupFn) {
+    return async (req) => {
+        const apiKey = isRequest(req) ? null : req.apiKey;
+        if (!apiKey)
+            return null;
+        try {
+            const tenantId = await lookupFn(apiKey);
+            if (tenantId) {
+                logger.debug("Tenant resolved from API key");
+                return tenantId;
+            }
+        }
+        catch (err) {
+            logger.warn("Failed to lookup API key", { error: err });
+        }
+        return null;
+    };
+}
+/**
+ * Compose multiple tenant resolvers with fallback behavior.
+ *
+ * Tries each resolver in order; returns the first successful match.
+ * If all resolvers return null, returns null.
+ *
+ * @param resolvers Array of resolver functions
+ * @returns A composite resolver function
+ *
+ * @example
+ * ```ts
+ * // Try header first, then subdomain, then path
+ * const resolver = compose(
+ *   fromHeader("x-tenant-id"),
+ *   fromSubdomain("^([a-z0-9-]+)\\.app\\.nebutra\\.com$"),
+ *   fromPath("/org/:tenantId")
+ * );
+ *
+ * const tenantId = await resolver({
+ *   headers: { "x-tenant-id": "org_123" },
+ *   url: "https://acme.app.nebutra.com/org/xyz/dashboard"
+ * });
+ * // Returns "org_123" (first match)
+ * ```
+ */
+export function compose(...resolvers) {
+    return async (req) => {
+        for (const resolver of resolvers) {
+            try {
+                const result = await Promise.resolve(resolver(req));
+                if (result) {
+                    logger.debug("Tenant resolved via composed resolver", { tenantId: result });
+                    return result;
+                }
+            }
+            catch (err) {
+                logger.warn("Resolver in chain failed", { error: err });
+                // Continue to next resolver
+            }
+        }
+        return null;
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,96 @@
+import { z } from "zod";
+/**
+ * Isolation strategy determines how data is partitioned across tenants.
+ *
+ * - `shared_schema`: Single PostgreSQL schema with Row-Level Security (RLS) on `current_user` or `tenant_id`
+ * - `schema_per_tenant`: Separate PostgreSQL schema per tenant (e.g., `org_123_public`)
+ * - `database_per_tenant`: Separate PostgreSQL database per tenant (requires connection pooling)
+ */
+export type IsolationStrategy = "shared_schema" | "schema_per_tenant" | "database_per_tenant";
+/**
+ * Plan tier determines feature access and rate limits.
+ */
+export type PlanTier = "free" | "pro" | "enterprise";
+/**
+ * Runtime tenant context — available via AsyncLocalStorage in request handlers.
+ */
+export declare const TenantContextSchema: z.ZodObject<{
+    id: z.ZodString;
+    slug: z.ZodOptional<z.ZodString>;
+    plan: z.ZodOptional<z.ZodEnum<{
+        free: "free";
+        pro: "pro";
+        enterprise: "enterprise";
+    }>>;
+    features: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    limits: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type TenantContext = z.infer<typeof TenantContextSchema>;
+/**
+ * Persistent tenant information — typically loaded from database.
+ */
+export declare const TenantInfoSchema: z.ZodObject<{
+    id: z.ZodString;
+    slug: z.ZodString;
+    name: z.ZodString;
+    plan: z.ZodEnum<{
+        free: "free";
+        pro: "pro";
+        enterprise: "enterprise";
+    }>;
+    createdAt: z.ZodUnion<[z.ZodDate, z.ZodString]>;
+    settings: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    parentTenantId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type TenantInfo = z.infer<typeof TenantInfoSchema>;
+export interface TenantResolverObjectInput {
+    headers?: Headers | Record<string, string | string[] | undefined>;
+    url?: string | URL;
+    token?: string;
+    apiKey?: string;
+}
+export type TenantResolverInput = Request | TenantResolverObjectInput;
+/**
+ * Callback to resolve a tenant from various sources (header, subdomain, path, JWT, API key).
+ *
+ * Returns the resolved tenant ID or null if not found.
+ */
+export type TenantResolver = (req: TenantResolverInput) => Promise<string | null> | string | null;
+/**
+ * Configuration for tenant extraction and isolation.
+ */
+export declare const TenantConfigSchema: z.ZodObject<{
+    strategy: z.ZodDefault<z.ZodEnum<{
+        shared_schema: "shared_schema";
+        schema_per_tenant: "schema_per_tenant";
+        database_per_tenant: "database_per_tenant";
+    }>>;
+    headerName: z.ZodDefault<z.ZodString>;
+    subdomainPattern: z.ZodOptional<z.ZodString>;
+    pathPrefix: z.ZodOptional<z.ZodString>;
+    jwtClaimName: z.ZodOptional<z.ZodString>;
+    requireTenant: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type TenantConfig = z.infer<typeof TenantConfigSchema> & {
+    /** Custom tenant resolver function (optional, not in zod schema) */
+    resolver?: TenantResolver;
+};
+/**
+ * Error thrown when tenant context is required but not found.
+ */
+export declare class TenantRequiredError extends Error {
+    name: string;
+    statusCode: number;
+    constructor(message?: string);
+}
+/**
+ * Error thrown when tenant isolation fails (RLS, schema, database).
+ */
+export declare class TenantIsolationError extends Error {
+    strategy?: IsolationStrategy | undefined;
+    name: string;
+    statusCode: number;
+    constructor(message?: string, strategy?: IsolationStrategy | undefined);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG,eAAe,GAAG,mBAAmB,GAAG,qBAAqB,CAAC;AAE9F;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,KAAK,GAAG,YAAY,CAAC;AAErD;;GAEG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;iBAkB9B,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE;;GAEG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;iBAqB3B,CAAC;AAEH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,MAAM,WAAW,yBAAyB;IACxC,OAAO,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;IAClE,GAAG,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,yBAAyB,CAAC;AAEtE;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,GAAG,EAAE,mBAAmB,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,MAAM,GAAG,IAAI,CAAC;AAElG;;GAEG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;iBAoB7B,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,GAAG;IAC9D,oEAAoE;IACpE,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC3B,CAAC;AAEF;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,IAAI,SAAyB;IAC7B,UAAU,SAAO;gBAEL,OAAO,GAAE,MAAqC;CAG3D;AAED;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAMpC,QAAQ,CAAC,EAAE,iBAAiB;IALrC,IAAI,SAA0B;IAC9B,UAAU,SAAO;gBAGf,OAAO,GAAE,MAA2C,EAC7C,QAAQ,CAAC,EAAE,iBAAiB,YAAA;CAItC"}

package/dist/types.js

@@ -0,0 +1,78 @@
+import { z } from "zod";
+/**
+ * Runtime tenant context — available via AsyncLocalStorage in request handlers.
+ */
+export const TenantContextSchema = z.object({
+    /** Unique tenant identifier (UUID, slug, or org ID) */
+    id: z.string().min(1),
+    /** Optional tenant slug for URL-friendly routing (e.g., "acme-corp") */
+    slug: z.string().min(1).optional(),
+    /** Subscription tier — determines feature access and limits */
+    plan: z.enum(["free", "pro", "enterprise"]).optional(),
+    /** Feature flags enabled for this tenant */
+    features: z.array(z.string()).optional(),
+    /** Rate limits and quota settings */
+    limits: z.record(z.string(), z.number()).optional(),
+    /** Custom metadata (arbitrary JSON) */
+    metadata: z.record(z.string(), z.unknown()).optional(),
+});
+/**
+ * Persistent tenant information — typically loaded from database.
+ */
+export const TenantInfoSchema = z.object({
+    /** Unique tenant ID */
+    id: z.string().min(1),
+    /** URL-friendly slug */
+    slug: z.string().min(1),
+    /** Display name */
+    name: z.string().min(1),
+    /** Subscription plan */
+    plan: z.enum(["free", "pro", "enterprise"]),
+    /** When the tenant was created */
+    createdAt: z.date().or(z.string().datetime()),
+    /** Tenant-specific settings (arbitrary JSON) */
+    settings: z.record(z.string(), z.unknown()).default({}),
+    /** For hierarchical organizations — parent org ID */
+    parentTenantId: z.string().optional(),
+});
+/**
+ * Configuration for tenant extraction and isolation.
+ */
+export const TenantConfigSchema = z.object({
+    /** Data isolation strategy */
+    strategy: z
+        .enum(["shared_schema", "schema_per_tenant", "database_per_tenant"])
+        .default("shared_schema"),
+    /** HTTP header name for tenant ID (API gateway default) */
+    headerName: z.string().default("x-tenant-id"),
+    /** Subdomain pattern for tenant extraction (e.g., "([a-z0-9-]+)\\.app\\.nebutra\\.com") */
+    subdomainPattern: z.string().optional(),
+    /** URL path prefix for tenant extraction (e.g., "/org/:tenantId") */
+    pathPrefix: z.string().optional(),
+    /** JWT claim name containing tenant ID */
+    jwtClaimName: z.string().optional(),
+    /** Whether to throw error if tenant is required but not resolved */
+    requireTenant: z.boolean().default(true),
+});
+/**
+ * Error thrown when tenant context is required but not found.
+ */
+export class TenantRequiredError extends Error {
+    name = "TenantRequiredError";
+    statusCode = 400;
+    constructor(message = "Tenant context is required") {
+        super(message);
+    }
+}
+/**
+ * Error thrown when tenant isolation fails (RLS, schema, database).
+ */
+export class TenantIsolationError extends Error {
+    strategy;
+    name = "TenantIsolationError";
+    statusCode = 500;
+    constructor(message = "Failed to apply tenant isolation", strategy) {
+        super(message);
+        this.strategy = strategy;
+    }
+}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@nebutra/tenant",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "private": false,
-  "license": "AGPL-3.0",
+  "license": "MIT",
   "type": "module",
   "nebutra": {
     "status": "foundation",
@@ -44,7 +44,7 @@
   ],
   "dependencies": {
     "zod": "^4.3.6",
-    "@nebutra/logger": "0.1.0"
+    "@nebutra/logger": "0.1.1"
   },
   "devDependencies": {
     "vitest": "^4.1.4",