@cosmicdrift/kumiko-bundled-features 0.305.0 → 0.307.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.305.0",
+  "version": "0.307.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -133,12 +133,12 @@
     "./workflow-runner": "./src/workflow-runner/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.305.0",
-    "@cosmicdrift/kumiko-framework": "0.305.0",
-    "@cosmicdrift/kumiko-headless": "0.305.0",
-    "@cosmicdrift/kumiko-renderer": "0.305.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.305.0",
-    "@cosmicdrift/kumiko-types": "0.305.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.307.0",
+    "@cosmicdrift/kumiko-framework": "0.307.0",
+    "@cosmicdrift/kumiko-headless": "0.307.0",
+    "@cosmicdrift/kumiko-renderer": "0.307.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.307.0",
+    "@cosmicdrift/kumiko-types": "0.307.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",
@@ -167,8 +167,8 @@
   ],
   "devDependencies": {
     "@testing-library/user-event": "^14.6.1",
-    "@cosmicdrift/kumiko-locale-de": "0.305.0",
-    "@cosmicdrift/kumiko-locale-es": "0.305.0",
+    "@cosmicdrift/kumiko-locale-de": "0.307.0",
+    "@cosmicdrift/kumiko-locale-es": "0.307.0",
     "jsqr": "^1.4.0"
   }
 }

package/src/__tests__/extension-points-typed.test.ts

@@ -0,0 +1,135 @@
+// Ratchet: every extension point a bundled feature declares via
+// `r.extendsRegistrar` and whose options are actually read somewhere must be
+// entered into `KumikoExtensionOptionsMap` — see extension-options-map.ts.
+// New points either join TYPED_EXTENSION_POINTS (with the map augmentation)
+// or UNTYPED_BY_DESIGN (with a reason). Anything else fails this test.
+
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import type { KumikoExtensionOptionsMap } from "@cosmicdrift/kumiko-types/extension-options-map";
+import { authFoundationFeature } from "../auth-foundation/feature";
+import { billingFoundationFeature } from "../billing-foundation/feature";
+import { createCustomFieldsFeature } from "../custom-fields/feature";
+import { createDeliveryFeature } from "../delivery/feature";
+import { createFileDerivativesFeature } from "../file-derivatives/feature";
+import { fileFoundationFeature } from "../file-foundation/feature";
+import { inboundMailFoundationFeature } from "../inbound-mail-foundation/feature";
+import { mailFoundationFeature } from "../mail-foundation/feature";
+import { createRendererFoundationFeature } from "../renderer-foundation/feature";
+import { createTenantLifecycleFeature } from "../tenant-lifecycle/feature";
+import { createTierEngineFeature } from "../tier-engine/feature";
+import { createUserFeature } from "../user/feature";
+import { createUserDataRightsFeature } from "../user-data-rights/feature";
+
+const TYPED_EXTENSION_POINTS = [
+  "userData",
+  "tenantData",
+  "storageProvider",
+  "searchAdapter",
+  "externalResource",
+  "infraResource",
+  "fileProvider",
+  "derivativeRenderer",
+  "derivativeOverlayResolver",
+  "derivativePublicPredicate",
+  "principalStatus",
+  "tenantLifecycleStatus",
+  "tenantTierResolver",
+  "tokenVerifier",
+  "sessionStore",
+  "tenantResolver",
+  "tenantExistence",
+  "inboundMailProvider",
+  "renderer",
+  "deliveryChannel",
+  "subscriptionProvider",
+  "mailTransport",
+] as const satisfies readonly (keyof KumikoExtensionOptionsMap)[];
+
+const UNTYPED_BY_DESIGN: Record<string, string> = {
+  customFields: "opt-in marker only — registered options are never read",
+};
+
+// Owner-directories that declare at least one extension point via
+// `r.extendsRegistrar` — one entry per feature composed in
+// allRegistrarExtensionNames() below. Catches a new feature that starts
+// calling r.extendsRegistrar without being added to that composition list.
+const DECLARING_FEATURE_DIRS = [
+  "auth-foundation",
+  "billing-foundation",
+  "custom-fields",
+  "delivery",
+  "file-derivatives",
+  "file-foundation",
+  "inbound-mail-foundation",
+  "mail-foundation",
+  "renderer-foundation",
+  "tenant-lifecycle",
+  "tier-engine",
+  "user",
+  "user-data-rights",
+].sort();
+
+// Scans bundled-features source (excluding tests) for real `r.extendsRegistrar(`
+// call sites, ignoring occurrences inside line comments (e.g. a doc-comment
+// mentioning the call). Returns the sorted, deduped set of owning top-level
+// directories under packages/bundled-features/src.
+function scanExtendsRegistrarOwnerDirs(): readonly string[] {
+  const srcDir = new URL("..", import.meta.url).pathname;
+  const glob = new Bun.Glob("**/*.ts");
+  const owners = new Set<string>();
+  for (const relPath of glob.scanSync({ cwd: srcDir, onlyFiles: true })) {
+    if (relPath.includes("__tests__/") || relPath.endsWith(".test.ts")) continue;
+    const contents = readFileSync(`${srcDir}${relPath}`, "utf8");
+    const hasRealCall = contents
+      .split("\n")
+      .some((line) => line.split("//")[0]?.includes("r.extendsRegistrar("));
+    if (!hasRealCall) continue;
+    const topLevelDir = relPath.split("/")[0];
+    if (topLevelDir) owners.add(topLevelDir);
+  }
+  return [...owners].sort();
+}
+
+function allRegistrarExtensionNames(): readonly string[] {
+  const features = [
+    authFoundationFeature,
+    billingFoundationFeature,
+    createCustomFieldsFeature(),
+    createDeliveryFeature(),
+    createFileDerivativesFeature(),
+    fileFoundationFeature,
+    inboundMailFoundationFeature,
+    mailFoundationFeature,
+    createRendererFoundationFeature(),
+    createTenantLifecycleFeature(),
+    createTierEngineFeature(),
+    createUserFeature(),
+    createUserDataRightsFeature(),
+  ];
+  const names = new Set<string>();
+  for (const feature of features) {
+    for (const name of Object.keys(feature.registrarExtensions)) {
+      names.add(name);
+    }
+  }
+  return [...names];
+}
+
+describe("extension-points-typed ratchet", () => {
+  test("every declared extension point is either typed or explicitly untyped-by-design", () => {
+    const declared = allRegistrarExtensionNames();
+    const known = new Set<string>([...TYPED_EXTENSION_POINTS, ...Object.keys(UNTYPED_BY_DESIGN)]);
+    const unaccounted = declared.filter((name) => !known.has(name));
+    expect(unaccounted).toEqual([]);
+  });
+
+  test("TYPED_EXTENSION_POINTS and UNTYPED_BY_DESIGN don't overlap", () => {
+    const overlap = TYPED_EXTENSION_POINTS.filter((name) => name in UNTYPED_BY_DESIGN);
+    expect(overlap).toEqual([]);
+  });
+
+  test("every directory that calls r.extendsRegistrar is composed into allRegistrarExtensionNames", () => {
+    expect(scanExtendsRegistrarOwnerDirs()).toEqual(DECLARING_FEATURE_DIRS);
+  });
+});

package/src/__tests__/use-extension-options.test.ts

@@ -0,0 +1,278 @@
+// Imports only via package specifiers so the KumikoExtensionOptionsMap augmentation is proven to reach
+// consumers. Each @ts-expect-error has a positive control next to it, so an unrelated error cannot satisfy it.
+import { expect, expectTypeOf, test } from "bun:test";
+import { MAIL_TRANSPORT_EXTENSION } from "@cosmicdrift/kumiko-bundled-features/mail-foundation";
+import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+import {
+  defineFeature,
+  EXT_STORAGE_PROVIDER,
+  EXT_TENANT_DATA,
+  EXT_USER_DATA,
+  type ExtensionOptionsArgs,
+  type ExtensionOptionsFor,
+  type TenantDataDestroyHook,
+  type TenantDataHookCtx,
+  type TenantId,
+  type TenantResourceDestroyHook,
+  type TenantResourceHookCtx,
+  type UserDataDeleteHook,
+  type UserDataDeleteStrategy,
+  type UserDataExportHook,
+  type UserDataHookCtx,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+test("useExtension accepts a well-typed tenantData destroy hook", () => {
+  defineFeature("probe-tenant-data-ok", (r) => {
+    r.useExtension(EXT_TENANT_DATA, "x", {
+      destroy: async (ctx: TenantDataHookCtx) => {
+        expectTypeOf(ctx.db).not.toBeAny();
+      },
+    });
+  });
+});
+
+test("useExtension rejects a tenantData destroy hook with the #3196 wrong ctx shape", () => {
+  defineFeature("probe-tenant-data-wrong-ctx", (r) => {
+    r.useExtension(EXT_TENANT_DATA, "x", {
+      // @ts-expect-error #3196: destroy ctx must be TenantDataHookCtx, not a hand-rolled { db: DbRunner; tenantId } — TenantDb is not a DbRunner.
+      destroy: async (_ctx: { readonly db: DbRunner; readonly tenantId: TenantId }) => {},
+    });
+  });
+  expectTypeOf<
+    (ctx: { readonly db: DbRunner; readonly tenantId: TenantId }) => Promise<void>
+  >().not.toExtend<TenantDataDestroyHook>();
+});
+
+test("useExtension requires options for a known extension name — omitting them is a type error", () => {
+  defineFeature("probe-tenant-data-missing-options", (r) => {
+    // @ts-expect-error tenantData's options are mandatory — a bare (name, entity) call registered no hook, silently.
+    r.useExtension(EXT_TENANT_DATA, "x");
+  });
+  expectTypeOf<[]>().not.toExtend<ExtensionOptionsArgs<typeof EXT_TENANT_DATA>>();
+});
+
+test("useExtension infers the destroy hook's ctx type from context (positional form, no annotation)", () => {
+  defineFeature("probe-tenant-data-contextual", (r) => {
+    r.useExtension(EXT_TENANT_DATA, "x", {
+      destroy: async (ctx) => {
+        expectTypeOf(ctx).toEqualTypeOf<TenantDataHookCtx>();
+      },
+    });
+  });
+});
+
+test("useExtension's object form accepts a well-typed tenantData destroy hook", () => {
+  defineFeature("probe-tenant-data-object-form-ok", (r) => {
+    r.useExtension({
+      name: EXT_TENANT_DATA,
+      entity: "x",
+      destroy: async (ctx: TenantDataHookCtx) => {
+        expectTypeOf(ctx.tenantId).toBeString();
+      },
+    });
+  });
+});
+
+test("useExtension's object form rejects the #3196 wrong ctx shape", () => {
+  defineFeature("probe-tenant-data-object-form-wrong-ctx", (r) => {
+    r.useExtension({
+      name: EXT_TENANT_DATA,
+      entity: "x",
+      // @ts-expect-error #3196: same mismatch as the positional form above.
+      destroy: async (_ctx: { readonly db: DbRunner; readonly tenantId: TenantId }) => {},
+    });
+  });
+  expectTypeOf<
+    (ctx: { readonly db: DbRunner; readonly tenantId: TenantId }) => Promise<void>
+  >().not.toExtend<TenantDataDestroyHook>();
+});
+
+test("useExtension's object form infers the destroy hook's ctx type from context (no annotation)", () => {
+  defineFeature("probe-tenant-data-object-form-contextual", (r) => {
+    r.useExtension({
+      name: EXT_TENANT_DATA,
+      entity: "x",
+      destroy: async (ctx) => {
+        expectTypeOf(ctx).toEqualTypeOf<TenantDataHookCtx>();
+      },
+    });
+  });
+});
+
+test("useExtension accepts a tenantData registration with escapeHatch", () => {
+  const feature = defineFeature("probe-tenant-data-escape-hatch", (r) => {
+    r.useExtension(EXT_TENANT_DATA, "x", {
+      destroy: async (_ctx: TenantDataHookCtx) => {},
+      escapeHatch: { reason: "needs raw SQL for a batch delete" },
+    });
+  });
+  expect(feature.extensionUsages).toContainEqual(
+    expect.objectContaining({
+      extensionName: EXT_TENANT_DATA,
+      entityName: "x",
+      options: expect.objectContaining({
+        escapeHatch: { reason: "needs raw SQL for a batch delete" },
+      }),
+    }),
+  );
+});
+
+test("useExtension accepts export-only userData registration (#972)", () => {
+  const exportHook: UserDataExportHook = async (_ctx) => null;
+  const feature = defineFeature("probe-user-data-export-only", (r) => {
+    r.useExtension(EXT_USER_DATA, "x", { export: exportHook });
+  });
+  expect(feature.extensionUsages).toContainEqual(
+    expect.objectContaining({
+      extensionName: EXT_USER_DATA,
+      entityName: "x",
+      options: expect.objectContaining({ export: exportHook }),
+    }),
+  );
+});
+
+test("useExtension rejects a userData export hook with the wrong ctx shape", () => {
+  defineFeature("probe-user-data-wrong-ctx", (r) => {
+    r.useExtension(EXT_USER_DATA, "x", {
+      // @ts-expect-error export ctx must be UserDataHookCtx (ctx.db: TenantDb), not a hand-rolled { db: DbRunner; userId }.
+      export: async (_ctx: { readonly db: DbRunner; readonly userId: string }) => null,
+    });
+  });
+  expectTypeOf<
+    (ctx: { readonly db: DbRunner; readonly userId: string }) => Promise<null>
+  >().not.toExtend<UserDataExportHook>();
+});
+
+test("useExtension accepts delete-only userData registration with order", () => {
+  const deleteHook: UserDataDeleteHook = async (_ctx, _strategy) => undefined;
+  const feature = defineFeature("probe-user-data-delete-only", (r) => {
+    r.useExtension(EXT_USER_DATA, "x", { delete: deleteHook, order: 1 });
+  });
+  expect(feature.extensionUsages).toContainEqual(
+    expect.objectContaining({
+      extensionName: EXT_USER_DATA,
+      entityName: "x",
+      options: expect.objectContaining({ delete: deleteHook, order: 1 }),
+    }),
+  );
+});
+
+test("useExtension infers the delete hook's ctx/strategy types from context (no annotation)", () => {
+  defineFeature("probe-user-data-delete-contextual", (r) => {
+    r.useExtension(EXT_USER_DATA, "x", {
+      delete: async (ctx, strategy) => {
+        expectTypeOf(ctx).toEqualTypeOf<UserDataHookCtx>();
+        expectTypeOf(strategy).toEqualTypeOf<UserDataDeleteStrategy>();
+        return undefined;
+      },
+    });
+  });
+});
+
+test("useExtension rejects an empty userData registration", () => {
+  defineFeature("probe-user-data-empty", (r) => {
+    // @ts-expect-error userData needs at least one of export/delete — an empty bag silently registered neither hook.
+    r.useExtension(EXT_USER_DATA, "x", {});
+  });
+  expectTypeOf<Record<string, never>>().not.toExtend<ExtensionOptionsFor<typeof EXT_USER_DATA>>();
+});
+
+test("useExtension rejects a userData registration with only order", () => {
+  defineFeature("probe-user-data-only-order", (r) => {
+    // @ts-expect-error same as the empty-bag case above: order alone registers no hook.
+    r.useExtension(EXT_USER_DATA, "x", { order: 1 });
+  });
+  expectTypeOf<{ readonly order: number }>().not.toExtend<
+    ExtensionOptionsFor<typeof EXT_USER_DATA>
+  >();
+});
+
+test("useExtension accepts an unknown extension name with an arbitrary options bag", () => {
+  const feature = defineFeature("probe-unknown-name", (r) => {
+    r.useExtension("someAppPoint", "x", { anything: 42, goes: "here" });
+  });
+  expect(feature.extensionUsages).toContainEqual(
+    expect.objectContaining({
+      extensionName: "someAppPoint",
+      entityName: "x",
+      options: { anything: 42, goes: "here" },
+    }),
+  );
+});
+
+test("useExtension accepts an unknown extension name with no options at all", () => {
+  const feature = defineFeature("probe-unknown-name-no-options", (r) => {
+    r.useExtension("someOtherAppPoint", "x");
+  });
+  expect(feature.extensionUsages).toContainEqual(
+    expect.objectContaining({ extensionName: "someOtherAppPoint", entityName: "x" }),
+  );
+});
+
+test("useExtension accepts a string-typed extension name with an arbitrary options bag", () => {
+  const name: string = "someAppPoint";
+  const feature = defineFeature("probe-string-typed-name", (r) => {
+    r.useExtension(name, "x", { anything: 42 });
+  });
+  expect(feature.extensionUsages).toContainEqual(
+    expect.objectContaining({
+      extensionName: "someAppPoint",
+      entityName: "x",
+      options: { anything: 42 },
+    }),
+  );
+});
+
+test("useExtension accepts a well-typed storageProvider destroyTenant hook", () => {
+  defineFeature("probe-storage-provider-ok", (r) => {
+    r.useExtension(EXT_STORAGE_PROVIDER, "x", {
+      destroyTenant: async (tenantId: TenantId, ctx: TenantResourceHookCtx) => {
+        expectTypeOf(tenantId).toBeString();
+        expectTypeOf(ctx.db).not.toBeAny();
+      },
+    });
+  });
+});
+
+test("useExtension infers the storageProvider destroyTenant hook's arg types from context", () => {
+  defineFeature("probe-storage-provider-contextual", (r) => {
+    r.useExtension(EXT_STORAGE_PROVIDER, "x", {
+      destroyTenant: async (tenantId, ctx) => {
+        expectTypeOf(tenantId).toEqualTypeOf<TenantId>();
+        expectTypeOf(ctx).toEqualTypeOf<TenantResourceHookCtx>();
+      },
+    });
+  });
+});
+
+test("useExtension rejects a storageProvider destroyTenant hook shaped like the tenantData (ctx)-only hook", () => {
+  defineFeature("probe-storage-provider-wrong-shape", (r) => {
+    r.useExtension(EXT_STORAGE_PROVIDER, "x", {
+      // @ts-expect-error storageProvider's destroyTenant takes (tenantId, ctx) — a tenantData-style (ctx)-only hook is missing the tenantId arg.
+      destroyTenant: async (_ctx: TenantDataHookCtx) => {},
+    });
+  });
+  expectTypeOf<
+    (ctx: TenantDataHookCtx) => Promise<void>
+  >().not.toExtend<TenantResourceDestroyHook>();
+});
+
+test("useExtension rejects a storageProvider registration without destroyTenant", () => {
+  defineFeature("probe-storage-provider-missing-hook", (r) => {
+    // @ts-expect-error storageProvider requires destroyTenant — an empty bag silently registered no cleanup hook.
+    r.useExtension(EXT_STORAGE_PROVIDER, "x", {});
+  });
+  expectTypeOf<Record<string, never>>().not.toExtend<
+    ExtensionOptionsFor<typeof EXT_STORAGE_PROVIDER>
+  >();
+});
+
+test("useExtension rejects a mailTransport registration without build", () => {
+  defineFeature("probe-mail-transport-missing-build", (r) => {
+    // @ts-expect-error mailTransport requires build — an empty bag silently registered no transport factory.
+    r.useExtension(MAIL_TRANSPORT_EXTENSION, "x", {});
+  });
+  expectTypeOf<Record<string, never>>().not.toExtend<
+    ExtensionOptionsFor<typeof MAIL_TRANSPORT_EXTENSION>
+  >();
+});

package/src/auth-email-password/changes.json

@@ -1,4 +1,9 @@
 [
+  {
+    "version": "0.307.0",
+    "type": "improvement",
+    "title": "Anonymous signup-confirm and invite-signup-complete (auth-email-password) and verify / enable-confirm-preauth (auth-mfa) declare personalData: public-intake, since they write personal data through a TenantDb derived from ctx.db.unsafeRaw (fw#3185)"
+  },
   {
     "version": "0.305.0",
     "type": "breaking",

package/src/auth-email-password/handlers/invite-signup-complete.write.ts

@@ -92,7 +92,7 @@ export function createInviteSignupCompleteHandler() {
   >({
     name: "invite-signup-complete",
     schema: InviteSignupCompleteSchema,
-    access: { roles: ["anonymous"] },
+    access: { roles: ["anonymous"], personalData: "public-intake" },
     rateLimit: { per: "ip+handler", limit: 20, windowSeconds: 60 },
     agent: { expose: false },
     escapeHatch: {

package/src/auth-email-password/handlers/signup-confirm.write.ts

@@ -67,7 +67,7 @@ export function createSignupConfirmHandler() {
   return defineWriteHandler<"signup-confirm", typeof SignupConfirmSchema, SignupConfirmData>({
     name: "signup-confirm",
     schema: SignupConfirmSchema,
-    access: { roles: ["anonymous"] },
+    access: { roles: ["anonymous"], personalData: "public-intake" },
     rateLimit: { per: "ip+handler", limit: 20, windowSeconds: 60 },
     agent: { expose: false },
     escapeHatch: {

package/src/auth-foundation/__tests__/session-store.test.ts

@@ -67,6 +67,7 @@ describe("validateSessionStoreMultiplicity", () => {
 
   test("malformed registration (no build) → throws a malformed-plugin error", () => {
     const broken = defineFeature("mock-broken", (r) => {
+      // @ts-expect-error malformed plugin (no build) — proves the runtime guard rejects it too.
       r.useExtension(EXT_SESSION_STORE, "broken", {});
     });
     const registry = createRegistry([authFoundationFeature, broken]);

package/src/auth-foundation/__tests__/tenant-providers.test.ts

@@ -92,6 +92,7 @@ describe("validateTenantResolverMultiplicity", () => {
 
   test("malformed (no trust) → throws", () => {
     const broken = defineFeature("mock-broken-resolver", (r) => {
+      // @ts-expect-error malformed plugin (no trust) — proves the runtime guard rejects it too.
       r.useExtension(EXT_TENANT_RESOLVER, "broken", { build: () => () => null });
     });
     const registry = createRegistry([authFoundationFeature, broken]);

package/src/auth-foundation/__tests__/token-verifier.test.ts

@@ -127,6 +127,7 @@ describe("validateTokenVerifierMultiplicity", () => {
 
   test("wrong-shape registration → throws a malformed-plugin error", () => {
     const broken = defineFeature("mock-broken", (r) => {
+      // @ts-expect-error malformed plugin (no build) — proves the runtime guard rejects it too.
       r.useExtension(EXT_TOKEN_VERIFIER, "broken", { shape: { kind: "prefix" } });
     });
     const registry = createRegistry([authFoundationFeature, broken]);
@@ -138,6 +139,7 @@ describe("validateTokenVerifierMultiplicity", () => {
   test("malformed shape (build present, prefix missing) → throws a malformed-plugin error", () => {
     const broken = defineFeature("mock-broken-shape", (r) => {
       r.useExtension(EXT_TOKEN_VERIFIER, "broken-shape", {
+        // @ts-expect-error malformed shape (prefix missing) — proves the runtime guard rejects it too.
         shape: { kind: "prefix" },
         build: () => async () => null,
       });

package/src/auth-foundation/types.ts

@@ -22,7 +22,7 @@ import type { SessionUser } from "@cosmicdrift/kumiko-framework/engine";
 
 export type { SessionMassRevoker };
 
-export const EXT_TOKEN_VERIFIER = "tokenVerifier";
+export const EXT_TOKEN_VERIFIER = "tokenVerifier" as const;
 
 /**
  * Deps available to a provider's `build()`. DB access only — a hot-path
@@ -84,7 +84,7 @@ export function tokenShapeKey(shape: TokenShape): string {
 // single-provider — sessions have no per-provider shape to route on, so
 // exactly one implementation must be registered (boot-fails on 0 or ≥2).
 
-export const EXT_SESSION_STORE = "sessionStore";
+export const EXT_SESSION_STORE = "sessionStore" as const;
 
 /** Keep current sid (if any); revoke every other live session. Used by auth-mfa. */
 export type SessionRevokeAllOthers = (
@@ -117,8 +117,8 @@ export function isSessionStoreProvider(o: unknown): o is SessionStoreProvider {
 // optional — zero registered means today's single-tenant / header-cookie
 // path (no subdomain resolver, no existence check). ≥2 fails boot.
 
-export const EXT_TENANT_RESOLVER = "tenantResolver";
-export const EXT_TENANT_EXISTENCE = "tenantExistence";
+export const EXT_TENANT_RESOLVER = "tenantResolver" as const;
+export const EXT_TENANT_EXISTENCE = "tenantExistence" as const;
 
 /** Trust mode for a registered tenantResolver — mirrors AnonymousAccessConfig.resolverTrust. */
 export type TenantResolverTrust = "authoritative" | "fallback-only";
@@ -168,3 +168,13 @@ export function isTenantExistenceProvider(o: unknown): o is TenantExistenceProvi
     typeof (o as { build: unknown }).build === "function"
   );
 }
+
+// r.useExtension options-shape for auth-foundation's four extension points.
+declare module "@cosmicdrift/kumiko-framework/engine" {
+  interface KumikoExtensionOptionsMap {
+    [EXT_TOKEN_VERIFIER]: AuthProviderPlugin;
+    [EXT_SESSION_STORE]: SessionStoreProvider;
+    [EXT_TENANT_RESOLVER]: TenantResolverProvider;
+    [EXT_TENANT_EXISTENCE]: TenantExistenceProvider;
+  }
+}