@nixxie-cms/auth-oauth 1.0.1 → 1.1.0

package/README.md

@@ -33,3 +33,40 @@ app.get('/auth/google/callback', async (req, res) => {
   // upsert a user keyed by profile.id / profile.email and start a session
 })
 ```
+
+## Automatic routes
+
+Skip the hand-written routes entirely: `installOAuthRoutes` mounts
+`GET /auth/:provider` (redirect to consent screen) and `GET /auth/:provider/callback`
+(code exchange, find-or-create user, session start) for every configured provider, with
+signed-cookie state validation built in.
+
+```ts
+import { installOAuthRoutes } from '@nixxie-cms/auth-oauth'
+
+server: {
+  extendExpressApp: (app, context) => {
+    installOAuthRoutes(app, context, { oauth, listKey: 'User' })
+  },
+}
+```
+
+Or as a plugin:
+
+```ts
+import { oauthPlugin } from '@nixxie-cms/auth-oauth'
+
+config({
+  plugins: [oauthPlugin({ oauth, listKey: 'User' })],
+})
+```
+
+Users are matched by the profile's email against `identityField` (default `'email'`) and
+created on first sign-in unless `allowSignup: false`. Sessions are started via the
+configured session strategy with `{ itemId }`, compatible with `createAuth` sessions.
+
+Options: `listKey` (default `'User'`), `identityField`, `allowSignup`, `resolveUser`
+(data for users created on first sign-in — return `null` to reject), `onSignIn`
+(post-sign-in hook with `{ provider, itemId, created, profile, tokens, context }`),
+`basePath` (default `'/auth'`), `successRedirect` (default `'/'`) and `failureRedirect`
+(default `'/signin'`, gets `?error=<code>` appended).

package/dist/declarations/src/express.d.ts

@@ -0,0 +1,82 @@
+import type { NixxieContext, NixxiePlugin } from '@nixxie-cms/core/types';
+import type { OAuth } from "./index.js";
+import type { OAuthProfile, OAuthTokens } from "./types.js";
+export type OAuthRoutesOptions = {
+    /** The OAuth client created with `createOAuth()`. */
+    oauth: OAuth;
+    /**
+     * Collection holding your users.
+     * @default 'User'
+     */
+    listKey?: string;
+    /**
+     * Field used to match OAuth profiles to existing users (by the profile's email).
+     * @default 'email'
+     */
+    identityField?: string;
+    /**
+     * Create users on first sign-in. When false, sign-ins from unknown
+     * profiles are redirected to `failureRedirect`.
+     * @default true
+     */
+    allowSignup?: boolean;
+    /**
+     * Resolve the data for a user being created on first sign-in.
+     * Return null to reject the sign-in. Defaults to `{ [identityField]: profile.email }`
+     * plus `name` when the collection's input accepts it.
+     */
+    resolveUser?: (args: {
+        provider: string;
+        profile: OAuthProfile;
+        tokens: OAuthTokens;
+        context: NixxieContext;
+    }) => Promise<Record<string, unknown> | null> | Record<string, unknown> | null;
+    /**
+     * Called after a successful sign-in (e.g. to link accounts or audit). Receives the
+     * signed-in user's id.
+     */
+    onSignIn?: (args: {
+        provider: string;
+        itemId: string;
+        created: boolean;
+        profile: OAuthProfile;
+        tokens: OAuthTokens;
+        context: NixxieContext;
+    }) => Promise<void> | void;
+    /**
+     * Base path the routes are mounted under: `<basePath>/:provider` starts the flow and
+     * `<basePath>/:provider/callback` completes it.
+     * @default '/auth'
+     */
+    basePath?: string;
+    /** Where to send the user after a successful sign-in. @default '/' */
+    successRedirect?: string;
+    /** Where to send the user after a failure (gets `?error=<code>` appended). @default '/signin' */
+    failureRedirect?: string;
+};
+/**
+ * Mount ready-made OAuth sign-in routes on the Express app:
+ *
+ * - `GET <basePath>/:provider` — redirects to the provider's consent screen
+ * - `GET <basePath>/:provider/callback` — exchanges the code, finds-or-creates the
+ *   user, starts a session (compatible with `createAuth` sessions: `{ itemId }`),
+ *   and redirects
+ *
+ * Call from `server.extendExpressApp`, or use `oauthPlugin()` to wire it automatically.
+ */
+export declare function installOAuthRoutes(app: any, context: NixxieContext, options: OAuthRoutesOptions): void;
+/**
+ * The same OAuth routes as `installOAuthRoutes`, packaged as a Nixxie plugin.
+ *
+ * @example
+ * config({
+ *   plugins: [
+ *     oauthPlugin({
+ *       oauth: createOAuth({ providers: { google: { provider: 'google', ... } } }),
+ *       listKey: 'User',
+ *     }),
+ *   ],
+ * })
+ */
+export declare function oauthPlugin(options: OAuthRoutesOptions): NixxiePlugin;
+//# sourceMappingURL=express.d.ts.map

package/dist/declarations/src/express.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"express.d.ts","sourceRoot":"../../../src","sources":["express.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAA;AACzE,OAAO,KAAK,EAAE,KAAK,EAAE,mBAAe;AACpC,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,mBAAe;AAIxD,MAAM,MAAM,kBAAkB,GAAG;IAC/B,qDAAqD;IACrD,KAAK,EAAE,KAAK,CAAA;IACZ;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE;QACnB,QAAQ,EAAE,MAAM,CAAA;QAChB,OAAO,EAAE,YAAY,CAAA;QACrB,MAAM,EAAE,WAAW,CAAA;QACnB,OAAO,EAAE,aAAa,CAAA;KACvB,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;IAC9E;;;OAGG;IACH,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE;QAChB,QAAQ,EAAE,MAAM,CAAA;QAChB,MAAM,EAAE,MAAM,CAAA;QACd,OAAO,EAAE,OAAO,CAAA;QAChB,OAAO,EAAE,YAAY,CAAA;QACrB,MAAM,EAAE,WAAW,CAAA;QACnB,OAAO,EAAE,aAAa,CAAA;KACvB,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,sEAAsE;IACtE,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,iGAAiG;IACjG,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB,CAAA;AAaD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,GAAG,EACR,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE,kBAAkB,GAC1B,IAAI,CAwGN;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,YAAY,CAcrE"}

package/dist/declarations/src/index.d.ts

@@ -24,6 +24,8 @@ export declare class OAuth {
     }>;
 }
 export declare function createOAuth(config: OAuthConfig): OAuth;
+export { installOAuthRoutes, oauthPlugin } from "./express.js";
+export type { OAuthRoutesOptions } from "./express.js";
 export { builtInProviders as providers };
 export type { OAuthConfig, OAuthProviderConfig, OAuthProviderDefinition, OAuthProviderName, OAuthProfile, OAuthTokens, } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/declarations/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"../../../src","sources":["index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,IAAI,gBAAgB,EAAE,uBAAmB;AAC3D,OAAO,KAAK,EACV,WAAW,EACX,YAAY,EAGZ,WAAW,EACZ,mBAAe;AAQhB,qBAAa,KAAK;IAChB,OAAO,CAAC,MAAM,CAAa;gBAEf,MAAM,EAAE,WAAW;IAI/B,yCAAyC;IACzC,IAAI,IAAI,MAAM,EAAE;IAIhB,OAAO,CAAC,GAAG;IAMX,0FAA0F;IAC1F,WAAW,IAAI,MAAM;IAIrB,wEAAwE;IACxE,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,GAAG,MAAM;IAa1G,8EAA8E;IACxE,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IA+BpE,+DAA+D;IACzD,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC;IAc5E,wEAAwE;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,WAAW,CAAC;QAAC,OAAO,EAAE,YAAY,CAAA;KAAE,CAAC;CAKpG;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,KAAK,CAEtD;AAED,OAAO,EAAE,gBAAgB,IAAI,SAAS,EAAE,CAAA;AACxC,YAAY,EACV,WAAW,EACX,mBAAmB,EACnB,uBAAuB,EACvB,iBAAiB,EACjB,YAAY,EACZ,WAAW,GACZ,mBAAe"}
+{"version":3,"file":"index.d.ts","sourceRoot":"../../../src","sources":["index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,IAAI,gBAAgB,EAAE,uBAAmB;AAC3D,OAAO,KAAK,EACV,WAAW,EACX,YAAY,EAGZ,WAAW,EACZ,mBAAe;AAQhB,qBAAa,KAAK;IAChB,OAAO,CAAC,MAAM,CAAa;gBAEf,MAAM,EAAE,WAAW;IAI/B,yCAAyC;IACzC,IAAI,IAAI,MAAM,EAAE;IAIhB,OAAO,CAAC,GAAG;IAMX,0FAA0F;IAC1F,WAAW,IAAI,MAAM;IAIrB,wEAAwE;IACxE,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,GAAG,MAAM;IAa1G,8EAA8E;IACxE,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IA+BpE,+DAA+D;IACzD,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC;IAc5E,wEAAwE;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,WAAW,CAAC;QAAC,OAAO,EAAE,YAAY,CAAA;KAAE,CAAC;CAKpG;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,KAAK,CAEtD;AAED,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,qBAAiB;AAC3D,YAAY,EAAE,kBAAkB,EAAE,qBAAiB;AACnD,OAAO,EAAE,gBAAgB,IAAI,SAAS,EAAE,CAAA;AACxC,YAAY,EACV,WAAW,EACX,mBAAmB,EACnB,uBAAuB,EACvB,iBAAiB,EACjB,YAAY,EACZ,WAAW,GACZ,mBAAe"}

package/dist/nixxie-cms-auth-oauth.cjs.js

@@ -97,6 +97,184 @@ const providers = {
   }
 };
 
+const STATE_COOKIE = 'nixxie-oauth-state';
+function parseCookies(header) {
+  const out = {};
+  if (!header) return out;
+  for (const part of header.split(';')) {
+    const eq = part.indexOf('=');
+    if (eq === -1) continue;
+    out[part.slice(0, eq).trim()] = decodeURIComponent(part.slice(eq + 1).trim());
+  }
+  return out;
+}
+
+/**
+ * Mount ready-made OAuth sign-in routes on the Express app:
+ *
+ * - `GET <basePath>/:provider` — redirects to the provider's consent screen
+ * - `GET <basePath>/:provider/callback` — exchanges the code, finds-or-creates the
+ *   user, starts a session (compatible with `createAuth` sessions: `{ itemId }`),
+ *   and redirects
+ *
+ * Call from `server.extendExpressApp`, or use `oauthPlugin()` to wire it automatically.
+ */
+function installOAuthRoutes(app, context, options) {
+  const {
+    oauth,
+    listKey = 'User',
+    identityField = 'email',
+    allowSignup = true,
+    resolveUser,
+    onSignIn,
+    basePath = '/auth',
+    successRedirect = '/',
+    failureRedirect = '/signin'
+  } = options;
+
+  // The state value is signed so the callback can verify it even though the cookie
+  // itself is the only storage — no server-side flow state needed.
+  const stateSecret = node_crypto.randomBytes(32).toString('hex');
+  const signState = value => `${value}.${node_crypto.createHmac('sha256', stateSecret).update(value).digest('hex')}`;
+  const verifyState = signed => {
+    if (!signed) return;
+    const at = signed.lastIndexOf('.');
+    if (at === -1) return;
+    const value = signed.slice(0, at);
+    const mac = node_crypto.createHmac('sha256', stateSecret).update(value).digest('hex');
+    return mac === signed.slice(at + 1) ? value : undefined;
+  };
+  const fail = (res, code) => {
+    const sep = failureRedirect.includes('?') ? '&' : '?';
+    res.redirect(`${failureRedirect}${sep}error=${encodeURIComponent(code)}`);
+  };
+  app.get(`${basePath}/:provider`, (req, res) => {
+    try {
+      var _res$cookie;
+      const provider = req.params.provider;
+      if (!oauth.list().includes(provider)) return fail(res, 'unknown-provider');
+      const state = oauth.createState();
+      (_res$cookie = res.cookie) === null || _res$cookie === void 0 || _res$cookie.call(res, STATE_COOKIE, signState(`${provider}:${state}`), {
+        httpOnly: true,
+        sameSite: 'lax',
+        secure: process.env.NODE_ENV === 'production',
+        maxAge: 10 * 60 * 1000,
+        path: basePath
+      });
+      res.redirect(oauth.authorizationUrl(provider, {
+        state
+      }));
+    } catch (err) {
+      console.error('[nixxie/auth-oauth] start failed:', err);
+      fail(res, 'oauth-start-failed');
+    }
+  });
+  app.get(`${basePath}/:provider/callback`, (req, res) => {
+    void (async (_req$query, _res$clearCookie) => {
+      const provider = req.params.provider;
+      const {
+        code,
+        state,
+        error
+      } = (_req$query = req.query) !== null && _req$query !== void 0 ? _req$query : {};
+      if (error) return fail(res, String(error));
+      if (!code) return fail(res, 'missing-code');
+      const stored = verifyState(parseCookies(req.headers.cookie)[STATE_COOKIE]);
+      (_res$clearCookie = res.clearCookie) === null || _res$clearCookie === void 0 || _res$clearCookie.call(res, STATE_COOKIE, {
+        path: basePath
+      });
+      if (!stored || stored !== `${provider}:${state}`) return fail(res, 'invalid-state');
+      const {
+        tokens,
+        profile
+      } = await oauth.callback(provider, String(code));
+      if (!profile.email) return fail(res, 'no-email');
+      const requestContext = await context.withRequest(req, res);
+      const sudo = requestContext.sudo();
+      const existing = await sudo.db[listKey].findMany({
+        where: {
+          [identityField]: {
+            equals: profile.email
+          }
+        },
+        take: 1
+      });
+      let itemId;
+      let created = false;
+      if (existing.length) {
+        itemId = String(existing[0].id);
+      } else {
+        if (!allowSignup) return fail(res, 'unknown-user');
+        const data = resolveUser ? await resolveUser({
+          provider,
+          profile,
+          tokens,
+          context: requestContext
+        }) : {
+          [identityField]: profile.email
+        };
+        if (!data) return fail(res, 'signup-rejected');
+        const createdItem = await sudo.db[listKey].createOne({
+          data: data
+        });
+        itemId = String(createdItem.id);
+        created = true;
+      }
+      if (!requestContext.sessionStrategy) {
+        throw new Error('installOAuthRoutes: no session strategy configured');
+      }
+      await requestContext.sessionStrategy.start({
+        context: requestContext,
+        data: {
+          itemId
+        }
+      });
+      await (onSignIn === null || onSignIn === void 0 ? void 0 : onSignIn({
+        provider,
+        itemId,
+        created,
+        profile,
+        tokens,
+        context: requestContext
+      }));
+      res.redirect(successRedirect);
+    })().catch(err => {
+      console.error('[nixxie/auth-oauth] callback failed:', err);
+      fail(res, 'oauth-failed');
+    });
+  });
+}
+
+/**
+ * The same OAuth routes as `installOAuthRoutes`, packaged as a Nixxie plugin.
+ *
+ * @example
+ * config({
+ *   plugins: [
+ *     oauthPlugin({
+ *       oauth: createOAuth({ providers: { google: { provider: 'google', ... } } }),
+ *       listKey: 'User',
+ *     }),
+ *   ],
+ * })
+ */
+function oauthPlugin(options) {
+  return {
+    name: 'nixxie-auth-oauth',
+    extendConfig: config => ({
+      ...config,
+      server: {
+        ...config.server,
+        extendExpressApp: async (app, context) => {
+          var _config$server, _config$server$extend;
+          await ((_config$server = config.server) === null || _config$server === void 0 || (_config$server$extend = _config$server.extendExpressApp) === null || _config$server$extend === void 0 ? void 0 : _config$server$extend.call(_config$server, app, context));
+          installOAuthRoutes(app, context, options);
+        }
+      }
+    })
+  };
+}
+
 function resolveDefinition(cfg) {
   if (cfg.definition) return cfg.definition;
   if (cfg.provider) return providers[cfg.provider];
@@ -214,4 +392,6 @@ function createOAuth(config) {
 
 exports.OAuth = OAuth;
 exports.createOAuth = createOAuth;
+exports.installOAuthRoutes = installOAuthRoutes;
+exports.oauthPlugin = oauthPlugin;
 exports.providers = providers;

package/dist/nixxie-cms-auth-oauth.esm.js

@@ -1,4 +1,4 @@
-import { randomBytes } from 'node:crypto';
+import { randomBytes, createHmac } from 'node:crypto';
 
 const providers = {
   google: {
@@ -93,6 +93,184 @@ const providers = {
   }
 };
 
+const STATE_COOKIE = 'nixxie-oauth-state';
+function parseCookies(header) {
+  const out = {};
+  if (!header) return out;
+  for (const part of header.split(';')) {
+    const eq = part.indexOf('=');
+    if (eq === -1) continue;
+    out[part.slice(0, eq).trim()] = decodeURIComponent(part.slice(eq + 1).trim());
+  }
+  return out;
+}
+
+/**
+ * Mount ready-made OAuth sign-in routes on the Express app:
+ *
+ * - `GET <basePath>/:provider` — redirects to the provider's consent screen
+ * - `GET <basePath>/:provider/callback` — exchanges the code, finds-or-creates the
+ *   user, starts a session (compatible with `createAuth` sessions: `{ itemId }`),
+ *   and redirects
+ *
+ * Call from `server.extendExpressApp`, or use `oauthPlugin()` to wire it automatically.
+ */
+function installOAuthRoutes(app, context, options) {
+  const {
+    oauth,
+    listKey = 'User',
+    identityField = 'email',
+    allowSignup = true,
+    resolveUser,
+    onSignIn,
+    basePath = '/auth',
+    successRedirect = '/',
+    failureRedirect = '/signin'
+  } = options;
+
+  // The state value is signed so the callback can verify it even though the cookie
+  // itself is the only storage — no server-side flow state needed.
+  const stateSecret = randomBytes(32).toString('hex');
+  const signState = value => `${value}.${createHmac('sha256', stateSecret).update(value).digest('hex')}`;
+  const verifyState = signed => {
+    if (!signed) return;
+    const at = signed.lastIndexOf('.');
+    if (at === -1) return;
+    const value = signed.slice(0, at);
+    const mac = createHmac('sha256', stateSecret).update(value).digest('hex');
+    return mac === signed.slice(at + 1) ? value : undefined;
+  };
+  const fail = (res, code) => {
+    const sep = failureRedirect.includes('?') ? '&' : '?';
+    res.redirect(`${failureRedirect}${sep}error=${encodeURIComponent(code)}`);
+  };
+  app.get(`${basePath}/:provider`, (req, res) => {
+    try {
+      var _res$cookie;
+      const provider = req.params.provider;
+      if (!oauth.list().includes(provider)) return fail(res, 'unknown-provider');
+      const state = oauth.createState();
+      (_res$cookie = res.cookie) === null || _res$cookie === void 0 || _res$cookie.call(res, STATE_COOKIE, signState(`${provider}:${state}`), {
+        httpOnly: true,
+        sameSite: 'lax',
+        secure: process.env.NODE_ENV === 'production',
+        maxAge: 10 * 60 * 1000,
+        path: basePath
+      });
+      res.redirect(oauth.authorizationUrl(provider, {
+        state
+      }));
+    } catch (err) {
+      console.error('[nixxie/auth-oauth] start failed:', err);
+      fail(res, 'oauth-start-failed');
+    }
+  });
+  app.get(`${basePath}/:provider/callback`, (req, res) => {
+    void (async (_req$query, _res$clearCookie) => {
+      const provider = req.params.provider;
+      const {
+        code,
+        state,
+        error
+      } = (_req$query = req.query) !== null && _req$query !== void 0 ? _req$query : {};
+      if (error) return fail(res, String(error));
+      if (!code) return fail(res, 'missing-code');
+      const stored = verifyState(parseCookies(req.headers.cookie)[STATE_COOKIE]);
+      (_res$clearCookie = res.clearCookie) === null || _res$clearCookie === void 0 || _res$clearCookie.call(res, STATE_COOKIE, {
+        path: basePath
+      });
+      if (!stored || stored !== `${provider}:${state}`) return fail(res, 'invalid-state');
+      const {
+        tokens,
+        profile
+      } = await oauth.callback(provider, String(code));
+      if (!profile.email) return fail(res, 'no-email');
+      const requestContext = await context.withRequest(req, res);
+      const sudo = requestContext.sudo();
+      const existing = await sudo.db[listKey].findMany({
+        where: {
+          [identityField]: {
+            equals: profile.email
+          }
+        },
+        take: 1
+      });
+      let itemId;
+      let created = false;
+      if (existing.length) {
+        itemId = String(existing[0].id);
+      } else {
+        if (!allowSignup) return fail(res, 'unknown-user');
+        const data = resolveUser ? await resolveUser({
+          provider,
+          profile,
+          tokens,
+          context: requestContext
+        }) : {
+          [identityField]: profile.email
+        };
+        if (!data) return fail(res, 'signup-rejected');
+        const createdItem = await sudo.db[listKey].createOne({
+          data: data
+        });
+        itemId = String(createdItem.id);
+        created = true;
+      }
+      if (!requestContext.sessionStrategy) {
+        throw new Error('installOAuthRoutes: no session strategy configured');
+      }
+      await requestContext.sessionStrategy.start({
+        context: requestContext,
+        data: {
+          itemId
+        }
+      });
+      await (onSignIn === null || onSignIn === void 0 ? void 0 : onSignIn({
+        provider,
+        itemId,
+        created,
+        profile,
+        tokens,
+        context: requestContext
+      }));
+      res.redirect(successRedirect);
+    })().catch(err => {
+      console.error('[nixxie/auth-oauth] callback failed:', err);
+      fail(res, 'oauth-failed');
+    });
+  });
+}
+
+/**
+ * The same OAuth routes as `installOAuthRoutes`, packaged as a Nixxie plugin.
+ *
+ * @example
+ * config({
+ *   plugins: [
+ *     oauthPlugin({
+ *       oauth: createOAuth({ providers: { google: { provider: 'google', ... } } }),
+ *       listKey: 'User',
+ *     }),
+ *   ],
+ * })
+ */
+function oauthPlugin(options) {
+  return {
+    name: 'nixxie-auth-oauth',
+    extendConfig: config => ({
+      ...config,
+      server: {
+        ...config.server,
+        extendExpressApp: async (app, context) => {
+          var _config$server, _config$server$extend;
+          await ((_config$server = config.server) === null || _config$server === void 0 || (_config$server$extend = _config$server.extendExpressApp) === null || _config$server$extend === void 0 ? void 0 : _config$server$extend.call(_config$server, app, context));
+          installOAuthRoutes(app, context, options);
+        }
+      }
+    })
+  };
+}
+
 function resolveDefinition(cfg) {
   if (cfg.definition) return cfg.definition;
   if (cfg.provider) return providers[cfg.provider];
@@ -208,4 +386,4 @@ function createOAuth(config) {
   return new OAuth(config);
 }
 
-export { OAuth, createOAuth, providers };
+export { OAuth, createOAuth, installOAuthRoutes, oauthPlugin, providers };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nixxie-cms/auth-oauth",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "license": "MIT",
   "main": "dist/nixxie-cms-auth-oauth.cjs.js",
   "module": "dist/nixxie-cms-auth-oauth.esm.js",
@@ -16,7 +16,7 @@
     "@babel/runtime": "^7.24.7"
   },
   "devDependencies": {
-    "@nixxie-cms/core": "^1.0.1"
+    "@nixxie-cms/core": "^1.1.0"
   },
   "peerDependencies": {
     "@nixxie-cms/core": "^1.0.1"

package/src/express.ts

@@ -0,0 +1,220 @@
+import { createHmac, randomBytes } from 'node:crypto'
+import type { NixxieContext, NixxiePlugin } from '@nixxie-cms/core/types'
+import type { OAuth } from './index'
+import type { OAuthProfile, OAuthTokens } from './types'
+
+const STATE_COOKIE = 'nixxie-oauth-state'
+
+export type OAuthRoutesOptions = {
+  /** The OAuth client created with `createOAuth()`. */
+  oauth: OAuth
+  /**
+   * Collection holding your users.
+   * @default 'User'
+   */
+  listKey?: string
+  /**
+   * Field used to match OAuth profiles to existing users (by the profile's email).
+   * @default 'email'
+   */
+  identityField?: string
+  /**
+   * Create users on first sign-in. When false, sign-ins from unknown
+   * profiles are redirected to `failureRedirect`.
+   * @default true
+   */
+  allowSignup?: boolean
+  /**
+   * Resolve the data for a user being created on first sign-in.
+   * Return null to reject the sign-in. Defaults to `{ [identityField]: profile.email }`
+   * plus `name` when the collection's input accepts it.
+   */
+  resolveUser?: (args: {
+    provider: string
+    profile: OAuthProfile
+    tokens: OAuthTokens
+    context: NixxieContext
+  }) => Promise<Record<string, unknown> | null> | Record<string, unknown> | null
+  /**
+   * Called after a successful sign-in (e.g. to link accounts or audit). Receives the
+   * signed-in user's id.
+   */
+  onSignIn?: (args: {
+    provider: string
+    itemId: string
+    created: boolean
+    profile: OAuthProfile
+    tokens: OAuthTokens
+    context: NixxieContext
+  }) => Promise<void> | void
+  /**
+   * Base path the routes are mounted under: `<basePath>/:provider` starts the flow and
+   * `<basePath>/:provider/callback` completes it.
+   * @default '/auth'
+   */
+  basePath?: string
+  /** Where to send the user after a successful sign-in. @default '/' */
+  successRedirect?: string
+  /** Where to send the user after a failure (gets `?error=<code>` appended). @default '/signin' */
+  failureRedirect?: string
+}
+
+function parseCookies(header: string | undefined): Record<string, string> {
+  const out: Record<string, string> = {}
+  if (!header) return out
+  for (const part of header.split(';')) {
+    const eq = part.indexOf('=')
+    if (eq === -1) continue
+    out[part.slice(0, eq).trim()] = decodeURIComponent(part.slice(eq + 1).trim())
+  }
+  return out
+}
+
+/**
+ * Mount ready-made OAuth sign-in routes on the Express app:
+ *
+ * - `GET <basePath>/:provider` — redirects to the provider's consent screen
+ * - `GET <basePath>/:provider/callback` — exchanges the code, finds-or-creates the
+ *   user, starts a session (compatible with `createAuth` sessions: `{ itemId }`),
+ *   and redirects
+ *
+ * Call from `server.extendExpressApp`, or use `oauthPlugin()` to wire it automatically.
+ */
+export function installOAuthRoutes(
+  app: any,
+  context: NixxieContext,
+  options: OAuthRoutesOptions
+): void {
+  const {
+    oauth,
+    listKey = 'User',
+    identityField = 'email',
+    allowSignup = true,
+    resolveUser,
+    onSignIn,
+    basePath = '/auth',
+    successRedirect = '/',
+    failureRedirect = '/signin',
+  } = options
+
+  // The state value is signed so the callback can verify it even though the cookie
+  // itself is the only storage — no server-side flow state needed.
+  const stateSecret = randomBytes(32).toString('hex')
+  const signState = (value: string) =>
+    `${value}.${createHmac('sha256', stateSecret).update(value).digest('hex')}`
+  const verifyState = (signed: string | undefined): string | undefined => {
+    if (!signed) return
+    const at = signed.lastIndexOf('.')
+    if (at === -1) return
+    const value = signed.slice(0, at)
+    const mac = createHmac('sha256', stateSecret).update(value).digest('hex')
+    return mac === signed.slice(at + 1) ? value : undefined
+  }
+
+  const fail = (res: any, code: string) => {
+    const sep = failureRedirect.includes('?') ? '&' : '?'
+    res.redirect(`${failureRedirect}${sep}error=${encodeURIComponent(code)}`)
+  }
+
+  app.get(`${basePath}/:provider`, (req: any, res: any) => {
+    try {
+      const provider = req.params.provider
+      if (!oauth.list().includes(provider)) return fail(res, 'unknown-provider')
+
+      const state = oauth.createState()
+      res.cookie?.(STATE_COOKIE, signState(`${provider}:${state}`), {
+        httpOnly: true,
+        sameSite: 'lax',
+        secure: process.env.NODE_ENV === 'production',
+        maxAge: 10 * 60 * 1000,
+        path: basePath,
+      })
+      res.redirect(oauth.authorizationUrl(provider, { state }))
+    } catch (err) {
+      console.error('[nixxie/auth-oauth] start failed:', err)
+      fail(res, 'oauth-start-failed')
+    }
+  })
+
+  app.get(`${basePath}/:provider/callback`, (req: any, res: any) => {
+    void (async () => {
+      const provider = req.params.provider
+      const { code, state, error } = req.query ?? {}
+      if (error) return fail(res, String(error))
+      if (!code) return fail(res, 'missing-code')
+
+      const stored = verifyState(parseCookies(req.headers.cookie)[STATE_COOKIE])
+      res.clearCookie?.(STATE_COOKIE, { path: basePath })
+      if (!stored || stored !== `${provider}:${state}`) return fail(res, 'invalid-state')
+
+      const { tokens, profile } = await oauth.callback(provider, String(code))
+      if (!profile.email) return fail(res, 'no-email')
+
+      const requestContext = await context.withRequest(req, res)
+      const sudo = requestContext.sudo()
+
+      const existing = await sudo.db[listKey].findMany({
+        where: { [identityField]: { equals: profile.email } } as any,
+        take: 1,
+      })
+
+      let itemId: string
+      let created = false
+      if (existing.length) {
+        itemId = String(existing[0].id)
+      } else {
+        if (!allowSignup) return fail(res, 'unknown-user')
+        const data = resolveUser
+          ? await resolveUser({ provider, profile, tokens, context: requestContext })
+          : { [identityField]: profile.email }
+        if (!data) return fail(res, 'signup-rejected')
+        const createdItem = await sudo.db[listKey].createOne({ data: data as any })
+        itemId = String(createdItem.id)
+        created = true
+      }
+
+      if (!requestContext.sessionStrategy) {
+        throw new Error('installOAuthRoutes: no session strategy configured')
+      }
+      await requestContext.sessionStrategy.start({
+        context: requestContext,
+        data: { itemId } as any,
+      })
+
+      await onSignIn?.({ provider, itemId, created, profile, tokens, context: requestContext })
+      res.redirect(successRedirect)
+    })().catch((err: unknown) => {
+      console.error('[nixxie/auth-oauth] callback failed:', err)
+      fail(res, 'oauth-failed')
+    })
+  })
+}
+
+/**
+ * The same OAuth routes as `installOAuthRoutes`, packaged as a Nixxie plugin.
+ *
+ * @example
+ * config({
+ *   plugins: [
+ *     oauthPlugin({
+ *       oauth: createOAuth({ providers: { google: { provider: 'google', ... } } }),
+ *       listKey: 'User',
+ *     }),
+ *   ],
+ * })
+ */
+export function oauthPlugin(options: OAuthRoutesOptions): NixxiePlugin {
+  return {
+    name: 'nixxie-auth-oauth',
+    extendConfig: config => ({
+      ...config,
+      server: {
+        ...config.server,
+        extendExpressApp: async (app: any, context: NixxieContext) => {
+          await (config.server as any)?.extendExpressApp?.(app, context)
+          installOAuthRoutes(app, context, options)
+        },
+      },
+    }),
+  }
+}

package/src/index.ts

@@ -110,6 +110,8 @@ export function createOAuth(config: OAuthConfig): OAuth {
   return new OAuth(config)
 }
 
+export { installOAuthRoutes, oauthPlugin } from './express'
+export type { OAuthRoutesOptions } from './express'
 export { builtInProviders as providers }
 export type {
   OAuthConfig,