@cosmicdrift/kumiko-bundled-features 0.158.2 → 0.159.1

package/src/inbound-mail-foundation/handlers/ingest-message.write.ts

@@ -26,6 +26,7 @@ import {
   encryptPiiFieldValues,
 } from "@cosmicdrift/kumiko-framework/crypto";
 import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import { Temporal } from "temporal-polyfill";
 import { z } from "zod";
 import { inboundMessageAggregateId, mailThreadAggregateId } from "../aggregate-id";
@@ -99,6 +100,7 @@ function buildThreadKey(p: IngestMessagePayload, effectiveMessageIdHeader: strin
   return `mid:${effectiveMessageIdHeader}`.slice(0, 500);
 }
 
+const THREAD_ROLLUP_MAX_ATTEMPTS = 5;
 export const ingestMessageHandler: WriteHandlerDef = {
   name: "ingest-message",
   schema: ingestMessageSchema,
@@ -221,46 +223,33 @@ export const ingestMessageHandler: WriteHandlerDef = {
     }
 
     // ---------------------------------------------------------------
-    // 5. Thread-Rollup. Der Handler berechnet den NEUEN Snapshot
-    //    (count via Live-COUNT, max(lastMessageAt)) — die apply ist ein
-    //    dummer UPSERT und bleibt replay-idempotent. lastMessageAtIso ist
-    //    kein PII (Zeitpunkt), damit plaintext-vergleichbar; subject
-    //    wird frisch encrypted (jede Thread-Version trägt das Subject
-    //    der jüngsten Mail).
+    // 5. Thread-Rollup. New snapshot (live COUNT + max(lastMessageAt)) via
+    //    ctx.tryAppendEvent in a bounded retry loop — the apply stays a
+    //    dumb, replay-idempotent UPSERT. lastMessageAtIso is not PII (a
+    //    timestamp), so it stays plaintext-comparable; subject is
+    //    encrypted once up front (constant across retries, doesn't
+    //    depend on the thread's prior state).
     //
-    //    messageCount kommt bewusst NICHT aus einem frueher gelesenen
-    //    threadEvents-Snapshot (previousCount+1): getStreamVersion in
-    //    unsafeAppendEvent liest die Stream-Version FRISCH zum
-    //    Append-Zeitpunkt, unabhaengig vom Read hier — zwei parallele
-    //    ingests auf denselben Thread (Watch-Push + Poll-Reconciliation)
-    //    koennten beide denselben previousCount sehen und der Append der
-    //    zweiten TX wuerde trotzdem gelingen (kein VersionConflictError,
-    //    da der Version-Check nur die Stream-Version prueft), sodass
-    //    previousCount+1 dauerhaft nach unten drieftet.
+    //    messageCount deliberately does NOT come from a previously loaded
+    //    threadEvents snapshot (previousCount+1): two concurrent ingests
+    //    on the same thread (Watch-Push vs. Poll-Reconciliation overlap,
+    //    or two different messages of the same thread arriving at once)
+    //    can both read the same stream version before either commits.
+    //    tryAppendEvent's fresh version-read at append time then makes
+    //    the loser's append fail with a VersionConflictError instead of
+    //    silently succeeding — so we retry: reload the thread stream,
+    //    recompute the live row-count and lastMessageAt, and append
+    //    again. Unlike step 4, a lost race here must NOT be treated as a
+    //    no-op duplicate — skipping would leave this message's
+    //    contribution to messageCount/lastMessageAt out of the thread
+    //    forever. Exhausting all attempts throws, rolling back the whole
+    //    TX (including the step-4 message append) for a clean re-ingest
+    //    on the next poll — never return success with a stale snapshot.
     //
-    //    Ein COUNT gegen read_inbound_messages SCHLIESST das Race-Fenster
-    //    NICHT (COUNT und Append sind weiterhin zwei getrennte Statements —
-    //    zwischen COUNT und Append kann die andere TX committen und derselbe
-    //    Drift theoretisch weiterhin auftreten). Was der COUNT aendert: er
-    //    macht den Fehler SELBSTKORRIGIEREND statt kumulativ — jeder
-    //    nachfolgende ingest liest den echten Row-Count neu, statt einen
-    //    frueher falsch geschriebenen previousCount fortzuschreiben. Eine
-    //    echte Race-freie Loesung braucht ein atomares Read+Append (z.B.
-    //    SELECT ... FOR UPDATE oder eine Advisory-Lock auf threadAggId) —
-    //    das ist bewusst nicht Teil dieses Fixes (siehe PR-Beschreibung).
+    //    A true race-free read+append (e.g. SELECT ... FOR UPDATE or an
+    //    advisory lock on threadAggId) is deliberately not part of this
+    //    fix — two writers (watch + poll) make bounded retry sufficient.
     // ---------------------------------------------------------------
-    const threadEvents = await ctx.loadAggregate(threadAggId);
-    const lastThreadEvent = threadEvents[threadEvents.length - 1];
-    // @cast-boundary engine-payload — eigene events, shape via defineEvent
-    const previousThread = lastThreadEvent?.payload as MailThreadEventPayload | undefined;
-    const previousLastAt = previousThread?.lastMessageAtIso ?? "";
-    const newLastAt =
-      payload.receivedAtIso > previousLastAt ? payload.receivedAtIso : previousLastAt;
-    const messageCount = await countWhere(ctx.db.raw, inboundMessagesProjectionTable, {
-      tenantId,
-      threadKey,
-    });
-
     const threadPlainPii = { tenantId, subject: payload.subject };
     const encryptedThreadFields = piiKms
       ? await encryptPiiFieldValues(
@@ -275,19 +264,40 @@ export const ingestMessageHandler: WriteHandlerDef = {
         )
       : threadPlainPii;
 
-    const threadEventPayload: MailThreadEventPayload = {
-      threadKey,
-      subject: encryptedThreadFields["subject"] as string,
-      lastMessageAtIso: newLastAt,
-      messageCount,
-    };
-    await ctx.unsafeAppendEvent({
-      aggregateId: threadAggId,
-      aggregateType: MAIL_THREAD_AGGREGATE_TYPE,
-      type: MAIL_THREAD_UPDATED_EVENT_QN,
-      payload: threadEventPayload,
-      headers: messageHeaders,
-    });
+    let threadAppendOk = false;
+    for (let attempt = 1; attempt <= THREAD_ROLLUP_MAX_ATTEMPTS && !threadAppendOk; attempt++) {
+      const threadEvents = await ctx.loadAggregate(threadAggId);
+      const lastThreadEvent = threadEvents[threadEvents.length - 1];
+      // @cast-boundary engine-payload — eigene events, shape via defineEvent
+      const previousThread = lastThreadEvent?.payload as MailThreadEventPayload | undefined;
+      const previousLastAt = previousThread?.lastMessageAtIso ?? "";
+      const newLastAt =
+        payload.receivedAtIso > previousLastAt ? payload.receivedAtIso : previousLastAt;
+      const messageCount = await countWhere(ctx.db.raw, inboundMessagesProjectionTable, {
+        tenantId,
+        threadKey,
+      });
+
+      const threadEventPayload: MailThreadEventPayload = {
+        threadKey,
+        subject: encryptedThreadFields["subject"] as string,
+        lastMessageAtIso: newLastAt,
+        messageCount,
+      };
+      const threadAppend = await ctx.tryAppendEvent({
+        aggregateId: threadAggId,
+        aggregateType: MAIL_THREAD_AGGREGATE_TYPE,
+        type: MAIL_THREAD_UPDATED_EVENT_QN,
+        payload: threadEventPayload,
+        headers: messageHeaders,
+      });
+      threadAppendOk = threadAppend.ok;
+    }
+    if (!threadAppendOk) {
+      throw new InternalError({
+        message: `ingest-message: thread-rollup append for "${threadAggId}" lost the version-conflict race ${THREAD_ROLLUP_MAX_ATTEMPTS} times in a row — aborting for a clean re-ingest instead of persisting a stale messageCount.`,
+      });
+    }
 
     // ---------------------------------------------------------------
     // 6. Dedup-Anchor. Läuft in derselben TX wie die appends — stirbt

package/src/inbound-provider-imap/__tests__/imap-live.integration.test.ts

@@ -25,6 +25,7 @@ import {
   type MailAccountRecord,
   type RawInboundMessage,
 } from "../../inbound-mail-foundation";
+import { describeInboundMailProviderContract } from "../../inbound-mail-foundation/__tests__/inbound-mail-provider-contract";
 import { imapInboundMailPlugin } from "../feature";
 
 const HOST = process.env["IMAP_LIVE_HOST"] ?? "127.0.0.1";
@@ -192,3 +193,14 @@ describe("imap-live — echter Server (greenmail)", () => {
     20_000,
   );
 });
+
+describeInboundMailProviderContract(
+  "imap (greenmail)",
+  () => ({
+    plugin: imapInboundMailPlugin,
+    ctx: ctxWithCredentials(credentialDoc(PASSWORD)),
+    account,
+    seed: (subject) => sendTestMail(subject, "contract seed"),
+  }),
+  { skip: !available },
+);

package/src/inbound-provider-inmemory/__tests__/feature.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, test } from "bun:test";
+import { describeInboundMailProviderContract } from "../../inbound-mail-foundation/__tests__/inbound-mail-provider-contract";
+import {
+  inboundProviderInMemoryFeature,
+  inMemoryInboundMailPlugin,
+  seedInboundMessage,
+} from "../feature";
+
+describe("inboundProviderInMemoryFeature — shape", () => {
+  test("has the expected name + requirement", () => {
+    expect(inboundProviderInMemoryFeature.name).toBe("inbound-provider-inmemory");
+    expect(inboundProviderInMemoryFeature.requires).toContain("inbound-mail-foundation");
+  });
+});
+
+describeInboundMailProviderContract("inmemory", () => {
+  const accountId = crypto.randomUUID();
+  return {
+    plugin: inMemoryInboundMailPlugin,
+    ctx: {},
+    account: {
+      id: accountId,
+      tenantId: "00000000-0000-4000-8000-000000004242",
+      provider: "inmemory",
+      authMethod: "password",
+      ownerUserId: null,
+      address: "contract@example.com",
+      displayName: "Contract-Test",
+      status: "active",
+      watchState: "idle",
+    },
+    seed: (subject) =>
+      seedInboundMessage(accountId, {
+        providerMessageId: crypto.randomUUID(),
+        messageIdHeader: null,
+        providerThreadId: null,
+        references: [],
+        from: "sender@example.com",
+        to: ["contract@example.com"],
+        cc: [],
+        subject,
+        snippet: subject,
+        receivedAtIso: "2026-07-01T10:00:00Z",
+        rawMime: null,
+        scope: "inbox",
+      }),
+  };
+});

package/src/inbound-provider-inmemory/feature.ts

@@ -102,7 +102,7 @@ function offsetOf(cursor: SyncCursorPayload | null): number {
   return typeof raw === "number" && Number.isInteger(raw) && raw >= 0 ? raw : 0;
 }
 
-const plugin: InboundMailProviderPlugin = {
+export const inMemoryInboundMailPlugin: InboundMailProviderPlugin = {
   verify: async (_ctx, account: MailAccountRecord) => {
     const state = stateFor(account.id);
     if (state.nextVerifyError) {
@@ -150,5 +150,5 @@ export const inboundProviderInMemoryFeature = defineFeature(FEATURE_NAME, (r) =>
     recommended: false,
   });
   r.requires("inbound-mail-foundation");
-  r.useExtension("inboundMailProvider", INMEMORY_PROVIDER_KEY, plugin);
+  r.useExtension("inboundMailProvider", INMEMORY_PROVIDER_KEY, inMemoryInboundMailPlugin);
 });

package/src/jobs/__tests__/reindex-entity-job.integration.test.ts

@@ -12,7 +12,12 @@ import {
   createEventStoreExecutor,
   createTenantDb,
 } from "@cosmicdrift/kumiko-framework/db";
-import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createEntity,
+  createTextField,
+  defineFeature,
+  type JobContext,
+} from "@cosmicdrift/kumiko-framework/engine";
 import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import {
   setupTestStack,
@@ -20,6 +25,7 @@ import {
   TestUsers,
   unsafeCreateEntityTable,
 } from "@cosmicdrift/kumiko-framework/stack";
+import { bridgeStub } from "@cosmicdrift/kumiko-framework/testing";
 import { createJobsFeature } from "../feature";
 import { reindexEntityJob } from "../handlers/reindex-entity.job";
 
@@ -43,6 +49,16 @@ const widgetFeature = defineFeature("reindex-job-test", (r) => {
 let stack: TestStack;
 const admin = TestUsers.admin;
 
+const noopLogger: JobContext["log"] = {
+  info() {},
+  warn() {},
+  error() {},
+  debug() {},
+  child() {
+    return noopLogger;
+  },
+};
+
 beforeAll(async () => {
   stack = await setupTestStack({ features: [widgetFeature, createJobsFeature()] });
   await unsafeCreateEntityTable(stack.db, widgetEntity);
@@ -87,6 +103,42 @@ describe("reindexEntityJob", () => {
     expect(postResults.some((r) => r.entityId === created.data.id)).toBe(true);
   });
 
+  test("the registered job handler resolves a systemUser-scoped fan-out run and actually indexes (not reindexEntityJob called directly)", async () => {
+    // The two direct-call tests above bypass jobRunner.dispatch()'s
+    // ctx-resolution/guard chain entirely — a bug there (e.g. a systemUser
+    // that isn't wired through) would be invisible to them. Invoke the
+    // ACTUAL registered handler, same as retention-cleanup's handler test.
+    const executor = createEventStoreExecutor(widgetTable, widgetEntity, { entityName: "widget" });
+    const tenantDb = createTenantDb(stack.db, admin.tenantId, "system");
+    const created = await executor.create({ name: "Registry-Resolved Widget" }, admin, tenantDb);
+    if (!created.isSuccess) throw new Error("seed failed");
+
+    const preResults = await stack.search.search(admin.tenantId, "registry-resolved", {
+      filterType: "widget",
+    });
+    expect(preResults).toHaveLength(0);
+
+    const job = stack.registry.getJob(REINDEX_ENTITY_JOB);
+    expect(job).toBeDefined();
+    if (!job) return;
+
+    const ctx: JobContext = {
+      db: stack.db,
+      registry: stack.registry,
+      searchAdapter: stack.search,
+      systemUser: admin,
+      log: noopLogger,
+      triggeredBy: null,
+      ...bridgeStub(),
+    };
+    await job.handler({ entity: "widget" }, ctx);
+
+    const postResults = await stack.search.search(admin.tenantId, "registry-resolved", {
+      filterType: "widget",
+    });
+    expect(postResults.some((r) => r.entityId === created.data.id)).toBe(true);
+  });
+
   test("skips silently when no tenant is resolvable (fan-out misfire)", async () => {
     await expect(
       reindexEntityJob(

package/src/jobs/handlers/detail.query.ts

@@ -21,7 +21,7 @@ export const detailQuery = defineQueryHandler({
 
     // payload is stored encrypted under the triggering user's DEK (#799).
     if (typeof row["payload"] === "string") {
-      row["payload"] = await decryptStoredPii(row["payload"], "job-run-detail");
+      row["payload"] = await decryptStoredPii(row["payload"], "payload", "job-run-detail");
     }
 
     const logs = await selectMany(

package/src/jobs/handlers/list.query.ts

@@ -6,7 +6,7 @@ import { jobRunsTable } from "../job-run-table";
 
 async function decryptRunPayload<T extends Record<string, unknown>>(row: T): Promise<T> {
   if (typeof row["payload"] !== "string") return row;
-  return { ...row, payload: await decryptStoredPii(row["payload"], "job-runs") };
+  return { ...row, payload: await decryptStoredPii(row["payload"], "payload", "job-runs") };
 }
 
 export const listQuery = defineQueryHandler({

package/src/mail-foundation/__tests__/mail-transport-contract.ts

@@ -0,0 +1,42 @@
+import { beforeEach, describe, expect, test } from "bun:test";
+import type { EmailMessage } from "@cosmicdrift/kumiko-bundled-features/channel-email";
+import type { MailTransportContext, MailTransportPlugin } from "../feature";
+
+export type MailTransportContractFixture = {
+  readonly plugin: MailTransportPlugin;
+  readonly ctx: MailTransportContext;
+  readonly tenantId: string;
+  // Local providers (inmemory) expose readBack to assert real delivery;
+  // remote providers (smtp) omit it — send() needs a live server.
+  readonly readBack?: (tenantId: string) => readonly EmailMessage[];
+};
+
+export function describeMailTransportContract(
+  name: string,
+  factory: () => MailTransportContractFixture | Promise<MailTransportContractFixture>,
+): void {
+  describe(`${name} — MailTransportPlugin contract`, () => {
+    let fixture: MailTransportContractFixture;
+
+    beforeEach(async () => {
+      fixture = await factory();
+    });
+
+    test("build resolves to an EmailTransport with a send function", async () => {
+      const transport = await fixture.plugin.build(fixture.ctx, fixture.tenantId);
+      expect(typeof transport.send).toBe("function");
+    });
+
+    test("send delivers the message — verified via readBack", async () => {
+      if (!fixture.readBack) return;
+      const message: EmailMessage = {
+        to: "contract-recipient@example.test",
+        subject: "contract-test-subject",
+        html: "<p>contract-test-body</p>",
+      };
+      const transport = await fixture.plugin.build(fixture.ctx, fixture.tenantId);
+      await transport.send(message);
+      expect(fixture.readBack(fixture.tenantId)).toContainEqual(message);
+    });
+  });
+}

package/src/mail-transport-inmemory/__tests__/feature.test.ts

@@ -1,8 +1,27 @@
 // feature.ts contract tests for mail-transport-inmemory.
 
 import { describe, expect, test } from "bun:test";
+import { isMailTransportPlugin, type MailTransportPlugin } from "../../mail-foundation";
+import { describeMailTransportContract } from "../../mail-foundation/__tests__/mail-transport-contract";
 import { clearInbox, getInbox, mailTransportInMemoryFeature } from "../feature";
 
+function registeredPlugin(): MailTransportPlugin {
+  const usage = mailTransportInMemoryFeature.extensionUsages.find(
+    (u) => u.extensionName === "mailTransport" && u.entityName === "inmemory",
+  );
+  if (!usage || !isMailTransportPlugin(usage.options)) {
+    throw new Error("mail-transport-inmemory: plugin not registered under 'inmemory'");
+  }
+  return usage.options;
+}
+
+describeMailTransportContract("mail-transport-inmemory", () => ({
+  plugin: registeredPlugin(),
+  ctx: {},
+  tenantId: "contract-test-tenant",
+  readBack: getInbox,
+}));
+
 describe("mailTransportInMemoryFeature — shape", () => {
   test("has the expected name", () => {
     expect(mailTransportInMemoryFeature.name).toBe("mail-transport-inmemory");

package/src/mail-transport-smtp/__tests__/feature.test.ts

@@ -4,8 +4,68 @@
 // build-fn presence).
 
 import { describe, expect, test } from "bun:test";
+import type { ConfigAccessor } from "@cosmicdrift/kumiko-framework/engine";
+import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
+import { createSecret } from "@cosmicdrift/kumiko-framework/secrets";
+import { isMailTransportPlugin, type MailTransportPlugin } from "../../mail-foundation";
+import { describeMailTransportContract } from "../../mail-foundation/__tests__/mail-transport-contract";
 import { mailTransportSmtpFeature, SMTP_PASSWORD } from "../feature";
 
+function registeredPlugin(): MailTransportPlugin {
+  const usage = mailTransportSmtpFeature.extensionUsages.find(
+    (u) => u.extensionName === "mailTransport" && u.entityName === "smtp",
+  );
+  if (!usage || !isMailTransportPlugin(usage.options)) {
+    throw new Error("mail-transport-smtp: plugin not registered under 'smtp'");
+  }
+  return usage.options;
+}
+
+function fakeConfig(
+  overrides: Partial<
+    Record<"host" | "port" | "secure" | "from" | "authUser", string | number | boolean>
+  > = {},
+): ConfigAccessor {
+  const keys = mailTransportSmtpFeature.exports.configKeys;
+  const values = new Map<string, string | number | boolean>([
+    [keys.host.name, overrides.host ?? "smtp.contract-test.invalid"],
+    [keys.port.name, overrides.port ?? 587],
+    [keys.secure.name, overrides.secure ?? false],
+    [keys.from.name, overrides.from ?? "noreply@contract-test.invalid"],
+    [keys.authUser.name, overrides.authUser ?? "contract-test-user"],
+  ]);
+  return (async (handle: string | { readonly name: string }) => {
+    const key = typeof handle === "string" ? handle : handle.name;
+    return values.get(key);
+  }) as ConfigAccessor;
+}
+
+function fakeSecrets(): SecretsContext {
+  return {
+    get: async () => createSecret("contract-test-password"),
+    has: async () => true,
+    set: async () => {},
+    delete: async () => true,
+  };
+}
+
+describeMailTransportContract("mail-transport-smtp", () => ({
+  plugin: registeredPlugin(),
+  ctx: { config: fakeConfig(), secrets: fakeSecrets(), _userId: "contract-test-user" },
+  tenantId: "contract-test-tenant",
+}));
+
+describe("mailTransportSmtpFeature — build error path", () => {
+  test("build rejects when a required config-key (host) is unset", async () => {
+    const ctx = {
+      config: fakeConfig({ host: "" }),
+      secrets: fakeSecrets(),
+      _userId: "contract-test-user",
+    };
+    await expect(registeredPlugin().build(ctx, "contract-test-tenant")).rejects.toThrow(/host/);
+  });
+});
+
 describe("mailTransportSmtpFeature — shape", () => {
   test("has the expected name", () => {
     expect(mailTransportSmtpFeature.name).toBe("mail-transport-smtp");

package/src/managed-pages/handlers/branding.query.ts

@@ -21,7 +21,11 @@ export function createBrandingQuery(opts: { readonly allowCustomCss: boolean })
     access: { roles: ["anonymous", "User", "TenantAdmin", "SystemAdmin"] },
     handler: async (_query, ctx) => {
       const base = await readBranding(ctx.config);
-      if (!opts.allowCustomCss || !ctx.config || !ctx.hasFeature(MANAGED_PAGES_CSS_FEATURE)) {
+      if (
+        !opts.allowCustomCss ||
+        !ctx.config ||
+        !(await ctx.hasFeature(MANAGED_PAGES_CSS_FEATURE))
+      ) {
         return base;
       }
       return { ...base, customCss: await readCustomCss(ctx.config) };

package/src/personal-access-tokens/__tests__/feature.test.ts

@@ -1,4 +1,6 @@
 import { describe, expect, test } from "bun:test";
+import { PAT_TOKEN_PREFIX } from "@cosmicdrift/kumiko-framework/api";
+import { EXT_TOKEN_VERIFIER } from "../../auth-foundation";
 import { createPersonalAccessTokensFeature } from "../feature";
 
 describe("createPersonalAccessTokensFeature toggleable-option (tier-gating)", () => {
@@ -22,3 +24,19 @@ describe("createPersonalAccessTokensFeature toggleable-option (tier-gating)", ()
     expect(feature.toggleableDefault).toBe(true);
   });
 });
+
+describe("createPersonalAccessTokensFeature — tokenVerifier registration (#1369)", () => {
+  test('registers via r.useExtension(EXT_TOKEN_VERIFIER, "pat", ...) instead of a patResolver field', () => {
+    const feature = createPersonalAccessTokensFeature({ scopes: {} });
+    expect(feature.extensionUsages).toHaveLength(1);
+    const [usage] = feature.extensionUsages;
+    expect(usage?.extensionName).toBe(EXT_TOKEN_VERIFIER);
+    expect(usage?.entityName).toBe("pat");
+    expect(usage?.options).toMatchObject({ shape: { kind: "prefix", prefix: PAT_TOKEN_PREFIX } });
+  });
+
+  test("requires auth-foundation (owner of EXT_TOKEN_VERIFIER)", () => {
+    const feature = createPersonalAccessTokensFeature({ scopes: {} });
+    expect(feature.requires).toContain("auth-foundation");
+  });
+});

package/src/personal-access-tokens/__tests__/pat.integration.test.ts

@@ -1,9 +1,6 @@
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { randomBytes } from "node:crypto";
-import {
-  createInMemoryLoginRateLimiter,
-  type PatResolver,
-} from "@cosmicdrift/kumiko-framework/api";
+import { createInMemoryLoginRateLimiter } from "@cosmicdrift/kumiko-framework/api";
 import { selectMany, updateMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
   configureBlindIndexKey,
@@ -25,6 +22,7 @@ import { createTestEnvelopeCipher, deleteRows } from "@cosmicdrift/kumiko-framew
 import { Temporal } from "temporal-polyfill";
 import { AuthHandlers } from "../../auth-email-password/constants";
 import { createAuthEmailPasswordFeature } from "../../auth-email-password/feature";
+import { authFoundationFeature, resolveTokenVerifier } from "../../auth-foundation";
 import { createConfigFeature } from "../../config";
 import { createConfigResolver } from "../../config/resolver";
 import { configValuesTable } from "../../config/table";
@@ -39,7 +37,6 @@ import { createUserFeature } from "../../user/feature";
 import { userEntity } from "../../user/schema/user";
 import { PatHandlers, PatQueries } from "../constants";
 import { createPersonalAccessTokensFeature } from "../feature";
-import { createPatResolver } from "../resolver";
 import { apiTokenEntity, apiTokenTable } from "../schema/api-token";
 import type { PatScopeConfig } from "../scopes";
 
@@ -51,7 +48,6 @@ import type { PatScopeConfig } from "../scopes";
 
 let stack: TestStack;
 let h: ReturnType<typeof makeSessionHelpers>;
-let patResolver: PatResolver | undefined;
 
 const encryptionKey = randomBytes(32).toString("base64");
 const TENANT: TenantId = testTenantId(1);
@@ -91,21 +87,22 @@ beforeAll(async () => {
       createAuthEmailPasswordFeature(),
       createSessionsFeature(),
       createPersonalAccessTokensFeature({ scopes: SCOPES }),
+      authFoundationFeature,
     ],
     extraContext: { configResolver: resolver, configEncryption: encryption },
     authConfig: {
       membershipQuery: "tenant:query:memberships",
       loginHandler: AuthHandlers.login,
-      patResolver: (raw: string) => {
-        if (!patResolver) throw new Error("resolver not set");
-        return patResolver(raw);
-      },
+      // PAT registers itself as a tokenVerifier provider (auth-foundation)
+      // instead of the app wiring a dedicated patResolver — resolved
+      // generically here, same as run-prod-app/run-dev-app do.
+      tokenVerifier: (raw: string) =>
+        resolveTokenVerifier({ db: stack.db, registry: stack.registry }, raw),
       // Low per-token cap so the rate-limit test can exhaust it. Other tests do
       // ≤2 requests per (distinct) token, so this ceiling never trips them.
       patRateLimiter: createInMemoryLoginRateLimiter(3, 60_000),
     },
   });
-  patResolver = createPatResolver({ db: stack.db, scopes: SCOPES });
   h = makeSessionHelpers(stack, TENANT);
 
   await unsafeCreateEntityTable(stack.db, userEntity);

package/src/personal-access-tokens/feature.ts

@@ -1,3 +1,8 @@
+import {
+  type AuthProviderPlugin,
+  EXT_TOKEN_VERIFIER,
+} from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
+import { PAT_TOKEN_PREFIX } from "@cosmicdrift/kumiko-framework/api";
 import { buildEntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
 import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
 import { PAT_DEFAULT_RATE_LIMIT, PAT_FEATURE, PAT_SCREEN_ID, type PatRateLimit } from "./constants";
@@ -6,6 +11,7 @@ import { createPatWrite } from "./handlers/create.write";
 import { listPatQuery } from "./handlers/list.query";
 import { revokePatWrite } from "./handlers/revoke.write";
 import { PAT_FEATURE_I18N } from "./i18n";
+import { createPatResolver } from "./resolver";
 import { apiTokenEntity } from "./schema/api-token";
 import type { PatScopeConfig } from "./scopes";
 
@@ -25,14 +31,13 @@ export type PersonalAccessTokensOptions = {
 };
 
 export type PatFeatureExports = {
-  readonly scopes: PatScopeConfig;
   readonly rateLimit: PatRateLimit;
 };
 
 // Personal Access Tokens — long-lived, revocable bearer credentials for the
 // HTTP API. Like `sessions`, the hot-path resolver is NOT a handler: it runs on
 // every PAT-authenticated request and does a direct-DB point-read (see
-// createPatResolver / run-prod-app wiring). The dispatcher-side handlers here
+// createPatResolver / the tokenVerifier extension-point registration below). The dispatcher-side handlers here
 // only mint/list/revoke tokens and expose the scope catalog.
 export function createPersonalAccessTokensFeature(
   options: PersonalAccessTokensOptions,
@@ -40,7 +45,7 @@ export function createPersonalAccessTokensFeature(
   const { scopes } = options;
   return defineFeature(PAT_FEATURE, (r) => {
     r.describe(
-      "Long-lived, revocable Personal Access Tokens for headless HTTP-API access. Stores SHA-256 token hashes in the `store_api_tokens` direct-write table; the plaintext is returned once at creation. `create`/`revoke`/`mine` manage a user's own tokens and `available-scopes` lists the app-declared scope catalog. Bearer tokens carrying the PAT prefix are resolved before jwt.verify (roles resolved live, granted scopes enforced fail-closed at the API boundary) — the resolver is wired via run-prod-app, not the dispatcher. Pass { toggleable: { default: false } } to tier-gate the whole feature.",
+      "Long-lived, revocable Personal Access Tokens for headless HTTP-API access. Stores SHA-256 token hashes in the `store_api_tokens` direct-write table; the plaintext is returned once at creation. `create`/`revoke`/`mine` manage a user's own tokens and `available-scopes` lists the app-declared scope catalog. Bearer tokens carrying the PAT prefix are resolved before jwt.verify (roles resolved live, granted scopes enforced fail-closed at the API boundary) — registered as an auth-foundation tokenVerifier provider, resolved generically by the middleware. Pass { toggleable: { default: false } } to tier-gate the whole feature.",
     );
     r.uiHints({ displayLabel: "Personal Access Tokens", category: "identity", recommended: false });
     // Opt-in tier-gating (mirrors ledger/tags): when set, the feature declares
@@ -49,7 +54,16 @@ export function createPersonalAccessTokensFeature(
     if (options.toggleable !== undefined) r.toggleable(options.toggleable);
     // Resolver reads memberships + users on every PAT request to build live
     // roles — make both boot-time deps so a mis-wiring fails validateBoot.
-    r.requires("user", "tenant");
+    // auth-foundation owns EXT_TOKEN_VERIFIER, which the useExtension below
+    // registers against.
+    r.requires("user", "tenant", "auth-foundation");
+    // Self-registers as a bearer-auth provider instead of the app wiring a
+    // dedicated patResolver callback — the middleware finds it generically
+    // via resolveTokenVerifier(), shape-matched by the PAT token prefix.
+    r.useExtension(EXT_TOKEN_VERIFIER, "pat", {
+      shape: { kind: "prefix", prefix: PAT_TOKEN_PREFIX },
+      build: (deps) => createPatResolver({ db: deps.db, scopes }),
+    } satisfies AuthProviderPlugin);
     // Direct-write store like store_user_sessions: create/revoke write it, the
     // resolver point-reads it. r.entity would make it a rebuildable projection
     // whose replay (no token events) would wipe every live token (#498/#494).
@@ -78,12 +92,13 @@ export function createPersonalAccessTokensFeature(
     });
     r.translations({ keys: PAT_FEATURE_I18N });
 
-    // scopes + rateLimit flow into feature.exports so run-prod-app builds the
-    // resolver + limiter from the same declaration — single source of truth.
+    // rateLimit flows into feature.exports so run-prod-app builds the
+    // limiter from the same declaration — single source of truth. `scopes`
+    // is closed over directly by the useExtension build() above and by
+    // available-scopes, so it doesn't need to round-trip through exports.
     return {
       handlers,
       queries,
-      scopes,
       rateLimit: options.rateLimit ?? PAT_DEFAULT_RATE_LIMIT,
     } satisfies { handlers: unknown; queries: unknown } & PatFeatureExports;
   });