@cosmicdrift/kumiko-framework 0.265.0 → 0.268.0

package/src/db/index.ts

@@ -146,14 +146,16 @@ export { tableExists } from "./schema-inspection";
 export {
   buildBaseColumns,
   buildEntityTable,
+  declareGlobalTenancy,
   type EntityTable,
   toSnakeCase,
   toTableName,
 } from "./table-builder";
-export type { TenantDb, TenantDbMode, UncheckedSystemDb } from "./tenant-db";
+export type { TenantDb, TenantDbGrants, TenantDbMode, UncheckedSystemDb } from "./tenant-db";
 export {
   castTenantRows,
   createTenantDb,
   createUncheckedSystemDb,
   SYSTEM_SCOPE_CHECK_BRAND,
+  withUnsafeRawGrant,
 } from "./tenant-db";

package/src/db/table-builder.ts

@@ -29,6 +29,7 @@ import {
   moneyAmount,
   table as pgTable,
   plainDate,
+  type SchemaTable,
   SQL_EXPR_BRAND,
   type SqlExpression,
   serial,
@@ -505,6 +506,32 @@ function stampGlobalTenancyMeta<E extends EntityDefinition>(
   };
 }
 
+/**
+ * Stamps `tenancy: "global"` onto a `table()`/SchemaTable's meta in place.
+ * Throws if the table has a `tenant_id` column or no EntityTableMeta to stamp.
+ */
+export function declareGlobalTenancy<T extends SchemaTable>(table: T): T & TenancyBrand<"global"> {
+  const meta = (table as unknown as Record<symbol, EntityTableMeta | undefined>)[
+    KUMIKO_META_SYMBOL
+  ];
+  if (!meta) {
+    throw new Error("declareGlobalTenancy(): table has no EntityTableMeta to stamp.");
+  }
+  if (meta.columns.some((c) => c.name === "tenant_id")) {
+    throw new Error(
+      `declareGlobalTenancy("${meta.tableName}"): tables with a "tenant_id" column cannot be ` +
+        'declared tenancy: "global" — a global table\'s rows carry the system tenant, not a ' +
+        "per-row tenant identity.",
+    );
+  }
+  (table as unknown as Record<symbol, EntityTableMeta>)[KUMIKO_META_SYMBOL] = {
+    ...meta,
+    tenancy: "global",
+  };
+  // @cast-boundary type-brand — TenancyBrand<"global"> is a phantom marker with no runtime representation.
+  return table as T & TenancyBrand<"global">;
+}
+
 export function buildEntityTable<E extends EntityDefinition>(
   entityName: string,
   entity: E,

package/src/db/tenant-db.ts

@@ -137,17 +137,48 @@ function tableNameOf(table: Table | EntityTableMeta): string {
   return asEntityTableMeta(table)?.tableName ?? "<unknown>";
 }
 
+// A grant is only real when its reason is non-empty — `{ reason: "" }` must not silently unlock it.
+function hasGrant(decl: EscapeHatchDeclaration | undefined): boolean {
+  return decl !== undefined && decl.reason.trim().length > 0;
+}
+
+function isForeignTenantId(tenantIdValue: unknown): boolean {
+  return tenantIdValue !== undefined && tenantIdValue !== SYSTEM_TENANT_ID;
+}
+
 // Checks the canonical EntityTableMeta (branded EntityTable's KUMIKO_META_SYMBOL
 // or a plain deriveEntityTableMeta/defineUnmanagedTable result), not a direct
 // `table.tenantId` property read — the latter only exists on branded EntityTables
 // and silently returned false (no tenant filter!) for plain EntityTableMeta
 // tables like unmanaged direct-write stores, e.g. userSessionTable.
-function hasTenantColumn(table: Table): boolean {
+function hasTenantColumn(table: Table | EntityTableMeta): boolean {
   const meta = asEntityTableMeta(table);
   if (meta) return meta.columns.some((c) => c.name === "tenant_id");
   return (table as Record<string, unknown>)["tenantId"] !== undefined;
 }
 
+// Grants for TenantDb's two escape hatches: db.global()'s write methods
+// (write-handler-only) and ctx.db.unsafeRaw() (handler or hook, re-granted per hook).
+export type TenantDbGrants = {
+  readonly globalWrites?: EscapeHatchDeclaration;
+  readonly unsafeRaw?: EscapeHatchDeclaration;
+};
+
+const unsafeRawRebinders = new WeakMap<
+  TenantDb,
+  (grant: EscapeHatchDeclaration | undefined) => TenantDb
+>();
+
+// Rebinds tenantDb's unsafeRaw grant (e.g. a hook's own escapeHatch); inputs not built by
+// createTenantDb pass through unchanged, without touching any property (ctx.db may be a throwing Proxy).
+export function withUnsafeRawGrant(
+  tenantDb: TenantDb,
+  grant: EscapeHatchDeclaration | undefined,
+): TenantDb {
+  const rebind = unsafeRawRebinders.get(tenantDb);
+  return rebind ? rebind(grant) : tenantDb;
+}
+
 export function createTenantDb(
   db: DbRunner,
   tenantId: TenantId,
@@ -155,8 +186,7 @@ export function createTenantDb(
   tracer?: Tracer,
   meter?: Meter,
   signal?: AbortSignal,
-  // Gates db.global(table)'s write methods; write-path-only (see dispatch-shared.ts buildHandlerContext).
-  escapeHatch?: EscapeHatchDeclaration,
+  grants?: TenantDbGrants,
 ): TenantDb {
   if (meter) registerStandardMetrics(meter);
 
@@ -215,7 +245,7 @@ export function createTenantDb(
   // (e.g. exclude SYSTEM reference rows at the DB instead of post-filtering
   // after a limit). Values outside the scope are dropped; if nothing valid
   // remains, the full enforced scope applies — widening is never possible.
-  function readWhere(table: Table, where?: WhereObject): WhereObject | undefined {
+  function readWhere(table: Table | EntityTableMeta, where?: WhereObject): WhereObject | undefined {
     if (!hasTenantColumn(table) || mode === "system") return where;
     const allowed = [tenantId, SYSTEM_TENANT_ID];
     const requested = where?.["tenantId"];
@@ -242,7 +272,7 @@ export function createTenantDb(
   }
 
   function missingEscapeHatch(table: Table | EntityTableMeta): AccessDeniedError | undefined {
-    if (escapeHatch && escapeHatch.reason.trim().length > 0) return undefined;
+    if (hasGrant(grants?.globalWrites)) return undefined;
     return new AccessDeniedError({
       message:
         `db.global(${tableNameOf(table)}): write rejected — declare ` +
@@ -251,6 +281,15 @@ export function createTenantDb(
     });
   }
 
+  function foreignTenantOnGlobalWrite(
+    table: Table | EntityTableMeta,
+    tenantIdValue: unknown,
+    message: string = `db.global(${tableNameOf(table)}): tenantId "${String(tenantIdValue)}" is not SYSTEM_TENANT_ID — a "global" table's rows must carry the system tenant, not an arbitrary tenant's id.`,
+  ): AccessDeniedError | undefined {
+    if (!isForeignTenantId(tenantIdValue)) return undefined;
+    return new AccessDeniedError({ message });
+  }
+
   function globalTable<TTable extends (SchemaTable | EntityTableMeta) & TenancyBrand<"global">>(
     table: TTable,
   ): GlobalTableDb<TTable> {
@@ -273,7 +312,8 @@ export function createTenantDb(
       insertOne<T = Record<string, unknown>>(
         values: Record<string, unknown>,
       ): Promise<T | undefined> {
-        const denied = missingEscapeHatch(table);
+        const denied =
+          missingEscapeHatch(table) ?? foreignTenantOnGlobalWrite(table, values["tenantId"]);
         if (denied) return Promise.reject(denied);
         return withDbSpan("insert", table, async () => bunInsertOne<T>(db, table, values));
       },
@@ -281,7 +321,8 @@ export function createTenantDb(
         set: Record<string, unknown>,
         where: WhereObject,
       ): Promise<readonly T[]> {
-        const denied = missingEscapeHatch(table);
+        const denied =
+          missingEscapeHatch(table) ?? foreignTenantOnGlobalWrite(table, set["tenantId"]);
         if (denied) return Promise.reject(denied);
         if (!where || Object.keys(where).length === 0) {
           return Promise.reject(
@@ -308,14 +349,28 @@ export function createTenantDb(
     } as GlobalTableDb<TTable>;
   }
 
-  return {
+  const tenantDb: TenantDb = {
     tenantId,
     mode,
     raw: db,
     global: globalTable,
 
+    unsafeRaw(reason: string): DbRunner {
+      if (reason.trim().length === 0) {
+        throw new Error("unsafeRaw requires a non-empty reason");
+      }
+      if (!hasGrant(grants?.unsafeRaw)) {
+        throw new AccessDeniedError({
+          message:
+            'ctx.db.unsafeRaw(reason): rejected — declare `escapeHatch: { reason: "..." }` on ' +
+            "the handler or hook to allow unsafeRaw.",
+        });
+      }
+      return db;
+    },
+
     selectMany<T = Record<string, unknown>>(
-      table: Table,
+      table: Table | EntityTableMeta,
       where?: WhereObject,
       options?: SelectOptions,
     ): Promise<readonly T[]> {
@@ -324,7 +379,7 @@ export function createTenantDb(
     },
 
     fetchOne<T = Record<string, unknown>>(
-      table: Table,
+      table: Table | EntityTableMeta,
       where: WhereObject,
     ): Promise<T | undefined> {
       const filter = readWhere(table, where) ?? {};
@@ -335,6 +390,19 @@ export function createTenantDb(
       table: Table,
       values: Record<string, unknown>,
     ): Promise<T | undefined> {
+      if (
+        mode === "tenant" &&
+        hasTenantColumn(table) &&
+        asEntityTableMeta(table)?.tenancy === "global"
+      ) {
+        const denied = foreignTenantOnGlobalWrite(
+          table,
+          tenantId,
+          `insertOne(${tableNameOf(table)}): "global" table rows must carry SYSTEM_TENANT_ID; ` +
+            "use db.global(table) with escapeHatch instead.",
+        );
+        if (denied) return Promise.reject(denied);
+      }
       const data = insertValues(table, values);
       return withDbSpan("insert", table, async () => bunInsertOne<T>(db, table, data));
     },
@@ -367,6 +435,11 @@ export function createTenantDb(
       return withDbSpan("delete", table, async () => bunDeleteMany(db, table, filter));
     },
   };
+
+  unsafeRawRebinders.set(tenantDb, (grant) =>
+    createTenantDb(db, tenantId, mode, tracer, meter, signal, { ...grants, unsafeRaw: grant }),
+  );
+  return tenantDb;
 }
 
 export { asRawClient };

package/src/engine/active-membership.ts

@@ -10,12 +10,26 @@ import type { TenantId } from "./types/identifiers";
 // with a since-deleted row should not silently treat it as active.
 export type PrincipalStatus = "active" | "blocked" | "unknown";
 
+// Global-roles/timezone/locale snapshot ctx.queryAsMember needs to mint a
+// resolved principal's SessionUser, without exposing its own table.
+export type PrincipalProfile = {
+  readonly globalRoles: readonly string[];
+  readonly timezone?: string;
+  readonly locale?: string;
+};
+
 // Registered via r.useExtension(EXT_PRINCIPAL_STATUS, "user", principalStatusPlugin).
 export type PrincipalStatusPlugin = {
   readonly resolveStatus: (
     userId: string,
     deps: { readonly db: DbConnection },
   ) => Promise<PrincipalStatus>;
+  // Required so a missing provider fails closed (InternalError) instead of
+  // silently minting empty global roles for ctx.queryAsMember.
+  readonly resolveProfile: (
+    userId: string,
+    deps: { readonly db: DbConnection },
+  ) => Promise<PrincipalProfile | null>;
 };
 
 // `null` means the tenant has no lifecycle row (never entered teardown).
@@ -38,7 +52,7 @@ function hasResolveStatusFn(v: unknown): v is { readonly resolveStatus: unknown
 }
 
 export function isPrincipalStatusPlugin(v: unknown): v is PrincipalStatusPlugin {
-  return hasResolveStatusFn(v);
+  return hasResolveStatusFn(v) && "resolveProfile" in v && typeof v.resolveProfile === "function";
 }
 
 export function isTenantLifecycleStatusPlugin(v: unknown): v is TenantLifecycleStatusPlugin {