@momentumcms/auth 0.0.1

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@momentumcms/auth",
+  "version": "0.0.1",
+  "description": "Better Auth integration for Momentum CMS",
+  "license": "MIT",
+  "author": "Momentum CMS Contributors",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/momentum-cms/momentum-cms.git",
+    "directory": "libs/auth"
+  },
+  "homepage": "https://github.com/momentum-cms/momentum-cms#readme",
+  "bugs": {
+    "url": "https://github.com/momentum-cms/momentum-cms/issues"
+  },
+  "keywords": [
+    "cms",
+    "momentum-cms",
+    "authentication",
+    "better-auth",
+    "auth"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "type": "commonjs",
+  "main": "./index.cjs",
+  "types": "./src/index.d.ts",
+  "peerDependencies": {
+    "@momentumcms/core": ">=0.0.1",
+    "@momentumcms/logger": ">=0.0.1",
+    "better-auth": "^1.4.0",
+    "better-sqlite3": "^12.0.0",
+    "nodemailer": "^8.0.0",
+    "pg": "^8.0.0"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,10 @@
+export * from './lib/auth';
+export * from './lib/email';
+export * from './lib/email-templates';
+export { momentumAuth } from './lib/auth-plugin';
+export type { MomentumAuthPluginConfig, MomentumAuthPlugin, MomentumAuthPluginRuntimeConfig, } from './lib/auth-plugin';
+export { AuthUserCollection, AuthSessionCollection, AuthAccountCollection, AuthVerificationCollection, AuthApiKeysCollection, BASE_AUTH_COLLECTIONS, } from './lib/auth-collections';
+export { authTwoFactor } from './lib/plugins/two-factor';
+export { authAdmin } from './lib/plugins/admin';
+export { authOrganization } from './lib/plugins/organization';
+export type { MomentumAuthSubPlugin } from './lib/plugins/sub-plugin.types';

package/src/lib/auth-collections.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Base Auth Collections for Momentum CMS
+ *
+ * Defines Better Auth tables as Momentum collections.
+ * Visible collections (auth-user, auth-api-keys) are fully interactive in the
+ * admin UI with access restricted to admin role. Internal collections (session,
+ * account, verification) are managed and hidden — Better Auth owns those data
+ * operations.
+ *
+ * Column types are chosen to match Better Auth's expected schema exactly.
+ */
+import type { CollectionConfig, SelectOption } from '@momentumcms/core';
+/**
+ * Canonical list of auth roles, ordered by privilege (highest first).
+ * Used by both server middleware and admin UI for role validation and display.
+ */
+export declare const AUTH_ROLES: SelectOption[];
+export declare const AuthUserCollection: CollectionConfig;
+export declare const AuthSessionCollection: CollectionConfig;
+export declare const AuthAccountCollection: CollectionConfig;
+export declare const AuthVerificationCollection: CollectionConfig;
+export declare const AuthApiKeysCollection: CollectionConfig;
+/**
+ * All base auth collections.
+ * These are injected into the Momentum config by the auth plugin's onInit.
+ */
+export declare const BASE_AUTH_COLLECTIONS: CollectionConfig[];

package/src/lib/auth-plugin.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Momentum Auth Plugin Factory
+ *
+ * Creates a first-class Momentum plugin that manages all Better Auth integration:
+ * - Injects auth collections into the Momentum config (schema generation)
+ * - Creates the Better Auth instance with dynamic plugins/fields
+ * - Exposes getAuth()/tryGetAuth() for server framework middleware creation
+ *
+ * Framework-agnostic: no Express dependency. Middleware creation is handled by
+ * @momentumcms/server-express (initializeMomentum + createDeferredSessionResolver).
+ */
+import type { MomentumPlugin, Field } from '@momentumcms/core';
+import { type MomentumAuth, type DatabaseConfig, type MomentumEmailOptions, type OAuthProvidersConfig } from './auth';
+import type { MomentumAuthSubPlugin } from './plugins/sub-plugin.types';
+/**
+ * Configuration for the Momentum Auth plugin.
+ */
+export interface MomentumAuthPluginConfig {
+    /** Database configuration (same as createMomentumAuth) */
+    db: DatabaseConfig;
+    /** Base URL of the application (e.g., 'http://localhost:4000') */
+    baseURL?: string;
+    /** Secret key for signing tokens */
+    secret?: string;
+    /** Trusted origins for CORS */
+    trustedOrigins?: string[];
+    /** Email configuration */
+    email?: MomentumEmailOptions;
+    /** OAuth social login providers */
+    socialProviders?: OAuthProvidersConfig;
+    /** Auth sub-plugins (2FA, admin, organization, etc.) */
+    plugins?: MomentumAuthSubPlugin[];
+    /** Admin UI configuration */
+    admin?: {
+        /** Show auth collections in admin UI. Default: true */
+        showCollections?: boolean;
+    };
+    /** Extra fields to add to the auth-user collection */
+    userFields?: Field[];
+}
+/**
+ * Config exposed by the auth plugin for the server framework to create middleware.
+ * This avoids the auth library needing to import server-express (circular dep).
+ */
+export interface MomentumAuthPluginRuntimeConfig {
+    db: DatabaseConfig;
+    socialProviders?: OAuthProvidersConfig;
+}
+export interface MomentumAuthPlugin extends MomentumPlugin {
+    /** Get the Better Auth instance (available after onInit). Throws if not yet initialized. */
+    getAuth(): MomentumAuth;
+    /** Get the Better Auth instance if initialized, or null if not yet ready. */
+    tryGetAuth(): MomentumAuth | null;
+    /** Get the plugin's runtime config (db, socialProviders) for server-framework middleware creation. */
+    getPluginConfig(): MomentumAuthPluginRuntimeConfig;
+}
+/**
+ * Creates the Momentum Auth plugin.
+ *
+ * This is the recommended way to integrate Better Auth with Momentum CMS.
+ * Add the returned plugin to your `momentum.config.ts` plugins array.
+ *
+ * @example
+ * ```typescript
+ * import { momentumAuth, authTwoFactor } from '@momentumcms/auth';
+ *
+ * export default defineMomentumConfig({
+ *   plugins: [
+ *     momentumAuth({
+ *       db: { type: 'postgres', pool },
+ *       baseURL: 'http://localhost:4000',
+ *       plugins: [authTwoFactor()],
+ *     }),
+ *   ],
+ *   collections: [Posts],
+ * });
+ * ```
+ */
+export declare function momentumAuth(config: MomentumAuthPluginConfig): MomentumAuthPlugin;

package/src/lib/auth.d.ts

@@ -0,0 +1,144 @@
+import { betterAuth } from 'better-auth';
+import type { Pool } from 'pg';
+import type { Database } from 'better-sqlite3';
+import { type EmailConfig } from './email';
+import type { Field } from '@momentumcms/core';
+/**
+ * Database configuration for Better Auth.
+ * Supports both SQLite (better-sqlite3) and PostgreSQL (pg).
+ */
+export type DatabaseConfig = {
+    type: 'sqlite';
+    database: Database;
+} | {
+    type: 'postgres';
+    pool: Pool;
+};
+/**
+ * Email configuration options for Momentum Auth.
+ */
+export interface MomentumEmailOptions extends EmailConfig {
+    /** Enable email features (password reset, verification). Default: auto-detect from SMTP_HOST env var */
+    enabled?: boolean;
+    /** Application name shown in emails. Default: 'Momentum CMS' */
+    appName?: string;
+    /** Require email verification on signup. Default: false */
+    requireEmailVerification?: boolean;
+}
+/**
+ * OAuth provider configuration.
+ */
+export interface OAuthProviderConfig {
+    clientId: string;
+    clientSecret: string;
+    redirectURI?: string;
+}
+/**
+ * Supported OAuth providers.
+ */
+export interface OAuthProvidersConfig {
+    google?: OAuthProviderConfig;
+    github?: OAuthProviderConfig;
+}
+/**
+ * Configuration options for Momentum Auth.
+ */
+export interface MomentumAuthConfig {
+    /** Database configuration - supports SQLite or PostgreSQL */
+    db: DatabaseConfig;
+    /** Base URL of the application (e.g., 'http://localhost:4000') */
+    baseURL?: string;
+    /** Secret key for signing tokens. Use env var AUTH_SECRET in production. */
+    secret?: string;
+    /** Trusted origins for CORS */
+    trustedOrigins?: string[];
+    /** Email configuration for password reset and verification */
+    email?: MomentumEmailOptions;
+    /** OAuth social login providers */
+    socialProviders?: OAuthProvidersConfig;
+    /** Enable two-factor authentication (TOTP). Default: false */
+    twoFactorAuth?: boolean;
+    /** Additional Better Auth plugins (from sub-plugins). */
+    plugins?: unknown[];
+    /** Extra user fields to register with Better Auth's user.additionalFields. */
+    userFields?: Field[];
+}
+/**
+ * Legacy configuration for SQLite (backwards compatibility).
+ */
+export interface MomentumAuthConfigLegacy {
+    /** The better-sqlite3 database instance (deprecated, use db instead) */
+    database: Database;
+    /** Base URL of the application (e.g., 'http://localhost:4000') */
+    baseURL?: string;
+    /** Secret key for signing tokens. Use env var AUTH_SECRET in production. */
+    secret?: string;
+    /** Trusted origins for CORS */
+    trustedOrigins?: string[];
+    /** Email configuration for password reset and verification */
+    email?: MomentumEmailOptions;
+    /** OAuth social login providers */
+    socialProviders?: OAuthProvidersConfig;
+    /** Enable two-factor authentication (TOTP). Default: false */
+    twoFactorAuth?: boolean;
+}
+/**
+ * User type from Better Auth with additional role field.
+ */
+export interface MomentumUser {
+    id: string;
+    email: string;
+    name: string;
+    role: string;
+    emailVerified: boolean;
+    twoFactorEnabled?: boolean;
+    image?: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * Session type from Better Auth.
+ */
+export interface MomentumSession {
+    id: string;
+    userId: string;
+    token: string;
+    expiresAt: Date;
+    ipAddress?: string | null;
+    userAgent?: string | null;
+}
+/**
+ * Get the list of enabled OAuth provider names from config/env vars.
+ * Useful for exposing available providers to the client.
+ */
+export declare function getEnabledOAuthProviders(config?: OAuthProvidersConfig): string[];
+/**
+ * Creates a Momentum Auth instance using Better Auth.
+ *
+ * @example
+ * ```typescript
+ * import { createMomentumAuth } from '@momentumcms/auth';
+ *
+ * // With PostgreSQL
+ * const auth = createMomentumAuth({
+ *   db: { type: 'postgres', pool: pgPool },
+ *   baseURL: 'http://localhost:4000',
+ *   secret: process.env.AUTH_SECRET,
+ * });
+ *
+ * // With SQLite (legacy)
+ * const auth = createMomentumAuth({
+ *   database: sqliteDb,
+ *   baseURL: 'http://localhost:4000',
+ *   secret: process.env.AUTH_SECRET,
+ * });
+ *
+ * // Use in Express
+ * app.all('/api/auth/*', toNodeHandler(auth));
+ * ```
+ */
+export declare function createMomentumAuth(config: MomentumAuthConfig | MomentumAuthConfigLegacy): ReturnType<typeof betterAuth>;
+/**
+ * Type for the Momentum Auth instance.
+ */
+export type MomentumAuth = ReturnType<typeof createMomentumAuth>;

package/src/lib/email-templates.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Email template options.
+ */
+interface EmailTemplateOptions {
+    /** Recipient's name */
+    name?: string;
+    /** Action URL (reset link, verification link, etc.) */
+    url: string;
+    /** Application name (default: 'Momentum CMS') */
+    appName?: string;
+    /** Expiration time for the link (e.g., '1 hour') */
+    expiresIn?: string;
+}
+/**
+ * Generate password reset email content.
+ *
+ * @example
+ * ```typescript
+ * const { subject, text, html } = getPasswordResetEmail({
+ *   name: 'John',
+ *   url: 'https://example.com/admin/reset-password?token=abc123',
+ *   expiresIn: '1 hour',
+ * });
+ * ```
+ */
+export declare function getPasswordResetEmail(options: EmailTemplateOptions): {
+    subject: string;
+    text: string;
+    html: string;
+};
+/**
+ * Generate email verification email content.
+ *
+ * @example
+ * ```typescript
+ * const { subject, text, html } = getVerificationEmail({
+ *   name: 'John',
+ *   url: 'https://example.com/admin/verify-email?token=abc123',
+ *   expiresIn: '24 hours',
+ * });
+ * ```
+ */
+export declare function getVerificationEmail(options: EmailTemplateOptions): {
+    subject: string;
+    text: string;
+    html: string;
+};
+export {};

package/src/lib/email.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Email configuration options.
+ */
+export interface EmailConfig {
+    /** SMTP server hostname (default: localhost) */
+    host?: string;
+    /** SMTP server port (default: 1025 for Mailpit) */
+    port?: number;
+    /** Sender email address */
+    from?: string;
+    /** Use TLS/SSL (default: false for local dev) */
+    secure?: boolean;
+    /** SMTP authentication credentials */
+    auth?: {
+        user: string;
+        pass: string;
+    };
+}
+/**
+ * Options for sending an email.
+ */
+export interface SendEmailOptions {
+    /** Recipient email address */
+    to: string;
+    /** Email subject line */
+    subject: string;
+    /** Plain text body */
+    text: string;
+    /** HTML body (optional) */
+    html?: string;
+}
+/**
+ * Email service for sending transactional emails.
+ */
+export interface EmailService {
+    /**
+     * Send an email.
+     * @param options Email options (to, subject, text, html)
+     */
+    sendEmail(options: SendEmailOptions): Promise<void>;
+}
+/**
+ * Create an email service with SMTP transport.
+ *
+ * Configuration is merged in order of priority:
+ * 1. Explicit config passed to this function
+ * 2. Environment variables (SMTP_HOST, SMTP_PORT, etc.)
+ * 3. Default values (Mailpit on localhost:1025)
+ *
+ * @example
+ * ```typescript
+ * // Use environment variables or defaults
+ * const emailService = createEmailService();
+ *
+ * // Or provide explicit config
+ * const emailService = createEmailService({
+ *   host: 'smtp.example.com',
+ *   port: 587,
+ *   secure: true,
+ *   auth: { user: 'apikey', pass: 'your-api-key' },
+ *   from: 'noreply@example.com',
+ * });
+ *
+ * await emailService.sendEmail({
+ *   to: 'user@example.com',
+ *   subject: 'Password Reset',
+ *   text: 'Click here to reset your password...',
+ *   html: '<p>Click <a href="...">here</a> to reset your password.</p>',
+ * });
+ * ```
+ */
+export declare function createEmailService(config?: EmailConfig): EmailService;

package/src/lib/plugins/admin.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Admin Sub-Plugin (Stub)
+ *
+ * Wraps Better Auth's admin plugin for user management capabilities:
+ * - Ban/unban users
+ * - Impersonate users
+ * - Admin-level session fields
+ *
+ * This is a stub — the Better Auth admin plugin import will be added
+ * when the full admin integration is implemented.
+ */
+import type { MomentumAuthSubPlugin } from './sub-plugin.types';
+/**
+ * Creates the admin sub-plugin.
+ *
+ * Adds ban/impersonation fields to the user and session collections.
+ * The actual Better Auth admin plugin will be wired in a future iteration.
+ */
+export declare function authAdmin(): MomentumAuthSubPlugin;

package/src/lib/plugins/index.d.ts

@@ -0,0 +1,4 @@
+export * from './sub-plugin.types';
+export { authTwoFactor } from './two-factor';
+export { authAdmin } from './admin';
+export { authOrganization } from './organization';

package/src/lib/plugins/organization.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Organization Sub-Plugin (Stub)
+ *
+ * Wraps Better Auth's organization plugin for multi-tenant capabilities:
+ * - Organizations
+ * - Members with roles
+ * - Invitations
+ *
+ * This is a stub — the Better Auth organization plugin import will be added
+ * when the full organization integration is implemented.
+ */
+import type { MomentumAuthSubPlugin } from './sub-plugin.types';
+/**
+ * Creates the organization sub-plugin.
+ *
+ * Adds organization, member, and invitation collections.
+ * The actual Better Auth organization plugin will be wired in a future iteration.
+ */
+export declare function authOrganization(): MomentumAuthSubPlugin;

package/src/lib/plugins/sub-plugin.types.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Sub-Plugin Types for Momentum Auth
+ *
+ * Each sub-plugin wraps a Better Auth plugin and brings its own
+ * collections, user/session fields, and admin routes.
+ */
+import type { CollectionConfig, Field } from '@momentumcms/core';
+import type { PluginAdminRouteDescriptor } from '@momentumcms/core';
+/**
+ * A Momentum Auth sub-plugin wraps a Better Auth plugin.
+ *
+ * It declares what schema changes and admin UI additions the
+ * Better Auth plugin requires, allowing the auth plugin factory
+ * to merge everything together.
+ */
+export interface MomentumAuthSubPlugin {
+    /** Human-readable name (for logging / admin UI). */
+    name: string;
+    /** The Better Auth plugin instance to be spread into betterAuth({ plugins: [...] }). */
+    betterAuthPlugin: unknown;
+    /** Additional managed collections this plugin needs. */
+    collections?: CollectionConfig[];
+    /** Extra fields to add to the auth-user collection. */
+    userFields?: Field[];
+    /** Extra fields to add to the auth-session collection. */
+    sessionFields?: Field[];
+    /** Admin routes contributed by this plugin. */
+    adminRoutes?: PluginAdminRouteDescriptor[];
+}

package/src/lib/plugins/two-factor.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Two-Factor Authentication Sub-Plugin
+ *
+ * Wraps Better Auth's twoFactor plugin and provides:
+ * - A `twoFactor` managed collection (stores TOTP secrets and backup codes)
+ * - A `twoFactorEnabled` field on the auth-user collection
+ */
+import type { MomentumAuthSubPlugin } from './sub-plugin.types';
+/**
+ * Creates the two-factor authentication sub-plugin.
+ */
+export declare function authTwoFactor(): MomentumAuthSubPlugin;