@zudojs/tenancy 0.1.0 → 1.0.0

package/dist/security/guard.core.d.ts

@@ -10,6 +10,12 @@ import type { TenantResolutionSource, TenantTrustLevel } from "../tenancyTypes/t
  * Get the default trust level for a resolution source.
  */
 export declare function getDefaultTrust(source: TenantResolutionSource): TenantTrustLevel;
+/**
+ * Compare two trust levels.
+ *
+ * @returns True when `actual` is at least as trusted as `required`.
+ */
+export declare function meetsTrustLevel(actual: TenantTrustLevel, required: TenantTrustLevel): boolean;
 /**
  * Validate that a tenant is usable.
  */
@@ -20,10 +26,23 @@ export declare function assertTenantUsable(tenant: Tenant): void;
 export declare function assertTenantOwnership(resource: TenantResource, tenantId: TenantId): void;
 /**
  * Validate that a trust level is sufficient.
+ *
+ * @throws {TenantTrustLevelError} when the resolution is not trusted enough.
  */
 export declare function assertTrustLevel(actual: TenantTrustLevel, required: TenantTrustLevel, source: TenantResolutionSource): void;
+/**
+ * Assert that a caller may act on a tenant other than its own.
+ *
+ * @throws {TenantAccessDeniedError} when the two tenants differ.
+ */
+export declare function assertSameTenant(actual: TenantId, expected: TenantId): void;
 /**
  * Create a tenant key for scoped resources.
+ *
+ * @param tenantId - The owning tenant.
+ * @param key - The resource key within that tenant.
+ * @param separator - Segment separator. Defaults to ":".
+ * @returns A key that no other tenant's key can collide with.
  */
 export declare function tenantKey(tenantId: TenantId, key: string, separator?: string): string;
 /**

package/dist/security/guard.core.js

@@ -3,25 +3,46 @@
  *
  * @module security/guard
  */
-import { TenantAccessDeniedError, TenantIsolationError, TenantUnavailableError, } from "../tenancyErrors/tenancyError.types.js";
-/** Trust levels for resolution sources. */
+import { TenantAccessDeniedError, TenantIsolationError, TenantTrustLevelError, TenantUnavailableError, } from "../tenancyErrors/tenancyError.types.js";
+/**
+ * Trust levels for resolution sources.
+ *
+ * `header` is untrusted: the value arrives on the wire under the client's
+ * control unless a trusted proxy overwrites it, and this package cannot know
+ * whether one does. Applications that can attest to their edge raise it
+ * explicitly via `createHeaderResolver({ trust: "verified" })`.
+ */
 const TRUST_MAP = {
     jwt: "trusted",
     "api-key": "trusted",
     manual: "trusted",
     system: "trusted",
-    header: "verified",
     subdomain: "verified",
     domain: "verified",
+    header: "untrusted",
     path: "untrusted",
     custom: "untrusted",
 };
+/** Trust levels in ascending order of confidence. */
+const TRUST_ORDER = [
+    "untrusted",
+    "verified",
+    "trusted",
+];
 /**
  * Get the default trust level for a resolution source.
  */
 export function getDefaultTrust(source) {
     return TRUST_MAP[source] ?? "untrusted";
 }
+/**
+ * Compare two trust levels.
+ *
+ * @returns True when `actual` is at least as trusted as `required`.
+ */
+export function meetsTrustLevel(actual, required) {
+    return TRUST_ORDER.indexOf(actual) >= TRUST_ORDER.indexOf(required);
+}
 /**
  * Validate that a tenant is usable.
  */
@@ -40,20 +61,48 @@ export function assertTenantOwnership(resource, tenantId) {
 }
 /**
  * Validate that a trust level is sufficient.
+ *
+ * @throws {TenantTrustLevelError} when the resolution is not trusted enough.
  */
 export function assertTrustLevel(actual, required, source) {
-    const levels = ["untrusted", "verified", "trusted"];
-    const actualIdx = levels.indexOf(actual);
-    const requiredIdx = levels.indexOf(required);
-    if (actualIdx < requiredIdx) {
-        throw new TenantAccessDeniedError(`Insufficient trust level from "${source}": need ${required}, got ${actual}`);
+    if (!meetsTrustLevel(actual, required)) {
+        throw new TenantTrustLevelError(source, required, actual);
+    }
+}
+/**
+ * Assert that a caller may act on a tenant other than its own.
+ *
+ * @throws {TenantAccessDeniedError} when the two tenants differ.
+ */
+export function assertSameTenant(actual, expected) {
+    if (actual !== expected) {
+        throw new TenantAccessDeniedError(actual);
     }
 }
+/**
+ * Escape a key segment so it cannot forge a separator boundary.
+ *
+ * Tenant ids are already constrained by `createTenantId`, but arbitrary keys
+ * are not; without this, a key of `"cache:k"` under tenant `a` collides with
+ * key `"k"` under a tenant literally named `a:cache`.
+ */
+function escapeSegment(segment, separator) {
+    return segment.split(separator).join(`\\${separator}`);
+}
 /**
  * Create a tenant key for scoped resources.
+ *
+ * @param tenantId - The owning tenant.
+ * @param key - The resource key within that tenant.
+ * @param separator - Segment separator. Defaults to ":".
+ * @returns A key that no other tenant's key can collide with.
  */
 export function tenantKey(tenantId, key, separator = ":") {
-    return `tenant${separator}${tenantId}${separator}${key}`;
+    return [
+        "tenant",
+        escapeSegment(tenantId, separator),
+        escapeSegment(key, separator),
+    ].join(separator);
 }
 /**
  * Create a tenant cache key.

package/dist/security/index.d.ts

@@ -3,5 +3,5 @@
  *
  * @module security
  */
-export { getDefaultTrust, assertTenantUsable, assertTenantOwnership, assertTrustLevel, tenantKey, createTenantCacheKey, } from "./guard.core.js";
+export { getDefaultTrust, meetsTrustLevel, assertTenantUsable, assertTenantOwnership, assertTrustLevel, assertSameTenant, tenantKey, createTenantCacheKey, } from "./guard.core.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/security/index.js

@@ -3,5 +3,5 @@
  *
  * @module security
  */
-export { getDefaultTrust, assertTenantUsable, assertTenantOwnership, assertTrustLevel, tenantKey, createTenantCacheKey, } from "./guard.core.js";
+export { getDefaultTrust, meetsTrustLevel, assertTenantUsable, assertTenantOwnership, assertTrustLevel, assertSameTenant, tenantKey, createTenantCacheKey, } from "./guard.core.js";
 //# sourceMappingURL=index.js.map

package/dist/tenancyErrors/index.d.ts

@@ -4,5 +4,5 @@
  * @module tenancyErrors
  */
 export { TenantError } from "./tenancyError.base.js";
-export { InvalidTenantIdError, TenantNotFoundError, TenantContextMissingError, TenantResolutionError, TenantResolutionConflictError, TenantUnavailableError, TenantAccessDeniedError, TenantAlreadyExistsError, TenantProvisioningError, TenantIsolationError, } from "./tenancyError.types.js";
+export { InvalidTenantIdError, TenantNotFoundError, TenantContextMissingError, TenantResolutionError, TenantResolutionConflictError, TenantUnavailableError, TenantAccessDeniedError, TenantTrustLevelError, TenantAlreadyExistsError, TenantIsolationError, } from "./tenancyError.types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/tenancyErrors/index.js

@@ -4,5 +4,5 @@
  * @module tenancyErrors
  */
 export { TenantError } from "./tenancyError.base.js";
-export { InvalidTenantIdError, TenantNotFoundError, TenantContextMissingError, TenantResolutionError, TenantResolutionConflictError, TenantUnavailableError, TenantAccessDeniedError, TenantAlreadyExistsError, TenantProvisioningError, TenantIsolationError, } from "./tenancyError.types.js";
+export { InvalidTenantIdError, TenantNotFoundError, TenantContextMissingError, TenantResolutionError, TenantResolutionConflictError, TenantUnavailableError, TenantAccessDeniedError, TenantTrustLevelError, TenantAlreadyExistsError, TenantIsolationError, } from "./tenancyError.types.js";
 //# sourceMappingURL=index.js.map

package/dist/tenancyErrors/tenancyError.types.d.ts

@@ -5,6 +5,7 @@
  */
 import { TenantError } from "./tenancyError.base.js";
 import type { TenantId, TenantStatus } from "../tenancyTypes/tenantIdentity.js";
+import type { TenantResolutionSource, TenantTrustLevel } from "../tenancyTypes/tenantInterface.js";
 /**
  * The provided tenant ID is invalid.
  */
@@ -48,16 +49,20 @@ export declare class TenantAccessDeniedError extends TenantError {
     constructor(tenantId: string);
 }
 /**
- * Tenant already exists.
+ * The tenant was resolved from a source that is not trusted enough.
+ *
+ * Distinct from {@link TenantAccessDeniedError} so the resolution source and
+ * the two trust levels stay in structured metadata instead of being formatted
+ * into a field that is supposed to hold a tenant id.
  */
-export declare class TenantAlreadyExistsError extends TenantError {
-    constructor(identifier: string);
+export declare class TenantTrustLevelError extends TenantError {
+    constructor(source: TenantResolutionSource, required: TenantTrustLevel, actual: TenantTrustLevel);
 }
 /**
- * Tenant provisioning failed.
+ * Tenant already exists.
  */
-export declare class TenantProvisioningError extends TenantError {
-    constructor(tenantId: string, cause?: unknown);
+export declare class TenantAlreadyExistsError extends TenantError {
+    constructor(identifier: string);
 }
 /**
  * Tenant isolation violation detected.

package/dist/tenancyErrors/tenancyError.types.js

@@ -81,6 +81,21 @@ export class TenantAccessDeniedError extends TenantError {
         });
     }
 }
+/**
+ * The tenant was resolved from a source that is not trusted enough.
+ *
+ * Distinct from {@link TenantAccessDeniedError} so the resolution source and
+ * the two trust levels stay in structured metadata instead of being formatted
+ * into a field that is supposed to hold a tenant id.
+ */
+export class TenantTrustLevelError extends TenantError {
+    constructor(source, required, actual) {
+        super(`Insufficient trust level from "${source}": need ${required}, got ${actual}`, {
+            code: ErrorCode.ACCESS_DENIED,
+            metadata: { source, required, actual },
+        });
+    }
+}
 /**
  * Tenant already exists.
  */
@@ -92,18 +107,6 @@ export class TenantAlreadyExistsError extends TenantError {
         });
     }
 }
-/**
- * Tenant provisioning failed.
- */
-export class TenantProvisioningError extends TenantError {
-    constructor(tenantId, cause) {
-        super(`Provisioning failed for tenant "${tenantId}"`, {
-            code: ErrorCode.OPERATION_FAILED,
-            cause,
-            metadata: { tenantId },
-        });
-    }
-}
 /**
  * Tenant isolation violation detected.
  */

package/dist/tenancyTypes/index.d.ts

@@ -3,9 +3,9 @@
  *
  * @module tenancyTypes
  */
-export { type TenantId, createTenantId, type TenantStatus, type TenantIsolationStrategy, type TenancyMode, } from "./tenantIdentity.js";
+export { type TenantId, MAX_TENANT_ID_LENGTH, createTenantId, tryCreateTenantId, isValidTenantId, type TenantStatus, } from "./tenantIdentity.js";
 export { type Tenant, type TenantResolutionSource, type TenantTrustLevel, type TenantContext, type SystemContext, type TenantExecutionContext, type ExecutionTenantContext, type TenantRequirement, type TenantResource, } from "./tenantInterface.js";
 export { type TenantResolution, type TenantResolutionResult, type TenantResolver, type ResolverChainOptions, } from "./resolverTypes.js";
-export { type TenantRepository, type TenantCache, type TenantManager, type TenantProvisioner, type TenantIsolationConfig, type TenantConfigurationProvider, } from "./repositoryTypes.js";
-export { type TenancyOptions, type TenantDomain, type TenantScopeOptions, } from "./tenancyOptions.js";
+export { type TenantRepository, type TenantCache, } from "./repositoryTypes.js";
+export { type TenantDomain } from "./repositoryTypes.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/tenancyTypes/index.js

@@ -3,9 +3,9 @@
  *
  * @module tenancyTypes
  */
-export { createTenantId, } from "./tenantIdentity.js";
+export { MAX_TENANT_ID_LENGTH, createTenantId, tryCreateTenantId, isValidTenantId, } from "./tenantIdentity.js";
 export {} from "./tenantInterface.js";
 export {} from "./resolverTypes.js";
 export {} from "./repositoryTypes.js";
-export {} from "./tenancyOptions.js";
+export {} from "./repositoryTypes.js";
 //# sourceMappingURL=index.js.map

package/dist/tenancyTypes/repositoryTypes.d.ts

@@ -3,7 +3,7 @@
  *
  * @module tenancyTypes/repositoryTypes
  */
-import type { TenantId, TenantIsolationStrategy } from "./tenantIdentity.js";
+import type { TenantId } from "./tenantIdentity.js";
 import type { Tenant } from "./tenantInterface.js";
 /** Repository for loading tenants. */
 export interface TenantRepository {
@@ -11,30 +11,15 @@ export interface TenantRepository {
     findBySlug?(slug: string): Promise<Tenant | undefined>;
     findByDomain?(domain: string): Promise<Tenant | undefined>;
 }
+/** A custom domain mapped to the tenant it serves. */
+export interface TenantDomain {
+    readonly domain: string;
+    readonly tenantId: TenantId;
+}
 /** Cache for tenant data. */
 export interface TenantCache {
     get(id: TenantId): Promise<Tenant | undefined>;
     set(tenant: Tenant): Promise<void>;
     delete(id: TenantId): Promise<void>;
 }
-/** High-level tenant orchestration. */
-export interface TenantManager {
-    resolve(context: unknown): Promise<Tenant | undefined>;
-    get(id: TenantId): Promise<Tenant | undefined>;
-    require(id: TenantId): Promise<Tenant>;
-}
-/** Handles tenant setup operations. */
-export interface TenantProvisioner {
-    provision(tenant: Tenant): Promise<void>;
-}
-/** Isolation configuration for a tenant. */
-export interface TenantIsolationConfig {
-    readonly strategy: TenantIsolationStrategy;
-    readonly identifier?: string;
-}
-/** Tenant configuration provider. */
-export interface TenantConfigurationProvider {
-    get<T = unknown>(tenantId: TenantId, key: string): Promise<T | undefined>;
-    set<T = unknown>(tenantId: TenantId, key: string, value: T): Promise<void>;
-}
 //# sourceMappingURL=repositoryTypes.d.ts.map

package/dist/tenancyTypes/resolverTypes.d.ts

@@ -26,9 +26,21 @@ export interface TenantResolver<Context = unknown> {
 }
 /** Options for resolver chain. */
 export interface ResolverChainOptions {
-    /** Whether to detect conflicts between resolver results. */
+    /** Name reported when the chain is used as a resolver. Defaults to "chain". */
+    readonly name?: string;
+    /** Priority when nested in another chain. Defaults to the highest member's. */
+    readonly priority?: number;
+    /**
+     * Run every resolver and collect all candidates, rather than stopping at the
+     * first match. Required for conflict detection.
+     */
     readonly detectConflicts?: boolean;
-    /** Throw on conflict instead of using highest priority. */
+    /**
+     * Throw when candidates name different tenants. Defaults to true.
+     *
+     * Disagreement between a verified credential and a client-supplied header is
+     * the signature of an attempted cross-tenant request.
+     */
     readonly throwOnConflict?: boolean;
 }
 //# sourceMappingURL=resolverTypes.d.ts.map

package/dist/tenancyTypes/tenantIdentity.d.ts

@@ -9,13 +9,32 @@ declare const TenantIdBrand: unique symbol;
 export type TenantId = string & {
     readonly [TenantIdBrand]: true;
 };
-/** Create a validated TenantId. */
+/** Maximum accepted tenant id length. */
+export declare const MAX_TENANT_ID_LENGTH = 64;
+/**
+ * Create a validated TenantId.
+ *
+ * Input is trimmed, Unicode-normalized and lowercased before validation, so
+ * two spellings of the same identifier cannot become two tenants.
+ *
+ * @param value - The candidate identifier.
+ * @returns The normalized, validated tenant id.
+ * @throws {InvalidTenantIdError} when the value is not a valid tenant id.
+ */
 export declare function createTenantId(value: string): TenantId;
+/**
+ * Create a validated TenantId, or undefined when the value is unusable.
+ *
+ * Resolvers use this: an unparseable candidate means "this resolver found
+ * nothing", not "the request is malformed".
+ *
+ * @param value - The candidate identifier.
+ * @returns The tenant id, or undefined.
+ */
+export declare function tryCreateTenantId(value: unknown): TenantId | undefined;
+/** Whether a value is a well-formed tenant id. */
+export declare function isValidTenantId(value: unknown): value is TenantId;
 /** Tenant lifecycle status. */
 export type TenantStatus = "provisioning" | "active" | "inactive" | "suspended" | "deleting" | "deleted";
-/** Database isolation strategy for tenant data. */
-export type TenantIsolationStrategy = "shared" | "schema" | "database" | "hybrid";
-/** Tenancy execution mode. */
-export type TenancyMode = "tenant" | "system";
 export {};
 //# sourceMappingURL=tenantIdentity.d.ts.map

package/dist/tenancyTypes/tenantIdentity.js

@@ -3,11 +3,61 @@
  *
  * @module tenancyTypes/tenantIdentity
  */
-/** Create a validated TenantId. */
+import { InvalidTenantIdError } from "../tenancyErrors/tenancyError.types.js";
+/**
+ * Characters a tenant id may contain.
+ *
+ * Deliberately narrow. A tenant id is concatenated into cache keys, log lines,
+ * schema names and file paths, so anything that could act as a separator or a
+ * path segment in one of those contexts is rejected here rather than escaped
+ * at every use site.
+ */
+const TENANT_ID_PATTERN = /^[a-z0-9][a-z0-9_-]*$/u;
+/** Maximum accepted tenant id length. */
+export const MAX_TENANT_ID_LENGTH = 64;
+/**
+ * Create a validated TenantId.
+ *
+ * Input is trimmed, Unicode-normalized and lowercased before validation, so
+ * two spellings of the same identifier cannot become two tenants.
+ *
+ * @param value - The candidate identifier.
+ * @returns The normalized, validated tenant id.
+ * @throws {InvalidTenantIdError} when the value is not a valid tenant id.
+ */
 export function createTenantId(value) {
-    if (!value || value.trim().length === 0) {
-        throw new Error("TenantId cannot be empty");
+    if (typeof value !== "string")
+        throw new InvalidTenantIdError(String(value));
+    const normalized = value.normalize("NFKC").trim().toLowerCase();
+    if (normalized.length === 0 || normalized.length > MAX_TENANT_ID_LENGTH) {
+        throw new InvalidTenantIdError(value);
+    }
+    if (!TENANT_ID_PATTERN.test(normalized)) {
+        throw new InvalidTenantIdError(value);
     }
-    return value;
+    return normalized;
+}
+/**
+ * Create a validated TenantId, or undefined when the value is unusable.
+ *
+ * Resolvers use this: an unparseable candidate means "this resolver found
+ * nothing", not "the request is malformed".
+ *
+ * @param value - The candidate identifier.
+ * @returns The tenant id, or undefined.
+ */
+export function tryCreateTenantId(value) {
+    if (typeof value !== "string")
+        return undefined;
+    try {
+        return createTenantId(value);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Whether a value is a well-formed tenant id. */
+export function isValidTenantId(value) {
+    return tryCreateTenantId(value) !== undefined;
 }
 //# sourceMappingURL=tenantIdentity.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/tenancy",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "description": "Multi-tenant context and isolation with tenant resolution, AsyncLocalStorage propagation, resolver chains, trust levels, and guard middleware.",
   "license": "MIT",
   "type": "module",
@@ -15,21 +15,17 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "!dist/**/*.map",
+    "!dist/**/*.tsbuildinfo",
+    "!dist/.tsbuildinfo"
   ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "clean": "rm -rf dist",
-    "test": "vitest run",
-    "test:watch": "vitest"
-  },
   "dependencies": {
-    "@zudojs/errors": "0.1.0",
-    "@zudojs/constants": "0.1.0"
+    "@zudojs/errors": "1.0.0",
+    "@zudojs/constants": "1.0.0"
   },
   "peerDependencies": {
-    "@zudojs/http": "0.1.0"
+    "@zudojs/http": "1.0.0"
   },
   "peerDependenciesMeta": {
     "@zudojs/http": {
@@ -40,7 +36,7 @@
     "node": ">=24.0.0"
   },
   "devDependencies": {
-    "typescript": "^7.0.2",
+    "typescript": "7.0.2",
     "vitest": "^4.1.11"
   },
   "publishConfig": {
@@ -53,8 +49,19 @@
     "saas"
   ],
   "homepage": "https://github.com/oyinlola-tech/zudo#readme",
+  "bugs": {
+    "url": "https://github.com/oyinlola-tech/zudo/issues"
+  },
   "repository": {
     "type": "git",
-    "url": "https://github.com/oyinlola-tech/zudo"
+    "url": "https://github.com/oyinlola-tech/zudo",
+    "directory": "packages/tenancy"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
-}
+}