@sviy/authglue 0.0.0-stage → 1.0.2

package/README

@@ -0,0 +1,94 @@
+# @sviy/authglue
+
+OIDC authentication glue for Express apps.
+
+Wraps [`openid-client`](https://www.npmjs.com/package/openid-client) and [`express-session`](https://www.npmjs.com/package/express-session) into a single setup call. Your app redirects to any OIDC provider, handles the callback, creates a session, and gives you back `req.session.user`. No auth boilerplate per app.
+
+## Install
+
+```sh
+npm install @sviy/authglue
+```
+
+## Usage
+
+```js
+import express from 'express';
+import { setupAuth } from '@sviy/authglue';
+
+const app = express();
+
+const requireAuth = await setupAuth(app, {
+  issuerUrl: process.env.IDP_ISSUER,
+  clientId: process.env.IDP_CLIENT_ID,
+  clientSecret: process.env.IDP_CLIENT_SECRET,
+  callbackUrl: `${process.env.HOST}/callback`,
+  sessionSecret: process.env.SESSION_SECRET,
+  sessionPath: '/app/data/.session',
+  secure: true,
+  successRedirect: '/dashboard',
+});
+
+app.get('/dashboard', requireAuth, (req, res) => {
+  res.render('dashboard', { user: req.session.user });
+});
+
+app.listen(3000);
+```
+
+## Configuration
+
+| Field | Required | Description |
+|---|---|---|
+| `issuerUrl` | Yes | OIDC provider issuer URL (e.g. `https://rauthy.example.com`) |
+| `clientId` | Yes | Client ID registered with the OIDC provider |
+| `clientSecret` | Yes | Client secret registered with the OIDC provider |
+| `callbackUrl` | Yes | Redirect URI registered with the provider |
+| `sessionSecret` | Yes | Secret used to sign session cookies |
+| `sessionPath` | No | Where to persist session files. Default: `./sessions` |
+| `scopes` | No | OIDC scopes to request. Default: `openid profile email offline_access` |
+| `secure` | No | Set `true` to enable Secure cookies (requires HTTPS). Default: `false` |
+| `loginPath` | No | Route that triggers login. Default: `/login` |
+| `callbackPath` | No | Route the provider redirects to. Default: `/callback` |
+| `logoutPath` | No | Route that triggers logout. Default: `/logout` |
+| `successRedirect` | No | Where to send the user after successful login. Default: `/` |
+
+## How It Works
+
+1. User visits a protected route without a session
+2. `requireAuth` redirects to `/login`
+3. `authglue` generates PKCE verifier + state, redirects to the OIDC provider
+4. User authenticates at the provider (password, passkey, 2FA — whatever the provider supports)
+5. Provider redirects back to `/callback`
+6. `authglue` exchanges the authorization code for tokens, creates an Express session
+7. User is redirected to `successRedirect` with `req.session.user` populated
+
+## Provider-Agnostic
+
+Works with any OIDC-compatible provider:
+
+- Rauthy
+- Autentico
+- Pocket ID
+- Keycloak
+- Zitadel
+- Auth0
+- Okta
+- Google
+- Any other OIDC provider
+
+Switching providers means changing `issuerUrl`, `clientId`, and `clientSecret`. Nothing else.
+
+## What This Package Does Not Do
+
+- Does not store users or passwords — that's the IdP's job
+- Does not provide an admin UI or login page — the IdP renders those
+- Does not implement OIDC protocol details — [`openid-client`](https://www.npmjs.com/package/openid-client) does that
+- Does not handle 2FA or passkeys — the IdP handles those
+
+This package is the glue between your Express app and your OIDC provider. Nothing more.
+
+## License
+
+MIT
+No responsibility, liability ro warranty.  Use at your risk.

package/index.js

@@ -0,0 +1,83 @@
+import * as client from 'openid-client';
+import session from 'express-session';
+import FileStore from 'session-file-store';
+
+export async function setupAuth(app, config) {
+  // ── Sessions ──────────────────────────
+  app.use(session({
+    secret: config.sessionSecret,
+    resave: false,
+    saveUninitialized: false,
+    store: new FileStore({ path: config.sessionPath }),
+    cookie: {
+      httpOnly: true,
+      sameSite: 'lax',
+      secure: config.secure ?? false,
+    },
+  }));
+
+  // ── Discover the IdP ───────────────────
+  const issuer = await client.discovery(
+    new URL(config.issuerUrl),
+    config.clientId,
+    config.clientSecret,
+  );
+
+  const oidcClient = new issuer.Client({
+    client_id: config.clientId,
+    client_secret: config.clientSecret,
+    redirect_uris: [config.callbackUrl],
+    response_types: ['code'],
+  });
+
+  // ── Login ─────────────────────────────
+  app.get(config.loginPath || '/login', (req, res) => {
+    const verifier = client.randomPKCECodeVerifier();
+    const challenge = await client.calculatePKCECodeChallenge(verifier);
+    const state = client.randomState();
+
+    req.session.pkce = { verifier, state };
+    req.session.save();
+
+    res.redirect(client.buildAuthorizationUrl(oidcClient, {
+      scope: config.scopes || 'openid profile email offline_access',
+      state,
+      code_challenge: challenge,
+      code_challenge_method: 'S256',
+      redirect_uri: config.callbackUrl,
+    }));
+  });
+
+  // ── Callback ───────────────────────────
+  app.get(config.callbackPath || '/callback', async (req, res) => {
+    const { pkce } = req.session;
+    if (!pkce) return res.status(400).send('Session expired. Try again.');
+
+    const tokens = await client.authorizationCodeGrant(
+      oidcClient,
+      new URL(`${req.protocol}://${req.get('host')}${req.originalUrl}`),
+      { pkceCodeVerifier: pkce.verifier, expectedState: pkce.state },
+    );
+
+    req.session.user = tokens.claims();
+    req.session.tokens = tokens;
+    delete req.session.pkce;
+
+    res.redirect(config.successRedirect || '/');
+  });
+
+  // ── Logout ───────────────────────────
+  app.get(config.logoutPath || '/logout', (req, res) => {
+    const logoutUrl = client.buildEndSessionUrl(oidcClient, {
+      id_token_hint: req.session.tokens?.id_token,
+      post_logout_redirect_uri: config.postLogoutUrl || config.successRedirect || '/',
+    });
+    req.session.destroy(() => res.redirect(logoutUrl));
+  });
+
+  // ── Auth guard ───────────────────────
+  return function requireAuth(req, res, next) {
+    if (req.session?.user) return next();
+    res.redirect(config.loginPath || '/login');
+  };
+}

package/package.json

@@ -1,6 +1,24 @@
 {
   "name": "@sviy/authglue",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.2",
+  "description": "OIDC auth glue for Express apps",
+  "keywords": [
+    "oidc",
+    "oauth",
+    "auth",
+    "express",
+    "sso"
+  ],
+  "license": "MIT",
+  "author": "sviy",
+  "type": "module",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "dependencies": {
+    "openid-client": "^6.8.8",
+    "express-session": "^1.19.0",
+    "session-file-store": "^1.5.0"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.