@porulle/core 0.13.0 → 0.15.0

package/dist/runtime/kernel-types.d.ts

@@ -1,6 +1,7 @@
 import type { CommerceConfig, PluginPermission } from "../config/types.js";
 import type { HookRegistry } from "../kernel/hooks/registry.js";
 import type { DatabaseAdapter } from "../kernel/database/adapter.js";
+import type { PluginDb } from "../kernel/database/plugin-types.js";
 import { CatalogServiceImpl } from "../modules/catalog/service.js";
 import { InventoryService } from "../modules/inventory/service.js";
 import { MediaService } from "../modules/media/service.js";
@@ -63,6 +64,12 @@ export interface Kernel {
     pluginPermissions: PluginPermission[];
     logger: ReturnType<typeof createLogger>;
 }
+export interface ConfigRouteDatabase extends DatabaseAdapter {
+    readonly scoped: PluginDb;
+}
+export type ConfigRouteKernel = Omit<Kernel, "database"> & {
+    database: ConfigRouteDatabase;
+};
 export declare const KERNEL_REQUIRED_SERVICE_KEYS: ["catalog", "inventory", "media", "cart", "orders", "payments", "fulfillment", "customers", "webhooks", "analytics", "pricing", "promotions", "tax", "shipping", "search", "settings", "documents", "audit", "compensationFailures"];
 export declare function assertKernelServicesReady(services: Partial<Kernel["services"]>): asserts services is Kernel["services"];
 export declare function assertSortedBefore(topo: readonly string[], a: string, b: string): void;

package/dist/runtime/kernel-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"kernel-types.d.ts","sourceRoot":"","sources":["../../src/runtime/kernel-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,gBAAgB,EACjB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AACrE,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACnE,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACjE,OAAO,EAAE,kBAAkB,EAAE,MAAM,mCAAmC,CAAC;AACvE,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAClE,OAAO,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AACpE,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACjE,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACjE,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACnE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,8BAA8B,EAAE,MAAM,sCAAsC,CAAC;AAEtF,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACtD,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,MAAM;IACrB,MAAM,EAAE,cAAc,CAAC;IACvB,KAAK,EAAE,YAAY,CAAC;IACpB,QAAQ,EAAE,eAAe,CAAC;IAC1B,QAAQ,EAAE;QACR,OAAO,EAAE,kBAAkB,CAAC;QAC5B,SAAS,EAAE,gBAAgB,CAAC;QAC5B,KAAK,EAAE,YAAY,CAAC;QACpB,IAAI,EAAE,WAAW,CAAC;QAClB,MAAM,EAAE,YAAY,CAAC;QACrB,QAAQ,EAAE,eAAe,CAAC;QAC1B,WAAW,EAAE,kBAAkB,CAAC;QAChC,SAAS,EAAE,eAAe,CAAC;QAC3B,QAAQ,EAAE,cAAc,GAAG;YACzB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;SACjE,CAAC;QACF,SAAS,EAAE,gBAAgB,CAAC;QAC5B,OAAO,EAAE,cAAc,CAAC;QACxB,UAAU,EAAE,gBAAgB,CAAC;QAC7B,GAAG,EAAE,UAAU,CAAC;QAChB,QAAQ,EAAE,eAAe,CAAC;QAC1B,MAAM,EAAE,aAAa,CAAC;QACtB,QAAQ,EAAE,eAAe,CAAC;QAC1B,SAAS,EAAE,gBAAgB,CAAC;QAC5B,KAAK,EAAE,YAAY,CAAC;QACpB,oBAAoB,EAAE,8BAA8B,CAAC;QACrD,KAAK,EAAE,cAAc,CAAC,OAAO,CAAC,CAAC;QAC/B,YAAY,EAAE,mBAAmB,CAAC;KACnC,CAAC;IACF,iBAAiB,EAAE,gBAAgB,EAAE,CAAC;IACtC,MAAM,EAAE,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;CACzC;AAED,eAAO,MAAM,4BAA4B,sOAoBW,CAAC;AAErD,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,GACpC,OAAO,CAAC,QAAQ,IAAI,MAAM,CAAC,UAAU,CAAC,CAMxC;AAED,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,GACR,IAAI,CAWN"}
+{"version":3,"file":"kernel-types.d.ts","sourceRoot":"","sources":["../../src/runtime/kernel-types.ts"],"names":[],"mappings":"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"}

package/dist/runtime/kernel.d.ts

@@ -1,6 +1,7 @@
 import type { CommerceConfig } from "../config/types.js";
 import { type Kernel, type WebhookDeliveryPayload } from "./kernel-types.js";
 export type { Kernel, WebhookDeliveryPayload };
+export type { ConfigRouteKernel, ConfigRouteDatabase } from "./kernel-types.js";
 export { KERNEL_ALL_MODULES, kernelModuleInstantiationOrder, } from "./kernel-modules.js";
 export declare function createKernel(config: CommerceConfig): Kernel;
 //# sourceMappingURL=kernel.d.ts.map

package/dist/runtime/kernel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"kernel.d.ts","sourceRoot":"","sources":["../../src/runtime/kernel.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAqBzD,OAAO,EAGL,KAAK,MAAM,EACX,KAAK,sBAAsB,EAC5B,MAAM,mBAAmB,CAAC;AAE3B,YAAY,EAAE,MAAM,EAAE,sBAAsB,EAAE,CAAC;AAC/C,OAAO,EACL,kBAAkB,EAClB,8BAA8B,GAC/B,MAAM,qBAAqB,CAAC;AAE7B,wBAAgB,YAAY,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CA0I3D"}
+{"version":3,"file":"kernel.d.ts","sourceRoot":"","sources":["../../src/runtime/kernel.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAqBzD,OAAO,EAGL,KAAK,MAAM,EACX,KAAK,sBAAsB,EAC5B,MAAM,mBAAmB,CAAC;AAE3B,YAAY,EAAE,MAAM,EAAE,sBAAsB,EAAE,CAAC;AAC/C,YAAY,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAChF,OAAO,EACL,kBAAkB,EAClB,8BAA8B,GAC/B,MAAM,qBAAqB,CAAC;AAE7B,wBAAgB,YAAY,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CA0I3D"}

package/dist/runtime/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/runtime/server.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAQhD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AASzD,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAkB,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAMtE,KAAK,SAAS,GAAG;IACf,SAAS,EAAE;QACT,IAAI,EAAE,YAAY,CAAC;QACnB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;QACpB,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;CACH,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,aAAa,IAAI,OAAO,CAcvC;AAeD;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,cAAc;;;;;sBAiWxB,MAAM,UAAU,MAAM;GA6FtD"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/runtime/server.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAQhD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAUzD,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAkB,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAStE,KAAK,SAAS,GAAG;IACf,SAAS,EAAE;QACT,IAAI,EAAE,YAAY,CAAC;QACnB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;QACpB,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;CACH,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,aAAa,IAAI,OAAO,CAcvC;AAeD;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,cAAc;;;;;sBAkXxB,MAAM,UAAU,MAAM;GA8GtD"}

package/dist/runtime/server.js

@@ -7,6 +7,7 @@ import { rateLimiter } from "hono-rate-limiter";
 import { createHash } from "node:crypto";
 import { createClientIpResolver } from "./client-ip.js";
 import { authMiddleware } from "../auth/middleware.js";
+import { resolveOrgIdForCommerce } from "../auth/org.js";
 import { organizationGuard } from "../auth/organization-guard.js";
 import { CommerceCsrfError } from "../kernel/errors.js";
 import { createRestRoutes } from "../interfaces/rest/index.js";
@@ -16,6 +17,9 @@ import { rewriteCommerceAliasRequest } from "./url-alias-rewrite.js";
 import { mapErrorToResponse } from "../kernel/error-mapper.js";
 import { assertRouteCoverage } from "../interfaces/rest/route-coverage.js";
 import { markRoutePermissionGuard } from "../interfaces/rest/utils.js";
+import { isStrictOrgResolution } from "../auth/strict-org-resolution.js";
+import { runWithPluginDatabaseScope } from "../kernel/database/plugin-db-context.js";
+import { buildConfigRoutesKernel } from "../kernel/plugin/manifest.js";
 /**
  * Returns true if running in a Node-like runtime that supports
  * `process.on()` + `process.exit()`. Edge runtimes (Cloudflare Workers,
@@ -212,10 +216,16 @@ export async function createServer(config) {
     const signInEmailRateKeyCache = new WeakMap();
     const getClientIp = createClientIpResolver(config);
     const keyGenerator = getClientIp;
+    app.use("/api/auth/get-session", rateLimiter({
+        windowMs: 60 * 1000,
+        limit: config.rateLimits?.session ?? 120,
+        keyGenerator,
+    }));
     app.use("/api/auth/*", rateLimiter({
         windowMs: 60 * 1000,
         limit: config.rateLimits?.auth ?? 10,
         keyGenerator,
+        skip: (c) => c.req.path === "/api/auth/get-session",
     }));
     app.use("/api/auth/sign-in/email", async (c, next) => {
         if (c.req.method !== "POST") {
@@ -280,6 +290,17 @@ export async function createServer(config) {
         return auth.handler(c.req.raw);
     });
     app.use("*", authMiddleware(auth, config));
+    app.use("*", async (c, next) => {
+        let organizationId;
+        try {
+            organizationId = resolveOrgIdForCommerce(c.get("actor"), config);
+        }
+        catch {
+            await next();
+            return;
+        }
+        await runWithPluginDatabaseScope(organizationId, next);
+    });
     app.use("*", async (c, next) => {
         c.set("auth", auth);
         await next();
@@ -296,7 +317,7 @@ export async function createServer(config) {
     // body-limit stack apply (all are scoped to /api/*).
     app.route("/api/me", createCustomerPortalRoutes(kernel));
     if (config.routes) {
-        config.routes(app, kernel, auth);
+        config.routes(app, buildConfigRoutesKernel(kernel), auth);
     }
     // OpenAPI spec — disabled in production unless explicitly enabled
     const exposeSpec = config.exposeOpenApiSpec ?? !isProd;
@@ -420,6 +441,17 @@ export async function createServer(config) {
                 "or set config.jobs.autorun.enabled = true for in-process polling.");
         }
     }
+    const defaultOrganizationId = config.auth?.defaultOrganizationId;
+    const hasDefaultOrganization = typeof defaultOrganizationId === "string" && defaultOrganizationId.trim().length > 0;
+    if (isStrictOrgResolution(config) &&
+        !hasDefaultOrganization &&
+        !config.auth?.storeResolver) {
+        throw new Error("Cannot resolve an organization for a request with no actor. Set " +
+            "auth.defaultOrganizationId for a single-tenant deployment, or " +
+            "auth.storeResolver for a multi-tenant one. To keep the previous " +
+            "permissive behaviour during a migration, set " +
+            "auth.strictOrgResolution: false (or STRICT_ORG_RESOLUTION=false).");
+    }
     assertRouteCoverage(app);
     const dispatchFetch = app.fetch.bind(app);
     app.fetch = ((input, env, executionCtx) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@porulle/core",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -56,8 +56,8 @@
     "eslint": "^9.39.1",
     "typescript": "5.9.2",
     "vitest": "^3.2.4",
-    "@porulle/eslint-config": "0.1.0",
-    "@porulle/typescript-config": "0.1.0"
+    "@porulle/typescript-config": "0.1.0",
+    "@porulle/eslint-config": "0.1.0"
   },
   "publishConfig": {
     "access": "public"

package/src/auth/actor.ts

@@ -0,0 +1,110 @@
+import type { AuthSessionLike, CommerceConfig } from "../config/types.js";
+import type { Actor } from "./types.js";
+import type { AuthInstance } from "./setup.js";
+import { DEFAULT_ORG_ID } from "./org.js";
+
+export const AUTH_COOKIE_PREFIX = "uc";
+export const SESSION_COOKIE_NAME = `${AUTH_COOKIE_PREFIX}.session_token`;
+
+export const DEFAULT_CUSTOMER_PERMISSIONS = [
+  "catalog:read",
+  "cart:create",
+  "cart:read",
+  "cart:update",
+  "orders:create",
+  "orders:read:own",
+  "customers:read:self",
+  "customers:update:self",
+] as const;
+
+export function getCustomerPermissions(config: CommerceConfig): string[] {
+  return config.auth?.customerPermissions ?? [...DEFAULT_CUSTOMER_PERMISSIONS];
+}
+
+function resolvePermissions(
+  session: AuthSessionLike,
+  config: CommerceConfig,
+): string[] {
+  const role = session.session.activeOrganizationRole;
+  if (!role) return getCustomerPermissions(config);
+  const roleConfig = config.auth?.roles?.[role];
+  return roleConfig ? roleConfig.permissions : [];
+}
+
+/** Resolve a better-auth session and its porulle organization permissions. */
+export async function resolveActor(
+  headers: Headers,
+  auth: AuthInstance,
+  config: CommerceConfig,
+  request: Request = new Request("http://localhost", { headers }),
+): Promise<Actor | null> {
+  let session: AuthSessionLike | null;
+  try {
+    session = (await auth.api.getSession({
+      headers,
+    })) as AuthSessionLike | null;
+  } catch {
+    return null;
+  }
+
+  if (!session) return null;
+
+  const defaultOrgId = config.auth?.defaultOrganizationId ?? DEFAULT_ORG_ID;
+  let role = session.session.activeOrganizationRole as string | undefined;
+  let orgId = session.session.activeOrganizationId as string | null;
+
+  if (!role && auth.api.getFullOrganization) {
+    try {
+      const org = await auth.api.getFullOrganization({
+        query: { organizationId: orgId ?? defaultOrgId },
+        headers,
+      });
+      if (org?.members) {
+        const membership = org.members.find(
+          (m) => m.userId === session.user.id,
+        );
+        if (membership) {
+          role = membership.role;
+          orgId = orgId ?? defaultOrgId;
+        }
+      }
+    } catch {
+      // fall through — treat as customer
+    }
+  }
+
+  if (!role && orgId && auth.api.getActiveMemberRole) {
+    try {
+      const roleResult = await auth.api.getActiveMemberRole({ headers });
+      role = (roleResult as Record<string, unknown>)?.role as
+        | string
+        | undefined;
+    } catch {
+      // fall through — treat as customer
+    }
+  }
+
+  if (!orgId && config.auth?.storeResolver) {
+    try {
+      const resolved = await config.auth.storeResolver(request);
+      if (resolved) orgId = resolved;
+    } catch {
+      // fall through — use defaultOrgId
+    }
+  }
+
+  const enrichedSession = {
+    ...session,
+    session: { ...session.session, activeOrganizationRole: role ?? null },
+  };
+  return {
+    type: "user",
+    userId: session.user.id,
+    email: session.user.email ?? null,
+    name: session.user.name ?? "User",
+    vendorId: session.user.vendorId ?? null,
+    organizationId: orgId ?? defaultOrgId,
+    role: role ?? "customer",
+    permissions: resolvePermissions(enrichedSession, config),
+  } satisfies Actor;
+}

package/src/auth/middleware.ts

@@ -1,7 +1,8 @@
 import type { MiddlewareHandler } from "hono";
-import type { AuthSessionLike, CommerceConfig } from "../config/types.js";
+import type { CommerceConfig } from "../config/types.js";
 import type { Actor } from "./types.js";
 import type { AuthInstance } from "./setup.js";
+import { getCustomerPermissions, resolveActor } from "./actor.js";
 import { DEFAULT_ORG_ID } from "./org.js";
 import { isStrictOrgResolution } from "./strict-org-resolution.js";
 
@@ -12,37 +13,11 @@ function emptyToNull(value: string | null | undefined): string | null {
 // Exported so the storefront contract can be pinned by a test: an anonymous
 // visitor resolved by `storeResolver` gets these permissions, so dropping
 // `catalog:read` here would 401 every public storefront read.
-
-export const DEFAULT_CUSTOMER_PERMISSIONS = [
-  "catalog:read",
-  "cart:create",
-  "cart:read",
-  "cart:update",
-  "orders:create",
-  "orders:read:own",
-  "customers:read:self",
-  "customers:update:self",
-] as const;
-
-function getCustomerPermissions(config: CommerceConfig): string[] {
-  return config.auth?.customerPermissions ?? [...DEFAULT_CUSTOMER_PERMISSIONS];
-}
+export { DEFAULT_CUSTOMER_PERMISSIONS } from "./actor.js";
 
 const LEGACY_STORE_RESOLVER_WARN_COOLDOWN_MS = 60_000;
 let lastLegacyStoreResolverWarnAt = 0;
 
-function resolvePermissions(
-  session: AuthSessionLike,
-  config: CommerceConfig,
-): string[] {
-  const role = session.session.activeOrganizationRole;
-  if (!role) {
-    return getCustomerPermissions(config);
-  }
-  const roleConfig = config.auth?.roles?.[role];
-  return roleConfig ? roleConfig.permissions : [];
-}
-
 export function authMiddleware(
   auth: AuthInstance,
   config: CommerceConfig,
@@ -68,77 +43,14 @@ export function authMiddleware(
       }
     }
 
-    const session = (await auth.api.getSession({
-      headers: c.req.raw.headers,
-    })) as AuthSessionLike | null;
-
-    if (session) {
-      // Better Auth's session stores activeOrganizationId, but often not the role.
-      // For single-store apps (org_default), users may never call set-active,
-      // so activeOrganizationId can be null even for valid org members.
-      let role = session.session.activeOrganizationRole as string | undefined;
-      let orgId = session.session.activeOrganizationId as string | null;
-
-      // If no active org, try to resolve the user's membership in org_default.
-      // This handles the common case where the user is a member but hasn't
-      // called organization/set-active (single-store apps, seed scripts, tests).
-      if (!role && auth.api.getFullOrganization) {
-        try {
-          const org = await auth.api.getFullOrganization({
-            query: { organizationId: orgId ?? defaultOrgId },
-            headers: c.req.raw.headers,
-          });
-          if (org?.members) {
-            const membership = org.members.find(
-              (m) => m.userId === session.user.id,
-            );
-            if (membership) {
-              role = membership.role;
-              orgId = orgId ?? defaultOrgId;
-            }
-          }
-        } catch {
-          // fall through — treat as customer
-        }
-      }
-
-      // Also try getActiveMemberRole if active org is set
-      if (!role && orgId && auth.api.getActiveMemberRole) {
-        try {
-          const roleResult = await auth.api.getActiveMemberRole({
-            headers: c.req.raw.headers,
-          });
-          role = (roleResult as Record<string, unknown>)?.role as string | undefined;
-        } catch {
-          // fall through — treat as customer
-        }
-      }
-
-      // For customers without org membership, resolve the store from the request.
-      // This enables multi-store SaaS where each storefront is a different org.
-      if (!orgId && config.auth?.storeResolver) {
-        try {
-          const resolved = await config.auth.storeResolver(c.req.raw);
-          if (resolved) orgId = resolved;
-        } catch {
-          // fall through — use defaultOrgId
-        }
-      }
-
-      const enrichedSession = {
-        ...session,
-        session: { ...session.session, activeOrganizationRole: role ?? null },
-      };
-      c.set("actor", {
-        type: "user",
-        userId: session.user.id,
-        email: session.user.email ?? null,
-        name: session.user.name ?? "User",
-        vendorId: session.user.vendorId ?? null,
-        organizationId: orgId ?? defaultOrgId,
-        role: role ?? "customer",
-        permissions: resolvePermissions(enrichedSession, config),
-      } satisfies Actor);
+    const actor = await resolveActor(
+      c.req.raw.headers,
+      auth,
+      config,
+      c.req.raw,
+    );
+    if (actor) {
+      c.set("actor", actor);
       await next();
       return;
     }

package/src/auth/setup.ts

@@ -6,6 +6,7 @@ import { organization, twoFactor, phoneNumber, jwt, bearer } from "better-auth/p
 import type { CommerceConfig } from "../config/types.js";
 import type { DatabaseAdapter } from "../kernel/database/adapter.js";
 import * as authSchema from "./auth-schema.js";
+import { AUTH_COOKIE_PREFIX } from "./actor.js";
 
 type BetterAuthDbProvider = "pg";
 
@@ -178,7 +179,7 @@ export function createAuth(
         },
       },
       advanced: {
-        cookiePrefix: "uc",
+        cookiePrefix: AUTH_COOKIE_PREFIX,
         useSecureCookies: process.env.NODE_ENV === "production",
         // VAPT r2 (pi) finding: SameSite was never set anywhere. Without it,
         // browsers default to Lax for new cookies, but the explicit setting

package/src/config/types.ts

@@ -3,7 +3,7 @@ import type { Actor } from "../auth/types.js";
 import type { BeforeHook, AfterHook } from "../kernel/hooks/types.js";
 import type { PaymentAdapter } from "../modules/payments/adapter.js";
 import type { StorageAdapter } from "../modules/media/adapter.js";
-import type { Kernel } from "../runtime/kernel.js";
+import type { ConfigRouteKernel } from "../runtime/kernel.js";
 import type { AuthInstance } from "../auth/setup.js";
 import type { DatabaseAdapter } from "../kernel/database/adapter.js";
 import type { TaxAdapter } from "../modules/tax/adapter.js";
@@ -439,7 +439,7 @@ export interface CommerceConfig {
    * third argument so integrations can mint/revoke API keys or call
    * `auth.api.*` without module-global holder shims.
    */
-  routes?: (app: Hono<any>, kernel: Kernel, auth?: AuthInstance) => void;
+  routes?: (app: Hono<any>, kernel: ConfigRouteKernel, auth?: AuthInstance) => void;
   /** Log level for structured logging. Default: "info". */
   logLevel?: "fatal" | "error" | "warn" | "info" | "debug" | "trace";
   /**
@@ -453,6 +453,8 @@ export interface CommerceConfig {
     api?: number;
     /** Requests per minute for auth endpoints. Default: 10. */
     auth?: number;
+    /** Requests per minute for session reads. Default: 120. */
+    session?: number;
     /** Requests per minute for checkout. Default: 5. */
     checkout?: number;
     /** Attempts per 15 minutes for sign-in per email. Default: 10. */

package/src/index.ts

@@ -26,12 +26,17 @@ export { createLogger } from "./runtime/logger.js";
 export type { Logger as PinoLogger } from "./runtime/logger.js";
 export { setupGracefulShutdown } from "./runtime/shutdown.js";
 export { createKernel } from "./runtime/kernel.js";
-export type { Kernel } from "./runtime/kernel.js";
+export type { Kernel, ConfigRouteKernel, ConfigRouteDatabase } from "./runtime/kernel.js";
 // Test utilities moved to @porulle/core/testing sub-path export.
 // Import from "@porulle/core/testing" instead of "@porulle/core".
 // This avoids pulling drizzle-kit/tsx/esbuild into Turbopack's bundle graph.
 
 export type { Actor } from "./auth/types.js";
+export {
+  AUTH_COOKIE_PREFIX,
+  resolveActor,
+  SESSION_COOKIE_NAME,
+} from "./auth/actor.js";
 export { resolveOrgId, resolveOrgIdForCommerce, ensureDefaultOrg, DEFAULT_ORG_ID } from "./auth/org.js";
 export { createSystemActor } from "./auth/system-actor.js";
 export { OrganizationService } from "./modules/organization/service.js";

package/src/kernel/database/plugin-types.ts

@@ -13,6 +13,17 @@ import type { PgDatabase, PgQueryResultHKT } from "drizzle-orm/pg-core";
 /**
  * Database instance type for plugin services.
  * This is the Drizzle PgDatabase with an opaque schema record.
+ *
+ * Tenant scoping depends on which handle you were given, not on this type.
+ * `PluginContext.database.db` is wrapped so that `insert`, `select`, `update`
+ * and `delete` on any table with an `organizationId` column are constrained to
+ * the request's organization. `PluginContext.database.unscoped` and the kernel
+ * handle passed to `config.routes` are not wrapped at all.
+ *
+ * `execute()` is never scoped, on any handle — see the scope-boundary note in
+ * `scoped-db.ts`. When you drop to raw SQL, filter by organization yourself and
+ * interpolate values as bind parameters (`sql`... ${value}`) rather than
+ * through `sql.raw`.
  */
 export type PluginDb = PgDatabase<PgQueryResultHKT, Record<string, unknown>>;
 

package/src/kernel/database/scoped-db.ts

@@ -9,6 +9,18 @@
  * Plugin route handlers receive this scoped db via PluginContext.database.db
  * (organization resolved per operation from AsyncLocalStorage when used from
  * plugin routes) or a fixed string / getter from router() / tests.
+ *
+ * SCOPE BOUNDARY — what this does NOT cover:
+ *
+ * Only `insert`, `select`, `update` and `delete` are wrapped. `execute()` is
+ * deliberately outside the boundary: injecting a tenant predicate into
+ * arbitrary SQL would mean parsing it, and a parser that is wrong once is worse
+ * than no guarantee at all. So `db.execute(sql`...`)` on a scoped handle is
+ * exactly as unscoped as one on the raw handle — which is the surprising part,
+ * because the caller reached for the safe object and still has to filter by
+ * organization themselves.
+ *
+ * Adding a fifth wrapped method is fine. Adding a raw-SQL rewriter is not.
  */
 
 import { and, eq, getTableColumns } from "drizzle-orm";

package/src/kernel/plugin/manifest.ts

@@ -9,7 +9,7 @@ import {
   getPluginDatabaseScopeOrganizationId,
   runWithPluginDatabaseScope,
 } from "../database/plugin-db-context.js";
-import type { Kernel } from "../../runtime/kernel.js";
+import type { ConfigRouteKernel, Kernel } from "../../runtime/kernel.js";
 import type {
   CommerceConfig,
   CommercePlugin,
@@ -73,8 +73,12 @@ export interface PluginContext {
 
 const UNSCOPED_WARN_COOLDOWN_MS = 60_000;
 const UNSCOPED_WARN_EVERY_N = 100;
+const configRouteRawDatabases = new WeakMap<object, DatabaseAdapter>();
 
-function createRateLimitedUnscopedAccessWarning(logger: PluginLogger): () => void {
+export function createRateLimitedUnscopedAccessWarning(
+  logger: Pick<PluginLogger, "warn">,
+  message: string,
+): () => void {
   let lastWarnAt = 0;
   let accessCount = 0;
   return () => {
@@ -84,24 +88,64 @@ function createRateLimitedUnscopedAccessWarning(logger: PluginLogger): () => voi
       return;
     }
     lastWarnAt = now;
-    logger.warn(
-      "[plugin:database] PluginContext.database.unscoped is deprecated (MT-4 escape hatch); prefer ctx.database.db for tenant-scoped access.",
-    );
+    logger.warn(message);
   };
 }
 
+function getPluginDatabaseOrganizationId(commerceConfig: CommerceConfig): string {
+  return (
+    getPluginDatabaseScopeOrganizationId() ??
+    resolveOrgIdForCommerce(null, commerceConfig)
+  );
+}
+
+function getRawDatabaseForConfigRoutes(database: DatabaseAdapter): DatabaseAdapter {
+  if (database && typeof database === "object") {
+    return configRouteRawDatabases.get(database) ?? database;
+  }
+  return database;
+}
+
+export function buildConfigRoutesKernel(kernel: Kernel): ConfigRouteKernel {
+  const rawDatabase = getRawDatabaseForConfigRoutes(kernel.database);
+  const rawDb = rawDatabase.db as PluginDb;
+  const scopedDb = createScopedDb(
+    rawDb,
+    () => getPluginDatabaseOrganizationId(kernel.config),
+  );
+  const warnUnscoped = createRateLimitedUnscopedAccessWarning(
+    kernel.logger,
+    "[config:database] kernel.database.db is unscoped; prefer kernel.database.scoped for tenant-scoped access.",
+  );
+
+  const database: ConfigRouteKernel["database"] = {
+    ...rawDatabase,
+    get db(): unknown {
+      warnUnscoped();
+      return rawDatabase.db;
+    },
+    get scoped(): PluginDb {
+      return scopedDb;
+    },
+  };
+  configRouteRawDatabases.set(database, rawDatabase);
+
+  return { ...kernel, database };
+}
+
 function buildPluginContextDatabase(
   rawDb: PluginDb,
   transactionFn: PluginContext["database"]["transaction"],
   commerceConfig: CommerceConfig,
   logger: PluginLogger,
 ): PluginContext["database"] {
-  const orgGetter = () =>
-    getPluginDatabaseScopeOrganizationId() ??
-    resolveOrgIdForCommerce(null, commerceConfig);
+  const orgGetter = () => getPluginDatabaseOrganizationId(commerceConfig);
 
   const scopedDb = createScopedDb(rawDb, orgGetter);
-  const warnUnscoped = createRateLimitedUnscopedAccessWarning(logger);
+  const warnUnscoped = createRateLimitedUnscopedAccessWarning(
+    logger,
+    "[plugin:database] PluginContext.database.unscoped is deprecated (MT-4 escape hatch); prefer ctx.database.db for tenant-scoped access.",
+  );
 
   return {
     get db(): PluginDb {
@@ -261,7 +305,7 @@ export function defineCommercePlugin(
       const pluginRoutes = manifest.routes;
       result = {
         ...result,
-        routes: (app: Hono, kernel: Kernel, auth?: unknown) => {
+        routes: (app: Hono, kernel: ConfigRouteKernel, auth?: unknown) => {
           existingRoutes?.(app, kernel, auth as never);
           const k = kernel as {
             config: CommerceConfig;
@@ -269,14 +313,15 @@ export function defineCommercePlugin(
             database: DatabaseAdapter;
             logger: PluginLogger;
           };
+          const rawDatabase = getRawDatabaseForConfigRoutes(k.database);
           // Narrow DatabaseAdapter<unknown> → PluginContext.database once here.
           // All plugin code receives typed PluginDb — no casts downstream.
           const regs = pluginRoutes({
             config: k.config,
             services: k.services,
             database: buildPluginContextDatabase(
-              k.database.db as PluginDb,
-              k.database.transaction as PluginContext["database"]["transaction"],
+              rawDatabase.db as PluginDb,
+              rawDatabase.transaction as PluginContext["database"]["transaction"],
               k.config,
               k.logger,
             ),

package/src/modules/search/adapter.ts

@@ -1,4 +1,5 @@
 import type { Result } from "../../kernel/result.js";
+import type { PluginDb } from "../../kernel/database/plugin-types.js";
 
 export interface SearchDocument {
   id: string;
@@ -58,6 +59,8 @@ export interface SearchQueryResult {
 
 export interface SearchAdapter {
   readonly providerId: string;
+  /** Called once when the search module wires the adapter to the live database. */
+  init?(deps: { db: PluginDb }): void;
   index(documents: SearchDocument[]): Promise<Result<void>>;
   remove(ids: string[]): Promise<Result<void>>;
   search(params: SearchQueryParams): Promise<Result<SearchQueryResult>>;

package/src/modules/search/module.ts

@@ -1,4 +1,5 @@
 import type { CommerceConfig } from "../../config/types.js";
+import type { PluginDb } from "../../kernel/database/plugin-types.js";
 import { defineModule } from "../../kernel/module/index.js";
 import type { CatalogServiceImpl } from "../catalog/service.js";
 import { SearchService } from "./service.js";
@@ -14,12 +15,14 @@ export const searchModule = defineModule<Record<string, never>, SearchService, S
     schema: () => ({}),
     service: (deps) => {
       const config = deps.config as CommerceConfig;
+      const adapter = config.search?.adapter;
+      adapter?.init?.({ db: deps.db.db as PluginDb });
       return new SearchService({
         catalogRepository: deps.services.catalog.repository,
         resolveEntityFieldDefinitions: deps.services.catalog.resolveEntityFieldDefinitions.bind(deps.services.catalog),
         config,
         ...(config.entities ? { entities: config.entities } : {}),
-        ...(config.search?.adapter ? { adapter: config.search.adapter } : {}),
+        ...(adapter ? { adapter } : {}),
         ...(config.search?.defaultFacets
           ? { defaultFacets: config.search.defaultFacets }
           : {}),