@crewhaus/tenancy 0.1.4 → 0.1.6

package/dist/index.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Catalog R17 `tenancy` — per-tenant storage rebase + cross-tenant guard.
+ *
+ * The managed daemon (Section 20) routes every request through
+ * `withTenant(tenantId, fn)` which:
+ *
+ *   1. Validates `tenantId` against `TENANT_ID_RE` so a malformed claim
+ *      cannot become a path-traversal vector.
+ *   2. Resolves a per-tenant root: `<tenantsRoot>/<tenantId>/`.
+ *   3. Exposes that root via the AsyncLocalStorage-backed
+ *      `currentTenantContext()` so downstream code (session-store,
+ *      checkpoint-store, audit-log, tool-result-store) can rebase
+ *      its own `rootDir`.
+ *   4. Fences cross-tenant reads — `assertSamePath(absPath)` throws
+ *      `TenancyError` if `absPath` is not under the active tenant's
+ *      root. Storage adapters call this on every public method.
+ *
+ * The runtime carries the active tenant id through `RunContext.tenantId`;
+ * tenancy itself stays loosely coupled to the wider runtime so it can
+ * be unit-tested in isolation.
+ *
+ * Layer R17. Pairs with `gateway-server` (R16) and `audit-log` (R17).
+ */
+import { CrewhausError } from "@crewhaus/errors";
+export declare class TenancyError extends CrewhausError {
+    readonly name = "TenancyError";
+    constructor(message: string, cause?: unknown);
+}
+export type TenantBudget = {
+    /** Cumulative tokens granted before runs.create returns 429. */
+    readonly maxInputTokens: number;
+    readonly maxOutputTokens: number;
+};
+export type Tenant = {
+    readonly id: string;
+    /** Path-rebased session-store root. */
+    readonly sessionRoot: string;
+    /** Path-rebased eval-store root. */
+    readonly evalRoot: string;
+    /** Path-rebased tool-result-store root. */
+    readonly toolResultRoot: string;
+    /** Per-tenant audit-log root. */
+    readonly auditRoot: string;
+    /** Per-tenant policy overrides (extends the global policy ruleset). */
+    readonly policyOverrides: ReadonlyArray<{
+        readonly toolName: string;
+        readonly action: "allow" | "deny" | "audit";
+    }>;
+    readonly budget: TenantBudget;
+};
+export type TenantContext = {
+    readonly tenant: Tenant;
+};
+export declare function validateTenantId(id: string): void;
+export type TenantOptions = {
+    /** Filesystem root under which per-tenant subtrees live. */
+    readonly tenantsRoot?: string;
+    /** Optional overrides keyed by tenantId. */
+    readonly overrides?: Readonly<Record<string, Partial<Tenant>>>;
+};
+export declare function buildTenant(id: string, opts?: TenantOptions): Tenant;
+/**
+ * Run `fn` with `tenant` as the active context. Nested calls override
+ * outer; the outer context is restored on return.
+ */
+export declare function withTenant<T>(tenant: Tenant, fn: () => Promise<T> | T): Promise<T> | T;
+export declare function currentTenantContext(): TenantContext | undefined;
+export declare function requireTenant(): Tenant;
+/**
+ * Throw `TenancyError` if `absPath` is not contained within `expectedRoot`.
+ * Used by storage adapters before every public read/write to fail-closed
+ * on a cross-tenant path leak.
+ */
+export declare function assertSamePath(absPath: string, expectedRoot: string): void;

package/dist/index.js

@@ -0,0 +1,87 @@
+/**
+ * Catalog R17 `tenancy` — per-tenant storage rebase + cross-tenant guard.
+ *
+ * The managed daemon (Section 20) routes every request through
+ * `withTenant(tenantId, fn)` which:
+ *
+ *   1. Validates `tenantId` against `TENANT_ID_RE` so a malformed claim
+ *      cannot become a path-traversal vector.
+ *   2. Resolves a per-tenant root: `<tenantsRoot>/<tenantId>/`.
+ *   3. Exposes that root via the AsyncLocalStorage-backed
+ *      `currentTenantContext()` so downstream code (session-store,
+ *      checkpoint-store, audit-log, tool-result-store) can rebase
+ *      its own `rootDir`.
+ *   4. Fences cross-tenant reads — `assertSamePath(absPath)` throws
+ *      `TenancyError` if `absPath` is not under the active tenant's
+ *      root. Storage adapters call this on every public method.
+ *
+ * The runtime carries the active tenant id through `RunContext.tenantId`;
+ * tenancy itself stays loosely coupled to the wider runtime so it can
+ * be unit-tested in isolation.
+ *
+ * Layer R17. Pairs with `gateway-server` (R16) and `audit-log` (R17).
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+import { resolve as resolvePath } from "node:path";
+import { CrewhausError } from "@crewhaus/errors";
+const TENANT_ID_RE = /^[a-zA-Z0-9][a-zA-Z0-9_\-]{0,63}$/;
+export class TenancyError extends CrewhausError {
+    name = "TenancyError";
+    constructor(message, cause) {
+        super("config", message, cause);
+    }
+}
+const storage = new AsyncLocalStorage();
+export function validateTenantId(id) {
+    if (!TENANT_ID_RE.test(id)) {
+        throw new TenancyError(`invalid tenantId "${id}" — expected alphanumeric / hyphen / underscore, max 64 chars, no leading separator`);
+    }
+}
+const DEFAULT_BUDGET = {
+    maxInputTokens: 1_000_000,
+    maxOutputTokens: 200_000,
+};
+const DEFAULT_TENANTS_ROOT = ".crewhaus/tenants";
+export function buildTenant(id, opts = {}) {
+    validateTenantId(id);
+    const root = resolvePath(opts.tenantsRoot ?? DEFAULT_TENANTS_ROOT, id);
+    const override = opts.overrides?.[id] ?? {};
+    return {
+        id,
+        sessionRoot: override.sessionRoot ?? resolvePath(root, "sessions"),
+        evalRoot: override.evalRoot ?? resolvePath(root, "evals"),
+        toolResultRoot: override.toolResultRoot ?? resolvePath(root, "tool-results"),
+        auditRoot: override.auditRoot ?? resolvePath(root, "audit"),
+        policyOverrides: override.policyOverrides ?? [],
+        budget: override.budget ?? DEFAULT_BUDGET,
+    };
+}
+/**
+ * Run `fn` with `tenant` as the active context. Nested calls override
+ * outer; the outer context is restored on return.
+ */
+export function withTenant(tenant, fn) {
+    return storage.run({ tenant }, fn);
+}
+export function currentTenantContext() {
+    return storage.getStore();
+}
+export function requireTenant() {
+    const ctx = storage.getStore();
+    if (ctx === undefined) {
+        throw new TenancyError("no active tenant — wrap the call in withTenant(tenant, fn)");
+    }
+    return ctx.tenant;
+}
+/**
+ * Throw `TenancyError` if `absPath` is not contained within `expectedRoot`.
+ * Used by storage adapters before every public read/write to fail-closed
+ * on a cross-tenant path leak.
+ */
+export function assertSamePath(absPath, expectedRoot) {
+    const resolved = resolvePath(absPath);
+    const root = resolvePath(expectedRoot);
+    if (resolved !== root && !resolved.startsWith(`${root}/`)) {
+        throw new TenancyError(`cross-tenant access denied: "${resolved}" is not under "${root}"`);
+    }
+}

package/package.json

@@ -1,18 +1,21 @@
 {
   "name": "@crewhaus/tenancy",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "type": "module",
   "description": "Per-tenant storage rebase + cross-tenant guard for the managed-daemon target",
-  "main": "src/index.ts",
-  "types": "src/index.ts",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
   },
   "scripts": {
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/errors": "0.1.4"
+    "@crewhaus/errors": "0.1.6"
   },
   "license": "Apache-2.0",
   "author": {
@@ -32,5 +35,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "files": ["src", "README.md", "LICENSE", "NOTICE"]
+  "files": ["dist", "README.md", "LICENSE", "NOTICE"]
 }

package/src/index.test.ts

@@ -1,127 +0,0 @@
-import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { mkdtempSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import {
-  TenancyError,
-  assertSamePath,
-  buildTenant,
-  currentTenantContext,
-  requireTenant,
-  validateTenantId,
-  withTenant,
-} from "./index";
-
-let tmp: string;
-
-beforeEach(() => {
-  tmp = mkdtempSync(join(tmpdir(), "tenancy-"));
-});
-
-afterEach(() => {
-  rmSync(tmp, { recursive: true, force: true });
-});
-
-describe("validateTenantId", () => {
-  test("accepts alphanumeric ids", () => {
-    expect(() => validateTenantId("tenant-a")).not.toThrow();
-    expect(() => validateTenantId("Acme_42")).not.toThrow();
-    expect(() => validateTenantId("a")).not.toThrow();
-  });
-
-  test("rejects leading hyphen / underscore", () => {
-    expect(() => validateTenantId("-bad")).toThrow(TenancyError);
-    expect(() => validateTenantId("_bad")).toThrow(TenancyError);
-  });
-
-  test("rejects path-traversal characters", () => {
-    expect(() => validateTenantId("../etc")).toThrow(TenancyError);
-    expect(() => validateTenantId("a/b")).toThrow(TenancyError);
-    expect(() => validateTenantId("a\\b")).toThrow(TenancyError);
-  });
-
-  test("rejects whitespace / nulls / overlong ids", () => {
-    expect(() => validateTenantId("a b")).toThrow(TenancyError);
-    expect(() => validateTenantId("a".repeat(70))).toThrow(TenancyError);
-  });
-});
-
-describe("buildTenant", () => {
-  test("rebases all per-tenant roots under the tenants root", () => {
-    const t = buildTenant("acme", { tenantsRoot: tmp });
-    expect(t.id).toBe("acme");
-    expect(t.sessionRoot).toBe(join(tmp, "acme", "sessions"));
-    expect(t.evalRoot).toBe(join(tmp, "acme", "evals"));
-    expect(t.toolResultRoot).toBe(join(tmp, "acme", "tool-results"));
-    expect(t.auditRoot).toBe(join(tmp, "acme", "audit"));
-  });
-
-  test("applies overrides", () => {
-    const t = buildTenant("acme", {
-      tenantsRoot: tmp,
-      overrides: { acme: { sessionRoot: "/srv/custom" } },
-    });
-    expect(t.sessionRoot).toBe("/srv/custom");
-    // Other roots still default.
-    expect(t.evalRoot).toBe(join(tmp, "acme", "evals"));
-  });
-});
-
-describe("withTenant + AsyncLocalStorage", () => {
-  test("requireTenant returns the active tenant inside withTenant", async () => {
-    const t = buildTenant("acme", { tenantsRoot: tmp });
-    await withTenant(t, async () => {
-      expect(requireTenant().id).toBe("acme");
-    });
-  });
-
-  test("requireTenant throws outside of withTenant", () => {
-    expect(() => requireTenant()).toThrow(TenancyError);
-  });
-
-  test("currentTenantContext returns undefined outside", () => {
-    expect(currentTenantContext()).toBeUndefined();
-  });
-
-  test("nested withTenant overrides the outer", async () => {
-    const a = buildTenant("acme", { tenantsRoot: tmp });
-    const b = buildTenant("bravo", { tenantsRoot: tmp });
-    await withTenant(a, async () => {
-      await withTenant(b, () => {
-        expect(requireTenant().id).toBe("bravo");
-      });
-      expect(requireTenant().id).toBe("acme");
-    });
-  });
-
-  test("async work inside withTenant retains the context across awaits", async () => {
-    const t = buildTenant("acme", { tenantsRoot: tmp });
-    await withTenant(t, async () => {
-      await new Promise((r) => setTimeout(r, 10));
-      expect(requireTenant().id).toBe("acme");
-    });
-  });
-});
-
-describe("assertSamePath (T8)", () => {
-  test("accepts exact root match", () => {
-    expect(() => assertSamePath("/srv/acme", "/srv/acme")).not.toThrow();
-  });
-  test("accepts a child path", () => {
-    expect(() => assertSamePath("/srv/acme/sessions/abc", "/srv/acme")).not.toThrow();
-  });
-  test("rejects a sibling path", () => {
-    expect(() => assertSamePath("/srv/bravo/sessions/abc", "/srv/acme")).toThrow(
-      /cross-tenant access denied/,
-    );
-  });
-  test("rejects a parent path", () => {
-    expect(() => assertSamePath("/srv", "/srv/acme")).toThrow(TenancyError);
-  });
-  test("rejects an unrelated path", () => {
-    expect(() => assertSamePath("/etc/passwd", "/srv/acme")).toThrow(TenancyError);
-  });
-  test("normalises ../ traversal before checking", () => {
-    expect(() => assertSamePath("/srv/acme/../bravo/data", "/srv/acme")).toThrow(TenancyError);
-  });
-});

package/src/index.ts

@@ -1,135 +0,0 @@
-/**
- * Catalog R17 `tenancy` — per-tenant storage rebase + cross-tenant guard.
- *
- * The managed daemon (Section 20) routes every request through
- * `withTenant(tenantId, fn)` which:
- *
- *   1. Validates `tenantId` against `TENANT_ID_RE` so a malformed claim
- *      cannot become a path-traversal vector.
- *   2. Resolves a per-tenant root: `<tenantsRoot>/<tenantId>/`.
- *   3. Exposes that root via the AsyncLocalStorage-backed
- *      `currentTenantContext()` so downstream code (session-store,
- *      checkpoint-store, audit-log, tool-result-store) can rebase
- *      its own `rootDir`.
- *   4. Fences cross-tenant reads — `assertSamePath(absPath)` throws
- *      `TenancyError` if `absPath` is not under the active tenant's
- *      root. Storage adapters call this on every public method.
- *
- * The runtime carries the active tenant id through `RunContext.tenantId`;
- * tenancy itself stays loosely coupled to the wider runtime so it can
- * be unit-tested in isolation.
- *
- * Layer R17. Pairs with `gateway-server` (R16) and `audit-log` (R17).
- */
-
-import { AsyncLocalStorage } from "node:async_hooks";
-import { resolve as resolvePath } from "node:path";
-import { CrewhausError } from "@crewhaus/errors";
-
-const TENANT_ID_RE = /^[a-zA-Z0-9][a-zA-Z0-9_\-]{0,63}$/;
-
-export class TenancyError extends CrewhausError {
-  override readonly name = "TenancyError";
-  constructor(message: string, cause?: unknown) {
-    super("config", message, cause);
-  }
-}
-
-export type TenantBudget = {
-  /** Cumulative tokens granted before runs.create returns 429. */
-  readonly maxInputTokens: number;
-  readonly maxOutputTokens: number;
-};
-
-export type Tenant = {
-  readonly id: string;
-  /** Path-rebased session-store root. */
-  readonly sessionRoot: string;
-  /** Path-rebased eval-store root. */
-  readonly evalRoot: string;
-  /** Path-rebased tool-result-store root. */
-  readonly toolResultRoot: string;
-  /** Per-tenant audit-log root. */
-  readonly auditRoot: string;
-  /** Per-tenant policy overrides (extends the global policy ruleset). */
-  readonly policyOverrides: ReadonlyArray<{
-    readonly toolName: string;
-    readonly action: "allow" | "deny" | "audit";
-  }>;
-  readonly budget: TenantBudget;
-};
-
-export type TenantContext = {
-  readonly tenant: Tenant;
-};
-
-const storage = new AsyncLocalStorage<TenantContext>();
-
-export function validateTenantId(id: string): void {
-  if (!TENANT_ID_RE.test(id)) {
-    throw new TenancyError(
-      `invalid tenantId "${id}" — expected alphanumeric / hyphen / underscore, max 64 chars, no leading separator`,
-    );
-  }
-}
-
-export type TenantOptions = {
-  /** Filesystem root under which per-tenant subtrees live. */
-  readonly tenantsRoot?: string;
-  /** Optional overrides keyed by tenantId. */
-  readonly overrides?: Readonly<Record<string, Partial<Tenant>>>;
-};
-
-const DEFAULT_BUDGET: TenantBudget = {
-  maxInputTokens: 1_000_000,
-  maxOutputTokens: 200_000,
-};
-const DEFAULT_TENANTS_ROOT = ".crewhaus/tenants";
-
-export function buildTenant(id: string, opts: TenantOptions = {}): Tenant {
-  validateTenantId(id);
-  const root = resolvePath(opts.tenantsRoot ?? DEFAULT_TENANTS_ROOT, id);
-  const override = opts.overrides?.[id] ?? {};
-  return {
-    id,
-    sessionRoot: override.sessionRoot ?? resolvePath(root, "sessions"),
-    evalRoot: override.evalRoot ?? resolvePath(root, "evals"),
-    toolResultRoot: override.toolResultRoot ?? resolvePath(root, "tool-results"),
-    auditRoot: override.auditRoot ?? resolvePath(root, "audit"),
-    policyOverrides: override.policyOverrides ?? [],
-    budget: override.budget ?? DEFAULT_BUDGET,
-  };
-}
-
-/**
- * Run `fn` with `tenant` as the active context. Nested calls override
- * outer; the outer context is restored on return.
- */
-export function withTenant<T>(tenant: Tenant, fn: () => Promise<T> | T): Promise<T> | T {
-  return storage.run({ tenant }, fn);
-}
-
-export function currentTenantContext(): TenantContext | undefined {
-  return storage.getStore();
-}
-
-export function requireTenant(): Tenant {
-  const ctx = storage.getStore();
-  if (ctx === undefined) {
-    throw new TenancyError("no active tenant — wrap the call in withTenant(tenant, fn)");
-  }
-  return ctx.tenant;
-}
-
-/**
- * Throw `TenancyError` if `absPath` is not contained within `expectedRoot`.
- * Used by storage adapters before every public read/write to fail-closed
- * on a cross-tenant path leak.
- */
-export function assertSamePath(absPath: string, expectedRoot: string): void {
-  const resolved = resolvePath(absPath);
-  const root = resolvePath(expectedRoot);
-  if (resolved !== root && !resolved.startsWith(`${root}/`)) {
-    throw new TenancyError(`cross-tenant access denied: "${resolved}" is not under "${root}"`);
-  }
-}