oidc-remote 0.0.0-stage → 0.1.0-rc2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rafael Gaspar
+
+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

@@ -1,3 +1,90 @@
-# Temporary Holding Version
+# oidc-remote
 
-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.
+Attach a live OAuth2 access token on the hop to a remote HTTPS server.
+
+`oidc-remote` is a **local** process (or library) that gets and refreshes an access token, then injects it as `Authorization: Bearer`. It does not implement an OpenID Provider, and it is not a full OIDC relying party.
+
+The token request is `client_credentials` with a JWT `client_assertion` (for example a projected Kubernetes ServiceAccount token). Any token endpoint that accepts that grant works.
+
+## Install
+
+```bash
+npm install oidc-remote
+```
+
+Node.js 22+.
+
+## Library
+
+```ts
+import { TokenClient } from "oidc-remote";
+
+const tokens = new TokenClient({
+  tokenUrl: "https://idp.example/token",
+  clientId: "cluster-mcp.example.test",
+  assertionFile: "/var/run/secrets/tokens/oidc",
+});
+
+const accessToken = await tokens.getAccessToken();
+```
+
+`getAccessToken()` reads the assertion file on each exchange (the projected token is rotated in place), POSTs `grant_type=client_credentials` with `client_assertion`, and caches the access token until 80% of `expires_in`. A failed exchange throws `TokenExchangeError` — it does not mint a fallback token.
+
+Default scope is `openid profile entitlements`. Default assertion path is `/var/run/secrets/tokens/oidc`.
+
+Callers that already speak HTTPS should use `TokenClient` directly and keep the real hostname on the request so TLS SNI and `:authority` match the gateway.
+
+## CLI
+
+### `stdio`
+
+For MCP clients that spawn a command (Cursor `mcp.json`, Claude `mcpServers`):
+
+```json
+"cluster": {
+  "command": "oidc-remote",
+  "args": [
+    "stdio",
+    "--gateway", "cluster-mcp.example.test",
+    "--token-url", "https://idp.example/token"
+  ]
+}
+```
+
+Stdio to the parent, Streamable HTTP to `https://<gateway>/mcp` (MCP SDK transports, same hop as mcp-remote). `authProvider.token()` runs before every HTTP request so the Bearer can refresh. SNI and Host are the gateway hostname.
+
+### `proxy`
+
+For HTTP clients that freeze a URL or API key at construct time:
+
+```bash
+oidc-remote proxy \
+  --gateway ai.example.test \
+  --token-url https://idp.example/token \
+  --listen 127.0.0.1:8080
+```
+
+Point the app at `http://127.0.0.1:8080` (plaintext loopback). The proxy injects Bearer and forwards to `https://<gateway>` with that hostname as SNI/Host.
+
+### Flags
+
+| Flag | Env | Default |
+|---|---|---|
+| `--gateway` | | *(required)* hostname; also the OAuth `client_id` unless `--client-id` is set |
+| `--token-url` | `OIDC_REMOTE_TOKEN_URL` | *(required)* |
+| `--assertion-file` | `OIDC_REMOTE_ASSERTION_FILE` | `/var/run/secrets/tokens/oidc` |
+| `--scope` | `OIDC_REMOTE_SCOPE` | `openid profile entitlements` |
+| `--client-id` | | `--gateway` |
+| `--url` | | `https://<gateway>/mcp` (`stdio`) |
+| `--mcp-path` | | `/mcp` |
+| `--upstream` | | `https://<gateway>` (`proxy`) |
+| `--listen` | | `127.0.0.1:8080` (`proxy`) |
+
+## What this is not
+
+- Not an OIDC stack. No authorization-code browser flow, no DCR, no PKCE.
+- Assertion JWTs never go to the gateway. They are only exchanged at the token URL.
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+export type Command = "stdio" | "proxy";
+export type CliOptions = {
+    command: Command;
+    gateway: string;
+    clientId: string;
+    tokenUrl: string;
+    assertionFile: string;
+    scope: string;
+    url: string;
+    upstream: string;
+    listenHost: string;
+    listenPort: number;
+};
+export declare function parseArgs(argv: string[], env?: NodeJS.ProcessEnv): CliOptions;
+export declare function main(argv?: string[], env?: NodeJS.ProcessEnv): Promise<void>;

package/dist/cli.js

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+import { pathToFileURL } from "node:url";
+import { createProxyServer, listen } from "./proxy.js";
+import { runStdio } from "./stdio.js";
+import { DEFAULT_ASSERTION_FILE, DEFAULT_SCOPE, TokenClient } from "./token.js";
+function nextValue(argv, i, flag) {
+    const value = argv[i];
+    if (value === undefined || value.length === 0)
+        throw new Error(`${flag} requires a value`);
+    return value;
+}
+function envValue(env, name) {
+    const value = env[name];
+    return value && value.length > 0 ? value : undefined;
+}
+function parseListen(value) {
+    const idx = value.lastIndexOf(":");
+    if (idx <= 0)
+        throw new Error(`--listen requires host:port, got ${value}`);
+    const host = value.slice(0, idx);
+    const port = Number(value.slice(idx + 1));
+    if (!Number.isInteger(port) || port < 0)
+        throw new Error(`--listen has an invalid port: ${value}`);
+    return { host, port };
+}
+export function parseArgs(argv, env = process.env) {
+    const command = argv[0];
+    if (command !== "stdio" && command !== "proxy") {
+        throw new Error("usage: oidc-remote <stdio|proxy> --gateway <hostname> --token-url <url>");
+    }
+    let gateway = "";
+    let clientId = "";
+    let tokenUrl = envValue(env, "OIDC_REMOTE_TOKEN_URL") ?? "";
+    let assertionFile = envValue(env, "OIDC_REMOTE_ASSERTION_FILE") ?? DEFAULT_ASSERTION_FILE;
+    let scope = envValue(env, "OIDC_REMOTE_SCOPE") ?? DEFAULT_SCOPE;
+    let url = "";
+    let mcpPath = "/mcp";
+    let upstream = "";
+    let listenHost = "127.0.0.1";
+    let listenPort = 8080;
+    const rest = argv.slice(1);
+    for (let i = 0; i < rest.length; i++) {
+        const arg = rest[i] ?? "";
+        if (arg === "--gateway")
+            gateway = nextValue(rest, ++i, "--gateway");
+        else if (arg.startsWith("--gateway="))
+            gateway = arg.slice("--gateway=".length);
+        else if (arg === "--client-id")
+            clientId = nextValue(rest, ++i, "--client-id");
+        else if (arg.startsWith("--client-id="))
+            clientId = arg.slice("--client-id=".length);
+        else if (arg === "--token-url")
+            tokenUrl = nextValue(rest, ++i, "--token-url");
+        else if (arg.startsWith("--token-url="))
+            tokenUrl = arg.slice("--token-url=".length);
+        else if (arg === "--assertion-file")
+            assertionFile = nextValue(rest, ++i, "--assertion-file");
+        else if (arg.startsWith("--assertion-file="))
+            assertionFile = arg.slice("--assertion-file=".length);
+        else if (arg === "--scope")
+            scope = nextValue(rest, ++i, "--scope");
+        else if (arg.startsWith("--scope="))
+            scope = arg.slice("--scope=".length);
+        else if (arg === "--url")
+            url = nextValue(rest, ++i, "--url");
+        else if (arg.startsWith("--url="))
+            url = arg.slice("--url=".length);
+        else if (arg === "--mcp-path")
+            mcpPath = nextValue(rest, ++i, "--mcp-path");
+        else if (arg.startsWith("--mcp-path="))
+            mcpPath = arg.slice("--mcp-path=".length);
+        else if (arg === "--upstream")
+            upstream = nextValue(rest, ++i, "--upstream");
+        else if (arg.startsWith("--upstream="))
+            upstream = arg.slice("--upstream=".length);
+        else if (arg === "--listen") {
+            const parsed = parseListen(nextValue(rest, ++i, "--listen"));
+            listenHost = parsed.host;
+            listenPort = parsed.port;
+        }
+        else if (arg.startsWith("--listen=")) {
+            const parsed = parseListen(arg.slice("--listen=".length));
+            listenHost = parsed.host;
+            listenPort = parsed.port;
+        }
+    }
+    if (!gateway)
+        throw new Error("--gateway is required");
+    if (!tokenUrl)
+        throw new Error("--token-url or OIDC_REMOTE_TOKEN_URL is required");
+    if (!mcpPath.startsWith("/"))
+        mcpPath = `/${mcpPath}`;
+    const id = clientId || gateway;
+    return {
+        command,
+        gateway,
+        clientId: id,
+        tokenUrl,
+        assertionFile,
+        scope,
+        url: url || `https://${gateway}${mcpPath}`,
+        upstream: upstream || `https://${gateway}`,
+        listenHost,
+        listenPort,
+    };
+}
+export async function main(argv = process.argv.slice(2), env = process.env) {
+    const options = parseArgs(argv, env);
+    const tokens = new TokenClient({
+        tokenUrl: options.tokenUrl,
+        clientId: options.clientId,
+        assertionFile: options.assertionFile,
+        scope: options.scope,
+    });
+    if (options.command === "stdio") {
+        await runStdio({
+            url: options.url,
+            getAccessToken: () => tokens.getAccessToken(),
+        });
+        return;
+    }
+    const server = createProxyServer({
+        upstream: options.upstream,
+        getAccessToken: () => tokens.getAccessToken(),
+    });
+    const addr = await listen(server, options.listenHost, options.listenPort);
+    console.error(`oidc-remote proxy listening on http://${addr.host}:${addr.port} -> ${options.upstream}`);
+}
+const entry = process.argv[1] ? pathToFileURL(process.argv[1]).href : undefined;
+if (import.meta.url === entry) {
+    main().catch((err) => {
+        console.error(err instanceof Error ? err.message : err);
+        process.exit(1);
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createTokenClient, DEFAULT_ASSERTION_FILE, DEFAULT_SCOPE, JWT_BEARER_ASSERTION_TYPE, TokenClient, TokenExchangeError, type TokenClientOptions, } from "./token.js";
+export { createProxyServer, listen, type ProxyOptions } from "./proxy.js";
+export { runStdio, type StdioOptions } from "./stdio.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { createTokenClient, DEFAULT_ASSERTION_FILE, DEFAULT_SCOPE, JWT_BEARER_ASSERTION_TYPE, TokenClient, TokenExchangeError, } from "./token.js";
+export { createProxyServer, listen } from "./proxy.js";
+export { runStdio } from "./stdio.js";

package/dist/proxy.d.ts

@@ -0,0 +1,10 @@
+import http from "node:http";
+export type ProxyOptions = {
+    upstream: string;
+    getAccessToken: () => Promise<string>;
+};
+export declare function createProxyServer(options: ProxyOptions): http.Server;
+export declare function listen(server: http.Server, host: string, port: number): Promise<{
+    host: string;
+    port: number;
+}>;

package/dist/proxy.js

@@ -0,0 +1,78 @@
+import http from "node:http";
+import https from "node:https";
+import { URL } from "node:url";
+const HOP_BY_HOP = new Set([
+    "connection",
+    "keep-alive",
+    "proxy-authenticate",
+    "proxy-authorization",
+    "te",
+    "trailers",
+    "transfer-encoding",
+    "upgrade",
+    "host",
+    "authorization",
+]);
+export function createProxyServer(options) {
+    const upstream = new URL(options.upstream);
+    const isHttps = upstream.protocol === "https:";
+    const port = upstream.port ? Number(upstream.port) : isHttps ? 443 : 80;
+    return http.createServer((req, res) => {
+        void (async () => {
+            try {
+                const token = await options.getAccessToken();
+                const headers = {};
+                for (const [key, value] of Object.entries(req.headers)) {
+                    if (HOP_BY_HOP.has(key.toLowerCase()))
+                        continue;
+                    headers[key] = value;
+                }
+                headers.host = upstream.host;
+                headers.authorization = `Bearer ${token}`;
+                const requestFn = isHttps ? https.request : http.request;
+                const upstreamReq = requestFn({
+                    protocol: upstream.protocol,
+                    hostname: upstream.hostname,
+                    port,
+                    method: req.method,
+                    path: req.url,
+                    headers,
+                    servername: isHttps ? upstream.hostname : undefined,
+                }, (upstreamRes) => {
+                    const outHeaders = {};
+                    for (const [key, value] of Object.entries(upstreamRes.headers)) {
+                        if (key.toLowerCase() === "transfer-encoding")
+                            continue;
+                        outHeaders[key] = value;
+                    }
+                    res.writeHead(upstreamRes.statusCode ?? 502, outHeaders);
+                    upstreamRes.pipe(res);
+                });
+                upstreamReq.on("error", (err) => {
+                    if (!res.headersSent)
+                        res.writeHead(502);
+                    res.end(err instanceof Error ? err.message : "upstream error");
+                });
+                req.pipe(upstreamReq);
+            }
+            catch (err) {
+                if (!res.headersSent)
+                    res.writeHead(502);
+                res.end(err instanceof Error ? err.message : "proxy error");
+            }
+        })();
+    });
+}
+export function listen(server, host, port) {
+    return new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(port, host, () => {
+            const addr = server.address();
+            if (!addr || typeof addr === "string") {
+                reject(new Error("failed to bind"));
+                return;
+            }
+            resolve({ host: addr.address, port: addr.port });
+        });
+    });
+}

package/dist/stdio.d.ts

@@ -0,0 +1,13 @@
+import type { Readable, Writable } from "node:stream";
+export type StdioOptions = {
+    url: string;
+    getAccessToken: () => Promise<string>;
+    stdin?: Readable;
+    stdout?: Writable;
+};
+/**
+ * Same hop as mcp-remote: MCP SDK stdio transport on the parent, Streamable
+ * HTTP to the gateway. `authProvider.token()` runs before every HTTP request
+ * so the Bearer can refresh.
+ */
+export declare function runStdio(options: StdioOptions): Promise<void>;

package/dist/stdio.js

@@ -0,0 +1,35 @@
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
+import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
+/**
+ * Same hop as mcp-remote: MCP SDK stdio transport on the parent, Streamable
+ * HTTP to the gateway. `authProvider.token()` runs before every HTTP request
+ * so the Bearer can refresh.
+ */
+export async function runStdio(options) {
+    const remote = new StreamableHTTPClientTransport(new URL(options.url), {
+        authProvider: { token: options.getAccessToken },
+        onInsufficientScope: "throw",
+    });
+    const local = new StdioServerTransport(options.stdin, options.stdout);
+    const report = (err) => {
+        console.error(err instanceof Error ? err.message : err);
+    };
+    local.onmessage = (message) => {
+        void remote.send(message).catch(report);
+    };
+    remote.onmessage = (message) => {
+        void local.send(message).catch(report);
+    };
+    local.onerror = report;
+    remote.onerror = report;
+    await remote.start();
+    await local.start();
+    await new Promise((resolve) => {
+        local.onclose = () => {
+            void remote.close().finally(resolve);
+        };
+        remote.onclose = () => {
+            void local.close();
+        };
+    });
+}

package/dist/token.d.ts

@@ -0,0 +1,40 @@
+export declare const JWT_BEARER_ASSERTION_TYPE = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer";
+export declare const DEFAULT_SCOPE = "openid profile entitlements";
+/** Default projected JWT used as client_assertion. */
+export declare const DEFAULT_ASSERTION_FILE = "/var/run/secrets/tokens/oidc";
+export type TokenClientOptions = {
+    tokenUrl: string;
+    clientId: string;
+    assertionFile?: string;
+    scope?: string;
+    fetch?: typeof fetch;
+    readFile?: (path: string) => Promise<string>;
+    now?: () => number;
+    /** Refresh when this fraction of `expires_in` has elapsed. */
+    refreshRatio?: number;
+};
+export declare class TokenExchangeError extends Error {
+    readonly status?: number;
+    readonly body?: string;
+    constructor(message: string, opts?: {
+        status?: number;
+        body?: string;
+    });
+}
+export declare class TokenClient {
+    private readonly tokenUrl;
+    private readonly clientId;
+    private readonly assertionFile;
+    private readonly scope;
+    private readonly fetchFn;
+    private readonly readFile;
+    private readonly now;
+    private readonly refreshRatio;
+    private cached;
+    private inflight;
+    constructor(options: TokenClientOptions);
+    invalidate(): void;
+    getAccessToken(): Promise<string>;
+    private exchange;
+}
+export declare function createTokenClient(options: TokenClientOptions): TokenClient;

package/dist/token.js

@@ -0,0 +1,110 @@
+export const JWT_BEARER_ASSERTION_TYPE = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer";
+export const DEFAULT_SCOPE = "openid profile entitlements";
+/** Default projected JWT used as client_assertion. */
+export const DEFAULT_ASSERTION_FILE = "/var/run/secrets/tokens/oidc";
+export class TokenExchangeError extends Error {
+    status;
+    body;
+    constructor(message, opts) {
+        super(message);
+        this.name = "TokenExchangeError";
+        this.status = opts?.status;
+        this.body = opts?.body;
+    }
+}
+export class TokenClient {
+    tokenUrl;
+    clientId;
+    assertionFile;
+    scope;
+    fetchFn;
+    readFile;
+    now;
+    refreshRatio;
+    cached = null;
+    inflight = null;
+    constructor(options) {
+        if (!options.tokenUrl)
+            throw new Error("tokenUrl is required");
+        if (!options.clientId)
+            throw new Error("clientId is required");
+        this.tokenUrl = options.tokenUrl;
+        this.clientId = options.clientId;
+        this.assertionFile = options.assertionFile ?? DEFAULT_ASSERTION_FILE;
+        this.scope = options.scope ?? DEFAULT_SCOPE;
+        this.fetchFn = options.fetch ?? fetch;
+        this.readFile =
+            options.readFile ??
+                (async (path) => {
+                    const { readFile } = await import("node:fs/promises");
+                    return readFile(path, "utf8");
+                });
+        this.now = options.now ?? (() => Date.now() / 1000);
+        this.refreshRatio = options.refreshRatio ?? 0.8;
+    }
+    invalidate() {
+        this.cached = null;
+    }
+    async getAccessToken() {
+        const now = this.now();
+        if (this.cached && now < this.cached.refreshAt)
+            return this.cached.token;
+        if (this.inflight)
+            return this.inflight;
+        this.inflight = this.exchange().finally(() => {
+            this.inflight = null;
+        });
+        return this.inflight;
+    }
+    async exchange() {
+        let assertion;
+        try {
+            assertion = (await this.readFile(this.assertionFile)).trim();
+        }
+        catch (err) {
+            const why = err instanceof Error ? err.message : String(err);
+            throw new TokenExchangeError(`failed to read assertion file ${this.assertionFile}: ${why}`);
+        }
+        if (!assertion) {
+            throw new TokenExchangeError(`assertion file ${this.assertionFile} is empty`);
+        }
+        const body = new URLSearchParams({
+            grant_type: "client_credentials",
+            client_id: this.clientId,
+            client_assertion_type: JWT_BEARER_ASSERTION_TYPE,
+            client_assertion: assertion,
+            scope: this.scope,
+        });
+        const res = await this.fetchFn(this.tokenUrl, {
+            method: "POST",
+            headers: { "content-type": "application/x-www-form-urlencoded" },
+            body,
+        });
+        const text = await res.text();
+        if (!res.ok) {
+            throw new TokenExchangeError(`token endpoint HTTP ${res.status}`, {
+                status: res.status,
+                body: text.slice(0, 400),
+            });
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            throw new TokenExchangeError("token endpoint returned non-JSON", { body: text.slice(0, 400) });
+        }
+        if (typeof parsed.access_token !== "string" || !parsed.access_token) {
+            throw new TokenExchangeError("token endpoint omitted access_token", { body: text.slice(0, 400) });
+        }
+        const expiresIn = typeof parsed.expires_in === "number" && parsed.expires_in > 0 ? parsed.expires_in : 3600;
+        this.cached = {
+            token: parsed.access_token,
+            refreshAt: this.now() + expiresIn * this.refreshRatio,
+        };
+        return parsed.access_token;
+    }
+}
+export function createTokenClient(options) {
+    return new TokenClient(options);
+}

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "oidc-remote",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-rc2",
+  "description": "Attach a live OAuth2 access token on the hop to a remote HTTPS server (library, stdio, proxy).",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rafaelgaspar/oidc-remote"
+  },
+  "homepage": "https://github.com/rafaelgaspar/oidc-remote",
+  "bugs": {
+    "url": "https://github.com/rafaelgaspar/oidc-remote/issues"
+  },
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "oidc-remote": "dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/client": "^2.3.1",
+    "@modelcontextprotocol/server": "^2.3.1"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "tsx --test 'src/**/*.test.ts'"
+  },
+  "keywords": [
+    "oauth2",
+    "oidc",
+    "mcp",
+    "authentik",
+    "kubernetes",
+    "client-assertion"
+  ],
+  "devDependencies": {
+    "@types/node": "24.19.2",
+    "tsx": "4.23.15",
+    "typescript": "7.0.2"
+  }
+}