@zelavis/app-auth-oidc 2.0.0-alpha.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ivan Jeremic
+
+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,36 @@
+# @zelavis/app-auth-oidc
+
+An ordinary Zelavis auth plugin for validating OIDC access tokens through the
+native `Request` authentication contract. It verifies issuer, audience,
+algorithm allow-lists, signatures, and remote JWKS keys before mapping claims
+to a Zelavis principal.
+
+The optional `authorizationCode` configuration enables endpoint-backed login
+and explicit account linking. Zelavis creates short-lived one-time flow state,
+binds callbacks to state and nonce, uses S256 PKCE, verifies the returned ID
+token against issuer/audience/algorithm/JWKS constraints, and never links an
+existing account merely because an email address matches.
+
+```ts
+import { oidcBearerService } from "@zelavis/app-auth-oidc";
+
+export const service = oidcBearerService({
+  issuer: "https://identity.example.com",
+  audience: "zelavis-project",
+  jwksUrl: "https://identity.example.com/.well-known/jwks.json",
+  authorizationCode: {
+    clientId: "zelavis-project",
+    authorizationEndpoint: "https://identity.example.com/oauth2/authorize",
+    tokenEndpoint: "https://identity.example.com/oauth2/token",
+    redirectUri: "https://app.example.com/zelavis/api/v1/auth/oauth/oidc/callback",
+  },
+});
+```
+
+The plugin requires explicit issuer, audience, JWKS URL, and an algorithm
+allow-list (or its conservative asymmetric default). It never accepts an
+unsigned token or derives trust from unverified token claims.
+
+Login starts at `POST /auth/oauth/oidc/start`. Authenticated accounts can start
+an explicit link at `POST /auth/oauth/oidc/link/start`; both complete through
+`GET /auth/oauth/oidc/callback`.

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+import { type ZelavisPrincipal } from "zelavis/core";
+/**
+ * Accepts JWT bearer tokens issued by an external OpenID Connect provider.
+ *
+ * This is machine-to-machine access: a caller already holding a token from the
+ * issuer presents it, and the token is verified against the issuer's key set.
+ * No sign-in happens here and no account is created.
+ *
+ * Browser sign-in is a different thing and lives in `@zelavis/auth`, which
+ * runs the Authorization Code flow through core auth and creates real
+ * accounts. This package used to carry a second implementation of that flow;
+ * two implementations of one exchange drift, and only one of them can be the
+ * one an operator has configured.
+ */
+export interface OidcBearerPluginOptions {
+    providerName?: string;
+    issuer: string;
+    audience: string | readonly string[];
+    jwksUrl: string | URL;
+    algorithms?: readonly string[];
+    mapPrincipal?: (claims: Readonly<Record<string, unknown>>) => ZelavisPrincipal | undefined | Promise<ZelavisPrincipal | undefined>;
+}
+export declare function oidcBearerService(options: OidcBearerPluginOptions): Readonly<{
+    name: "@zelavis/auth-oidc";
+    kind: "plugin";
+    capabilities: readonly string[];
+    authenticators: import("zelavis/core").ZelavisRequestAuthenticator<unknown>[];
+    service: {
+        name: string;
+        register(): void;
+    };
+}>;

package/dist/index.js

@@ -0,0 +1,30 @@
+import { createJwksAuthenticator, } from "zelavis/core";
+export function oidcBearerService(options) {
+    const issuer = options.issuer.replace(/\/$/u, "");
+    return Object.freeze({
+        name: "@zelavis/auth-oidc",
+        kind: "plugin",
+        capabilities: Object.freeze(["zelavis/identity:credentials"]),
+        authenticators: [
+            createJwksAuthenticator({
+                name: options.providerName ?? "oidc",
+                issuer,
+                audience: options.audience,
+                algorithms: options.algorithms ?? ["RS256", "ES256", "EdDSA"],
+                jwksUrl: options.jwksUrl,
+                async mapPrincipal(payload) {
+                    if (options.mapPrincipal)
+                        return options.mapPrincipal(payload);
+                    if (typeof payload.sub !== "string" || !payload.sub)
+                        return undefined;
+                    return {
+                        id: payload.sub,
+                        type: "user",
+                        metadata: { issuer: payload.iss, authentication: "oidc" },
+                    };
+                },
+            }),
+        ],
+        service: { name: options.providerName ?? "oidc", register() { } },
+    });
+}

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@zelavis/app-auth-oidc",
+  "version": "2.0.0-alpha.3",
+  "private": false,
+  "description": "OIDC/JWKS bearer authentication plugin for Zelavis.",
+  "license": "MIT",
+  "author": "Ivan Jeremic",
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "zelavis": {
+    "kind": "plugin",
+    "capabilities": [
+      "zelavis/identity:credentials"
+    ],
+    "namespace": "oidc",
+    "marketplace": {
+      "title": "OpenID Connect Sign-in",
+      "summary": "Let people sign in with any OpenID Connect provider, or verify bearer tokens from one.",
+      "categories": [
+        "auth",
+        "identity",
+        "official"
+      ],
+      "tags": [
+        "oidc",
+        "jwks",
+        "sso"
+      ]
+    }
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zelavis/zelavis.git",
+    "directory": "zelavis-services/auth-oidc"
+  },
+  "homepage": "https://github.com/zelavis/zelavis/tree/main/zelavis-services/auth-oidc#readme",
+  "bugs": {
+    "url": "https://github.com/zelavis/zelavis/issues"
+  },
+  "peerDependencies": {
+    "zelavis": ">=2.0.0-alpha.4"
+  },
+  "dependencies": {
+    "jose": "^6.2.12"
+  },
+  "devDependencies": {
+    "typescript": "^7.0.2",
+    "zelavis": "2.0.0-alpha.4"
+  },
+  "keywords": [
+    "auth",
+    "oauth",
+    "oidc",
+    "jwt",
+    "jwks"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "pnpm run typecheck"
+  }
+}