@porulle/core 0.1.0

package/src/adapters/console-email.ts

@@ -0,0 +1,43 @@
+/**
+ * Development email adapter that logs emails to the console.
+ *
+ * Zero dependencies. Use this during local development to see email
+ * content in the terminal without configuring Resend or an SMTP server.
+ *
+ * @example
+ * ```typescript
+ * import { consoleEmailAdapter } from "@porulle/core";
+ *
+ * export default defineConfig({
+ *   email: consoleEmailAdapter(),
+ * });
+ * ```
+ */
+export function consoleEmailAdapter(): {
+  send(input: { template: string; to: string; data?: Record<string, unknown> }): Promise<void>;
+} {
+  return {
+    async send(input) {
+      const divider = "=".repeat(60);
+      const lines = [
+        "",
+        divider,
+        `  EMAIL: ${input.template}`,
+        divider,
+        `  To:       ${input.to}`,
+        `  Template: ${input.template}`,
+      ];
+
+      if (input.data && Object.keys(input.data).length > 0) {
+        lines.push(`  Data:`);
+        for (const [key, value] of Object.entries(input.data)) {
+          lines.push(`    ${key}: ${JSON.stringify(value)}`);
+        }
+      }
+
+      lines.push(divider, "");
+
+      console.log(lines.join("\n"));
+    },
+  };
+}

package/src/auth/access.ts

@@ -0,0 +1,187 @@
+import type { Actor } from "./types.js";
+
+/**
+ * A WhereClause is a plain object representing database filter conditions.
+ * The shape mirrors what services and repositories can accept to narrow queries.
+ *
+ * Example: { customerId: "abc-123" } narrows results to that customer's records.
+ * Composite: { or: [{ customerId: "x" }, { organizationId: "y" }] }
+ */
+export type WhereClause = Record<string, unknown>;
+
+/**
+ * AccessResult: the return value of an access function.
+ *
+ * - `true`: full access, no filter needed
+ * - `false`: no access at all
+ * - `WhereClause`: partial access — the caller should apply this as a query filter
+ */
+export type AccessResult = boolean | WhereClause;
+
+/**
+ * AccessContext carries everything an access function needs to make a decision.
+ *
+ * - `actor`: the authenticated user/api-key/null (anonymous)
+ * - `data`: the document being accessed (for document-level checks)
+ * - `id`: the document ID (when data isn't loaded yet)
+ */
+export interface AccessContext<TData = unknown> {
+  actor: Actor | null;
+  data?: TData;
+  id?: string;
+  req?: Request;
+}
+
+/**
+ * An AccessFn evaluates access for a given context.
+ * Returns boolean (full/no access) or WhereClause (filtered access).
+ */
+export type AccessFn<TData = unknown> = (
+  ctx: AccessContext<TData>,
+) => AccessResult | Promise<AccessResult>;
+
+/**
+ * Combines multiple WhereClause objects with a logical operator.
+ * If there's only one clause, returns it directly (no unnecessary nesting).
+ */
+function combineWhere(
+  queries: WhereClause[],
+  operator: "and" | "or",
+): WhereClause {
+  if (queries.length === 1) return queries[0]!;
+  return { [operator]: queries };
+}
+
+/**
+ * Composes access functions with OR semantics.
+ *
+ * - If ANY function returns `true`, grants full access immediately (short-circuit).
+ * - If one or more return WhereClause, combines them with OR.
+ * - If ALL return `false`, denies access.
+ *
+ * Example:
+ * ```typescript
+ * const orderReadAccess = accessOR(isAdmin, isDocumentOwner("customerId"))
+ * // Admins see all orders; customers see only their own
+ * ```
+ */
+export const accessOR = <TData = unknown>(
+  ...fns: Array<AccessFn<TData>>
+): AccessFn<TData> => {
+  return async (ctx) => {
+    const queries: WhereClause[] = [];
+    for (const fn of fns) {
+      const result = await fn(ctx);
+      if (result === true) return true;
+      if (result && typeof result === "object") queries.push(result);
+    }
+    if (queries.length > 0) return combineWhere(queries, "or");
+    return false;
+  };
+};
+
+/**
+ * Composes access functions with AND semantics.
+ *
+ * - If ANY function returns `false`, denies access immediately (short-circuit).
+ * - If one or more return WhereClause, combines them with AND.
+ * - If ALL return `true`, grants full access.
+ *
+ * Example:
+ * ```typescript
+ * const restrictedAccess = accessAND(isAuthenticated, isDocumentOwner("customerId"))
+ * // Must be logged in AND own the document
+ * ```
+ */
+export const accessAND = <TData = unknown>(
+  ...fns: Array<AccessFn<TData>>
+): AccessFn<TData> => {
+  return async (ctx) => {
+    const queries: WhereClause[] = [];
+    for (const fn of fns) {
+      const result = await fn(ctx);
+      if (result === false) return false;
+      if (result !== true && result && typeof result === "object") {
+        queries.push(result);
+      }
+    }
+    if (queries.length > 0) return combineWhere(queries, "and");
+    return true;
+  };
+};
+
+/**
+ * Switches between two access functions based on a condition.
+ *
+ * Example:
+ * ```typescript
+ * const accessByRole = conditional(
+ *   ({ actor }) => actor?.role === "vendor",
+ *   isDocumentOwner("vendorId"),
+ *   isAdmin,
+ * )
+ * ```
+ */
+export const conditional = <TData = unknown>(
+  condition: ((ctx: AccessContext<TData>) => boolean) | boolean,
+  accessFn: AccessFn<TData>,
+  fallback: AccessFn<TData> = () => false,
+): AccessFn<TData> => {
+  return async (ctx) => {
+    const applies =
+      typeof condition === "function" ? condition(ctx) : condition;
+    return applies ? accessFn(ctx) : fallback(ctx);
+  };
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Built-in access functions
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Grants access if the actor has admin or owner role (wildcard permissions).
+ */
+export const isAdmin: AccessFn = ({ actor }) => {
+  if (!actor) return false;
+  return actor.permissions.includes("*:*");
+};
+
+/**
+ * Grants access if the actor is authenticated (any role).
+ */
+export const isAuthenticated: AccessFn = ({ actor }) => {
+  return actor != null;
+};
+
+/**
+ * Returns a WhereClause that filters to documents owned by the actor.
+ * The ownerField is the column name that holds the owner's user ID.
+ *
+ * For document-level checks (when data is provided), returns true/false.
+ * For list-level checks (when data is not provided), returns a WhereClause.
+ */
+export const isDocumentOwner = (
+  ownerField = "customerId",
+): AccessFn => {
+  return ({ actor, data }) => {
+    if (!actor) return false;
+
+    // Document-level check: compare directly
+    if (data) {
+      return (data as Record<string, unknown>)[ownerField] === actor.userId;
+    }
+
+    // List-level check: return a filter clause
+    return { [ownerField]: actor.userId };
+  };
+};
+
+/**
+ * Grants access to everyone, including anonymous users.
+ */
+export const publicAccess: AccessFn = () => true;
+
+/**
+ * Denies access to everyone.
+ */
+export const denyAll: AccessFn = () => false;

package/src/auth/auth-schema.ts

@@ -0,0 +1,139 @@
+import {
+  pgTable,
+  text,
+  timestamp,
+  boolean,
+  integer,
+} from "drizzle-orm/pg-core";
+
+export const user = pgTable("user", {
+  id: text("id").primaryKey(),
+  name: text("name").notNull(),
+  email: text("email").notNull().unique(),
+  emailVerified: boolean("email_verified").default(false).notNull(),
+  image: text("image"),
+  createdAt: timestamp("created_at").defaultNow().notNull(),
+  updatedAt: timestamp("updated_at")
+    .defaultNow()
+    .$onUpdate(() => /* @__PURE__ */ new Date())
+    .notNull(),
+  vendorId: text("vendor_id"),
+  posOperatorPin: text("pos_operator_pin"),
+});
+
+export const session = pgTable("session", {
+  id: text("id").primaryKey(),
+  expiresAt: timestamp("expires_at").notNull(),
+  token: text("token").notNull().unique(),
+  createdAt: timestamp("created_at").defaultNow().notNull(),
+  updatedAt: timestamp("updated_at")
+    .$onUpdate(() => /* @__PURE__ */ new Date())
+    .notNull(),
+  ipAddress: text("ip_address"),
+  userAgent: text("user_agent"),
+  userId: text("user_id")
+    .notNull()
+    .references(() => user.id, { onDelete: "cascade" }),
+  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 verification = pgTable("verification", {
+  id: text("id").primaryKey(),
+  identifier: text("identifier").notNull(),
+  value: text("value").notNull(),
+  expiresAt: timestamp("expires_at").notNull(),
+  createdAt: timestamp("created_at").defaultNow().notNull(),
+  updatedAt: timestamp("updated_at")
+    .defaultNow()
+    .$onUpdate(() => /* @__PURE__ */ new Date())
+    .notNull(),
+});
+
+export const organization = pgTable("organization", {
+  id: text("id").primaryKey(),
+  name: text("name").notNull(),
+  slug: text("slug").notNull().unique(),
+  logo: text("logo"),
+  createdAt: timestamp("created_at").notNull(),
+  metadata: text("metadata"),
+});
+
+export const member = pgTable("member", {
+  id: text("id").primaryKey(),
+  organizationId: text("organization_id")
+    .notNull()
+    .references(() => organization.id, { onDelete: "cascade" }),
+  userId: text("user_id")
+    .notNull()
+    .references(() => user.id, { onDelete: "cascade" }),
+  role: text("role").default("member").notNull(),
+  createdAt: timestamp("created_at").notNull(),
+});
+
+export const invitation = pgTable("invitation", {
+  id: text("id").primaryKey(),
+  organizationId: text("organization_id")
+    .notNull()
+    .references(() => organization.id, { onDelete: "cascade" }),
+  email: text("email").notNull(),
+  role: text("role"),
+  status: text("status").default("pending").notNull(),
+  expiresAt: timestamp("expires_at").notNull(),
+  createdAt: timestamp("created_at").defaultNow().notNull(),
+  inviterId: text("inviter_id")
+    .notNull()
+    .references(() => user.id, { onDelete: "cascade" }),
+});
+
+export const apikey = pgTable("apikey", {
+  id: text("id").primaryKey(),
+  configId: text("config_id").default("default").notNull(),
+  name: text("name"),
+  start: text("start"),
+  referenceId: text("reference_id").notNull(),
+  prefix: text("prefix"),
+  key: text("key").notNull(),
+  refillInterval: integer("refill_interval"),
+  refillAmount: integer("refill_amount"),
+  lastRefillAt: timestamp("last_refill_at"),
+  enabled: boolean("enabled").default(true),
+  rateLimitEnabled: boolean("rate_limit_enabled").default(false),
+  rateLimitTimeWindow: integer("rate_limit_time_window").default(3600000),
+  rateLimitMax: integer("rate_limit_max").default(10000),
+  requestCount: integer("request_count").default(0),
+  remaining: integer("remaining"),
+  lastRequest: timestamp("last_request"),
+  expiresAt: timestamp("expires_at"),
+  createdAt: timestamp("created_at").notNull(),
+  updatedAt: timestamp("updated_at").notNull(),
+  permissions: text("permissions"),
+  metadata: text("metadata"),
+});
+
+export const jwks = pgTable("jwks", {
+  id: text("id").primaryKey(),
+  publicKey: text("public_key").notNull(),
+  privateKey: text("private_key").notNull(),
+  createdAt: timestamp("created_at").notNull(),
+  expiresAt: timestamp("expires_at"),
+});

package/src/auth/middleware.ts

@@ -0,0 +1,257 @@
+import type { MiddlewareHandler } from "hono";
+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";
+import { isStrictOrgResolution } from "./strict-org-resolution.js";
+
+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];
+}
+
+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,
+): MiddlewareHandler {
+  return async (c, next) => {
+    // Resolve the default org from config, falling back to deprecated constant
+    const defaultOrgId = config.auth?.defaultOrganizationId ?? DEFAULT_ORG_ID;
+
+    // Test-only actor injection: NODE_ENV === "test" honors x-test-actor for
+    // route-level integration tests that bypass the Better Auth session
+    // round-trip. Production/non-test environments ignore this header entirely.
+    if (process.env.NODE_ENV === "test") {
+      const testActorHeader = c.req.header("x-test-actor");
+      if (testActorHeader) {
+        try {
+          const actor = JSON.parse(testActorHeader) as Actor;
+          c.set("actor", actor);
+          await next();
+          return;
+        } catch {
+          // Invalid JSON — continue to real auth resolution.
+        }
+      }
+    }
+
+    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);
+      await next();
+      return;
+    }
+
+    // Extract API key from headers
+    const apiKeyHeader =
+      c.req.header("x-api-key") ??
+      c.req.header("authorization")?.replace("Bearer ", "");
+
+    if (
+      apiKeyHeader &&
+      config.auth?.apiKeys?.enabled &&
+      auth.api.verifyApiKey
+    ) {
+      try {
+        // Better Auth server-side calls require { body: { ... } } wrapper.
+        // Returns { valid, error, key: Omit<ApiKey,"key"> | null }.
+        // See: https://better-auth.com/docs/plugins/api-key/reference
+        const result = await auth.api.verifyApiKey({
+          body: { key: apiKeyHeader },
+        });
+        if (result?.valid && result.key) {
+          const apiKey = result.key as Record<string, unknown>;
+
+          // v1.5+ renamed userId → referenceId on the apikey table.
+          const userId = (apiKey.referenceId ?? "") as string;
+          const name = (apiKey.name ?? "API Key") as string;
+          const orgId = (apiKey.organizationId ?? defaultOrgId) as string;
+
+          // Better Auth stores permissions as Record<string, string[]>
+          // (e.g. {"catalog":["read","create"]}).  Flatten to the
+          // "resource:action" string[] format the engine expects.
+          let permissions: string[];
+          const rawPerms = apiKey.permissions;
+          if (Array.isArray(rawPerms)) {
+            permissions = rawPerms;
+          } else if (rawPerms && typeof rawPerms === "object") {
+            permissions = [];
+            for (const [resource, actions] of Object.entries(
+              rawPerms as Record<string, string[]>,
+            )) {
+              for (const action of actions) {
+                permissions.push(`${resource}:${action}`);
+              }
+            }
+          } else {
+            permissions = config.auth?.apiKeys?.defaultPermissions ?? [];
+          }
+
+          c.set("actor", {
+            type: "api_key",
+            userId,
+            email: null,
+            name,
+            vendorId: null,
+            organizationId: orgId,
+            role: "api_key",
+            permissions,
+          } satisfies Actor);
+          await next();
+          return;
+        }
+      } catch {
+        // invalid, expired, or rate-limited key — fall through
+      }
+    }
+
+    if (!c.get("actor")) {
+      // For anonymous requests in multi-store deployments, resolve the
+      // store so catalog/search queries return the right store's data.
+      if (config.auth?.storeResolver) {
+        try {
+          const resolved = await config.auth.storeResolver(c.req.raw);
+          if (resolved) {
+            // Set a minimal anonymous actor with the resolved org so
+            // services can scope queries correctly.
+            c.set("actor", {
+              type: "user",
+              userId: "anonymous",
+              email: null,
+              name: "Anonymous",
+              vendorId: null,
+              organizationId: resolved,
+              role: "customer",
+              permissions: getCustomerPermissions(config),
+            } satisfies Actor);
+          }
+        } catch (err) {
+          if (isStrictOrgResolution(config)) {
+            const actorCtx = c.get("actor");
+            console.error(
+              { err, actor: actorCtx ?? null, path: c.req.path, method: c.req.method },
+              "storeResolver failed while resolving organization (strict org resolution)",
+            );
+            const message =
+              err instanceof Error ? err.message : String(err);
+            return c.json(
+              {
+                error: {
+                  code: "ORG_RESOLUTION_FAILED",
+                  message:
+                    message || "Organization resolution failed for this request.",
+                },
+              },
+              503,
+            );
+          }
+          const now = Date.now();
+          if (now - lastLegacyStoreResolverWarnAt >= LEGACY_STORE_RESOLVER_WARN_COOLDOWN_MS) {
+            lastLegacyStoreResolverWarnAt = now;
+            console.warn(
+              { err, path: c.req.path, method: c.req.method },
+              "storeResolver failed; continuing without actor (legacy org resolution)",
+            );
+          }
+        }
+      }
+      if (!c.get("actor")) {
+        c.set("actor", null);
+      }
+    }
+    await next();
+  };
+}