@porulle/core 0.10.8 → 0.13.0

package/dist/utils/id.d.ts

@@ -1,3 +1,5 @@
+import type { Actor } from "../auth/types.js";
 export declare function makeId(): string;
 export declare function makeDeterministicId(value: string): Promise<string>;
+export declare function makeIdempotencyScope(actor: Actor | null | undefined, guestCredential?: string, fallbackBinding?: string): Promise<string>;
 //# sourceMappingURL=id.d.ts.map

package/dist/utils/id.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"id.d.ts","sourceRoot":"","sources":["../../src/utils/id.ts"],"names":[],"mappings":"AAAA,wBAAgB,MAAM,IAAI,MAAM,CAE/B;AAED,wBAAsB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CASxE"}
+{"version":3,"file":"id.d.ts","sourceRoot":"","sources":["../../src/utils/id.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAE9C,wBAAgB,MAAM,IAAI,MAAM,CAE/B;AAED,wBAAsB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CASxE;AAED,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,KAAK,GAAG,IAAI,GAAG,SAAS,EAC/B,eAAe,CAAC,EAAE,MAAM,EACxB,eAAe,CAAC,EAAE,MAAM,GACvB,OAAO,CAAC,MAAM,CAAC,CAYjB"}

package/dist/utils/id.js

@@ -9,3 +9,14 @@ export async function makeDeterministicId(value) {
     const hex = [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
     return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
 }
+export async function makeIdempotencyScope(actor, guestCredential, fallbackBinding) {
+    const binding = actor?.userId
+        ? `actor:${actor.type}:${actor.userId}`
+        : guestCredential
+            ? `guest:${guestCredential}`
+            : fallbackBinding
+                ? `resource:${fallbackBinding}`
+                : "anonymous";
+    const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(binding)));
+    return [...digest].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@porulle/core",
-  "version": "0.10.8",
+  "version": "0.13.0",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -36,11 +36,11 @@
     }
   },
   "dependencies": {
-    "@better-auth/api-key": "^1.3.8",
-    "@better-auth/drizzle-adapter": "^1.3.8",
+    "@better-auth/api-key": "^1.7.1",
+    "@better-auth/drizzle-adapter": "^1.7.1",
     "@hono/zod-openapi": "^1.2.2",
     "@scalar/hono-api-reference": "^0.10.5",
-    "better-auth": "^1.3.8",
+    "better-auth": "^1.7.1",
     "drizzle-orm": "^0.45.1",
     "drizzle-zod": "^0.8.3",
     "hono": "^4.9.8",
@@ -81,7 +81,8 @@
   "scripts": {
     "generate:plugins": "node ./scripts/generate-plugin-types.mjs",
     "check:store-guard": "node ./scripts/check-store-guard.mjs",
-    "build": "rm -rf dist tsconfig.build.tsbuildinfo && npm run generate:plugins && npm run check:store-guard && tsc -p tsconfig.build.json",
+    "check:auth-schema": "vitest run test/auth-schema-better-auth-parity.test.ts",
+    "build": "rm -rf dist tsconfig.build.tsbuildinfo && npm run generate:plugins && npm run check:store-guard && npm run check:auth-schema && tsc -p tsconfig.build.json",
     "check-types": "npm run generate:plugins && npm run check:store-guard && tsc --noEmit",
     "lint": "eslint . --max-warnings 1000",
     "test": "vitest run"

package/src/auth/auth-schema-guard.ts

@@ -0,0 +1,143 @@
+/**
+ * Compares Porulle's Drizzle auth tables against better-auth's canonical
+ * {@link getAuthTables} output so a dependency minor bump cannot add a column
+ * the declared schema omits.
+ */
+
+import { getTableColumns, getTableName } from "drizzle-orm";
+import type { PgColumn, PgTable } from "drizzle-orm/pg-core";
+import { getAuthTables } from "better-auth/db";
+import type { BetterAuthOptions } from "better-auth";
+import { apiKey } from "@better-auth/api-key";
+import { organization, twoFactor, phoneNumber, jwt, bearer } from "better-auth/plugins";
+import * as authSchema from "./auth-schema.js";
+
+/**
+ * Every plugin {@link createAuth} can enable, not only the ones it enables by
+ * default. The shipped schema has to satisfy any configuration a merchant
+ * chooses, so the guard compares against the maximal table set: a column that
+ * only `twoFactor` needs is still a column this package must declare.
+ */
+export const AUTH_SCHEMA_GUARD_OPTIONS = {
+  plugins: [
+    organization({ roles: {} }),
+    bearer(),
+    jwt(),
+    twoFactor({ issuer: "porulle-auth-schema-guard" }),
+    apiKey(),
+    phoneNumber(),
+  ],
+  user: {
+    additionalFields: {
+      vendorId: { type: "string", required: false },
+      posOperatorPin: { type: "string", required: false },
+    },
+  },
+} satisfies BetterAuthOptions;
+
+/**
+ * Drizzle tables keyed by the SQL table name they declare, so the guard walks
+ * whatever models better-auth reports rather than a list someone has to
+ * remember to extend. A hand-maintained model list is how `jwks.alg` shipped
+ * missing while this guard passed.
+ */
+function drizzleTablesByName(): Map<string, PgTable> {
+  const byName = new Map<string, PgTable>();
+  for (const value of Object.values(authSchema)) {
+    try {
+      byName.set(getTableName(value as PgTable), value as PgTable);
+    } catch {
+      // Not a Drizzle table (type export, index helper) — skip.
+    }
+  }
+  return byName;
+}
+
+function drizzleColumnForField(
+  table: PgTable,
+  fieldKey: string,
+  fieldName: string,
+): PgColumn | undefined {
+  const columns = getTableColumns(table);
+  if (fieldKey in columns) {
+    return columns[fieldKey] as PgColumn;
+  }
+  for (const column of Object.values(columns)) {
+    if (column.name === fieldName) {
+      return column as PgColumn;
+    }
+  }
+  return undefined;
+}
+
+export type AuthSchemaParityMismatch = {
+  model: string;
+  field: string;
+  issue: string;
+};
+
+/**
+ * Returns every mismatch between better-auth's expected auth tables and the
+ * Drizzle definitions Porulle ships. An empty array means parity holds.
+ */
+export function findAuthSchemaParityMismatches(
+  options: BetterAuthOptions = AUTH_SCHEMA_GUARD_OPTIONS,
+): AuthSchemaParityMismatch[] {
+  const mismatches: AuthSchemaParityMismatch[] = [];
+  const authTables = getAuthTables(options);
+  const byName = drizzleTablesByName();
+
+  for (const [model, tableDef] of Object.entries(authTables)) {
+    if (!tableDef) continue;
+    const drizzleTable = byName.get(tableDef.modelName);
+    if (!drizzleTable) {
+      mismatches.push({
+        model,
+        field: "*",
+        issue: `no drizzle table declares better-auth model "${tableDef.modelName}"`,
+      });
+      continue;
+    }
+
+    for (const [fieldKey, fieldAttr] of Object.entries(tableDef.fields)) {
+      const column = drizzleColumnForField(
+        drizzleTable,
+        fieldKey,
+        fieldAttr.fieldName ?? fieldKey,
+      );
+      if (!column) {
+        mismatches.push({
+          model,
+          field: fieldKey,
+          issue: `drizzle column missing for better-auth field "${fieldKey}"`,
+        });
+        continue;
+      }
+
+      const required = fieldAttr.required !== false;
+      if (required && !column.notNull) {
+        mismatches.push({
+          model,
+          field: fieldKey,
+          issue: `column "${column.name}" must be NOT NULL (better-auth required)`,
+        });
+      }
+    }
+  }
+
+  return mismatches;
+}
+
+export function assertAuthSchemaParity(
+  options: BetterAuthOptions = AUTH_SCHEMA_GUARD_OPTIONS,
+): void {
+  const mismatches = findAuthSchemaParityMismatches(options);
+  if (mismatches.length === 0) return;
+
+  const detail = mismatches
+    .map((m) => `  ${m.model}.${m.field}: ${m.issue}`)
+    .join("\n");
+  throw new Error(
+    `Porulle auth-schema.ts is out of sync with installed better-auth:\n${detail}`,
+  );
+}

package/src/auth/auth-schema.ts

@@ -4,6 +4,7 @@ import {
   timestamp,
   boolean,
   integer,
+  uniqueIndex,
 } from "drizzle-orm/pg-core";
 
 export const user = pgTable("user", {
@@ -19,6 +20,12 @@ export const user = pgTable("user", {
     .notNull(),
   vendorId: text("vendor_id"),
   posOperatorPin: text("pos_operator_pin"),
+  // Contributed by the twoFactor and phoneNumber plugins. Declared
+  // unconditionally: the plugins are config-gated, but one shipped schema has
+  // to satisfy every configuration a merchant can choose.
+  twoFactorEnabled: boolean("two_factor_enabled").default(false),
+  phoneNumber: text("phone_number").unique(),
+  phoneNumberVerified: boolean("phone_number_verified").default(false),
 });
 
 export const session = pgTable("session", {
@@ -37,25 +44,35 @@ export const session = pgTable("session", {
   activeOrganizationId: text("active_organization_id"),
 });
 
-export const account = pgTable("account", {
-  id: text("id").primaryKey(),
-  accountId: text("account_id").notNull(),
-  providerId: text("provider_id").notNull(),
-  userId: text("user_id")
-    .notNull()
-    .references(() => user.id, { onDelete: "cascade" }),
-  accessToken: text("access_token"),
-  refreshToken: text("refresh_token"),
-  idToken: text("id_token"),
-  accessTokenExpiresAt: timestamp("access_token_expires_at"),
-  refreshTokenExpiresAt: timestamp("refresh_token_expires_at"),
-  scope: text("scope"),
-  password: text("password"),
-  createdAt: timestamp("created_at").defaultNow().notNull(),
-  updatedAt: timestamp("updated_at")
-    .$onUpdate(() => /* @__PURE__ */ new Date())
-    .notNull(),
-});
+export const account = pgTable(
+  "account",
+  {
+    id: text("id").primaryKey(),
+    issuer: text("issuer").notNull(),
+    accountId: text("account_id").notNull(),
+    providerId: text("provider_id").notNull(),
+    userId: text("user_id")
+      .notNull()
+      .references(() => user.id, { onDelete: "cascade" }),
+    accessToken: text("access_token"),
+    refreshToken: text("refresh_token"),
+    idToken: text("id_token"),
+    accessTokenExpiresAt: timestamp("access_token_expires_at"),
+    refreshTokenExpiresAt: timestamp("refresh_token_expires_at"),
+    scope: text("scope"),
+    password: text("password"),
+    createdAt: timestamp("created_at").defaultNow().notNull(),
+    updatedAt: timestamp("updated_at")
+      .$onUpdate(() => /* @__PURE__ */ new Date())
+      .notNull(),
+  },
+  (table) => [
+    uniqueIndex("account_issuer_account_id_unique").on(
+      table.issuer,
+      table.accountId,
+    ),
+  ],
+);
 
 export const verification = pgTable("verification", {
   id: text("id").primaryKey(),
@@ -136,4 +153,18 @@ export const jwks = pgTable("jwks", {
   privateKey: text("private_key").notNull(),
   createdAt: timestamp("created_at").notNull(),
   expiresAt: timestamp("expires_at"),
+  alg: text("alg"),
+  crv: text("crv"),
+});
+
+export const twoFactor = pgTable("twoFactor", {
+  id: text("id").primaryKey(),
+  secret: text("secret").notNull(),
+  backupCodes: text("backup_codes").notNull(),
+  userId: text("user_id")
+    .notNull()
+    .references(() => user.id, { onDelete: "cascade" }),
+  verified: boolean("verified").default(false),
+  failedVerificationCount: integer("failed_verification_count").default(0),
+  lockedUntil: timestamp("locked_until"),
 });

package/src/auth/middleware.ts

@@ -5,7 +5,15 @@ import type { AuthInstance } from "./setup.js";
 import { DEFAULT_ORG_ID } from "./org.js";
 import { isStrictOrgResolution } from "./strict-org-resolution.js";
 
-const DEFAULT_CUSTOMER_PERMISSIONS = [
+function emptyToNull(value: string | null | undefined): string | null {
+  return value == null || value === "" ? null : value;
+}
+
+// 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",
@@ -192,9 +200,13 @@ export function authMiddleware(
                 : null;
           const metaOrg = typeof meta?.organizationId === "string" ? meta.organizationId : undefined;
           const orgId = (metaOrg ?? apiKey.organizationId ?? defaultOrgId) as string;
-          const userId = ((typeof meta?.operatorId === "string" ? meta.operatorId : undefined)
-            ?? apiKey.referenceId
-            ?? "") as string;
+          // No operator and no reference means the key carries no user
+          // identity. Leave it absent rather than substituting a shared
+          // placeholder, which would make every such key look like one person.
+          const userId = emptyToNull(
+            (typeof meta?.operatorId === "string" ? meta.operatorId : undefined) ??
+              (typeof apiKey.referenceId === "string" ? apiKey.referenceId : undefined),
+          );
 
           // Better Auth stores permissions as Record<string, string[]>
           // (e.g. {"catalog":["read","create"]}).  Flatten to the
@@ -245,7 +257,7 @@ export function authMiddleware(
             // services can scope queries correctly.
             c.set("actor", {
               type: "user",
-              userId: "anonymous",
+              userId: null,
               email: null,
               name: "Anonymous",
               vendorId: null,

package/src/auth/org.ts

@@ -37,14 +37,26 @@ export function setBootDefaultOrgId(orgId: string): void {
   _bootDefaultOrgId = orgId;
 }
 
+/**
+ * Resolves org using an explicit config default — not ambient boot state.
+ * Use when the caller holds CommerceConfig and may lack an actor organizationId.
+ */
+export function resolveOrgIdForCommerce(
+  actor: unknown,
+  config?: CommerceConfig | null,
+): string {
+  return resolveOrgId(actor, config?.auth?.defaultOrganizationId, config ?? undefined);
+}
+
 /**
  * Extracts the organization ID from an actor.
  *
  * Resolution order:
  * 1. Actor's organizationId (set by middleware from session/API key/storeResolver)
  * 2. Explicit defaultOrgId parameter (caller override)
- * 3. Boot-time default (from config.auth.defaultOrganizationId via setBootDefaultOrgId)
- * 4. Deprecated fallback to DEFAULT_ORG_ID (will be removed)
+ * 3. Strict check — throw OrgResolutionError when enabled
+ * 4. Boot-time default (from config.auth.defaultOrganizationId via setBootDefaultOrgId)
+ * 5. Deprecated fallback to DEFAULT_ORG_ID (will be removed)
  */
 export function resolveOrgId(
   actor: unknown,
@@ -56,12 +68,12 @@ export function resolveOrgId(
     if (typeof orgId === "string") return orgId;
   }
   if (defaultOrgId) return defaultOrgId;
-  if (_bootDefaultOrgId) return _bootDefaultOrgId;
   if (isStrictOrgResolution(commerceConfig)) {
     throw new OrgResolutionError(
       "Organization could not be resolved: no actor organizationId, no defaultOrgId, and no configured default organization.",
     );
   }
+  if (_bootDefaultOrgId) return _bootDefaultOrgId;
   warnDeprecatedOrgDefaultFallback();
   return DEFAULT_ORG_ID;
 }

package/src/auth/organization-guard.ts

@@ -0,0 +1,158 @@
+import type { MiddlewareHandler } from "hono";
+import { and, eq } from "drizzle-orm";
+import type { CommerceConfig } from "../config/types.js";
+import type { DrizzleDatabase } from "../kernel/database/drizzle-db.js";
+import { invitation, member } from "./auth-schema.js";
+import { canGrantRole, granterForRole, isCompositeRole } from "./role-authority.js";
+
+/**
+ * Guards Better Auth's organization endpoints, which this repository mounts but
+ * does not govern.
+ *
+ * Red-team round 6 found two problems behind that mount.
+ *
+ * Invitation acceptance re-checked nothing: an invitation minted a member at
+ * the authority its inviter held up to seven days ago, so a demoted or revoked
+ * inviter's outstanding invitation still handed out ownership — a full
+ * organization takeover. Acceptance now re-reads the inviter's current
+ * authority before the grant is allowed through.
+ *
+ * And the plugin's own membership writers are a second role-changing surface
+ * running none of the rules `admin/staff.ts` enforces: no permission
+ * containment, no rank floor, no last-owner invariant, and they accept
+ * comma-composite role strings that `admin/staff.ts` refuses. They are refused
+ * here. `admin/staff.ts` is this repository's governed membership surface, and
+ * having one is worth more than making two of them agree.
+ */
+
+const ORGANIZATION_PREFIX = "/api/auth/organization/";
+
+/**
+ * Better Auth endpoints that write membership or define what a role may do.
+ *
+ * `invite-member` currently throws for every role instead of refusing: the
+ * plugin is configured with commerce permission arrays where its access-control
+ * model expects `Role` objects exposing `.authorize()`, so its permission check
+ * dies of type confusion. That is fail-closed by accident, and the accident is
+ * one "fix the roles wiring" commit away from being fail-open. Refusing here
+ * makes the closure deliberate, so repairing that wiring cannot quietly open an
+ * ungoverned door. `update-member-role` is not even inert today — Better Auth
+ * short-circuits it for organization creators, so an owner reaches it.
+ */
+const REFUSED_ENDPOINTS = new Set([
+  "invite-member",
+  "update-member-role",
+  "remove-member",
+  "leave",
+  "create-role",
+  "update-role",
+  "delete-role",
+]);
+
+function endpointName(path: string): string | null {
+  const normalized = path.replace(/\/+$/, "");
+  return normalized.startsWith(ORGANIZATION_PREFIX)
+    ? normalized.slice(ORGANIZATION_PREFIX.length)
+    : null;
+}
+
+async function readJsonBody(request: Request): Promise<Record<string, unknown>> {
+  try {
+    return (await request.clone().json()) as Record<string, unknown>;
+  } catch {
+    return {};
+  }
+}
+
+export function organizationGuard(
+  db: DrizzleDatabase,
+  config: CommerceConfig,
+): MiddlewareHandler {
+  return async (c, next) => {
+    if (c.req.method !== "POST") {
+      await next();
+      return;
+    }
+
+    const endpoint = endpointName(c.req.path);
+    if (endpoint === null) {
+      await next();
+      return;
+    }
+
+    if (REFUSED_ENDPOINTS.has(endpoint)) {
+      return c.json(
+        {
+          error: {
+            code: "FORBIDDEN",
+            message: `"${endpoint}" is not a governed membership surface. Use /api/admin/staff, which enforces permission containment, the rank floor, and the last-owner invariant.`,
+          },
+        },
+        403,
+      );
+    }
+
+    if (endpoint !== "accept-invitation") {
+      await next();
+      return;
+    }
+
+    const body = await readJsonBody(c.req.raw);
+    const invitationId = typeof body.invitationId === "string" ? body.invitationId : null;
+    if (!invitationId) {
+      await next();
+      return;
+    }
+
+    const rows = await db
+      .select()
+      .from(invitation)
+      .where(eq(invitation.id, invitationId));
+    const pending = rows[0];
+    // Missing, already-answered, or expired invitations are Better Auth's own
+    // error surface — do not duplicate its messages here.
+    if (!pending || pending.status !== "pending") {
+      await next();
+      return;
+    }
+
+    const invitedRole = pending.role ?? "member";
+    const inviterRows = await db
+      .select({ role: member.role })
+      .from(member)
+      .where(
+        and(
+          eq(member.organizationId, pending.organizationId),
+          eq(member.userId, pending.inviterId),
+        ),
+      );
+    const inviterRole = inviterRows[0]?.role;
+
+    const stillAuthorized =
+      inviterRole !== undefined &&
+      !isCompositeRole(invitedRole) &&
+      canGrantRole(config, granterForRole(config, inviterRole), invitedRole);
+
+    if (stillAuthorized) {
+      await next();
+      return;
+    }
+
+    // The grant is dead: burn it rather than leaving it to be retried.
+    await db
+      .update(invitation)
+      .set({ status: "canceled" })
+      .where(and(eq(invitation.id, invitationId), eq(invitation.status, "pending")));
+
+    return c.json(
+      {
+        error: {
+          code: "FORBIDDEN",
+          message:
+            "This invitation is no longer valid: the member who sent it can no longer grant that role.",
+        },
+      },
+      403,
+    );
+  };
+}

package/src/auth/permissions.ts

@@ -1,16 +1,18 @@
 import { CommerceForbiddenError } from "../kernel/errors.js";
 import type { Actor } from "./types.js";
 
-export function assertPermission(actor: Actor | null, required: string): void {
-  if (!actor) {
-    throw new CommerceForbiddenError("Authentication required.");
-  }
-
-  if (actor.permissions.includes("*:*")) return;
+export function hasPermission(actor: Actor | null, required: string): boolean {
+  if (!actor) return false;
+  if (actor.permissions.includes("*:*")) return true;
 
   const [resource] = required.split(":");
-  if (resource && actor.permissions.includes(`${resource}:*`)) return;
-  if (actor.permissions.includes(required)) return;
+  if (resource && actor.permissions.includes(`${resource}:*`)) return true;
+  return actor.permissions.includes(required);
+}
+
+export function assertPermission(actor: Actor | null, required: string): void {
+  if (hasPermission(actor, required)) return;
+  if (!actor) throw new CommerceForbiddenError("Authentication required.");
 
   throw new CommerceForbiddenError(
     `Permission "${required}" is required. Your role "${actor.role}" does not include this permission.`,
@@ -22,7 +24,28 @@ export function assertOwnership(actor: Actor | null, resourceOwnerId: string | n
     throw new CommerceForbiddenError("Authentication required.");
   }
   if (actor.permissions.includes("*:*")) return;
+  if (!actor.userId || !resourceOwnerId) {
+    throw new CommerceForbiddenError("You do not have access to this resource.");
+  }
   if (actor.userId !== resourceOwnerId) {
     throw new CommerceForbiddenError("You do not have access to this resource.");
   }
 }
+
+/**
+ * The actor's user id, for code that keys a per-person resource on it.
+ *
+ * An actor without a user identity — a store resolver, an API key — has no
+ * owner key at all. Passing its absence through as one would make every such
+ * caller look like the same person, so this refuses instead of returning a
+ * value that reads as an identity.
+ */
+export function requireUserId(actor: Pick<Actor, "userId"> | null): string {
+  if (!actor) {
+    throw new CommerceForbiddenError("Authentication required.");
+  }
+  if (!actor.userId) {
+    throw new CommerceForbiddenError("This action requires a signed-in user.");
+  }
+  return actor.userId;
+}