@porulle/core 0.1.0

package/src/auth/org.ts

@@ -0,0 +1,83 @@
+import type { CommerceConfig } from "../config/types.js";
+import { OrgResolutionError } from "../kernel/errors.js";
+import { OrganizationService } from "../modules/organization/service.js";
+import { isStrictOrgResolution } from "./strict-org-resolution.js";
+
+const LEGACY_ORG_DEFAULT_WARN_COOLDOWN_MS = 60_000;
+let lastLegacyOrgDefaultWarnAt = 0;
+
+function warnDeprecatedOrgDefaultFallback(): void {
+  const now = Date.now();
+  if (now - lastLegacyOrgDefaultWarnAt < LEGACY_ORG_DEFAULT_WARN_COOLDOWN_MS) return;
+  lastLegacyOrgDefaultWarnAt = now;
+  console.warn(
+    "resolveOrgId fell back to deprecated DEFAULT_ORG_ID (org_default); set auth.defaultOrganizationId, pass defaultOrgId, or ensure the actor has organizationId.",
+  );
+}
+
+/**
+ * @deprecated Will be removed. Use `config.auth.defaultOrganizationId` instead.
+ * Kept only for test utilities and backwards compatibility.
+ */
+export const DEFAULT_ORG_ID = "org_default";
+
+/**
+ * Module-level default set once at boot by `setBootDefaultOrgId()`.
+ * Allows resolveOrgId to use the config value without requiring
+ * every service caller to pass it explicitly.
+ */
+let _bootDefaultOrgId: string | undefined;
+
+/**
+ * Called once at boot by createCommerce/createServer to register
+ * the config-driven default org ID. This bridges the gap between
+ * config (available at boot) and services (which don't have config access).
+ */
+export function setBootDefaultOrgId(orgId: string): void {
+  _bootDefaultOrgId = orgId;
+}
+
+/**
+ * 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)
+ */
+export function resolveOrgId(
+  actor: unknown,
+  defaultOrgId?: string,
+  commerceConfig?: CommerceConfig,
+): string {
+  if (actor != null && typeof actor === "object" && "organizationId" in actor) {
+    const orgId = (actor as { organizationId: unknown }).organizationId;
+    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.",
+    );
+  }
+  warnDeprecatedOrgDefaultFallback();
+  return DEFAULT_ORG_ID;
+}
+
+/**
+ * @deprecated Use seed script with `auth.api.createOrganization()` instead.
+ * Kept for backwards compatibility during migration. Will be removed.
+ */
+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.");
+  }
+}

package/src/auth/setup.ts

@@ -0,0 +1,187 @@
+import { drizzleAdapter } from "@better-auth/drizzle-adapter";
+import { betterAuth } from "better-auth";
+import type { Role } from "better-auth/plugins/access";
+import { apiKey } from "@better-auth/api-key";
+import { organization, twoFactor, phoneNumber, jwt, bearer } from "better-auth/plugins";
+import type { CommerceConfig } from "../config/types.js";
+import type { DatabaseAdapter } from "../kernel/database/adapter.js";
+import * as authSchema from "./auth-schema.js";
+
+type BetterAuthDbProvider = "pg" | "mysql" | "sqlite";
+
+function resolveAuthDbProvider(provider: string): BetterAuthDbProvider {
+  if (provider === "postgres" || provider === "postgresql" || provider === "pg") return "pg";
+  if (provider === "mysql") return "mysql";
+  if (provider === "sqlite") return "sqlite";
+  throw new Error(`Unsupported auth database provider "${provider}".`);
+}
+
+interface AuthEmailPayload {
+  user: { email: string; name: string | null };
+  url: string;
+}
+
+/**
+ * The auth type is inferred from `typeof betterAuth(...)` with all plugins enabled.
+ * This gives us the full API surface without manual interface maintenance.
+ *
+ * We use a type-level-only reference (never executed) to capture the complete type.
+ */
+type FullBetterAuth = ReturnType<typeof betterAuth<{
+  plugins: [
+    ReturnType<typeof organization>,
+    ReturnType<typeof bearer>,
+    ReturnType<typeof jwt>,
+    ReturnType<typeof twoFactor>,
+    ReturnType<typeof apiKey>,
+    ReturnType<typeof phoneNumber>,
+  ];
+}>>;
+
+/**
+ * AuthInstance — inferred from Better Auth with all plugins.
+ * No manual type maintenance needed.
+ */
+export type AuthInstance = FullBetterAuth;
+
+export function createAuth(
+  db: DatabaseAdapter,
+  config: CommerceConfig,
+): AuthInstance {
+  if (
+    process.env.NODE_ENV === "production" &&
+    config.auth?.requireEmailVerification === false
+  ) {
+    console.warn(
+      "auth.requireEmailVerification is FALSE in production — anyone can sign up with any email and access the account immediately. Set to true and configure config.email.send for production storefronts.",
+    );
+  }
+
+  const plugins: Array<
+    | ReturnType<typeof organization>
+    | ReturnType<typeof twoFactor>
+    | ReturnType<typeof apiKey>
+    | ReturnType<typeof phoneNumber>
+    | ReturnType<typeof jwt>
+    | ReturnType<typeof bearer>
+  > = [
+    organization({
+      roles: (config.auth?.roles ?? {}) as unknown as Record<string, Role | undefined>,
+    }),
+    bearer(),
+    jwt(),
+  ];
+
+  if (config.auth?.twoFactor?.enabled) {
+    plugins.push(twoFactor({ issuer: config.storeName ?? "UnifiedCommerce" }));
+  }
+
+  const scopes = config.auth?.apiKeyScopes;
+  if (scopes && Object.keys(scopes).length > 0) {
+    const apiKeyConfigs = Object.entries(scopes).map(([scopeId, scope]) => ({
+      configId: scopeId,
+      defaultPrefix: scope.prefix,
+      ...(scope.rateLimit
+        ? {
+            rateLimit: {
+              enabled: true,
+              maxRequests: scope.rateLimit.maxRequests,
+              timeWindow: scope.rateLimit.timeWindow,
+            },
+          }
+        : {}),
+    }));
+    plugins.push(apiKey(apiKeyConfigs));
+  } else if (config.auth?.apiKeys?.enabled) {
+    plugins.push(apiKey());
+  }
+
+  if (config.auth?.phoneAuth) {
+    plugins.push(phoneNumber({
+      sendOTP: config.auth.phoneAuth.sendOTP,
+      verifyOTP: config.auth.phoneAuth.verifyOTP,
+      otpLength: config.auth.phoneAuth.otpLength ?? 6,
+      expiresIn: config.auth.phoneAuth.expiresIn ?? 300,
+      signUpOnVerification: config.auth.phoneAuth.signUpOnVerification ?? {
+        getTempEmail: (phone: string) => `${phone.replace(/\+/g, "")}@phone.local`,
+      },
+    }));
+  }
+
+  // Inject extra Better Auth plugins from config (e.g., @better-auth/expo)
+  if (config.auth?.extraAuthPlugins?.length) {
+    plugins.push(...(config.auth.extraAuthPlugins as typeof plugins[number][]));
+  }
+
+  try {
+    const auth = betterAuth({
+      database: drizzleAdapter(db.db as unknown as Record<string, unknown>, {
+        provider: resolveAuthDbProvider(db.provider),
+        schema: authSchema,
+      }),
+      // Customer profile creation is handled lazily by CustomerService.getByUserId()
+      // which calls getOrCreateByUserId() on first access (checkout, /api/me/profile).
+      // No databaseHook needed — admins/staff who sign up don't need customer profiles.
+      trustedOrigins: config.auth?.trustedOrigins ?? [],
+      emailAndPassword: {
+        enabled: true,
+        requireEmailVerification: config.auth?.requireEmailVerification ?? true,
+        sendResetPassword: async ({ user, url }: AuthEmailPayload) => {
+          if (!config.email) return;
+          await config.email.send({
+            template: "password-reset",
+            to: user.email,
+            data: { resetUrl: url, userName: user.name },
+          });
+        },
+        sendVerificationEmail: async ({ user, url }: AuthEmailPayload) => {
+          if (!config.email) return;
+          await config.email.send({
+            template: "email-verification",
+            to: user.email,
+            data: { verifyUrl: url, userName: user.name },
+          });
+        },
+      },
+      socialProviders: config.auth?.socialProviders ?? {},
+      session: {
+        expiresIn: config.auth?.sessionDuration ?? 60 * 60 * 24 * 7,
+        updateAge: 60 * 60 * 24,
+        cookieCache: {
+          enabled: true,
+          maxAge: 60 * 5,
+        },
+      },
+      advanced: {
+        cookiePrefix: "uc",
+        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
+        // is required for predictable cross-browser behavior and to satisfy
+        // PCI-DSS 4.0.1 cookie hygiene. Lax is the right default for a
+        // commerce session: blocks CSRF on POST/PUT/DELETE while still
+        // allowing top-level GET navigation (needed for OAuth redirects).
+        defaultCookieAttributes: {
+          sameSite: "lax",
+        },
+      },
+      plugins,
+      user: {
+        additionalFields: {
+          vendorId: { type: "string", required: false },
+          posOperatorPin: { type: "string", required: false },
+        },
+      },
+    });
+
+    // The runtime return matches FullBetterAuth structurally — plugins may differ
+    // at runtime (conditional) but the API surface is a superset.
+    return auth as unknown as AuthInstance;
+  } catch (error) {
+    const message =
+      error instanceof Error
+        ? error.message
+        : "Unknown better-auth initialization error.";
+    throw new Error(`Failed to initialize authentication: ${message}`);
+  }
+}

package/src/auth/strict-org-resolution.ts

@@ -0,0 +1,14 @@
+import type { CommerceConfig } from "../config/types.js";
+
+let _bootStrictOrgResolution = false;
+
+export function setBootStrictOrgResolution(strict: boolean): void {
+  _bootStrictOrgResolution = strict;
+}
+
+export function isStrictOrgResolution(config?: CommerceConfig | null): boolean {
+  if (config?.auth?.strictOrgResolution === true) return true;
+  if (process.env.STRICT_ORG_RESOLUTION === "true") return true;
+  if ((config === undefined || config === null) && _bootStrictOrgResolution) return true;
+  return false;
+}

package/src/auth/system-actor.ts

@@ -0,0 +1,19 @@
+import type { Actor } from "./types.js";
+import { DEFAULT_ORG_ID } from "./org.js";
+
+/**
+ * Creates a system actor for internal operations (webhooks, jobs, compensation chains).
+ * System actors have full permissions and are scoped to a specific organization.
+ */
+export function createSystemActor(orgId: string = DEFAULT_ORG_ID): Actor {
+  return {
+    type: "api_key",
+    userId: "system:internal",
+    email: null,
+    name: "System",
+    vendorId: null,
+    organizationId: orgId,
+    role: "system",
+    permissions: ["*:*"],
+  };
+}

package/src/auth/types.ts

@@ -0,0 +1,10 @@
+export interface Actor {
+  type: "user" | "api_key";
+  userId: string;
+  email: string | null;
+  name: string;
+  vendorId: string | null;
+  organizationId: string | null;
+  role: string;
+  permissions: string[];
+}

package/src/config/defaults.ts

@@ -0,0 +1,85 @@
+import type { CommerceConfig } from "./types.js";
+
+export const defaultConfig: Partial<CommerceConfig> = {
+  version: "0.0.1",
+  auth: {
+    requireEmailVerification: true,
+    sessionDuration: 60 * 60 * 24 * 7,
+    twoFactor: { enabled: false },
+    apiKeys: { enabled: false },
+    posPin: { enabled: false },
+    apiKeyScopes: {
+      compensation_admin: {
+        prefix: "uc_cfadm_",
+        description: "List and resolve compensation step failures",
+        permissions: { compensation: ["admin"] },
+      },
+    },
+    roles: {
+      owner: { permissions: ["*:*"] },
+      admin: { permissions: ["*:*", "compensation:admin"] },
+      manager: {
+        permissions: [
+          "catalog:create",
+          "catalog:update",
+          "catalog:delete",
+          "catalog:read",
+          "inventory:read",
+          "inventory:adjust",
+          "orders:read",
+          "orders:update",
+          "cart:create",
+          "cart:update",
+          "customers:read:self",
+          "customers:update:self",
+        ],
+      },
+      customer: {
+        permissions: [
+          "catalog:read",
+          "cart:create",
+          "cart:read",
+          "cart:update",
+          "orders:create",
+          "orders:read:own",
+          "customers:read:self",
+          "customers:update:self",
+        ],
+      },
+    },
+    customerPermissions: [
+      "catalog:read",
+      "cart:create",
+      "cart:read",
+      "cart:update",
+      "orders:create",
+      "orders:read:own",
+      "customers:read:self",
+      "customers:update:self",
+    ],
+  },
+  cart: {
+    ttlMinutes: 60 * 24 * 7,
+    hooks: {},
+  },
+  checkout: {
+    hooks: {
+      beforeCreate: [],
+      afterCreate: [],
+    },
+  },
+  orders: {
+    hooks: {
+      beforeCreate: [],
+      afterCreate: [],
+      beforeStatusChange: [],
+      afterStatusChange: [],
+      beforeDelete: [],
+    },
+  },
+  inventory: {
+    hooks: {
+      afterAdjust: [],
+    },
+  },
+};

package/src/config/define-config.ts

@@ -0,0 +1,81 @@
+import { defaultConfig } from "./defaults.js";
+import type { CommerceConfig, DefineConfigInput } from "./types.js";
+import type { TaskDefinition } from "../kernel/jobs/types.js";
+import { defaultKernelJobTasks } from "../kernel/jobs/builtin-job-tasks.js";
+import { _resetRegisteredPlugins } from "../kernel/plugin/manifest.js";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function mergeBuiltinJobTasks(
+  jobs: CommerceConfig["jobs"] | undefined,
+): NonNullable<CommerceConfig["jobs"]> {
+  const userTasks = jobs?.tasks ?? [];
+  const bySlug = new Map<string, TaskDefinition>();
+  for (const t of defaultKernelJobTasks) {
+    bySlug.set(t.slug, t);
+  }
+  for (const t of userTasks) {
+    bySlug.set(t.slug, t);
+  }
+  return {
+    ...(jobs ?? {}),
+    tasks: Array.from(bySlug.values()) as TaskDefinition<
+      Record<string, unknown>,
+      Record<string, unknown>
+    >[],
+  };
+}
+
+function merge<T extends object>(base: T, next: Partial<T>): T {
+  const output: Record<string, unknown> = {
+    ...(base as Record<string, unknown>),
+  };
+  for (const [key, value] of Object.entries(next as Record<string, unknown>)) {
+    if (value === undefined) continue;
+    const baseValue = output[key];
+    if (
+      isRecord(value) &&
+      isRecord(baseValue)
+    ) {
+      output[key] = merge(baseValue, value);
+    } else {
+      output[key] = value;
+    }
+  }
+  return output as T;
+}
+
+/**
+ * Builds the final CommerceConfig by:
+ * 1. Merging user input with defaults
+ * 2. Applying all plugins (each is a config transform function)
+ * 3. Merging built-in job task definitions (user tasks override by slug)
+ * 4. Freezing the result to prevent runtime mutation
+ */
+export async function defineConfig(
+  input: DefineConfigInput,
+): Promise<CommerceConfig> {
+  let config = merge(defaultConfig as CommerceConfig, input);
+
+  // Merge top-level `schema` into `customSchemas` before plugins run
+  if (config.schema?.length) {
+    config = {
+      ...config,
+      customSchemas: [...(config.customSchemas ?? []), ...config.schema],
+    };
+  }
+
+  _resetRegisteredPlugins();
+  for (const plugin of config.plugins ?? []) {
+    config = await plugin(config);
+  }
+
+  config = {
+    ...config,
+    jobs: mergeBuiltinJobTasks(config.jobs),
+  };
+
+  return Object.freeze(config);
+}