@unifiedcommerce/core 0.2.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unifiedcommerce/core",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "type": "module",
   "exports": {
     ".": {
@@ -65,6 +65,7 @@
     "access": "public"
   },
   "files": [
+    "src",
     "dist",
     "README.md"
   ]

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 "@unifiedcommerce/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,161 @@
+import { timingSafeEqual } from "node:crypto";
+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";
+
+function resolvePermissions(
+  session: AuthSessionLike,
+  config: CommerceConfig,
+): string[] {
+  const role = session.session.activeOrganizationRole;
+  if (!role) {
+    return (
+      config.auth?.customerPermissions ?? [
+        "catalog:read",
+        "cart:create",
+        "cart:read",
+        "cart:update",
+        "orders:create",
+        "orders:read:own",
+        "customers:read:self",
+        "customers:update:self",
+      ]
+    );
+  }
+  const roleConfig = config.auth?.roles?.[role];
+  return roleConfig ? roleConfig.permissions : [];
+}
+
+export function authMiddleware(
+  auth: AuthInstance,
+  config: CommerceConfig,
+): MiddlewareHandler {
+  return async (c, next) => {
+    const session = (await auth.api.getSession({
+      headers: c.req.raw.headers,
+    })) as AuthSessionLike | null;
+
+    if (session) {
+      // Better Auth's session only stores activeOrganizationId, not the role.
+      // Resolve role via the organization plugin's server-side API when needed.
+      let role = session.session.activeOrganizationRole as string | undefined;
+      if (!role && session.session.activeOrganizationId && 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
+        }
+      }
+      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: session.session.activeOrganizationId ?? null,
+        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 ?? DEFAULT_ORG_ID) 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
+      }
+    }
+
+    // Config-driven dev key (OFF by default, must be explicitly enabled)
+    if (
+      !c.get("actor") &&
+      apiKeyHeader &&
+      config.auth?.enableDevKey &&
+      config.auth.devKey &&
+      apiKeyHeader.length === config.auth.devKey.length &&
+      timingSafeEqual(Buffer.from(apiKeyHeader), Buffer.from(config.auth.devKey))
+    ) {
+      c.set("actor", {
+        type: "api_key",
+        userId: "dev-staff",
+        email: "dev@local",
+        name: "Dev Admin (dev key)",
+        vendorId: null,
+        organizationId: DEFAULT_ORG_ID,
+        role: "owner",
+        permissions: ["*:*"],
+      } satisfies Actor);
+    }
+
+    if (!c.get("actor")) {
+      c.set("actor", null);
+    }
+    await next();
+  };
+}

package/src/auth/org.ts

@@ -0,0 +1,41 @@
+import { OrganizationService } from "../modules/organization/service.js";
+
+/**
+ * Deterministic ID for the default organization.
+ * Auto-created on kernel boot / test setup for single-tenant deployments.
+ */
+export const DEFAULT_ORG_ID = "org_default";
+
+/**
+ * Extracts the organization ID from an actor.
+ * Falls back to the default org when the actor is null or has no org set.
+ */
+export function resolveOrgId(actor: unknown): string {
+  if (actor != null && typeof actor === "object" && "organizationId" in actor) {
+    const orgId = (actor as { organizationId: unknown }).organizationId;
+    if (typeof orgId === "string") return orgId;
+  }
+  return DEFAULT_ORG_ID;
+}
+
+/**
+ * Ensures the default organization row exists in the database.
+ * Idempotent — safe to call multiple times (no-ops if the row exists).
+ *
+ * Uses OrganizationService which creates both the org row and
+ * (when auth is available) a member record for the creator.
+ *
+ * Accepts `unknown` so callers never need casts — the function
+ * handles the Drizzle type narrowing internally.
+ */
+export async function ensureDefaultOrg(
+  db: unknown,
+  storeName = "Default Store",
+): Promise<void> {
+  const orgService = new OrganizationService(db);
+  await orgService.create({
+    id: DEFAULT_ORG_ID,
+    name: storeName,
+    slug: "default",
+  });
+}

package/src/auth/permissions.ts

@@ -0,0 +1,28 @@
+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;
+
+  const [resource] = required.split(":");
+  if (resource && actor.permissions.includes(`${resource}:*`)) return;
+  if (actor.permissions.includes(required)) return;
+
+  throw new CommerceForbiddenError(
+    `Permission "${required}" is required. Your role "${actor.role}" does not include this permission.`,
+  );
+}
+
+export function assertOwnership(actor: Actor | null, resourceOwnerId: string | null): void {
+  if (!actor) {
+    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.");
+  }
+}