@thotischner/observability-mcp 1.7.1 → 3.0.0

package/dist/sdk/hooks.d.ts

@@ -0,0 +1,77 @@
+/** Stable identifier for each hook point. Mirrors the canonical set
+ *  the rest of the MCP ecosystem expects to see; extending this is
+ *  a breaking change for the plugin contract. */
+export type HookKind = "tool_pre_invoke" | "tool_post_invoke" | "resource_pre_fetch" | "resource_post_fetch" | "prompt_pre_fetch" | "prompt_post_fetch";
+/** Hook-time context. Mirrors the RequestContext the gateway already
+ *  carries but is intentionally a flat shape so plugins don't take a
+ *  dependency on server internals. */
+export interface HookContext {
+    /** Principal sub identifier (anonymous, OIDC sub, or local user). */
+    principal: string;
+    /** Tenant the principal is acting under. Always set; "default"
+     *  when no tenancy is configured. */
+    tenant: string;
+    /** Hook fan-out kind. */
+    kind: HookKind;
+    /** Per-call metadata. Currently: tool name (for tool_*), resource
+     *  URI (for resource_*), prompt name (for prompt_*). */
+    target: string;
+    /** Free-form labels — used by audit + by the hook itself to
+     *  cooperate with siblings (e.g. correlation ids). */
+    labels?: Record<string, string>;
+}
+/** Hook-time payload. The exact shape depends on the hook kind:
+ *  - tool_pre_invoke: { args: unknown }
+ *  - tool_post_invoke: { args: unknown, result: unknown }
+ *  - resource_pre_fetch: { uri: string }
+ *  - resource_post_fetch: { uri: string, contents: unknown }
+ *  - prompt_pre_fetch: { name: string, arguments: unknown }
+ *  - prompt_post_fetch: { name: string, arguments: unknown, messages: unknown }
+ *
+ *  Plugins may mutate the payload — the gateway forwards the mutated
+ *  value to the next hook, then to the underlying handler / caller. */
+export type HookPayload = Record<string, unknown>;
+/** Hook result. `allow=false` short-circuits the dispatch with
+ *  `reason` surfaced to the caller. `payload` (when present) replaces
+ *  the current payload — used for redaction / transformation /
+ *  enrichment. */
+export interface HookResult {
+    allow: boolean;
+    payload?: HookPayload;
+    reason?: string;
+}
+/** A single hook registration. The plugin manifest carries one of
+ *  these per hook entry; the loader instantiates the function from
+ *  the plugin's source. */
+export interface HookRegistration {
+    pluginName: string;
+    kind: HookKind;
+    /** Lower number runs earlier. Default 100 (mid-range). */
+    priority?: number;
+    /** enforce: blocking errors short-circuit. permissive: errors are
+     *  logged and the chain continues with the prior payload.
+     *  disabled: hook is loaded but not invoked (emergency disable). */
+    mode?: "enforce" | "permissive" | "disabled";
+    handler: (ctx: HookContext, payload: HookPayload) => Promise<HookResult> | HookResult;
+}
+/** Mutable, in-process registry. Plugin loaders push entries here;
+ *  the dispatcher reads `fire()` per call.
+ *
+ *  Hot-swap-safe: a re-registration with the same (pluginName, kind)
+ *  replaces the prior entry — used by /api/connectors/install for
+ *  zero-downtime hook updates. */
+export declare class HookRegistry {
+    private entries;
+    /** Register or replace a hook entry. Returns the resolved registration. */
+    register(entry: HookRegistration): HookRegistration;
+    /** Remove all entries owned by a plugin (e.g. on uninstall). */
+    unregisterPlugin(pluginName: string): number;
+    /** All entries for a hook kind in priority order. */
+    list(kind: HookKind): HookRegistration[];
+    /** Snapshot of every registration regardless of kind (for diagnostics). */
+    all(): HookRegistration[];
+    /** Fire every hook of the given kind in priority order. Each hook
+     *  receives the (possibly mutated) payload from the previous one.
+     *  Short-circuits on first `allow:false`. */
+    fire(kind: HookKind, ctx: HookContext, initialPayload: HookPayload, logger?: (level: "warn" | "info", msg: string) => void): Promise<HookResult>;
+}

package/dist/sdk/hooks.js

@@ -0,0 +1,72 @@
+// Plugin lifecycle hooks — interpose on every tool / resource /
+// prompt invocation the gateway dispatches. Plugins declare hooks in
+// their manifest; the HookRegistry resolves them on load and the
+// dispatcher fires them around each call.
+//
+// Hooks land here as part of Phase F7 so Phase F9 (virtual servers)
+// and Phase F10 (federation) can interpose without duplicating
+// dispatch logic.
+/** Mutable, in-process registry. Plugin loaders push entries here;
+ *  the dispatcher reads `fire()` per call.
+ *
+ *  Hot-swap-safe: a re-registration with the same (pluginName, kind)
+ *  replaces the prior entry — used by /api/connectors/install for
+ *  zero-downtime hook updates. */
+export class HookRegistry {
+    entries = [];
+    /** Register or replace a hook entry. Returns the resolved registration. */
+    register(entry) {
+        this.entries = this.entries.filter((e) => !(e.pluginName === entry.pluginName && e.kind === entry.kind));
+        this.entries.push({
+            ...entry,
+            priority: entry.priority ?? 100,
+            mode: entry.mode ?? "enforce",
+        });
+        return entry;
+    }
+    /** Remove all entries owned by a plugin (e.g. on uninstall). */
+    unregisterPlugin(pluginName) {
+        const before = this.entries.length;
+        this.entries = this.entries.filter((e) => e.pluginName !== pluginName);
+        return before - this.entries.length;
+    }
+    /** All entries for a hook kind in priority order. */
+    list(kind) {
+        return this.entries
+            .filter((e) => e.kind === kind && e.mode !== "disabled")
+            .sort((a, b) => (a.priority ?? 100) - (b.priority ?? 100));
+    }
+    /** Snapshot of every registration regardless of kind (for diagnostics). */
+    all() {
+        return [...this.entries];
+    }
+    /** Fire every hook of the given kind in priority order. Each hook
+     *  receives the (possibly mutated) payload from the previous one.
+     *  Short-circuits on first `allow:false`. */
+    async fire(kind, ctx, initialPayload, logger = (l, m) => console[l === "warn" ? "warn" : "log"](m)) {
+        let payload = initialPayload;
+        for (const entry of this.list(kind)) {
+            try {
+                const r = await entry.handler({ ...ctx, kind }, payload);
+                if (!r.allow) {
+                    return r;
+                }
+                if (r.payload)
+                    payload = r.payload;
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                if (entry.mode === "permissive") {
+                    logger("warn", `hook ${entry.pluginName}/${kind} threw (permissive): ${msg}`);
+                    continue;
+                }
+                // enforce: block the call.
+                return {
+                    allow: false,
+                    reason: `hook ${entry.pluginName}/${kind} failed: ${msg}`,
+                };
+            }
+        }
+        return { allow: true, payload };
+    }
+}

package/dist/sdk/hooks.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sdk/hooks.test.js

@@ -0,0 +1,159 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { HookRegistry } from "./hooks.js";
+function ctx(target = "list_services") {
+    return {
+        principal: "alice",
+        tenant: "default",
+        kind: "tool_pre_invoke",
+        target,
+    };
+}
+test("HookRegistry.register: adds an entry with defaults applied", () => {
+    const r = new HookRegistry();
+    r.register({
+        pluginName: "p1",
+        kind: "tool_pre_invoke",
+        handler: () => ({ allow: true }),
+    });
+    const list = r.list("tool_pre_invoke");
+    assert.equal(list.length, 1);
+    assert.equal(list[0]?.priority, 100);
+    assert.equal(list[0]?.mode, "enforce");
+});
+test("HookRegistry.register: re-registering same (plugin,kind) replaces prior entry", () => {
+    const r = new HookRegistry();
+    r.register({ pluginName: "p", kind: "tool_pre_invoke", priority: 10, handler: () => ({ allow: true }) });
+    r.register({ pluginName: "p", kind: "tool_pre_invoke", priority: 20, handler: () => ({ allow: true }) });
+    const list = r.list("tool_pre_invoke");
+    assert.equal(list.length, 1);
+    assert.equal(list[0]?.priority, 20);
+});
+test("HookRegistry.list: orders by priority (lower runs first)", () => {
+    const r = new HookRegistry();
+    r.register({ pluginName: "a", kind: "tool_pre_invoke", priority: 50, handler: () => ({ allow: true }) });
+    r.register({ pluginName: "b", kind: "tool_pre_invoke", priority: 10, handler: () => ({ allow: true }) });
+    r.register({ pluginName: "c", kind: "tool_pre_invoke", priority: 99, handler: () => ({ allow: true }) });
+    const names = r.list("tool_pre_invoke").map((e) => e.pluginName);
+    assert.deepEqual(names, ["b", "a", "c"]);
+});
+test("HookRegistry.list: disabled hooks are filtered out", () => {
+    const r = new HookRegistry();
+    r.register({ pluginName: "a", kind: "tool_pre_invoke", handler: () => ({ allow: true }) });
+    r.register({ pluginName: "b", kind: "tool_pre_invoke", mode: "disabled", handler: () => ({ allow: true }) });
+    const names = r.list("tool_pre_invoke").map((e) => e.pluginName);
+    assert.deepEqual(names, ["a"]);
+});
+test("HookRegistry.unregisterPlugin: drops every entry for a plugin", () => {
+    const r = new HookRegistry();
+    r.register({ pluginName: "p", kind: "tool_pre_invoke", handler: () => ({ allow: true }) });
+    r.register({ pluginName: "p", kind: "tool_post_invoke", handler: () => ({ allow: true }) });
+    r.register({ pluginName: "q", kind: "tool_pre_invoke", handler: () => ({ allow: true }) });
+    const dropped = r.unregisterPlugin("p");
+    assert.equal(dropped, 2);
+    assert.equal(r.all().length, 1);
+    assert.equal(r.all()[0]?.pluginName, "q");
+});
+test("HookRegistry.fire: chains payload mutations and returns the final", async () => {
+    const r = new HookRegistry();
+    r.register({
+        pluginName: "a",
+        kind: "tool_pre_invoke",
+        priority: 10,
+        handler: (_c, p) => ({ allow: true, payload: { ...p, a: 1 } }),
+    });
+    r.register({
+        pluginName: "b",
+        kind: "tool_pre_invoke",
+        priority: 20,
+        handler: (_c, p) => ({ allow: true, payload: { ...p, b: 2 } }),
+    });
+    const result = await r.fire("tool_pre_invoke", ctx(), { initial: true });
+    assert.equal(result.allow, true);
+    assert.deepEqual(result.payload, { initial: true, a: 1, b: 2 });
+});
+test("HookRegistry.fire: first allow:false short-circuits subsequent hooks", async () => {
+    const r = new HookRegistry();
+    let sawSecond = false;
+    r.register({
+        pluginName: "a",
+        kind: "tool_pre_invoke",
+        priority: 10,
+        handler: () => ({ allow: false, reason: "denied by policy" }),
+    });
+    r.register({
+        pluginName: "b",
+        kind: "tool_pre_invoke",
+        priority: 20,
+        handler: () => {
+            sawSecond = true;
+            return { allow: true };
+        },
+    });
+    const result = await r.fire("tool_pre_invoke", ctx(), {});
+    assert.equal(result.allow, false);
+    assert.equal(result.reason, "denied by policy");
+    assert.equal(sawSecond, false);
+});
+test("HookRegistry.fire: enforce-mode throw blocks the chain", async () => {
+    const r = new HookRegistry();
+    let sawSecond = false;
+    r.register({
+        pluginName: "a",
+        kind: "tool_pre_invoke",
+        handler: () => {
+            throw new Error("boom");
+        },
+    });
+    r.register({
+        pluginName: "b",
+        kind: "tool_pre_invoke",
+        priority: 200,
+        handler: () => {
+            sawSecond = true;
+            return { allow: true };
+        },
+    });
+    const result = await r.fire("tool_pre_invoke", ctx(), {});
+    assert.equal(result.allow, false);
+    assert.match(result.reason ?? "", /boom/);
+    assert.equal(sawSecond, false);
+});
+test("HookRegistry.fire: permissive-mode throw is logged + chain continues with prior payload", async () => {
+    const r = new HookRegistry();
+    r.register({
+        pluginName: "a",
+        kind: "tool_pre_invoke",
+        priority: 10,
+        handler: (_c, p) => ({ allow: true, payload: { ...p, a: 1 } }),
+    });
+    r.register({
+        pluginName: "b",
+        kind: "tool_pre_invoke",
+        priority: 20,
+        mode: "permissive",
+        handler: () => {
+            throw new Error("intermittent failure");
+        },
+    });
+    r.register({
+        pluginName: "c",
+        kind: "tool_pre_invoke",
+        priority: 30,
+        handler: (_c, p) => ({ allow: true, payload: { ...p, c: 3 } }),
+    });
+    const logs = [];
+    const result = await r.fire("tool_pre_invoke", ctx(), {}, (lvl, m) => {
+        if (lvl === "warn")
+            logs.push(m);
+    });
+    assert.equal(result.allow, true);
+    assert.deepEqual(result.payload, { a: 1, c: 3 });
+    assert.equal(logs.length, 1);
+    assert.match(logs[0] ?? "", /b\/tool_pre_invoke/);
+});
+test("HookRegistry.fire: no hooks => allow with the initial payload", async () => {
+    const r = new HookRegistry();
+    const result = await r.fire("tool_pre_invoke", ctx(), { x: 1 });
+    assert.deepEqual(result, { allow: true, payload: { x: 1 } });
+});

package/dist/sdk/index.d.ts

@@ -1,6 +1,8 @@
 export type { ObservabilityConnector } from "../connectors/interface.js";
 export { manifestSchema } from "./manifest-schema.js";
 export type { ValidatedConnectorManifest } from "./manifest-schema.js";
+export { HookRegistry } from "./hooks.js";
+export type { HookKind, HookContext, HookPayload, HookResult, HookRegistration, } from "./hooks.js";
 export type { SignalType, SourceConfig, SourceAuth, SourceTls, ConnectorHealth, ServiceInfo, MetricInfo, MetricQuery, MetricResult, MetricSummary, DataPoint, LogQuery, LogResult, LogEntry, LogSummary, MetricDefinition, Resource, Edge, TopologySnapshot, TopologyChangeEvent, TopologyChangeListener, } from "../types.js";
 /**
  * Manifest shape declared in a plugin's `manifest.json`. The server

package/dist/sdk/index.js

@@ -11,3 +11,4 @@
 // against that package and an `observabilityMcp.compat.serverVersion`
 // constraint in their package.json (see docs/plugin-architecture.md).
 export { manifestSchema } from "./manifest-schema.js";
+export { HookRegistry } from "./hooks.js";

package/dist/sdk/manifest-schema.d.ts

@@ -25,5 +25,22 @@ export declare const manifestSchema: z.ZodObject<{
         serverVersion: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     integrity: z.ZodOptional<z.ZodString>;
+    hooks: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            tool_pre_invoke: "tool_pre_invoke";
+            tool_post_invoke: "tool_post_invoke";
+            resource_pre_fetch: "resource_pre_fetch";
+            resource_post_fetch: "resource_post_fetch";
+            prompt_pre_fetch: "prompt_pre_fetch";
+            prompt_post_fetch: "prompt_post_fetch";
+        }>;
+        module: z.ZodString;
+        priority: z.ZodOptional<z.ZodNumber>;
+        mode: z.ZodOptional<z.ZodEnum<{
+            enforce: "enforce";
+            permissive: "permissive";
+            disabled: "disabled";
+        }>>;
+    }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type ValidatedConnectorManifest = z.infer<typeof manifestSchema>;

package/dist/sdk/manifest-schema.js

@@ -44,4 +44,25 @@ export const manifestSchema = z.object({
         message: 'integrity must be "sha256-<base64>"',
     })
         .optional(),
+    // Lifecycle hooks the plugin wants to fire at. Each entry points to
+    // a module path INSIDE the plugin's bundled files. The loader
+    // resolves the module relative to the plugin root, imports its
+    // default export as the handler, and registers it on the gateway's
+    // HookRegistry. Hot-reloadable: install/upgrade of a plugin
+    // re-registers its hooks without restart.
+    hooks: z
+        .array(z.object({
+        kind: z.enum([
+            "tool_pre_invoke",
+            "tool_post_invoke",
+            "resource_pre_fetch",
+            "resource_post_fetch",
+            "prompt_pre_fetch",
+            "prompt_post_fetch",
+        ]),
+        module: z.string().min(1),
+        priority: z.number().int().optional(),
+        mode: z.enum(["enforce", "permissive", "disabled"]).optional(),
+    }))
+        .optional(),
 });

package/dist/tenancy/context.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Multi-tenant context primitives.
+ *
+ * Every request lands in EXACTLY ONE tenant. Identities resolve to a
+ * tenant via one of three paths:
+ *
+ *   1. Anonymous (no auth, the demo / single-operator path) → DEFAULT_TENANT.
+ *   2. Basic-mode local user → user file's optional `tenant` field;
+ *      missing → DEFAULT_TENANT (so existing single-tenant deployments
+ *      keep working without any config change).
+ *   3. OIDC session → OMCP_OIDC_TENANT_CLAIM (default `tenant`);
+ *      empty / missing claim → DEFAULT_TENANT.
+ *   4. MCP credential (bearer token) → optional per-credential
+ *      `tenant` field assigned via OMCP_KEY_TENANTS env, mirroring
+ *      OMCP_KEY_SOURCES / OMCP_KEY_BYPASS_REDACTION shape.
+ *
+ * The constant `DEFAULT_TENANT` is the universal escape hatch — any
+ * non-multi-tenant deployment behaves as if everything is in
+ * tenant `default`, identical to the pre-E7 single-namespace world.
+ *
+ * Cross-tenant requests return 404 (not 403) per the plan — leaking
+ * existence by status code defeats half the point of isolation.
+ */
+export declare const DEFAULT_TENANT = "default";
+/** Maximum tenant identifier length. Defence-in-depth against a
+ *  hostile claim payload pushing arbitrary KB-sized strings through
+ *  every cookie. Operators with longer names should pick shorter
+ *  ones; the audit chain still hashes the full string but the
+ *  cookie payload + log lines stay bounded. */
+export declare const MAX_TENANT_LENGTH = 64;
+/** Normalise + validate a tenant identifier. Returns the trimmed,
+ *  lower-cased string when valid; DEFAULT_TENANT for empty or
+ *  invalid input (silent fallback rather than crash — an OIDC claim
+ *  with junk should drop the user into the safe default, not 500
+ *  the whole flow). */
+export declare function normaliseTenant(raw: unknown): string;
+/** Walk a dotted-path claim out of an arbitrary claim set, then
+ *  normalise. Used for OIDC sessions where the tenant lives at e.g.
+ *  `app.tenant_id` rather than the top level. */
+export declare function tenantFromClaim(claims: Record<string, unknown>, claimPath: string): string;
+/** Parse OMCP_KEY_TENANTS="ci=acme;agent=bigco" into a name → tenant
+ *  map. Mirrors parseKeySources in auth/credentials.ts so the operator
+ *  cognitive load stays low. Invalid tenant strings normalise to
+ *  DEFAULT_TENANT silently. */
+export declare function parseKeyTenants(raw: string | undefined): Map<string, string>;

package/dist/tenancy/context.js

@@ -0,0 +1,97 @@
+/**
+ * Multi-tenant context primitives.
+ *
+ * Every request lands in EXACTLY ONE tenant. Identities resolve to a
+ * tenant via one of three paths:
+ *
+ *   1. Anonymous (no auth, the demo / single-operator path) → DEFAULT_TENANT.
+ *   2. Basic-mode local user → user file's optional `tenant` field;
+ *      missing → DEFAULT_TENANT (so existing single-tenant deployments
+ *      keep working without any config change).
+ *   3. OIDC session → OMCP_OIDC_TENANT_CLAIM (default `tenant`);
+ *      empty / missing claim → DEFAULT_TENANT.
+ *   4. MCP credential (bearer token) → optional per-credential
+ *      `tenant` field assigned via OMCP_KEY_TENANTS env, mirroring
+ *      OMCP_KEY_SOURCES / OMCP_KEY_BYPASS_REDACTION shape.
+ *
+ * The constant `DEFAULT_TENANT` is the universal escape hatch — any
+ * non-multi-tenant deployment behaves as if everything is in
+ * tenant `default`, identical to the pre-E7 single-namespace world.
+ *
+ * Cross-tenant requests return 404 (not 403) per the plan — leaking
+ * existence by status code defeats half the point of isolation.
+ */
+export const DEFAULT_TENANT = "default";
+/** Maximum tenant identifier length. Defence-in-depth against a
+ *  hostile claim payload pushing arbitrary KB-sized strings through
+ *  every cookie. Operators with longer names should pick shorter
+ *  ones; the audit chain still hashes the full string but the
+ *  cookie payload + log lines stay bounded. */
+export const MAX_TENANT_LENGTH = 64;
+/** Pattern: alphanumeric + `-` + `_` + `.`. Mirrors what most CI
+ *  identifiers accept. Rejects `/`, space, control chars (which
+ *  could break filesystem layouts in slice 2). */
+const VALID_TENANT_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+/** Normalise + validate a tenant identifier. Returns the trimmed,
+ *  lower-cased string when valid; DEFAULT_TENANT for empty or
+ *  invalid input (silent fallback rather than crash — an OIDC claim
+ *  with junk should drop the user into the safe default, not 500
+ *  the whole flow). */
+export function normaliseTenant(raw) {
+    if (typeof raw !== "string")
+        return DEFAULT_TENANT;
+    const trimmed = raw.trim().toLowerCase();
+    if (trimmed.length === 0)
+        return DEFAULT_TENANT;
+    if (trimmed.length > MAX_TENANT_LENGTH)
+        return DEFAULT_TENANT;
+    if (!VALID_TENANT_RE.test(trimmed))
+        return DEFAULT_TENANT;
+    return trimmed;
+}
+/** Walk a dotted-path claim out of an arbitrary claim set, then
+ *  normalise. Used for OIDC sessions where the tenant lives at e.g.
+ *  `app.tenant_id` rather than the top level. */
+export function tenantFromClaim(claims, claimPath) {
+    if (!claimPath)
+        return DEFAULT_TENANT;
+    const parts = claimPath.split(".");
+    let cur = claims;
+    for (const p of parts) {
+        if (cur && typeof cur === "object" && !Array.isArray(cur) && p in cur) {
+            cur = cur[p];
+        }
+        else {
+            return DEFAULT_TENANT;
+        }
+    }
+    // Arrays: take the first string-shaped entry (the same posture as
+    // resolveRoles in auth/oidc/runtime.ts). Operators wanting per-call
+    // multi-tenancy should use one tenant claim per token, not a list.
+    if (Array.isArray(cur)) {
+        for (const v of cur)
+            if (typeof v === "string")
+                return normaliseTenant(v);
+        return DEFAULT_TENANT;
+    }
+    return normaliseTenant(cur);
+}
+/** Parse OMCP_KEY_TENANTS="ci=acme;agent=bigco" into a name → tenant
+ *  map. Mirrors parseKeySources in auth/credentials.ts so the operator
+ *  cognitive load stays low. Invalid tenant strings normalise to
+ *  DEFAULT_TENANT silently. */
+export function parseKeyTenants(raw) {
+    const out = new Map();
+    if (!raw)
+        return out;
+    for (const entry of raw.split(";").map((s) => s.trim()).filter(Boolean)) {
+        const eq = entry.indexOf("=");
+        if (eq <= 0)
+            continue;
+        const name = entry.slice(0, eq).trim();
+        const tenant = normaliseTenant(entry.slice(eq + 1).trim());
+        if (name)
+            out.set(name, tenant);
+    }
+    return out;
+}

package/dist/tenancy/context.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tenancy/context.test.js

@@ -0,0 +1,72 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { DEFAULT_TENANT, MAX_TENANT_LENGTH, normaliseTenant, tenantFromClaim, parseKeyTenants, } from "./context.js";
+test("normaliseTenant — happy paths", () => {
+    assert.equal(normaliseTenant("acme"), "acme");
+    assert.equal(normaliseTenant("ACME"), "acme", "lowercases");
+    assert.equal(normaliseTenant("  acme-corp  "), "acme-corp", "trims");
+    assert.equal(normaliseTenant("team_a.us-east"), "team_a.us-east");
+});
+test("normaliseTenant — invalid / empty / null falls back to default", () => {
+    assert.equal(normaliseTenant(undefined), DEFAULT_TENANT);
+    assert.equal(normaliseTenant(null), DEFAULT_TENANT);
+    assert.equal(normaliseTenant(""), DEFAULT_TENANT);
+    assert.equal(normaliseTenant("   "), DEFAULT_TENANT);
+    assert.equal(normaliseTenant(123), DEFAULT_TENANT);
+    // Disallowed shapes
+    assert.equal(normaliseTenant("acme/corp"), DEFAULT_TENANT, "slash rejected");
+    assert.equal(normaliseTenant("acme corp"), DEFAULT_TENANT, "space rejected");
+    assert.equal(normaliseTenant("..hidden"), DEFAULT_TENANT, "leading dot rejected");
+    assert.equal(normaliseTenant("-leading"), DEFAULT_TENANT, "leading dash rejected");
+    // Too long
+    assert.equal(normaliseTenant("x".repeat(MAX_TENANT_LENGTH + 1)), DEFAULT_TENANT);
+});
+test("normaliseTenant — exactly MAX_TENANT_LENGTH passes", () => {
+    const t = "a" + "x".repeat(MAX_TENANT_LENGTH - 1);
+    assert.equal(t.length, MAX_TENANT_LENGTH);
+    assert.equal(normaliseTenant(t), t);
+});
+test("tenantFromClaim — flat claim", () => {
+    assert.equal(tenantFromClaim({ tenant: "acme" }, "tenant"), "acme");
+    assert.equal(tenantFromClaim({ tenant: "ACME" }, "tenant"), "acme");
+    assert.equal(tenantFromClaim({}, "tenant"), DEFAULT_TENANT);
+});
+test("tenantFromClaim — dotted claim path", () => {
+    assert.equal(tenantFromClaim({ app: { tenant_id: "acme" } }, "app.tenant_id"), "acme");
+    assert.equal(tenantFromClaim({ app: { tenant_id: "acme" } }, "app.missing"), DEFAULT_TENANT);
+    assert.equal(tenantFromClaim({ app: { tenant_id: "acme" } }, "missing.path"), DEFAULT_TENANT);
+});
+test("tenantFromClaim — array claim takes first string entry", () => {
+    assert.equal(tenantFromClaim({ tenants: ["acme", "other"] }, "tenants"), "acme");
+    assert.equal(tenantFromClaim({ tenants: [123, "acme"] }, "tenants"), "acme");
+    assert.equal(tenantFromClaim({ tenants: [123, 456] }, "tenants"), DEFAULT_TENANT);
+});
+test("tenantFromClaim — non-string scalar falls back", () => {
+    assert.equal(tenantFromClaim({ tenant: 42 }, "tenant"), DEFAULT_TENANT);
+    assert.equal(tenantFromClaim({ tenant: true }, "tenant"), DEFAULT_TENANT);
+    assert.equal(tenantFromClaim({ tenant: null }, "tenant"), DEFAULT_TENANT);
+});
+test("tenantFromClaim — empty claimPath returns default", () => {
+    assert.equal(tenantFromClaim({ tenant: "acme" }, ""), DEFAULT_TENANT);
+});
+test("parseKeyTenants — happy path", () => {
+    const m = parseKeyTenants("ci=acme;agent=bigco; dev=team_a.us");
+    assert.equal(m.size, 3);
+    assert.equal(m.get("ci"), "acme");
+    assert.equal(m.get("agent"), "bigco");
+    assert.equal(m.get("dev"), "team_a.us");
+});
+test("parseKeyTenants — invalid tenant on the right-hand side normalises to default", () => {
+    const m = parseKeyTenants("ci=acme/corp;agent=BIGCO");
+    assert.equal(m.get("ci"), DEFAULT_TENANT, "slash → default");
+    assert.equal(m.get("agent"), "bigco", "uppercase OK after normalise");
+});
+test("parseKeyTenants — malformed entries skipped, doesn't crash", () => {
+    const m = parseKeyTenants("noequal;=novalueeither;valid=acme");
+    assert.equal(m.size, 1);
+    assert.equal(m.get("valid"), "acme");
+});
+test("parseKeyTenants — undefined / empty returns empty map", () => {
+    assert.equal(parseKeyTenants(undefined).size, 0);
+    assert.equal(parseKeyTenants("").size, 0);
+});

package/dist/tenancy/migration.test.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Migration regression suite — pre-E7 single-tenant deployments must
+ * continue to work without any config change. These tests pin the
+ * "everything defaults to `default`" contract by simulating the
+ * exact data shapes a pre-E7 server / file / token would carry.
+ */
+export {};