@dropsh/plugin-oauth2 0.0.2

package/LICENSE

@@ -0,0 +1,51 @@
+drupal-cli is dual-licensed. You may use this software under the terms of
+either the MIT License or the GNU General Public License version 2 or any
+later version, at your option.
+
+SPDX-License-Identifier: (MIT OR GPL-2.0-or-later)
+
+================================================================================
+MIT License
+================================================================================
+
+Copyright (c) 2026 Christian Wiedemann
+
+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.
+
+================================================================================
+GNU General Public License, version 2 or later
+================================================================================
+
+The full text of the GNU GPL v2 is available at:
+  https://www.gnu.org/licenses/old-licenses/gpl-2.0.txt
+
+The full text of any later GPL version is available at:
+  https://www.gnu.org/licenses/
+
+Copyright (C) 2026 Christian Wiedemann
+
+This program is free software; you can redistribute it and/or modify it under
+the terms of the GNU General Public License as published by the Free Software
+Foundation; either version 2 of the License, or (at your option) any later
+version.
+
+This program is distributed in the hope that it will be useful, but WITHOUT
+ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
+details.

package/README.md

@@ -0,0 +1,71 @@
+# @dropsh/plugin-oauth2
+
+OAuth 2.0 authentication provider for [dropsh](https://github.com/pen-drop/dropsh),
+the entity-agnostic CLI for Drupal 11 JSON:API.
+
+Adds an OAuth2 login option to `dropsh auth login`. Supports three grant types
+against Drupal's `simple_oauth` module.
+
+## Install
+
+```bash
+pnpm add @dropsh/plugin-oauth2
+```
+
+`dropsh` is a peer dependency.
+
+## Usage
+
+Register the plugin in `dropsh.config.js` with **non-secret** connection
+parameters only. Secrets (client secret, user password) and tokens are prompted
+at login and stored at `~/.config/dropsh/<host>.json` (mode `0600`) — never in
+the config file.
+
+```js
+import { oauth2Plugin } from "@dropsh/plugin-oauth2";
+
+export default {
+  site: { base_url: "https://my-drupal.example.com", jsonapi_prefix: "/jsonapi" },
+  plugins: [
+    // Browser login (Authorization Code + PKCE) — recommended for humans:
+    oauth2Plugin({
+      type: "oauth2_authcode",
+      client_id: "my-client",
+      token_url: "https://my-drupal.example.com/oauth/token",
+      // scope: "...", redirect_port: 7432,
+    }),
+  ],
+};
+```
+
+Then:
+
+```bash
+dropsh auth login --provider oauth2_authcode
+dropsh auth status
+```
+
+## Grant types
+
+| `type`                        | Interactive login prompts        | Token refresh        |
+| ----------------------------- | -------------------------------- | -------------------- |
+| `oauth2_authcode`             | opens browser (PKCE, public client) | yes (refresh token) |
+| `oauth2_password`             | client secret + user password    | re-login on expiry   |
+| `oauth2_client_credentials`   | client secret                     | re-login on expiry   |
+
+Config fields per grant:
+
+- `oauth2_authcode` — `client_id`, `token_url`, optional `scope`, `redirect_port`
+- `oauth2_password` — `client_id`, `token_url`, `username`, optional `scope`
+- `oauth2_client_credentials` — `client_id`, `token_url`, optional `scope`
+
+`client_secret` and the user `password` are **prompted at login**, never stored
+in config.
+
+## Required Drupal module
+
+- [`simple_oauth`](https://www.drupal.org/project/simple_oauth)
+
+## License
+
+MIT OR GPL-2.0-or-later

package/dist/plugins/oauth2/src/index.js

@@ -0,0 +1,22 @@
+import { ConfigError } from "dropsh/plugin";
+import { oauth2Provider } from "./provider.js";
+function validate(config) {
+    if (!config.client_id)
+        throw new ConfigError("oauth2Plugin: client_id required");
+    if (!config.token_url)
+        throw new ConfigError("oauth2Plugin: token_url required");
+    if (config.type === "oauth2_password" && !config.username)
+        throw new ConfigError("oauth2Plugin: username required for oauth2_password");
+    return config;
+}
+export function oauth2Plugin(config) {
+    const cfg = validate(config);
+    return {
+        id: "oauth2",
+        requiredModules: ["simple_oauth"],
+        authProvider: oauth2Provider(cfg),
+        async extendSchema(_entityType, _bundle, schema, _ctx) {
+            return schema;
+        },
+    };
+}

package/dist/plugins/oauth2/src/login.js

@@ -0,0 +1,113 @@
+import { createHash, randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+import { AuthError } from "dropsh/plugin";
+const DEFAULT_PORT = 7432;
+const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
+export function generatePkce() {
+    const verifier = randomBytes(96).toString("base64url");
+    const challenge = createHash("sha256").update(verifier).digest("base64url");
+    return { verifier, challenge };
+}
+export function generateState() {
+    return randomBytes(16).toString("base64url");
+}
+function waitForCallbackCode(c) {
+    const { port, state, timeoutMs, authUrl } = c;
+    const stdout = c.deps.stdout;
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            server.close(() => fn());
+        };
+        const server = createServer((req, res) => {
+            const url = new URL(req.url ?? "/", `http://localhost:${port}`);
+            if (url.pathname !== "/callback") {
+                res.writeHead(404);
+                res.end();
+                return;
+            }
+            res.writeHead(200, { "Content-Type": "text/html" });
+            res.end("<html><body><p>Login successful. You can close this tab.</p></body></html>");
+            const receivedState = url.searchParams.get("state");
+            const receivedCode = url.searchParams.get("code");
+            if (receivedState !== state) {
+                finish(() => reject(new AuthError("OAuth state mismatch — possible CSRF attack")));
+                return;
+            }
+            if (!receivedCode) {
+                finish(() => reject(new AuthError("No authorization code received")));
+                return;
+            }
+            finish(() => resolve(receivedCode));
+        });
+        server.on("error", (err) => {
+            if (err.code === "EADDRINUSE") {
+                finish(() => reject(new AuthError(`Port ${port} is already in use. A previous login may still be running — kill it and retry.`)));
+            }
+            else {
+                finish(() => reject(err));
+            }
+        });
+        const timer = setTimeout(() => {
+            finish(() => reject(new AuthError("Login timed out. Run 'dropsh auth login' to try again.")));
+        }, timeoutMs);
+        server.listen(port, () => {
+            stdout("Opening browser for login...");
+            stdout(`If the browser does not open, visit:\n${authUrl.toString()}`);
+            c.deps.openBrowser(authUrl.toString()).catch(() => {
+                // URL is printed above — user can open it manually.
+            });
+        });
+    });
+}
+/** Runs the PKCE browser flow and returns an AuthSession (no persistence). */
+export async function acquireAuthCodeSession(deps) {
+    const timeoutMs = deps.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const port = deps.redirectPort ?? DEFAULT_PORT;
+    const pkce = (deps._generatePkce ?? generatePkce)();
+    const state = (deps._generateState ?? generateState)();
+    const baseUrl = deps.baseUrl.replace(/\/$/, "");
+    const redirectUri = `http://localhost:${port}/callback`;
+    const authUrl = new URL(`${baseUrl}/oauth/authorize`);
+    authUrl.searchParams.set("response_type", "code");
+    authUrl.searchParams.set("client_id", deps.clientId);
+    authUrl.searchParams.set("redirect_uri", redirectUri);
+    authUrl.searchParams.set("code_challenge", pkce.challenge);
+    authUrl.searchParams.set("code_challenge_method", "S256");
+    authUrl.searchParams.set("state", state);
+    if (deps.scope)
+        authUrl.searchParams.set("scope", deps.scope);
+    const code = await waitForCallbackCode({
+        port,
+        state,
+        timeoutMs,
+        authUrl,
+        deps: { openBrowser: deps.openBrowser, stdout: deps.stdout },
+    });
+    const params = new URLSearchParams({
+        grant_type: "authorization_code",
+        code,
+        code_verifier: pkce.verifier,
+        client_id: deps.clientId,
+        redirect_uri: redirectUri,
+    });
+    const res = await deps.http.send({
+        method: "POST",
+        url: deps.tokenUrl,
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: params.toString(),
+    });
+    const body = JSON.parse(res.body);
+    if (typeof body.access_token !== "string")
+        throw new AuthError("Token endpoint returned no access_token");
+    const ttlSec = typeof body.expires_in === "number" ? body.expires_in : 3600;
+    return {
+        access_token: body.access_token,
+        ...(typeof body.refresh_token === "string" ? { refresh_token: body.refresh_token } : {}),
+        expires_at: deps.now() + ttlSec * 1000 - 5000,
+    };
+}

package/dist/plugins/oauth2/src/oauth2-authcode.js

@@ -0,0 +1,64 @@
+import { AuthError, createHttpClient, HttpError } from "dropsh/plugin";
+import { readToken, writeToken } from "./token-store.js";
+export function createOAuth2AuthCodeAuth(cfg, deps = {}) {
+    const now = deps.now ?? Date.now;
+    const http = deps.http ?? createHttpClient();
+    // Derive base URL for token storage key
+    const baseUrl = cfg.token_url.replace(/\/oauth\/token$/, "");
+    return {
+        async apply(req) {
+            const stored = await readToken(baseUrl, deps.tokenDir);
+            if (!stored) {
+                throw new AuthError("Session expired. Run 'dropsh login' to authenticate.");
+            }
+            if (stored.expires_at - 30_000 > now()) {
+                return {
+                    ...req,
+                    headers: { ...(req.headers ?? {}), Authorization: `Bearer ${stored.access_token}` },
+                };
+            }
+            if (!stored.refresh_token) {
+                throw new AuthError("Session expired. Run 'dropsh login' to authenticate.");
+            }
+            try {
+                const params = new URLSearchParams({
+                    grant_type: "refresh_token",
+                    refresh_token: stored.refresh_token,
+                    client_id: cfg.client_id,
+                });
+                const res = await http.send({
+                    method: "POST",
+                    url: cfg.token_url,
+                    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+                    body: params.toString(),
+                });
+                const body = JSON.parse(res.body);
+                if (typeof body.access_token !== "string") {
+                    throw new AuthError("Token endpoint returned no access_token");
+                }
+                const ttlSec = typeof body.expires_in === "number" ? body.expires_in : 3600;
+                const refreshed = {
+                    access_token: body.access_token,
+                    refresh_token: typeof body.refresh_token === "string" ? body.refresh_token : stored.refresh_token,
+                    expires_at: now() + ttlSec * 1000 - 5000,
+                };
+                await writeToken(baseUrl, refreshed, deps.tokenDir);
+                return {
+                    ...req,
+                    headers: { ...(req.headers ?? {}), Authorization: `Bearer ${refreshed.access_token}` },
+                };
+            }
+            catch (err) {
+                if (err instanceof AuthError)
+                    throw err;
+                if (err instanceof HttpError) {
+                    throw new AuthError("Session expired. Run 'dropsh login' to authenticate.", {
+                        status: err.status,
+                        body: err.body,
+                    });
+                }
+                throw new AuthError("Session expired. Run 'dropsh login' to authenticate.");
+            }
+        },
+    };
+}

package/dist/plugins/oauth2/src/oauth2.js

@@ -0,0 +1,56 @@
+import { AuthError, createHttpClient, HttpError } from "dropsh/plugin";
+export function createOAuth2Auth(cfg, deps = {}) {
+    const now = deps.now ?? Date.now;
+    const http = deps.http ?? createHttpClient();
+    const params = new URLSearchParams({
+        client_id: cfg.client_id,
+        client_secret: cfg.client_secret,
+    });
+    if (cfg.type === "oauth2_password") {
+        params.set("grant_type", "password");
+        params.set("username", cfg.username);
+        params.set("password", cfg.password);
+        if (cfg.scope)
+            params.set("scope", cfg.scope);
+    }
+    else {
+        params.set("grant_type", "client_credentials");
+        if (cfg.scope)
+            params.set("scope", cfg.scope);
+    }
+    let cached = null;
+    async function fetchToken() {
+        try {
+            const res = await http.send({
+                method: "POST",
+                url: cfg.token_url,
+                headers: { "Content-Type": "application/x-www-form-urlencoded" },
+                body: params.toString(),
+            });
+            const body = JSON.parse(res.body);
+            if (typeof body.access_token !== "string") {
+                throw new AuthError("Token endpoint returned no access_token");
+            }
+            const ttlSec = typeof body.expires_in === "number" ? body.expires_in : 3600;
+            return { token: body.access_token, expiresAt: now() + ttlSec * 1000 - 5000 };
+        }
+        catch (err) {
+            if (err instanceof HttpError) {
+                throw new AuthError(`Token request failed: HTTP ${err.status}`, { body: err.body });
+            }
+            if (err instanceof AuthError)
+                throw err;
+            throw new AuthError(`Token request failed: ${err.message}`);
+        }
+    }
+    return {
+        async apply(req) {
+            if (!cached || cached.expiresAt <= now())
+                cached = await fetchToken();
+            return {
+                ...req,
+                headers: { ...(req.headers ?? {}), Authorization: `Bearer ${cached.token}` },
+            };
+        },
+    };
+}

package/dist/plugins/oauth2/src/provider.js

@@ -0,0 +1,133 @@
+import { AuthError, HttpError } from "dropsh/plugin";
+import { acquireAuthCodeSession } from "./login.js";
+const DISPLAY = {
+    oauth2_authcode: "OAuth 2.0 (browser login, PKCE)",
+    oauth2_password: "OAuth 2.0 (resource owner password)",
+    oauth2_client_credentials: "OAuth 2.0 (client credentials)",
+};
+function bearer(req, token) {
+    return { ...(req.headers ?? {}), Authorization: `Bearer ${token}` };
+}
+async function postToken(http, url, params, now) {
+    try {
+        const res = await http.send({
+            method: "POST",
+            url,
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: params.toString(),
+        });
+        const body = JSON.parse(res.body);
+        if (typeof body.access_token !== "string")
+            throw new AuthError("Token endpoint returned no access_token");
+        const ttlSec = typeof body.expires_in === "number" ? body.expires_in : 3600;
+        return {
+            access_token: body.access_token,
+            ...(typeof body.refresh_token === "string" ? { refresh_token: body.refresh_token } : {}),
+            expires_at: now() + ttlSec * 1000 - 5000,
+        };
+    }
+    catch (err) {
+        if (err instanceof AuthError)
+            throw err;
+        if (err instanceof HttpError)
+            throw new AuthError(`Token request failed: HTTP ${err.status}`, { body: err.body });
+        throw new AuthError(`Token request failed: ${err.message}`);
+    }
+}
+export function oauth2Provider(cfg) {
+    return {
+        id: cfg.type,
+        displayName: DISPLAY[cfg.type],
+        capabilities: { login: true, logout: true, status: true },
+        async login(ctx) {
+            if (cfg.type === "oauth2_authcode") {
+                return acquireAuthCodeSession({
+                    baseUrl: ctx.baseUrl,
+                    clientId: cfg.client_id,
+                    tokenUrl: cfg.token_url,
+                    ...(cfg.scope !== undefined ? { scope: cfg.scope } : {}),
+                    ...(cfg.redirect_port !== undefined ? { redirectPort: cfg.redirect_port } : {}),
+                    http: ctx.http,
+                    openBrowser: ctx.openBrowser,
+                    stdout: ctx.stdout,
+                    now: ctx.now,
+                });
+            }
+            const params = new URLSearchParams({ client_id: cfg.client_id });
+            const secret = await ctx.prompt({ label: "Client secret", secret: true });
+            params.set("client_secret", secret);
+            if (cfg.type === "oauth2_password") {
+                const password = await ctx.prompt({ label: "Password", secret: true });
+                params.set("grant_type", "password");
+                params.set("username", cfg.username);
+                params.set("password", password);
+            }
+            else {
+                params.set("grant_type", "client_credentials");
+            }
+            if (cfg.scope)
+                params.set("scope", cfg.scope);
+            return postToken(ctx.http, cfg.token_url, params, ctx.now);
+        },
+        async logout() {
+            // simple_oauth has no standard revoke endpoint wired; core clears the session.
+        },
+        async status(session) {
+            if (!session)
+                return { loggedIn: false, provider: cfg.type };
+            const expiresAt = typeof session.expires_at === "number" ? session.expires_at : undefined;
+            const info = {
+                loggedIn: true,
+                provider: cfg.type,
+            };
+            if (expiresAt !== undefined) {
+                info.expiresAt = expiresAt;
+                info.state = expiresAt > Date.now() ? "valid" : "expired";
+            }
+            return info;
+        },
+        createAdapter(session, rt) {
+            // Mutable reference to the live session, updated in place after a refresh
+            // so subsequent requests reuse the new token instead of re-refreshing.
+            let current = session;
+            let refreshing = null;
+            async function doRefresh(refreshToken) {
+                const params = new URLSearchParams({
+                    grant_type: "refresh_token",
+                    refresh_token: refreshToken,
+                    client_id: cfg.client_id,
+                });
+                const refreshed = await postToken(rt.http, cfg.token_url, params, rt.now);
+                if (typeof refreshed.refresh_token !== "string")
+                    refreshed.refresh_token = refreshToken;
+                current = refreshed;
+                await rt.save(refreshed);
+            }
+            return {
+                async apply(req) {
+                    const token = current.access_token;
+                    const expiresAt = typeof current.expires_at === "number" ? current.expires_at : 0;
+                    if (typeof token === "string" && expiresAt - 30_000 > rt.now())
+                        return { ...req, headers: bearer(req, token) };
+                    // Only the authcode grant uses a public client (PKCE) and can refresh
+                    // with client_id alone. For oauth2_password / oauth2_client_credentials
+                    // the client is confidential and a refresh without client_secret would
+                    // 401; we do not persist the long-lived client_secret at rest, so a
+                    // re-login is required instead.
+                    if (cfg.type !== "oauth2_authcode")
+                        throw new AuthError("Session expired. Run 'dropsh auth login'.");
+                    const refresh = current.refresh_token;
+                    if (typeof refresh !== "string")
+                        throw new AuthError("Session expired. Run 'dropsh auth login'.");
+                    // Coalesce concurrent refreshes so we exchange the token only once.
+                    if (!refreshing)
+                        refreshing = doRefresh(refresh).finally(() => {
+                            refreshing = null;
+                        });
+                    await refreshing;
+                    return { ...req, headers: bearer(req, current.access_token) };
+                },
+            };
+        },
+    };
+}

package/dist/plugins/oauth2/src/token-store.js

@@ -0,0 +1,26 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+function hostnameFromUrl(baseUrl) {
+    return new URL(baseUrl).hostname;
+}
+export function defaultTokenDir() {
+    return join(homedir(), ".config", "dropsh");
+}
+export async function readToken(baseUrl, dir) {
+    const tokenDir = dir ?? defaultTokenDir();
+    const tokenPath = join(tokenDir, `${hostnameFromUrl(baseUrl)}.json`);
+    try {
+        const raw = await readFile(tokenPath, "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeToken(baseUrl, token, dir) {
+    const tokenDir = dir ?? defaultTokenDir();
+    await mkdir(tokenDir, { recursive: true });
+    const tokenPath = join(tokenDir, `${hostnameFromUrl(baseUrl)}.json`);
+    await writeFile(tokenPath, JSON.stringify(token, null, 2), { encoding: "utf8", mode: 0o600 });
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@dropsh/plugin-oauth2",
+  "version": "0.0.2",
+  "type": "module",
+  "main": "./dist/plugins/oauth2/src/index.js",
+  "exports": {
+    ".": "./dist/plugins/oauth2/src/index.js"
+  },
+  "files": [
+    "dist/plugins/oauth2/src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "dropsh": "*"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.8",
+    "dropsh": "0.0.2"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run --passWithNoTests",
+    "typecheck": "tsc --noEmit"
+  }
+}