@muze-nl/metro-oidc 0.6.0 → 0.9.0

package/docs/README.md

@@ -0,0 +1,30 @@
+---
+title: '@muze-nl/metro-oidc'
+---
+# @muze-nl/metro-oidc
+
+```sh
+npm install @muze-nl/metro-core @muze-nl/metro-oidc
+```
+
+```js
+import { client } from '@muze-nl/metro-core'
+import { oidcmw } from '@muze-nl/metro-oidc'
+
+const api = client('https://example.solidcommunity.net/')
+  .with(oidcmw({
+    issuer: 'https://solidcommunity.net/',
+    client_info: {
+      client_name: 'My Metro App',
+      redirect_uris: [location.href]
+    }
+  }))
+
+const result = api.get('foo')
+```
+
+Use this package when a resource is protected by OpenID Connect. It can discover the issuer metadata, dynamically register a client when supported, configure OAuth2, validate the ID token, and store the resulting ID token claims.
+
+## Reference
+
+See [reference](reference.md).

package/docs/reference.md

@@ -0,0 +1,97 @@
+---
+title: 'Reference'
+---
+# @muze-nl/metro-oidc reference
+
+```js
+import oidc, {
+  oidcmw,
+  discover,
+  register,
+  isRedirected,
+  idToken,
+  idTokenClaims,
+  oidcStore,
+  validateIdToken
+} from '@muze-nl/metro-oidc'
+```
+
+## `oidcmw(options)`
+
+```js
+const api = client('https://example.solidcommunity.net/')
+  .with(oidcmw({
+    issuer: 'https://solidcommunity.net/',
+    client_info: {
+      client_name: 'My Metro App',
+      redirect_uris: [location.href]
+    }
+  }))
+```
+
+Adds OpenID Connect authorization to a Metro client. By default it tries the request first and authorizes after a `401` or `403`. Set `force_authorization: true` to authorize immediately.
+
+Important options: `issuer`, `client_info`, `client`, `openid_configuration`, `oauth2`, `store`, `scope`, `nonce`, `use_dpop`, `force_authorization`, and `authorize_callback`.
+
+`use_dpop` defaults to `true`. Disable it only for providers or tests that do not support DPoP.
+
+## `discover(options)`
+
+```js
+const config = await discover({ issuer: 'https://solidcommunity.net/' })
+```
+
+Fetches OIDC discovery metadata. Pass a Metro client with `client` when you want custom middleware or tests.
+
+## `register(options)`
+
+```js
+const info = await register({
+  registration_endpoint: config.registration_endpoint,
+  client_info: {
+    client_name: 'My Metro App',
+    redirect_uris: [location.href]
+  }
+})
+```
+
+Performs dynamic client registration and returns client information. `oidcmw()` calls this automatically when no `client_info.client_id` is present and the issuer supports registration.
+
+## ID token helpers
+
+```js
+const raw = idToken({ issuer: 'https://solidcommunity.net/' })
+const claims = idTokenClaims({ issuer: 'https://solidcommunity.net/' })
+```
+
+Returns the stored raw ID token or validated claims. Pass the same `issuer` or `store` used by the middleware.
+
+## `validateIdToken(idToken, options)`
+
+```js
+const validation = await validateIdToken(idToken, {
+  issuer: config.issuer,
+  client_id: clientInfo.client_id,
+  jwks,
+  openid_configuration: config,
+  nonce
+})
+```
+
+Validates the token signature and standard claims, including issuer, audience, expiry, required claims, and nonce.
+
+## Store
+
+```js
+const store = oidcStore('https://solidcommunity.net/')
+```
+
+Creates a simple storage object backed by `localStorage` when available or memory otherwise.
+
+## Test mock server
+
+```js
+import oidcmockserver from '@muze-nl/metro-oidc/testing'
+```
+
+The mock server exposes discovery metadata, dynamic client registration, JWKS, signed ID tokens, userinfo, and OAuth2-backed protected-resource behaviour for tests.

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@muze-nl/metro-oidc",
-  "version": "0.6.0",
+  "version": "0.9.0",
   "description": "oidc client middleware for @muze-nl/metro",
   "type": "module",
   "source": [
     "src/browser.mjs"
   ],
-  "main": "src/browser.mjs",
+  "main": "src/index.mjs",
   "targets": {
     "default": {
       "distDir": "./dist",
@@ -18,23 +18,28 @@
     "test": "test"
   },
   "scripts": {
-    "test": "tap test/*.mjs",
+    "test": "tap --disable-coverage --jobs=1 test/*.mjs",
     "tap": "tap",
-    "build": "npx esbuild --bundle src/browser.mjs --outfile=dist/browser.min.js --minify --sourcemap",
-    "build-dev": "npx esbuild --bundle src/browser.mjs --outfile=dist/browser.js --sourcemap"
+    "build": "esbuild --bundle src/browser.mjs --outfile=dist/browser.min.js --minify --sourcemap",
+    "build-dev": "esbuild --bundle src/browser.mjs --outfile=dist/browser.js --sourcemap",
+    "build:dev": "esbuild --bundle src/browser.mjs --outfile=dist/browser.js --sourcemap"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/muze-nl/metro-oidc.git"
+    "url": "git+https://github.com/muze-nl/metro.git",
+    "directory": "packages/metro-oidc"
   },
   "author": "auke@muze.nl",
   "license": "MIT",
   "bugs": {
-    "url": "https://github.com/muze-nl/metro-oidc/issues"
+    "url": "https://github.com/muze-nl/metro/issues"
   },
-  "homepage": "https://github.com/muze-nl/metro-oidc/#readme",
+  "homepage": "https://github.com/muze-nl/metro/tree/main/packages/metro-oidc#readme",
   "devDependencies": {
-    "eslint": "^8.13.0"
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.5.0",
+    "globals": "^17.7.0",
+    "tap": "^21.7.4"
   },
   "engines": {
     "node": ">=20.0.0"
@@ -43,11 +48,39 @@
     "/src",
     "/dist",
     "/LICENSE",
-    "/README.md"
+    "/README.md",
+    "/docs"
   ],
   "dependencies": {
-    "@muze-nl/assert": "^0.5.1",
-    "@muze-nl/metro": "^0.6.20",
-    "@muze-nl/metro-oauth2": "^0.8.1"
-  }
+    "@muze-nl/assert": "^0.6.0",
+    "@muze-nl/metro-core": "^0.9.0",
+    "@muze-nl/metro-middleware": "^0.9.0",
+    "@muze-nl/metro-oauth2": "^0.9.0",
+    "jose": "^6.2.3"
+  },
+  "exports": {
+    ".": "./src/index.mjs",
+    "./browser": "./src/browser.mjs",
+    "./browser.mjs": "./src/browser.mjs",
+    "./middleware": "./src/oidcmw.mjs",
+    "./middleware.mjs": "./src/oidcmw.mjs",
+    "./oidcmw": "./src/oidcmw.mjs",
+    "./oidcmw.mjs": "./src/oidcmw.mjs",
+    "./discovery": "./src/oidc.discovery.mjs",
+    "./discovery.mjs": "./src/oidc.discovery.mjs",
+    "./register": "./src/oidc.register.mjs",
+    "./register.mjs": "./src/oidc.register.mjs",
+    "./store": "./src/oidc.store.mjs",
+    "./store.mjs": "./src/oidc.store.mjs",
+    "./jwt": "./src/oidc.jwt.mjs",
+    "./jwt.mjs": "./src/oidc.jwt.mjs",
+    "./testing": "./src/testing.mjs",
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "sideEffects": [
+    "./src/browser.mjs",
+    "./dist/browser.js",
+    "./dist/browser.min.js"
+  ]
 }

package/src/browser.mjs

@@ -1,19 +1,13 @@
-import metro from '@muze-nl/metro'
-import oauth2 from '@muze-nl/metro-oauth2'
-import oidcDiscover from './oidc.discovery.mjs'
-import oidcRegister from './oidc.register.mjs'
-import oidcmw, {isRedirected, idToken} from './oidcmw.mjs'
+import * as core from '@muze-nl/metro-core'
+import oidc from './index.mjs'
 
-const oidc = {
-	oidcmw,
-	discover: oidcDiscover,
-	register: oidcRegister,
-	isRedirected,
-	idToken
-}
+const metro = Object.assign({}, core, globalThis.metro || {})
 
-if (!globalThis.metro.oidc) {
-	globalThis.metro.oidc = oidc
+if (!metro.oidc) {
+	metro.oidc = oidc
 }
 
-export default oidc
+globalThis.metro = metro
+
+export * from './index.mjs'
+export default oidc

package/src/index.mjs

@@ -0,0 +1,20 @@
+import oidcmw, { isRedirected, idToken, idTokenClaims } from './oidcmw.mjs'
+import discover from './oidc.discovery.mjs'
+import register from './oidc.register.mjs'
+
+const oidc = {
+	oidcmw,
+	discover,
+	register,
+	isRedirected,
+	idToken,
+	idTokenClaims
+}
+
+export default oidc
+export { default as oidcmw } from './oidcmw.mjs'
+export { isRedirected, idToken, idTokenClaims } from './oidcmw.mjs'
+export { default as discover } from './oidc.discovery.mjs'
+export { default as register } from './oidc.register.mjs'
+export { default as oidcStore } from './oidc.store.mjs'
+export { validateIdToken } from './oidc.jwt.mjs'

package/src/oidc.discovery.mjs

@@ -2,9 +2,9 @@
  * This module adheres to OpenID Connect Discovery 1.0 incorporating errata set 2 - december 15, 2023
  * https://openid.net/specs/openid-connect-discovery-1_0.html
  */
-import metro from '@muze-nl/metro'
-import jsonmw from '@muze-nl/metro/src/mw/json.mjs'
-import throwermw from '@muze-nl/metro/src/mw/thrower.mjs'
+import * as metro from '@muze-nl/metro-core'
+import jsonmw from '@muze-nl/metro-middleware/json'
+import throwermw from '@muze-nl/metro-middleware/thrower'
 import { validJWA, MustInclude, validAuthMethods } from './oidc.util.mjs'
 import { assert, fails, Required, Recommended, Optional, oneOf, anyOf, allOf, validURL, instanceOf, not, error } from '@muze-nl/assert'
 
@@ -29,6 +29,7 @@ export default async function oidcDiscovery(options={}) {
 	}
 
 	options = Object.assign({},defaultOptions,options)
+	options.client = options.client.with(throwermw()).with(jsonmw())
 
 	const TestSucceeded = false
 	function MustUseHTTPS(url) {

package/src/oidc.jwt.mjs

@@ -0,0 +1,65 @@
+import { createLocalJWKSet, jwtVerify } from 'jose'
+import * as metro from '@muze-nl/metro-core'
+
+const jwksCache = new WeakMap()
+
+function keySetFor(jwks) {
+	if (!jwks || !Array.isArray(jwks.keys)) {
+		throw metro.metroError('metro.oidc: Error: jwks must be an object with a keys array')
+	}
+	if (!jwksCache.has(jwks)) {
+		jwksCache.set(jwks, createLocalJWKSet(jwks))
+	}
+	return jwksCache.get(jwks)
+}
+
+function supportedAlgorithms(openidConfiguration = {}) {
+	const algorithms = openidConfiguration.id_token_signing_alg_values_supported
+	if (Array.isArray(algorithms) && algorithms.length) {
+		return algorithms.filter(algorithm => algorithm !== 'none')
+	}
+	return ['RS256']
+}
+
+/**
+ * Validate an OpenID Connect ID Token.
+ *
+ * This intentionally keeps jose behind a tiny Metro/OIDC helper so the public
+ * OIDC middleware API can stay small while still delegating JWT/JWS/JWKS
+ * validation to a mature library.
+ */
+export async function validateIdToken(idToken, options = {}) {
+	if (!idToken) {
+		throw metro.metroError('metro.oidc: Error: token response did not include an id_token')
+	}
+	if (!options.jwks) {
+		throw metro.metroError('metro.oidc: Error: cannot validate id_token without jwks')
+	}
+	if (!options.issuer) {
+		throw metro.metroError('metro.oidc: Error: cannot validate id_token without issuer')
+	}
+	if (!options.client_id) {
+		throw metro.metroError('metro.oidc: Error: cannot validate id_token without client_id')
+	}
+
+	const { payload, protectedHeader } = await jwtVerify(
+		idToken,
+		keySetFor(options.jwks),
+		{
+			issuer: options.issuer,
+			audience: options.client_id,
+			algorithms: options.algorithms || supportedAlgorithms(options.openid_configuration),
+			clockTolerance: options.clockTolerance ?? 60,
+			requiredClaims: ['iss', 'sub', 'aud', 'exp', 'iat']
+		}
+	)
+
+	if (options.nonce !== undefined && payload.nonce !== options.nonce) {
+		throw metro.metroError('metro.oidc: Error: id_token nonce mismatch')
+	}
+
+	return {
+		header: protectedHeader,
+		claims: payload
+	}
+}

package/src/oidc.mockserver.mjs

@@ -0,0 +1,195 @@
+import * as metro from '@muze-nl/metro-core'
+import oauth2mockserver from '@muze-nl/metro-oauth2/testing'
+import { exportJWK, generateKeyPair, SignJWT } from 'jose'
+
+const defaultIssuer = 'https://issuer.example/'
+const defaultRedirectUri = 'https://client.example/callback'
+const jsonHeaders = {
+	'Content-Type': 'application/json'
+}
+const textHeaders = {
+	'Content-Type': 'text/plain'
+}
+
+function jsonResponse(body, status = 200, statusText = 'OK') {
+	return metro.response({
+		status,
+		statusText,
+		headers: jsonHeaders,
+		body: JSON.stringify(body)
+	})
+}
+
+function errorResponse(error, description, status = 400) {
+	return jsonResponse({
+		error,
+		error_description: description
+	}, status, status === 401 ? 'Unauthorized' : 'Bad Request')
+}
+
+async function requestData(req) {
+	if (req.data instanceof URLSearchParams) {
+		return Object.fromEntries(req.data.entries())
+	}
+	if (req.data && typeof req.data === 'object') {
+		return req.data
+	}
+	if (!req.body) {
+		return {}
+	}
+	const text = await req.clone().text()
+	try {
+		return JSON.parse(text)
+	} catch (e) {
+		return Object.fromEntries(new URLSearchParams(text).entries())
+	}
+}
+
+/**
+ * Small OIDC provider mock for Metro tests.
+ *
+ * It exposes discovery metadata, dynamic client registration, userinfo, JWKS
+ * and delegates the OAuth2 authorization/token/protected-resource endpoints to
+ * the OAuth2 mock server. Its token endpoint returns real signed ID Tokens so
+ * the OIDC client tests exercise actual JWT/JWS/JWKS validation.
+ */
+export default function oidcmockserver(options = {}) {
+	options = Object.assign({
+		issuer: defaultIssuer,
+		client_id: 'mockClientId',
+		client_secret: 'mockClientSecret',
+		redirect_uri: defaultRedirectUri,
+		sub: 'mockSubject',
+		alg: 'RS256',
+		kid: 'mock-signing-key',
+		publishSigningKey: true,
+		idTokenClaims: {}
+	}, options)
+
+	const issuer = metro.url(options.issuer)
+	const keyPair = createSigningKey(options)
+	const oauth2 = oauth2mockserver({
+		client_id: options.client_id,
+		client_secret: options.client_secret,
+		redirect_uri: options.redirect_uri,
+		scope: 'openid profile email',
+		id_token: tokenContext => idToken(tokenContext),
+		requirePKCE: options.requirePKCE ?? false
+	})
+	const clients = new Map()
+
+	return async (req, next) => {
+		const url = metro.url(req.url)
+		switch (url.pathname) {
+			case '/.well-known/openid-configuration':
+				return discovery()
+			case '/register/':
+			case '/register':
+				return register(req)
+			case '/userinfo/':
+			case '/userinfo':
+				return userinfo(req)
+			case '/jwks/':
+			case '/jwks':
+				return jwks()
+			default:
+				return oauth2(req, next)
+		}
+	}
+
+	function endpoint(path) {
+		return metro.url(issuer, path).href
+	}
+
+	function discovery() {
+		return jsonResponse({
+			issuer: issuer.href,
+			authorization_endpoint: endpoint('/authorize/'),
+			token_endpoint: endpoint('/token/'),
+			userinfo_endpoint: endpoint('/userinfo/'),
+			jwks_uri: endpoint('/jwks/'),
+			registration_endpoint: endpoint('/register/'),
+			scopes_supported: ['openid', 'profile', 'email'],
+			response_types_supported: ['code', 'id_token', 'id_token token'],
+			grant_types_supported: ['authorization_code', 'refresh_token'],
+			subject_types_supported: ['public'],
+			id_token_signing_alg_values_supported: [options.alg],
+			claims_supported: ['iss', 'sub', 'aud', 'exp', 'iat', 'nonce', 'name', 'email']
+		})
+	}
+
+	async function jwks() {
+		if (!options.publishSigningKey) {
+			return jsonResponse({ keys: [] })
+		}
+		const { publicKey } = await keyPair
+		const jwk = await exportJWK(publicKey)
+		jwk.kid = options.jwksKid || options.kid
+		jwk.alg = options.alg
+		jwk.use = 'sig'
+		return jsonResponse({ keys: [jwk] })
+	}
+
+	async function register(req) {
+		if (req.method !== 'POST') {
+			return errorResponse('invalid_request', 'registration endpoint requires POST')
+		}
+		const body = await requestData(req)
+		if (!Array.isArray(body.redirect_uris) || body.redirect_uris.length === 0) {
+			return errorResponse('invalid_client_metadata', 'redirect_uris is required')
+		}
+		const info = {
+			...body,
+			client_id: options.client_id,
+			client_id_issued_at: Math.floor(Date.now() / 1000),
+			token_endpoint_auth_method: options.client_secret ? 'client_secret_post' : 'none'
+		}
+		if (options.client_secret) {
+			info.client_secret = options.client_secret
+		}
+		clients.set(info.client_id, info)
+		return jsonResponse(info, 201, 'Created')
+	}
+
+	function userinfo(req) {
+		const auth = req.headers.get('Authorization')
+		if (auth !== 'Bearer mockAccessToken') {
+			return metro.response({
+				status: 401,
+				statusText: 'Unauthorized',
+				headers: textHeaders,
+				body: '401 Unauthorized'
+			})
+		}
+		return jsonResponse({
+			sub: options.sub,
+			name: 'Mock User',
+			email: 'mock@example.test'
+		})
+	}
+
+	async function idToken(tokenContext = {}) {
+		const now = Math.floor(Date.now() / 1000)
+		const authorization = tokenContext.authorization || {}
+		const claims = {
+			iss: issuer.href,
+			sub: options.sub,
+			aud: options.client_id,
+			exp: now + 3600,
+			iat: now,
+			...(authorization.nonce ? { nonce: authorization.nonce } : {}),
+			...options.idTokenClaims
+		}
+		const { privateKey } = await keyPair
+		return new SignJWT(claims)
+			.setProtectedHeader({ alg: options.alg, kid: options.kid })
+			.sign(privateKey)
+	}
+}
+
+function createSigningKey(options) {
+	return generateKeyPair(options.alg, {
+		extractable: true,
+		modulusLength: 2048
+	})
+}

package/src/oidc.register.mjs

@@ -3,9 +3,9 @@
  * incorporating errata set 2 - december 15, 2023
  * https://openid.net/specs/openid-connect-registration-1_0.html
  */
-import metro from '@muze-nl/metro'
-import jsonmw from '@muze-nl/metro/src/mw/json.mjs'
-import throwermw from '@muze-nl/metro/src/mw/thrower.mjs'
+import * as metro from '@muze-nl/metro-core'
+import jsonmw from '@muze-nl/metro-middleware/json'
+import throwermw from '@muze-nl/metro-middleware/thrower'
 import { validJWA, validAuthMethods, MustHave } from './oidc.util.mjs'
 import { assert, Required, Optional, oneOf, anyOf, validURL, validEmail, not, instanceOf } from '@muze-nl/assert'
 
@@ -60,6 +60,7 @@ export default async function register(options)
 	}
 
 	options = Object.assign({}, defaultOptions, options)
+	options.client = options.client.with(throwermw()).with(jsonmw())
 	if (!options.client_info) {
 		options.client_info = {}
 	} 
@@ -71,8 +72,8 @@ export default async function register(options)
 			body: options.client_info
 		})
 	let info = response.data
-	if (!info.client_id || !info.client_secret) {
-		throw metro.metroError('metro.oidc: Error: dynamic registration of client failed, no client_id or client_secret returned', response)
+	if (!info.client_id) {
+		throw metro.metroError('metro.oidc: Error: dynamic registration of client failed, no client_id returned', response)
 	}
 	options.client_info = Object.assign(options.client_info, info)
 	return options.client_info

package/src/oidc.util.mjs

@@ -30,5 +30,5 @@ export const validJWA = [
 
 //TODO: add link to spec
 export const validAuthMethods = [
-	'client_secret_post', 'client_secret_basic','client_secret_jwt','private_key_jwt'
+	'none', 'client_secret_post', 'client_secret_basic','client_secret_jwt','private_key_jwt'
 ]