chadstart 1.0.1 → 1.0.2

package/.env.example

@@ -53,3 +53,23 @@ TOKEN_SECRET_KEY=replace-with-a-long-random-secret
 # 💡 Bugsink (https://www.bugsink.com) is a self-hosted alternative to Sentry
 #    that uses the same Sentry SDK — just point SENTRY_DSN at your Bugsink instance.
 # SENTRY_DSN=https://xxxxx@oXXXXX.ingest.sentry.io/XXXXXXX
+
+# Optional: OAuth / Social Login (powered by grant)
+# For each provider, set OAUTH_<PROVIDER>_KEY and OAUTH_<PROVIDER>_SECRET.
+# Provider names must be uppercase (e.g. GOOGLE, GITHUB, FACEBOOK).
+# See docs/oauth.md for the full list of 200+ supported providers.
+#
+# OAUTH_GOOGLE_KEY=your-google-client-id
+# OAUTH_GOOGLE_SECRET=your-google-client-secret
+# OAUTH_GITHUB_KEY=your-github-client-id
+# OAUTH_GITHUB_SECRET=your-github-client-secret
+# OAUTH_FACEBOOK_KEY=your-facebook-app-id
+# OAUTH_FACEBOOK_SECRET=your-facebook-app-secret
+# OAUTH_DISCORD_KEY=your-discord-client-id
+# OAUTH_DISCORD_SECRET=your-discord-client-secret
+# OAUTH_APPLE_KEY=your-apple-client-id
+# OAUTH_APPLE_SECRET=your-apple-client-secret
+# OAUTH_MICROSOFT_KEY=your-microsoft-client-id
+# OAUTH_MICROSOFT_SECRET=your-microsoft-client-secret
+# OAUTH_TWITTER_KEY=your-twitter-api-key
+# OAUTH_TWITTER_SECRET=your-twitter-api-secret

package/chadstart.example.yml

@@ -414,3 +414,55 @@ sentry:
   environment: production     # Label sent to Sentry. Defaults to NODE_ENV.
   tracesSampleRate: 1.0       # Fraction of transactions to sample (0.0–1.0)
   debug: false                # Enable Sentry SDK debug logging
+
+# ── OAuth / Social Login ─────────────────────────────────────────────────────
+# Powered by the "grant" library — supports 200+ OAuth providers.
+# Secrets (client keys / secrets) MUST be set via environment variables:
+#   OAUTH_<PROVIDER>_KEY    — client / app ID
+#   OAUTH_<PROVIDER>_SECRET — client / app secret
+# See docs/oauth.md for the full provider list and setup guides.
+
+oauth:
+  # Which authenticable entity to create/find users in (default: first authenticable entity).
+  entity: User
+
+  # Where to redirect after successful login. The JWT token is appended as ?token=...
+  # If omitted, the callback returns JSON instead.
+  successRedirect: /login?success=true
+
+  # Where to redirect on error. The error message is appended as ?error=...
+  errorRedirect: /login?error=true
+
+  # Default settings applied to all providers.
+  defaults:
+    transport: querystring
+
+  # Configure each provider you want to support.
+  # The provider names must match grant's provider names (lowercase).
+  # Full list: https://github.com/simov/grant#200-supported-providers
+  providers:
+    google:
+      scope:
+        - openid
+        - email
+        - profile
+      custom_params:
+        access_type: offline
+      # key and secret via: OAUTH_GOOGLE_KEY, OAUTH_GOOGLE_SECRET
+
+    github:
+      scope:
+        - user:email
+      # key and secret via: OAUTH_GITHUB_KEY, OAUTH_GITHUB_SECRET
+
+    # facebook:
+    #   scope:
+    #     - email
+    #     - public_profile
+    #   key and secret via: OAUTH_FACEBOOK_KEY, OAUTH_FACEBOOK_SECRET
+
+    # discord:
+    #   scope:
+    #     - identify
+    #     - email
+    #   key and secret via: OAUTH_DISCORD_KEY, OAUTH_DISCORD_SECRET

package/chadstart.schema.json

@@ -124,6 +124,43 @@
           "description": "Enable Sentry SDK debug logging."
         }
       }
+    },
+    "oauth": {
+      "type": "object",
+      "description": "OAuth / social login configuration powered by the grant library. Secrets (client keys and secrets) must be supplied via OAUTH_<PROVIDER>_KEY and OAUTH_<PROVIDER>_SECRET environment variables.",
+      "additionalProperties": false,
+      "properties": {
+        "entity": {
+          "type": "string",
+          "description": "Name of the authenticable entity to use for OAuth users (e.g. 'User'). Defaults to the first authenticable entity."
+        },
+        "successRedirect": {
+          "type": "string",
+          "description": "URL to redirect to after successful OAuth login. The JWT token is appended as a ?token= query parameter. If omitted, returns JSON."
+        },
+        "errorRedirect": {
+          "type": "string",
+          "description": "URL to redirect to on OAuth error. The error message is appended as an ?error= query parameter. If omitted, returns JSON error."
+        },
+        "defaults": {
+          "type": "object",
+          "description": "Default settings applied to all providers (e.g. transport, scope).",
+          "properties": {
+            "transport": {
+              "type": "string",
+              "enum": ["querystring", "session"],
+              "default": "querystring"
+            }
+          }
+        },
+        "providers": {
+          "type": "object",
+          "description": "Map of OAuth provider names to their configuration. Provider names must match grant's supported provider list (e.g. google, github, facebook). See https://www.npmjs.com/package/grant for all 200+ supported providers.",
+          "additionalProperties": {
+            "$ref": "#/$defs/oauthProvider"
+          }
+        }
+      }
     }
   },
   "$defs": {
@@ -362,6 +399,31 @@
         "limit": { "type": "integer", "description": "Maximum number of requests allowed in the time window." },
         "ttl":   { "type": "integer", "description": "Time window in milliseconds." }
       }
+    },
+    "oauthProvider": {
+      "type": "object",
+      "description": "Configuration for a single OAuth provider. The key and secret should be set via OAUTH_<PROVIDER>_KEY and OAUTH_<PROVIDER>_SECRET environment variables.",
+      "properties": {
+        "key":            { "type": "string", "description": "OAuth client/app ID. Prefer using OAUTH_<PROVIDER>_KEY env var instead." },
+        "secret":         { "type": "string", "description": "OAuth client/app secret. Prefer using OAUTH_<PROVIDER>_SECRET env var instead." },
+        "scope":          {
+          "oneOf": [
+            { "type": "string" },
+            { "type": "array", "items": { "type": "string" } }
+          ],
+          "description": "OAuth scopes to request (e.g. 'openid email profile')."
+        },
+        "callback":       { "type": "string", "description": "Custom callback URL path. Defaults to /api/auth/oauth/callback." },
+        "custom_params":  { "type": "object", "description": "Extra query parameters to send to the authorization URL." },
+        "subdomain":      { "type": "string", "description": "Subdomain for providers that require one (e.g. Shopify)." },
+        "nonce":          { "type": "boolean", "description": "Enable nonce generation (required by some OIDC providers)." },
+        "pkce":           { "type": "boolean", "description": "Enable PKCE (Proof Key for Code Exchange) for enhanced security." },
+        "response":       {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Data to include in the callback (e.g. ['tokens', 'profile'])."
+        }
+      }
     }
   }
 }

package/core/entity-engine.js

@@ -155,6 +155,7 @@ function buildCore(config) {
     port: parseInt(process.env.CHADSTART_PORT || process.env.PORT || config.port || 3000, 10),
     rateLimits,
     telemetry,
+    oauth: config.oauth || null,
     admin: {
       enable_app: adminCfg.enable_app !== false,
       enable_entity: adminCfg.enable_entity !== false,

package/core/oauth.js

@@ -0,0 +1,263 @@
+'use strict';
+
+/**
+ * OAuth / Social Login via the "grant" library.
+ *
+ * When the YAML config contains an `oauth` section, this module:
+ *   1. Mounts the Grant middleware at /connect (handles the redirect dance).
+ *   2. Registers a callback route at /api/auth/oauth/callback that
+ *      finds-or-creates the user and returns a JWT.
+ *
+ * Secrets (client IDs, client secrets) must be supplied via environment
+ * variables — never place them in the YAML file.
+ */
+
+const crypto = require('crypto');
+const Grant = require('grant').express();
+const rateLimit = require('express-rate-limit');
+const { signToken } = require('./auth');
+const db = require('./db');
+const logger = require('../utils/logger');
+
+const oauthLimiter = rateLimit({
+  windowMs: 15 * 60 * 1000,
+  max: 30,
+  standardHeaders: true,
+  legacyHeaders: false,
+  message: { error: 'Too many OAuth requests, please try again later.' },
+});
+
+// ─── Provider profile normalisation ─────────────────────────────────────────
+
+/**
+ * Normalise the profile returned by Grant into { email, name, providerId }.
+ * Different providers return profile data in different shapes.
+ *
+ * @param {string} provider  Lowercase provider key (e.g. "google").
+ * @param {object} profile   Raw profile object from the OAuth provider.
+ * @returns {{ email: string|null, name: string|null, providerId: string|null }}
+ */
+function normalizeProfile(provider, profile) {
+  if (!profile) return { email: null, name: null, providerId: null };
+
+  const email =
+    profile.email ||
+    profile.mail ||
+    (profile.emails && profile.emails[0] && (profile.emails[0].value || profile.emails[0])) ||
+    null;
+  const name =
+    profile.name ||
+    profile.displayName ||
+    profile.login ||
+    profile.username ||
+    (profile.first_name ? `${profile.first_name} ${profile.last_name || ''}`.trim() : null) ||
+    null;
+  const providerId =
+    String(profile.sub || profile.id || profile.user_id || profile.account_id || '');
+
+  return { email: email || null, name: name || null, providerId: providerId || null };
+}
+
+// ─── Grant config builder ───────────────────────────────────────────────────
+
+/**
+ * Build the Grant configuration object from the parsed YAML `oauth` section.
+ *
+ * Environment variable overrides (per-provider):
+ *   OAUTH_<PROVIDER>_KEY      – client/app ID
+ *   OAUTH_<PROVIDER>_SECRET   – client/app secret
+ *
+ * @param {object} oauthConfig  The `oauth` block from the YAML config.
+ * @param {string} baseUrl      The application base URL (e.g. http://localhost:3000).
+ * @returns {object}            Configuration object accepted by Grant.
+ */
+function buildGrantConfig(oauthConfig, baseUrl) {
+  const defaults = oauthConfig.defaults || {};
+  const origin = baseUrl.replace(/\/$/, '');
+
+  const grantConfig = {
+    defaults: {
+      origin,
+      transport: 'querystring',
+      prefix: '/connect',
+      ...defaults,
+    },
+  };
+
+  const providers = oauthConfig.providers || {};
+  for (const [name, cfg] of Object.entries(providers)) {
+    const envPrefix = `OAUTH_${name.toUpperCase()}_`;
+    const key = process.env[`${envPrefix}KEY`] || cfg.key || '';
+    const secret = process.env[`${envPrefix}SECRET`] || cfg.secret || '';
+
+    grantConfig[name] = {
+      ...cfg,
+      key,
+      secret,
+      // callback is where Grant redirects after the OAuth dance;
+      // we point it at our own API endpoint which issues a JWT.
+      callback: cfg.callback || `/api/auth/oauth/callback`,
+    };
+  }
+
+  return grantConfig;
+}
+
+// ─── Route registration ─────────────────────────────────────────────────────
+
+/**
+ * Mount the Grant middleware and register the OAuth callback route.
+ *
+ * @param {import('express').Application} app
+ * @param {object} core     Parsed core configuration.
+ * @param {Function} emit   EventBus emit function.
+ */
+function registerOAuthRoutes(app, core, emit) {
+  const oauthConfig = core.oauth;
+  if (!oauthConfig || !oauthConfig.providers || Object.keys(oauthConfig.providers).length === 0) {
+    return; // OAuth not configured — skip
+  }
+
+  const baseUrl = (
+    process.env.BASE_URL ||
+    `http://localhost:${core.port}`
+  ).replace(/\/$/, '');
+
+  const grantConfig = buildGrantConfig(oauthConfig, baseUrl);
+
+  // Mount grant middleware — handles /connect/:provider and /connect/:provider/callback
+  app.use(Grant(grantConfig));
+  logger.info('  Mounted OAuth middleware at /connect');
+
+  // Determine the target authenticable entity for OAuth users.
+  // The `oauth.entity` field specifies which entity to use (default: first authenticable entity).
+  const targetEntityName = oauthConfig.entity || null;
+  const entity =
+    (targetEntityName && core.authenticableEntities[targetEntityName]) ||
+    Object.values(core.authenticableEntities)[0];
+
+  if (!entity) {
+    logger.warn('  OAuth: no authenticable entity found — OAuth callback will not work.');
+    return;
+  }
+
+  const _emit = typeof emit === 'function' ? emit : () => {};
+
+  /**
+   * GET /api/auth/oauth/callback
+   *
+   * Grant redirects here with query-string parameters after the OAuth dance.
+   * We extract the access_token / profile, find-or-create the user, and
+   * return a JWT (or redirect if `oauth.successRedirect` is set).
+   */
+  app.get('/api/auth/oauth/callback', oauthLimiter, async (req, res) => {
+    try {
+      const { access_token, profile, provider, error } = req.query;
+
+      if (error) {
+        return _handleError(res, oauthConfig, `OAuth error: ${error}`);
+      }
+
+      if (!access_token && !profile) {
+        return _handleError(res, oauthConfig, 'OAuth callback missing token and profile');
+      }
+
+      // Grant may pass the profile as a JSON string in the querystring
+      let parsedProfile = {};
+      if (profile) {
+        try { parsedProfile = typeof profile === 'string' ? JSON.parse(profile) : profile; } catch { /* ignore */ }
+      }
+
+      const providerName = (provider || 'unknown').toLowerCase();
+      const { email, name, providerId } = normalizeProfile(providerName, parsedProfile);
+
+      if (!email && !providerId) {
+        return _handleError(res, oauthConfig, 'Could not obtain email or provider ID from OAuth profile');
+      }
+
+      // Find or create the user
+      const user = await _findOrCreateOAuthUser(entity, {
+        email,
+        name,
+        provider: providerName,
+        providerId,
+        accessToken: access_token || null,
+      });
+
+      _emit(`${entity.name}.oauthLogin`, { provider: providerName, userId: user.id });
+
+      const token = signToken({ id: user.id, entity: entity.name });
+
+      // Redirect or return JSON based on config
+      const successRedirect = oauthConfig.successRedirect;
+      if (successRedirect) {
+        const sep = successRedirect.includes('?') ? '&' : '?';
+        return res.redirect(`${successRedirect}${sep}token=${encodeURIComponent(token)}`);
+      }
+
+      res.json({ token, user: _omitSensitive(user) });
+    } catch (e) {
+      logger.error('OAuth callback error:', e.message);
+      return _handleError(res, oauthConfig, e.message);
+    }
+  });
+
+  // List configured providers
+  app.get('/api/auth/oauth/providers', oauthLimiter, (_req, res) => {
+    const providers = Object.keys(oauthConfig.providers || {});
+    res.json({ providers });
+  });
+
+  const providerNames = Object.keys(oauthConfig.providers);
+  logger.info(`  OAuth providers: ${providerNames.join(', ')}`);
+  logger.info(`  OAuth callback:  /api/auth/oauth/callback`);
+  logger.info(`  OAuth entity:    ${entity.name}`);
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+/**
+ * Find an existing user by email or create a new one.
+ */
+async function _findOrCreateOAuthUser(entity, { email, name, provider, providerId, accessToken }) {
+  const table = entity.tableName;
+
+  // 1. Try to find by email
+  if (email) {
+    const existing = await db.findAllSimple(table, { email });
+    if (existing.length > 0) return existing[0];
+  }
+
+  // 2. Create a new user with a random password (they authenticate via OAuth)
+  const newUser = {
+    email: email || `${provider}_${providerId}@oauth.local`,
+    password: crypto.randomBytes(32).toString('hex'), // random placeholder
+  };
+
+  // Add optional fields if the entity supports them
+  const propNames = new Set(entity.properties.map((p) => p.name));
+  if (name && propNames.has('name')) newUser.name = name;
+
+  const bcrypt = require('bcryptjs');
+  newUser.password = await bcrypt.hash(newUser.password, 10);
+
+  const created = await db.create(table, newUser);
+  return created;
+}
+
+function _omitSensitive(user) {
+  if (!user) return null;
+  const { password: _, ...rest } = user;
+  return rest;
+}
+
+function _handleError(res, oauthConfig, message) {
+  const errorRedirect = oauthConfig.errorRedirect;
+  if (errorRedirect) {
+    const sep = errorRedirect.includes('?') ? '&' : '?';
+    return res.redirect(`${errorRedirect}${sep}error=${encodeURIComponent(message)}`);
+  }
+  return res.status(400).json({ error: message });
+}
+
+module.exports = { registerOAuthRoutes, buildGrantConfig, normalizeProfile };

package/docs/auth.md

@@ -42,6 +42,9 @@ entities:
 
 Authenticable entities have 2 extra properties that are used as credentials to log in: `email` and `password`. You do not need to specify them.The `email` property expects a unique valid emails and the `password` property is automatically hashed using _bcryt_ with 10 salt rounds.
 
+!!! tip "Social Login"
+    Want users to log in with Google, GitHub, Discord, or other OAuth providers? See the [OAuth / Social Login](./oauth.md) guide.
+
 ## Actions
 
 ### Login