@objectstack/plugin-auth 8.0.1 → 9.0.0

package/README.md

@@ -24,7 +24,7 @@ Authentication & Identity Plugin for ObjectStack.
 - ✅ **Session Management** - Automatic session handling
 - ✅ **Password Reset** - Email-based password reset flow
 - ✅ **Email Verification** - Email verification workflow
-- ✅ **2FA** - Two-factor authentication (when enabled)
+- ⚠️ **2FA backend wiring** - better-auth two-factor plugin can be enabled for custom UIs
 - ✅ **Passkeys** - WebAuthn/Passkey support (when enabled)
 - ✅ **Magic Links** - Passwordless authentication (when enabled)
 - ✅ **Organizations** - Multi-tenant support (when enabled)
@@ -91,7 +91,7 @@ new AuthPlugin({
   baseUrl: 'http://localhost:3000',
   plugins: {
     organization: true,  // Enable organization/teams
-    twoFactor: true,     // Enable 2FA
+    twoFactor: true,     // Enable backend 2FA endpoints for a custom UI
     passkeys: true,      // Enable passkey support
   }
 })
@@ -105,7 +105,7 @@ The plugin accepts configuration via `AuthConfig` schema from `@objectstack/spec
 - `baseUrl` - Base URL for auth routes
 - `databaseUrl` - Database connection string
 - `providers` - Array of OAuth provider configurations
-- `plugins` - Enable additional auth features (organization, 2FA, passkeys, magic link)
+- `plugins` - Enable additional auth features (organization, backend 2FA, passkeys, magic link)
 - `session` - Session configuration (expiry, update frequency)
 
 ## API Routes
@@ -132,9 +132,13 @@ The plugin forwards all requests under `/api/v1/auth/*` directly to better-auth'
 - `GET /api/v1/auth/authorize/[provider]` - Start OAuth flow
 - `GET /api/v1/auth/callback/[provider]` - OAuth callback
 
-### 2FA (when enabled)
-- `POST /api/v1/auth/two-factor/enable` - Enable 2FA
-- `POST /api/v1/auth/two-factor/verify` - Verify 2FA code
+### 2FA backend (when enabled)
+- `POST /api/v1/auth/two-factor/enable` - Start 2FA enrollment
+- `POST /api/v1/auth/two-factor/verify-totp` - Verify a TOTP code
+
+The open-source Console does not yet provide a complete TOTP enrollment,
+login challenge, and backup-code recovery flow. Keep `plugins.twoFactor`
+disabled unless your application UI handles that full flow.
 
 ### Passkeys (when enabled)
 - `POST /api/v1/auth/passkey/register` - Register a passkey
@@ -158,7 +162,7 @@ This package provides authentication services powered by better-auth. Current im
 6. ✅ Direct request forwarding to better-auth handler
 7. ✅ Full better-auth API support
 8. ✅ OAuth providers (configurable)
-9. ✅ 2FA, passkeys, magic links (configurable)
+9. ⚠️ Backend 2FA wiring, passkeys, magic links (configurable; custom UI required for 2FA)
 10. ✅ ObjectQL-based database implementation (no ORM required)
 
 ### Architecture

package/dist/index.d.mts

@@ -85,9 +85,25 @@ declare class AuthPlugin implements Plugin {
     dependencies: string[];
     private options;
     private authManager;
+    private configuredSocialProviders;
     constructor(options?: AuthPluginOptions);
+    /**
+     * Open-source provider fallback: enable Google sign-in from conventional
+     * provider env vars when the application did not configure Google itself.
+     * Enterprise / product packages can contribute richer provider sets through
+     * the `auth:configure` hook below.
+     */
+    private applyEnvSocialProviderFallbacks;
     init(ctx: PluginContext): Promise<void>;
     start(ctx: PluginContext): Promise<void>;
+    /**
+     * Bind the small open-source auth settings namespace to better-auth config.
+     *
+     * Only explicit settings values (stored or OS_AUTH_* env overrides) affect
+     * runtime config. Manifest defaults are UI defaults and do not mask code or
+     * deployment configuration.
+     */
+    private bindAuthSettings;
     destroy(): Promise<void>;
     /**
      * Dev-only admin bootstrap.
@@ -307,6 +323,15 @@ declare class AuthManager {
      * a warning is emitted.
      */
     setRuntimeBaseUrl(url: string): void;
+    /**
+     * Merge runtime configuration into the manager.
+     *
+     * Settings-backed auth policy can change after the manager is constructed.
+     * better-auth itself is created lazily, so changing config before the first
+     * request is enough. If an instance already exists, reset it so the next
+     * request rebuilds with the new policy.
+     */
+    applyConfigPatch(patch: Partial<AuthManagerOptions>): void;
     /**
      * Inject (or replace) the outbound email service used by better-auth
      * callbacks. Safe to call after construction but BEFORE the first
@@ -393,6 +418,7 @@ declare class AuthManager {
             multiOrgEnabled: boolean;
             oidcProvider: boolean;
             deviceAuthorization: boolean;
+            admin: boolean;
         };
     };
     /**

package/dist/index.d.ts

@@ -85,9 +85,25 @@ declare class AuthPlugin implements Plugin {
     dependencies: string[];
     private options;
     private authManager;
+    private configuredSocialProviders;
     constructor(options?: AuthPluginOptions);
+    /**
+     * Open-source provider fallback: enable Google sign-in from conventional
+     * provider env vars when the application did not configure Google itself.
+     * Enterprise / product packages can contribute richer provider sets through
+     * the `auth:configure` hook below.
+     */
+    private applyEnvSocialProviderFallbacks;
     init(ctx: PluginContext): Promise<void>;
     start(ctx: PluginContext): Promise<void>;
+    /**
+     * Bind the small open-source auth settings namespace to better-auth config.
+     *
+     * Only explicit settings values (stored or OS_AUTH_* env overrides) affect
+     * runtime config. Manifest defaults are UI defaults and do not mask code or
+     * deployment configuration.
+     */
+    private bindAuthSettings;
     destroy(): Promise<void>;
     /**
      * Dev-only admin bootstrap.
@@ -307,6 +323,15 @@ declare class AuthManager {
      * a warning is emitted.
      */
     setRuntimeBaseUrl(url: string): void;
+    /**
+     * Merge runtime configuration into the manager.
+     *
+     * Settings-backed auth policy can change after the manager is constructed.
+     * better-auth itself is created lazily, so changing config before the first
+     * request is enough. If an instance already exists, reset it so the next
+     * request rebuilds with the new policy.
+     */
+    applyConfigPatch(patch: Partial<AuthManagerOptions>): void;
     /**
      * Inject (or replace) the outbound email service used by better-auth
      * callbacks. Safe to call after construction but BEFORE the first
@@ -393,6 +418,7 @@ declare class AuthManager {
             multiOrgEnabled: boolean;
             oidcProvider: boolean;
             deviceAuthorization: boolean;
+            admin: boolean;
         };
     };
     /**

package/dist/index.js

@@ -575,6 +575,18 @@ function installWebContainerRequestStatePolyfill() {
     );
   }
 }
+function readBooleanEnv(name, legacyName) {
+  const env = globalThis?.process?.env;
+  const raw = env?.[name] ?? (legacyName ? env?.[legacyName] : void 0);
+  if (raw == null) return void 0;
+  const normalized = String(raw).trim().toLowerCase();
+  return !["0", "false", "off", "no"].includes(normalized);
+}
+function readDisableSignUpEnv() {
+  const signupEnabled = readBooleanEnv("OS_AUTH_SIGNUP_ENABLED");
+  if (signupEnabled != null) return !signupEnabled;
+  return readBooleanEnv("OS_DISABLE_SIGNUP");
+}
 var AuthManager = class {
   constructor(config) {
     this.auth = null;
@@ -658,13 +670,10 @@ var AuthManager = class {
       // Social / OAuth providers
       ...this.config.socialProviders ? { socialProviders: this.config.socialProviders } : {},
       // Email and password configuration.
-      // `disableSignUp`: the env var `OS_DISABLE_SIGNUP=true` overrides
-      // the config-file value so deployments can flip the toggle without
-      // a code change (`getPublicConfig()` applies the same precedence so
-      // `/auth/config` stays consistent with the server enforcement).
+      // `disableSignUp`: env overrides config/settings so deployments can
+      // lock the registration policy without relying on UI state.
       emailAndPassword: (() => {
-        const disableSignUpEnv = globalThis?.process?.env?.OS_DISABLE_SIGNUP;
-        const disableSignUpFromEnv = disableSignUpEnv != null ? String(disableSignUpEnv).toLowerCase() === "true" : void 0;
+        const disableSignUpFromEnv = readDisableSignUpEnv();
         const effectiveDisableSignUp = disableSignUpFromEnv ?? this.config.emailAndPassword?.disableSignUp;
         return {
           enabled: this.config.emailAndPassword?.enabled ?? true,
@@ -879,9 +888,10 @@ var AuthManager = class {
     const plugins = [];
     const oidcEnv = globalThis?.process?.env?.OS_OIDC_PROVIDER_ENABLED;
     const oidcFromEnv = oidcEnv != null ? String(oidcEnv).toLowerCase() === "true" : void 0;
+    const twoFactorFromEnv = readBooleanEnv("OS_AUTH_TWO_FACTOR");
     const enabled = {
       organization: pluginConfig.organization ?? true,
-      twoFactor: pluginConfig.twoFactor ?? false,
+      twoFactor: twoFactorFromEnv ?? pluginConfig.twoFactor ?? false,
       passkeys: pluginConfig.passkeys ?? false,
       magicLink: pluginConfig.magicLink ?? false,
       oidcProvider: oidcFromEnv ?? pluginConfig.oidcProvider ?? false,
@@ -1223,6 +1233,39 @@ var AuthManager = class {
     }
     this.config = { ...this.config, baseUrl: url };
   }
+  /**
+   * Merge runtime configuration into the manager.
+   *
+   * Settings-backed auth policy can change after the manager is constructed.
+   * better-auth itself is created lazily, so changing config before the first
+   * request is enough. If an instance already exists, reset it so the next
+   * request rebuilds with the new policy.
+   */
+  applyConfigPatch(patch) {
+    const next = {
+      ...this.config,
+      ...patch,
+      ...patch.emailAndPassword ? {
+        emailAndPassword: {
+          ...this.config.emailAndPassword ?? {},
+          ...patch.emailAndPassword
+        }
+      } : {},
+      ...patch.plugins ? {
+        plugins: {
+          ...this.config.plugins ?? {},
+          ...patch.plugins
+        }
+      } : {}
+    };
+    if ("socialProviders" in patch) {
+      next.socialProviders = patch.socialProviders;
+    }
+    this.config = next;
+    if (this.auth && !patch.authInstance) {
+      this.auth = null;
+    }
+  }
   /**
    * Inject (or replace) the outbound email service used by better-auth
    * callbacks. Safe to call after construction but BEFORE the first
@@ -1355,8 +1398,7 @@ var AuthManager = class {
       }
     }
     const emailPasswordConfig = this.config.emailAndPassword ?? {};
-    const disableSignUpEnv = globalThis?.process?.env?.OS_DISABLE_SIGNUP;
-    const disableSignUpFromEnv = disableSignUpEnv != null ? String(disableSignUpEnv).toLowerCase() === "true" : void 0;
+    const disableSignUpFromEnv = readDisableSignUpEnv();
     const emailPassword = {
       enabled: emailPasswordConfig.enabled !== false,
       // Default to true
@@ -1381,14 +1423,16 @@ var AuthManager = class {
     const privacyUrl = resolveLegalUrl(rawPrivacyUrl, DEFAULT_PRIVACY_URL);
     const oidcEnv = globalThis?.process?.env?.OS_OIDC_PROVIDER_ENABLED;
     const oidcFromEnv = oidcEnv != null ? String(oidcEnv).toLowerCase() === "true" : void 0;
+    const twoFactorFromEnv = readBooleanEnv("OS_AUTH_TWO_FACTOR");
     const features = {
-      twoFactor: pluginConfig.twoFactor ?? false,
+      twoFactor: twoFactorFromEnv ?? pluginConfig.twoFactor ?? false,
       passkeys: pluginConfig.passkeys ?? false,
       magicLink: pluginConfig.magicLink ?? false,
       organization: pluginConfig.organization ?? true,
       multiOrgEnabled,
       oidcProvider: oidcFromEnv ?? pluginConfig.oidcProvider ?? false,
       deviceAuthorization: pluginConfig.deviceAuthorization ?? false,
+      admin: pluginConfig.admin ?? false,
       ...termsUrl ? { termsUrl } : {},
       ...privacyUrl ? { privacyUrl } : {}
     };
@@ -1488,6 +1532,30 @@ var AuthPlugin = class {
       ...options
     };
   }
+  /**
+   * Open-source provider fallback: enable Google sign-in from conventional
+   * provider env vars when the application did not configure Google itself.
+   * Enterprise / product packages can contribute richer provider sets through
+   * the `auth:configure` hook below.
+   */
+  applyEnvSocialProviderFallbacks(config) {
+    const env = globalThis?.process?.env;
+    if (String(env?.OS_AUTH_GOOGLE_ENABLED ?? "true").toLowerCase() === "false") return;
+    const googleClientId = env?.GOOGLE_CLIENT_ID;
+    const googleClientSecret = env?.GOOGLE_CLIENT_SECRET;
+    if (!googleClientId || !googleClientSecret) return;
+    const socialProviders = {
+      ...config.socialProviders ?? {}
+    };
+    if (!socialProviders.google) {
+      socialProviders.google = {
+        clientId: googleClientId,
+        clientSecret: googleClientSecret,
+        enabled: true
+      };
+      config.socialProviders = socialProviders;
+    }
+  }
   async init(ctx) {
     ctx.logger.info("Initializing Auth Plugin...");
     if (!this.options.secret) {
@@ -1497,10 +1565,14 @@ var AuthPlugin = class {
     if (!dataEngine) {
       ctx.logger.warn("No data engine service found - auth will use in-memory storage");
     }
-    this.authManager = new AuthManager({
+    const authConfig = {
       ...this.options,
       dataEngine
-    });
+    };
+    this.applyEnvSocialProviderFallbacks(authConfig);
+    await ctx.trigger("auth:configure", authConfig, ctx);
+    this.configuredSocialProviders = authConfig.socialProviders ? { ...authConfig.socialProviders } : void 0;
+    this.authManager = new AuthManager(authConfig);
     ctx.registerService("auth", this.authManager);
     ctx.getService("manifest").register({
       ...authPluginManifestHeader,
@@ -1529,7 +1601,9 @@ var AuthPlugin = class {
       // (e.g. legacy `users.view` had phone/status/active columns that do
       // not exist on sys_user). Schema-embedded listViews is the single
       // source of truth.
-      dashboards: [import_apps.SystemOverviewDashboard]
+      dashboards: [import_apps.SystemOverviewDashboard],
+      // ADR-0021 — datasets backing the System Overview dashboard's widgets.
+      datasets: import_apps.SystemOverviewDatasets
     });
     ctx.logger.info("Auth Plugin initialized successfully");
   }
@@ -1541,6 +1615,7 @@ var AuthPlugin = class {
     if (this.options.registerRoutes) {
       ctx.hook("kernel:ready", async () => {
         if (this.authManager) {
+          await this.bindAuthSettings(ctx);
           try {
             const emailSvc = ctx.getService("email");
             if (emailSvc) {
@@ -1627,6 +1702,97 @@ var AuthPlugin = class {
     }
     ctx.logger.info("Auth Plugin started successfully");
   }
+  /**
+   * Bind the small open-source auth settings namespace to better-auth config.
+   *
+   * Only explicit settings values (stored or OS_AUTH_* env overrides) affect
+   * runtime config. Manifest defaults are UI defaults and do not mask code or
+   * deployment configuration.
+   */
+  async bindAuthSettings(ctx) {
+    if (!this.authManager) return;
+    let settings;
+    try {
+      settings = ctx.getService("settings");
+    } catch {
+      return;
+    }
+    if (!settings || typeof settings.getNamespace !== "function") return;
+    const applySettings = async () => {
+      if (!this.authManager) return;
+      try {
+        const payload = await settings.getNamespace("auth");
+        const values = {};
+        const sources = {};
+        for (const [key, entry] of Object.entries(payload.values)) {
+          values[key] = entry?.value;
+          sources[key] = entry?.source;
+        }
+        const isExplicit = (key) => (sources[key] ?? "default") !== "default";
+        const asBoolean = (value, fallback) => {
+          if (typeof value === "boolean") return value;
+          if (typeof value === "string") return value.toLowerCase() !== "false";
+          if (typeof value === "number") return value !== 0;
+          return fallback;
+        };
+        const asTrimmedString = (value) => {
+          if (typeof value !== "string") return void 0;
+          const trimmed = value.trim();
+          return trimmed ? trimmed : void 0;
+        };
+        const patch = {};
+        const emailAndPassword = {};
+        if (isExplicit("email_password_enabled")) {
+          emailAndPassword.enabled = asBoolean(values.email_password_enabled, true);
+        }
+        if (isExplicit("signup_enabled")) {
+          emailAndPassword.disableSignUp = !asBoolean(values.signup_enabled, true);
+        }
+        if (isExplicit("require_email_verification")) {
+          emailAndPassword.requireEmailVerification = asBoolean(
+            values.require_email_verification,
+            false
+          );
+        }
+        if (Object.keys(emailAndPassword).length > 0) {
+          patch.emailAndPassword = emailAndPassword;
+        }
+        if (isExplicit("google_enabled") || isExplicit("google_client_id") || isExplicit("google_client_secret")) {
+          const socialProviders = {
+            ...this.configuredSocialProviders ?? {}
+          };
+          const env = globalThis?.process?.env;
+          const googleEnabledFromEnv = env?.OS_AUTH_GOOGLE_ENABLED != null ? asBoolean(env.OS_AUTH_GOOGLE_ENABLED, true) : void 0;
+          const googleClientId = asTrimmedString(values.google_client_id) ?? env?.GOOGLE_CLIENT_ID;
+          const googleClientSecret = asTrimmedString(values.google_client_secret) ?? env?.GOOGLE_CLIENT_SECRET;
+          if (googleEnabledFromEnv ?? (isExplicit("google_enabled") ? asBoolean(values.google_enabled, true) : true)) {
+            if (!socialProviders.google && googleClientId && googleClientSecret) {
+              socialProviders.google = {
+                clientId: googleClientId,
+                clientSecret: googleClientSecret,
+                enabled: true
+              };
+            }
+          } else {
+            delete socialProviders.google;
+          }
+          patch.socialProviders = Object.keys(socialProviders).length > 0 ? socialProviders : void 0;
+        }
+        if (Object.keys(patch).length > 0) {
+          this.authManager.applyConfigPatch(patch);
+        }
+      } catch (err) {
+        ctx.logger.warn("Auth: failed to apply auth settings: " + (err?.message ?? err));
+      }
+    };
+    await applySettings();
+    if (typeof settings.subscribe === "function") {
+      settings.subscribe("auth", () => {
+        void applySettings();
+      });
+      ctx.logger.info("Auth: bound to settings namespace=auth");
+    }
+  }
   async destroy() {
     this.authManager = null;
   }