@nixxie-cms/auth-oauth 1.0.1

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2026 Nixxie International DMCC
+Portions Copyright (c) 2023 Thinkmill Labs Pty Ltd and contributors
+(this software is derived from the KeystoneJS project, https://keystonejs.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,35 @@
+# @nixxie-cms/auth-oauth
+
+Social / OAuth 2.0 sign-in helpers for Nixxie CMS. Built-in providers for Google, GitHub, GitLab,
+Discord, Microsoft and Facebook, plus a `definition` escape hatch for any OAuth 2.0 / OIDC
+provider. No SDK dependencies — it talks to the provider endpoints with `fetch`.
+
+```ts
+import { createOAuth } from '@nixxie-cms/auth-oauth'
+
+const oauth = createOAuth({
+  providers: {
+    google: {
+      provider: 'google',
+      clientId: process.env.GOOGLE_CLIENT_ID!,
+      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+      redirectUri: 'http://localhost:3000/auth/google/callback',
+    },
+  },
+})
+```
+
+Wire it into Express via `server.extendExpressApp`:
+
+```ts
+app.get('/auth/google', (req, res) => {
+  const state = oauth.createState()
+  // persist `state` in the session, then:
+  res.redirect(oauth.authorizationUrl('google', { state }))
+})
+
+app.get('/auth/google/callback', async (req, res) => {
+  const { profile } = await oauth.callback('google', req.query.code as string)
+  // upsert a user keyed by profile.id / profile.email and start a session
+})
+```

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

@@ -0,0 +1,29 @@
+import { providers as builtInProviders } from "./providers.js";
+import type { OAuthConfig, OAuthProfile, OAuthTokens } from "./types.js";
+export declare class OAuth {
+    private config;
+    constructor(config: OAuthConfig);
+    /** Names of the configured providers. */
+    list(): string[];
+    private get;
+    /** Generate a random `state` value to protect against CSRF. Persist it in the session. */
+    createState(): string;
+    /** Build the URL to redirect the user to in order to begin the flow. */
+    authorizationUrl(name: string, options?: {
+        state?: string;
+        extraParams?: Record<string, string>;
+    }): string;
+    /** Exchange the authorization `code` returned to your callback for tokens. */
+    exchangeCode(name: string, code: string): Promise<OAuthTokens>;
+    /** Fetch the normalised user profile using an access token. */
+    fetchProfile(name: string, tokens: OAuthTokens): Promise<OAuthProfile>;
+    /** Convenience: exchange the code and fetch the profile in one call. */
+    callback(name: string, code: string): Promise<{
+        tokens: OAuthTokens;
+        profile: OAuthProfile;
+    }>;
+}
+export declare function createOAuth(config: OAuthConfig): OAuth;
+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

@@ -0,0 +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"}

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

@@ -0,0 +1,3 @@
+import type { OAuthProviderDefinition, OAuthProviderName } from "./types.js";
+export declare const providers: Record<OAuthProviderName, OAuthProviderDefinition>;
+//# sourceMappingURL=providers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"providers.d.ts","sourceRoot":"../../../src","sources":["providers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,mBAAe;AAEzE,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,iBAAiB,EAAE,uBAAuB,CAiFxE,CAAA"}

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

@@ -0,0 +1,48 @@
+export type OAuthProviderName = 'google' | 'github' | 'gitlab' | 'discord' | 'microsoft' | 'facebook';
+/** Endpoints + behaviour for an OAuth 2.0 / OpenID Connect provider. */
+export type OAuthProviderDefinition = {
+    /** Authorization endpoint (where the user is redirected to consent). */
+    authorizationUrl: string;
+    /** Token endpoint (where the auth code is exchanged for tokens). */
+    tokenUrl: string;
+    /** Userinfo endpoint used to fetch the profile. */
+    userInfoUrl: string;
+    /** Default scopes requested when the caller doesn't override them. */
+    defaultScopes: string[];
+    /** Normalise the raw userinfo response into a common profile shape. */
+    profile: (raw: any) => OAuthProfile;
+};
+export type OAuthProfile = {
+    /** Stable provider-specific user id. */
+    id: string;
+    email?: string;
+    name?: string;
+    avatarUrl?: string;
+    /** The untouched provider response. */
+    raw: any;
+};
+export type OAuthTokens = {
+    accessToken: string;
+    refreshToken?: string;
+    expiresIn?: number;
+    tokenType?: string;
+    scope?: string;
+    idToken?: string;
+};
+export type OAuthProviderConfig = {
+    /** Built-in provider name, or omit and supply `definition` for a custom provider. */
+    provider?: OAuthProviderName;
+    /** Custom provider definition (overrides `provider`). */
+    definition?: OAuthProviderDefinition;
+    clientId: string;
+    clientSecret: string;
+    /** Redirect/callback URL registered with the provider. */
+    redirectUri: string;
+    /** Override the provider's default scopes. */
+    scopes?: string[];
+};
+export type OAuthConfig = {
+    /** Map of named providers, keyed by however you want to reference them in routes. */
+    providers: Record<string, OAuthProviderConfig>;
+};
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"../../../src","sources":["types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,iBAAiB,GACzB,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,SAAS,GACT,WAAW,GACX,UAAU,CAAA;AAEd,wEAAwE;AACxE,MAAM,MAAM,uBAAuB,GAAG;IACpC,wEAAwE;IACxE,gBAAgB,EAAE,MAAM,CAAA;IACxB,oEAAoE;IACpE,QAAQ,EAAE,MAAM,CAAA;IAChB,mDAAmD;IACnD,WAAW,EAAE,MAAM,CAAA;IACnB,sEAAsE;IACtE,aAAa,EAAE,MAAM,EAAE,CAAA;IACvB,uEAAuE;IACvE,OAAO,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,YAAY,CAAA;CACpC,CAAA;AAED,MAAM,MAAM,YAAY,GAAG;IACzB,wCAAwC;IACxC,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,uCAAuC;IACvC,GAAG,EAAE,GAAG,CAAA;CACT,CAAA;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,WAAW,EAAE,MAAM,CAAA;IACnB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAAA;AAED,MAAM,MAAM,mBAAmB,GAAG;IAChC,qFAAqF;IACrF,QAAQ,CAAC,EAAE,iBAAiB,CAAA;IAC5B,yDAAyD;IACzD,UAAU,CAAC,EAAE,uBAAuB,CAAA;IACpC,QAAQ,EAAE,MAAM,CAAA;IAChB,YAAY,EAAE,MAAM,CAAA;IACpB,0DAA0D;IAC1D,WAAW,EAAE,MAAM,CAAA;IACnB,8CAA8C;IAC9C,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;CAClB,CAAA;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,qFAAqF;IACrF,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAA;CAC/C,CAAA"}

package/dist/nixxie-cms-auth-oauth.cjs.d.ts

@@ -0,0 +1,2 @@
+export * from "./declarations/src/index.js";
+//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibml4eGllLWNtcy1hdXRoLW9hdXRoLmNqcy5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi9kZWNsYXJhdGlvbnMvc3JjL2luZGV4LmQudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEifQ==

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

@@ -0,0 +1,217 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var node_crypto = require('node:crypto');
+
+const providers = {
+  google: {
+    authorizationUrl: 'https://accounts.google.com/o/oauth2/v2/auth',
+    tokenUrl: 'https://oauth2.googleapis.com/token',
+    userInfoUrl: 'https://openidconnect.googleapis.com/v1/userinfo',
+    defaultScopes: ['openid', 'email', 'profile'],
+    profile: raw => ({
+      id: raw.sub,
+      email: raw.email,
+      name: raw.name,
+      avatarUrl: raw.picture,
+      raw
+    })
+  },
+  github: {
+    authorizationUrl: 'https://github.com/login/oauth/authorize',
+    tokenUrl: 'https://github.com/login/oauth/access_token',
+    userInfoUrl: 'https://api.github.com/user',
+    defaultScopes: ['read:user', 'user:email'],
+    profile: raw => {
+      var _raw$name;
+      return {
+        id: String(raw.id),
+        email: raw.email,
+        name: (_raw$name = raw.name) !== null && _raw$name !== void 0 ? _raw$name : raw.login,
+        avatarUrl: raw.avatar_url,
+        raw
+      };
+    }
+  },
+  gitlab: {
+    authorizationUrl: 'https://gitlab.com/oauth/authorize',
+    tokenUrl: 'https://gitlab.com/oauth/token',
+    userInfoUrl: 'https://gitlab.com/api/v4/user',
+    defaultScopes: ['read_user'],
+    profile: raw => {
+      var _raw$name2;
+      return {
+        id: String(raw.id),
+        email: raw.email,
+        name: (_raw$name2 = raw.name) !== null && _raw$name2 !== void 0 ? _raw$name2 : raw.username,
+        avatarUrl: raw.avatar_url,
+        raw
+      };
+    }
+  },
+  discord: {
+    authorizationUrl: 'https://discord.com/oauth2/authorize',
+    tokenUrl: 'https://discord.com/api/oauth2/token',
+    userInfoUrl: 'https://discord.com/api/users/@me',
+    defaultScopes: ['identify', 'email'],
+    profile: raw => {
+      var _raw$global_name;
+      return {
+        id: raw.id,
+        email: raw.email,
+        name: (_raw$global_name = raw.global_name) !== null && _raw$global_name !== void 0 ? _raw$global_name : raw.username,
+        avatarUrl: raw.avatar ? `https://cdn.discordapp.com/avatars/${raw.id}/${raw.avatar}.png` : undefined,
+        raw
+      };
+    }
+  },
+  microsoft: {
+    authorizationUrl: 'https://login.microsoftonline.com/common/oauth2/v2.0/authorize',
+    tokenUrl: 'https://login.microsoftonline.com/common/oauth2/v2.0/token',
+    userInfoUrl: 'https://graph.microsoft.com/oidc/userinfo',
+    defaultScopes: ['openid', 'email', 'profile'],
+    profile: raw => ({
+      id: raw.sub,
+      email: raw.email,
+      name: raw.name,
+      avatarUrl: raw.picture,
+      raw
+    })
+  },
+  facebook: {
+    authorizationUrl: 'https://www.facebook.com/v19.0/dialog/oauth',
+    tokenUrl: 'https://graph.facebook.com/v19.0/oauth/access_token',
+    userInfoUrl: 'https://graph.facebook.com/me?fields=id,name,email,picture',
+    defaultScopes: ['email', 'public_profile'],
+    profile: raw => {
+      var _raw$picture;
+      return {
+        id: raw.id,
+        email: raw.email,
+        name: raw.name,
+        avatarUrl: (_raw$picture = raw.picture) === null || _raw$picture === void 0 || (_raw$picture = _raw$picture.data) === null || _raw$picture === void 0 ? void 0 : _raw$picture.url,
+        raw
+      };
+    }
+  }
+};
+
+function resolveDefinition(cfg) {
+  if (cfg.definition) return cfg.definition;
+  if (cfg.provider) return providers[cfg.provider];
+  throw new Error('OAuth provider config must specify either `provider` or `definition`');
+}
+class OAuth {
+  constructor(config) {
+    this.config = config;
+  }
+
+  /** Names of the configured providers. */
+  list() {
+    return Object.keys(this.config.providers);
+  }
+  get(name) {
+    const cfg = this.config.providers[name];
+    if (!cfg) throw new Error(`Unknown OAuth provider: ${name}`);
+    return {
+      cfg,
+      def: resolveDefinition(cfg)
+    };
+  }
+
+  /** Generate a random `state` value to protect against CSRF. Persist it in the session. */
+  createState() {
+    return node_crypto.randomBytes(16).toString('hex');
+  }
+
+  /** Build the URL to redirect the user to in order to begin the flow. */
+  authorizationUrl(name, options) {
+    var _cfg$scopes;
+    const {
+      cfg,
+      def
+    } = this.get(name);
+    const params = new URLSearchParams({
+      response_type: 'code',
+      client_id: cfg.clientId,
+      redirect_uri: cfg.redirectUri,
+      scope: ((_cfg$scopes = cfg.scopes) !== null && _cfg$scopes !== void 0 ? _cfg$scopes : def.defaultScopes).join(' '),
+      ...(options !== null && options !== void 0 && options.state ? {
+        state: options.state
+      } : {}),
+      ...(options === null || options === void 0 ? void 0 : options.extraParams)
+    });
+    return `${def.authorizationUrl}?${params}`;
+  }
+
+  /** Exchange the authorization `code` returned to your callback for tokens. */
+  async exchangeCode(name, code) {
+    var _data$error_descripti;
+    const {
+      cfg,
+      def
+    } = this.get(name);
+    const res = await fetch(def.tokenUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        Accept: 'application/json',
+        // GitHub's API rejects requests without a User-Agent (HTTP 403); harmless for others.
+        'User-Agent': 'nixxie-cms-oauth'
+      },
+      body: new URLSearchParams({
+        grant_type: 'authorization_code',
+        code,
+        client_id: cfg.clientId,
+        client_secret: cfg.clientSecret,
+        redirect_uri: cfg.redirectUri
+      })
+    });
+    if (!res.ok) throw new Error(`OAuth token exchange failed (${res.status}): ${await res.text()}`);
+    const data = await res.json();
+    if (data.error) throw new Error(`OAuth token exchange error: ${(_data$error_descripti = data.error_description) !== null && _data$error_descripti !== void 0 ? _data$error_descripti : data.error}`);
+    return {
+      accessToken: data.access_token,
+      refreshToken: data.refresh_token,
+      expiresIn: data.expires_in,
+      tokenType: data.token_type,
+      scope: data.scope,
+      idToken: data.id_token
+    };
+  }
+
+  /** Fetch the normalised user profile using an access token. */
+  async fetchProfile(name, tokens) {
+    const {
+      def
+    } = this.get(name);
+    const res = await fetch(def.userInfoUrl, {
+      headers: {
+        Authorization: `Bearer ${tokens.accessToken}`,
+        Accept: 'application/json',
+        // GitHub's API rejects requests without a User-Agent (HTTP 403); harmless for others.
+        'User-Agent': 'nixxie-cms-oauth'
+      }
+    });
+    if (!res.ok) throw new Error(`OAuth userinfo failed (${res.status}): ${await res.text()}`);
+    return def.profile(await res.json());
+  }
+
+  /** Convenience: exchange the code and fetch the profile in one call. */
+  async callback(name, code) {
+    const tokens = await this.exchangeCode(name, code);
+    const profile = await this.fetchProfile(name, tokens);
+    return {
+      tokens,
+      profile
+    };
+  }
+}
+function createOAuth(config) {
+  return new OAuth(config);
+}
+
+exports.OAuth = OAuth;
+exports.createOAuth = createOAuth;
+exports.providers = providers;

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

@@ -0,0 +1,211 @@
+import { randomBytes } from 'node:crypto';
+
+const providers = {
+  google: {
+    authorizationUrl: 'https://accounts.google.com/o/oauth2/v2/auth',
+    tokenUrl: 'https://oauth2.googleapis.com/token',
+    userInfoUrl: 'https://openidconnect.googleapis.com/v1/userinfo',
+    defaultScopes: ['openid', 'email', 'profile'],
+    profile: raw => ({
+      id: raw.sub,
+      email: raw.email,
+      name: raw.name,
+      avatarUrl: raw.picture,
+      raw
+    })
+  },
+  github: {
+    authorizationUrl: 'https://github.com/login/oauth/authorize',
+    tokenUrl: 'https://github.com/login/oauth/access_token',
+    userInfoUrl: 'https://api.github.com/user',
+    defaultScopes: ['read:user', 'user:email'],
+    profile: raw => {
+      var _raw$name;
+      return {
+        id: String(raw.id),
+        email: raw.email,
+        name: (_raw$name = raw.name) !== null && _raw$name !== void 0 ? _raw$name : raw.login,
+        avatarUrl: raw.avatar_url,
+        raw
+      };
+    }
+  },
+  gitlab: {
+    authorizationUrl: 'https://gitlab.com/oauth/authorize',
+    tokenUrl: 'https://gitlab.com/oauth/token',
+    userInfoUrl: 'https://gitlab.com/api/v4/user',
+    defaultScopes: ['read_user'],
+    profile: raw => {
+      var _raw$name2;
+      return {
+        id: String(raw.id),
+        email: raw.email,
+        name: (_raw$name2 = raw.name) !== null && _raw$name2 !== void 0 ? _raw$name2 : raw.username,
+        avatarUrl: raw.avatar_url,
+        raw
+      };
+    }
+  },
+  discord: {
+    authorizationUrl: 'https://discord.com/oauth2/authorize',
+    tokenUrl: 'https://discord.com/api/oauth2/token',
+    userInfoUrl: 'https://discord.com/api/users/@me',
+    defaultScopes: ['identify', 'email'],
+    profile: raw => {
+      var _raw$global_name;
+      return {
+        id: raw.id,
+        email: raw.email,
+        name: (_raw$global_name = raw.global_name) !== null && _raw$global_name !== void 0 ? _raw$global_name : raw.username,
+        avatarUrl: raw.avatar ? `https://cdn.discordapp.com/avatars/${raw.id}/${raw.avatar}.png` : undefined,
+        raw
+      };
+    }
+  },
+  microsoft: {
+    authorizationUrl: 'https://login.microsoftonline.com/common/oauth2/v2.0/authorize',
+    tokenUrl: 'https://login.microsoftonline.com/common/oauth2/v2.0/token',
+    userInfoUrl: 'https://graph.microsoft.com/oidc/userinfo',
+    defaultScopes: ['openid', 'email', 'profile'],
+    profile: raw => ({
+      id: raw.sub,
+      email: raw.email,
+      name: raw.name,
+      avatarUrl: raw.picture,
+      raw
+    })
+  },
+  facebook: {
+    authorizationUrl: 'https://www.facebook.com/v19.0/dialog/oauth',
+    tokenUrl: 'https://graph.facebook.com/v19.0/oauth/access_token',
+    userInfoUrl: 'https://graph.facebook.com/me?fields=id,name,email,picture',
+    defaultScopes: ['email', 'public_profile'],
+    profile: raw => {
+      var _raw$picture;
+      return {
+        id: raw.id,
+        email: raw.email,
+        name: raw.name,
+        avatarUrl: (_raw$picture = raw.picture) === null || _raw$picture === void 0 || (_raw$picture = _raw$picture.data) === null || _raw$picture === void 0 ? void 0 : _raw$picture.url,
+        raw
+      };
+    }
+  }
+};
+
+function resolveDefinition(cfg) {
+  if (cfg.definition) return cfg.definition;
+  if (cfg.provider) return providers[cfg.provider];
+  throw new Error('OAuth provider config must specify either `provider` or `definition`');
+}
+class OAuth {
+  constructor(config) {
+    this.config = config;
+  }
+
+  /** Names of the configured providers. */
+  list() {
+    return Object.keys(this.config.providers);
+  }
+  get(name) {
+    const cfg = this.config.providers[name];
+    if (!cfg) throw new Error(`Unknown OAuth provider: ${name}`);
+    return {
+      cfg,
+      def: resolveDefinition(cfg)
+    };
+  }
+
+  /** Generate a random `state` value to protect against CSRF. Persist it in the session. */
+  createState() {
+    return randomBytes(16).toString('hex');
+  }
+
+  /** Build the URL to redirect the user to in order to begin the flow. */
+  authorizationUrl(name, options) {
+    var _cfg$scopes;
+    const {
+      cfg,
+      def
+    } = this.get(name);
+    const params = new URLSearchParams({
+      response_type: 'code',
+      client_id: cfg.clientId,
+      redirect_uri: cfg.redirectUri,
+      scope: ((_cfg$scopes = cfg.scopes) !== null && _cfg$scopes !== void 0 ? _cfg$scopes : def.defaultScopes).join(' '),
+      ...(options !== null && options !== void 0 && options.state ? {
+        state: options.state
+      } : {}),
+      ...(options === null || options === void 0 ? void 0 : options.extraParams)
+    });
+    return `${def.authorizationUrl}?${params}`;
+  }
+
+  /** Exchange the authorization `code` returned to your callback for tokens. */
+  async exchangeCode(name, code) {
+    var _data$error_descripti;
+    const {
+      cfg,
+      def
+    } = this.get(name);
+    const res = await fetch(def.tokenUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        Accept: 'application/json',
+        // GitHub's API rejects requests without a User-Agent (HTTP 403); harmless for others.
+        'User-Agent': 'nixxie-cms-oauth'
+      },
+      body: new URLSearchParams({
+        grant_type: 'authorization_code',
+        code,
+        client_id: cfg.clientId,
+        client_secret: cfg.clientSecret,
+        redirect_uri: cfg.redirectUri
+      })
+    });
+    if (!res.ok) throw new Error(`OAuth token exchange failed (${res.status}): ${await res.text()}`);
+    const data = await res.json();
+    if (data.error) throw new Error(`OAuth token exchange error: ${(_data$error_descripti = data.error_description) !== null && _data$error_descripti !== void 0 ? _data$error_descripti : data.error}`);
+    return {
+      accessToken: data.access_token,
+      refreshToken: data.refresh_token,
+      expiresIn: data.expires_in,
+      tokenType: data.token_type,
+      scope: data.scope,
+      idToken: data.id_token
+    };
+  }
+
+  /** Fetch the normalised user profile using an access token. */
+  async fetchProfile(name, tokens) {
+    const {
+      def
+    } = this.get(name);
+    const res = await fetch(def.userInfoUrl, {
+      headers: {
+        Authorization: `Bearer ${tokens.accessToken}`,
+        Accept: 'application/json',
+        // GitHub's API rejects requests without a User-Agent (HTTP 403); harmless for others.
+        'User-Agent': 'nixxie-cms-oauth'
+      }
+    });
+    if (!res.ok) throw new Error(`OAuth userinfo failed (${res.status}): ${await res.text()}`);
+    return def.profile(await res.json());
+  }
+
+  /** Convenience: exchange the code and fetch the profile in one call. */
+  async callback(name, code) {
+    const tokens = await this.exchangeCode(name, code);
+    const profile = await this.fetchProfile(name, tokens);
+    return {
+      tokens,
+      profile
+    };
+  }
+}
+function createOAuth(config) {
+  return new OAuth(config);
+}
+
+export { OAuth, createOAuth, providers };

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@nixxie-cms/auth-oauth",
+  "version": "1.0.1",
+  "license": "MIT",
+  "main": "dist/nixxie-cms-auth-oauth.cjs.js",
+  "module": "dist/nixxie-cms-auth-oauth.esm.js",
+  "exports": {
+    ".": {
+      "types": "./dist/nixxie-cms-auth-oauth.cjs.js",
+      "module": "./dist/nixxie-cms-auth-oauth.esm.js",
+      "default": "./dist/nixxie-cms-auth-oauth.cjs.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@babel/runtime": "^7.24.7"
+  },
+  "devDependencies": {
+    "@nixxie-cms/core": "^1.0.1"
+  },
+  "peerDependencies": {
+    "@nixxie-cms/core": "^1.0.1"
+  },
+  "preconstruct": {
+    "entrypoints": [
+      "index.ts"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nixxiecms/nixxie/tree/main/packages/auth-oauth"
+  }
+}

package/src/index.ts

@@ -0,0 +1,121 @@
+import { randomBytes } from 'node:crypto'
+import { providers as builtInProviders } from './providers'
+import type {
+  OAuthConfig,
+  OAuthProfile,
+  OAuthProviderConfig,
+  OAuthProviderDefinition,
+  OAuthTokens,
+} from './types'
+
+function resolveDefinition(cfg: OAuthProviderConfig): OAuthProviderDefinition {
+  if (cfg.definition) return cfg.definition
+  if (cfg.provider) return builtInProviders[cfg.provider]
+  throw new Error('OAuth provider config must specify either `provider` or `definition`')
+}
+
+export class OAuth {
+  private config: OAuthConfig
+
+  constructor(config: OAuthConfig) {
+    this.config = config
+  }
+
+  /** Names of the configured providers. */
+  list(): string[] {
+    return Object.keys(this.config.providers)
+  }
+
+  private get(name: string): { cfg: OAuthProviderConfig; def: OAuthProviderDefinition } {
+    const cfg = this.config.providers[name]
+    if (!cfg) throw new Error(`Unknown OAuth provider: ${name}`)
+    return { cfg, def: resolveDefinition(cfg) }
+  }
+
+  /** Generate a random `state` value to protect against CSRF. Persist it in the session. */
+  createState(): string {
+    return randomBytes(16).toString('hex')
+  }
+
+  /** Build the URL to redirect the user to in order to begin the flow. */
+  authorizationUrl(name: string, options?: { state?: string; extraParams?: Record<string, string> }): string {
+    const { cfg, def } = this.get(name)
+    const params = new URLSearchParams({
+      response_type: 'code',
+      client_id: cfg.clientId,
+      redirect_uri: cfg.redirectUri,
+      scope: (cfg.scopes ?? def.defaultScopes).join(' '),
+      ...(options?.state ? { state: options.state } : {}),
+      ...options?.extraParams,
+    })
+    return `${def.authorizationUrl}?${params}`
+  }
+
+  /** Exchange the authorization `code` returned to your callback for tokens. */
+  async exchangeCode(name: string, code: string): Promise<OAuthTokens> {
+    const { cfg, def } = this.get(name)
+    const res = await fetch(def.tokenUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        Accept: 'application/json',
+        // GitHub's API rejects requests without a User-Agent (HTTP 403); harmless for others.
+        'User-Agent': 'nixxie-cms-oauth',
+      },
+      body: new URLSearchParams({
+        grant_type: 'authorization_code',
+        code,
+        client_id: cfg.clientId,
+        client_secret: cfg.clientSecret,
+        redirect_uri: cfg.redirectUri,
+      }),
+    })
+    if (!res.ok) throw new Error(`OAuth token exchange failed (${res.status}): ${await res.text()}`)
+    const data: any = await res.json()
+    if (data.error) throw new Error(`OAuth token exchange error: ${data.error_description ?? data.error}`)
+    return {
+      accessToken: data.access_token,
+      refreshToken: data.refresh_token,
+      expiresIn: data.expires_in,
+      tokenType: data.token_type,
+      scope: data.scope,
+      idToken: data.id_token,
+    }
+  }
+
+  /** Fetch the normalised user profile using an access token. */
+  async fetchProfile(name: string, tokens: OAuthTokens): Promise<OAuthProfile> {
+    const { def } = this.get(name)
+    const res = await fetch(def.userInfoUrl, {
+      headers: {
+        Authorization: `Bearer ${tokens.accessToken}`,
+        Accept: 'application/json',
+        // GitHub's API rejects requests without a User-Agent (HTTP 403); harmless for others.
+        'User-Agent': 'nixxie-cms-oauth',
+      },
+    })
+    if (!res.ok) throw new Error(`OAuth userinfo failed (${res.status}): ${await res.text()}`)
+    return def.profile(await res.json())
+  }
+
+  /** Convenience: exchange the code and fetch the profile in one call. */
+  async callback(name: string, code: string): Promise<{ tokens: OAuthTokens; profile: OAuthProfile }> {
+    const tokens = await this.exchangeCode(name, code)
+    const profile = await this.fetchProfile(name, tokens)
+    return { tokens, profile }
+  }
+}
+
+export function createOAuth(config: OAuthConfig): OAuth {
+  return new OAuth(config)
+}
+
+export { builtInProviders as providers }
+export type {
+  OAuthConfig,
+  OAuthProviderConfig,
+  OAuthProviderDefinition,
+  OAuthProviderName,
+  OAuthProfile,
+  OAuthTokens,
+} from './types'

package/src/providers.ts

@@ -0,0 +1,84 @@
+import type { OAuthProviderDefinition, OAuthProviderName } from './types'
+
+export const providers: Record<OAuthProviderName, OAuthProviderDefinition> = {
+  google: {
+    authorizationUrl: 'https://accounts.google.com/o/oauth2/v2/auth',
+    tokenUrl: 'https://oauth2.googleapis.com/token',
+    userInfoUrl: 'https://openidconnect.googleapis.com/v1/userinfo',
+    defaultScopes: ['openid', 'email', 'profile'],
+    profile: raw => ({
+      id: raw.sub,
+      email: raw.email,
+      name: raw.name,
+      avatarUrl: raw.picture,
+      raw,
+    }),
+  },
+  github: {
+    authorizationUrl: 'https://github.com/login/oauth/authorize',
+    tokenUrl: 'https://github.com/login/oauth/access_token',
+    userInfoUrl: 'https://api.github.com/user',
+    defaultScopes: ['read:user', 'user:email'],
+    profile: raw => ({
+      id: String(raw.id),
+      email: raw.email,
+      name: raw.name ?? raw.login,
+      avatarUrl: raw.avatar_url,
+      raw,
+    }),
+  },
+  gitlab: {
+    authorizationUrl: 'https://gitlab.com/oauth/authorize',
+    tokenUrl: 'https://gitlab.com/oauth/token',
+    userInfoUrl: 'https://gitlab.com/api/v4/user',
+    defaultScopes: ['read_user'],
+    profile: raw => ({
+      id: String(raw.id),
+      email: raw.email,
+      name: raw.name ?? raw.username,
+      avatarUrl: raw.avatar_url,
+      raw,
+    }),
+  },
+  discord: {
+    authorizationUrl: 'https://discord.com/oauth2/authorize',
+    tokenUrl: 'https://discord.com/api/oauth2/token',
+    userInfoUrl: 'https://discord.com/api/users/@me',
+    defaultScopes: ['identify', 'email'],
+    profile: raw => ({
+      id: raw.id,
+      email: raw.email,
+      name: raw.global_name ?? raw.username,
+      avatarUrl: raw.avatar
+        ? `https://cdn.discordapp.com/avatars/${raw.id}/${raw.avatar}.png`
+        : undefined,
+      raw,
+    }),
+  },
+  microsoft: {
+    authorizationUrl: 'https://login.microsoftonline.com/common/oauth2/v2.0/authorize',
+    tokenUrl: 'https://login.microsoftonline.com/common/oauth2/v2.0/token',
+    userInfoUrl: 'https://graph.microsoft.com/oidc/userinfo',
+    defaultScopes: ['openid', 'email', 'profile'],
+    profile: raw => ({
+      id: raw.sub,
+      email: raw.email,
+      name: raw.name,
+      avatarUrl: raw.picture,
+      raw,
+    }),
+  },
+  facebook: {
+    authorizationUrl: 'https://www.facebook.com/v19.0/dialog/oauth',
+    tokenUrl: 'https://graph.facebook.com/v19.0/oauth/access_token',
+    userInfoUrl: 'https://graph.facebook.com/me?fields=id,name,email,picture',
+    defaultScopes: ['email', 'public_profile'],
+    profile: raw => ({
+      id: raw.id,
+      email: raw.email,
+      name: raw.name,
+      avatarUrl: raw.picture?.data?.url,
+      raw,
+    }),
+  },
+}

package/src/types.ts

@@ -0,0 +1,58 @@
+export type OAuthProviderName =
+  | 'google'
+  | 'github'
+  | 'gitlab'
+  | 'discord'
+  | 'microsoft'
+  | 'facebook'
+
+/** Endpoints + behaviour for an OAuth 2.0 / OpenID Connect provider. */
+export type OAuthProviderDefinition = {
+  /** Authorization endpoint (where the user is redirected to consent). */
+  authorizationUrl: string
+  /** Token endpoint (where the auth code is exchanged for tokens). */
+  tokenUrl: string
+  /** Userinfo endpoint used to fetch the profile. */
+  userInfoUrl: string
+  /** Default scopes requested when the caller doesn't override them. */
+  defaultScopes: string[]
+  /** Normalise the raw userinfo response into a common profile shape. */
+  profile: (raw: any) => OAuthProfile
+}
+
+export type OAuthProfile = {
+  /** Stable provider-specific user id. */
+  id: string
+  email?: string
+  name?: string
+  avatarUrl?: string
+  /** The untouched provider response. */
+  raw: any
+}
+
+export type OAuthTokens = {
+  accessToken: string
+  refreshToken?: string
+  expiresIn?: number
+  tokenType?: string
+  scope?: string
+  idToken?: string
+}
+
+export type OAuthProviderConfig = {
+  /** Built-in provider name, or omit and supply `definition` for a custom provider. */
+  provider?: OAuthProviderName
+  /** Custom provider definition (overrides `provider`). */
+  definition?: OAuthProviderDefinition
+  clientId: string
+  clientSecret: string
+  /** Redirect/callback URL registered with the provider. */
+  redirectUri: string
+  /** Override the provider's default scopes. */
+  scopes?: string[]
+}
+
+export type OAuthConfig = {
+  /** Map of named providers, keyed by however you want to reference them in routes. */
+  providers: Record<string, OAuthProviderConfig>
+}