@dropsh/plugin-oauth2 0.7.1 → 0.7.3

package/README.md

@@ -3,7 +3,7 @@
 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
+Adds an OAuth2 login option to `dropsh auth login`. Supports four grant types
 against Drupal's `simple_oauth` module.
 
 ## Install
@@ -45,6 +45,39 @@ dropsh auth login --provider oauth2_authcode
 dropsh auth status
 ```
 
+### Device flow (remote machine, no local browser)
+
+Use `oauth2_device_code` when dropsh runs where your browser is not — over SSH, in a container, on
+a build host. There is no callback listener, no redirect URI and no client secret: dropsh prints a
+URL and a short code, you confirm the login on any other device, and dropsh polls until it is done.
+
+```js
+oauth2Plugin({
+  type: "oauth2_device_code",
+  client_id: "my-client",
+  device_authorization_url: "https://my-drupal.example.com/oauth/device_authorization",
+  token_url: "https://my-drupal.example.com/oauth/token",
+  // scope: "content",
+}),
+```
+
+```bash
+dropsh auth login --provider oauth2_device_code
+
+Open https://my-drupal.example.com/oauth/device
+and enter this code:
+
+    ABCD-EFGH
+
+Waiting for confirmation ...
+```
+
+dropsh never opens a browser for this flow, so the URL and the code stay on screen for use on
+another device. Press Ctrl+C to cancel. The stored tokens behave like any other profile —
+`dropsh auth status`, `dropsh auth logout` and the automatic refresh all work unchanged. If the
+server issues no `refresh_token` for the device grant, an expired session asks for a full login
+again instead of renewing.
+
 ## Named profiles
 
 Every `oauth2Plugin` is one auth **profile**, identified by its `id`. `id` defaults
@@ -69,12 +102,14 @@ for `auth use`, `--auth-profile`, and selection precedence.
 | `oauth2_authcode`             | opens browser (PKCE, public client) | yes — via `refresh_token`     |
 | `oauth2_password`             | client secret + user password    | yes — if `client_secret` in config |
 | `oauth2_client_credentials`   | client secret                     | yes — if `client_secret` in config |
+| `oauth2_device_code`          | prints a URL + code, no browser  | yes — via `refresh_token`       |
 
 Config fields per grant (all accept the shared `id` and `default`):
 
 - `oauth2_authcode` — `client_id`, `token_url`, optional `scope`, `redirect_port`
 - `oauth2_password` — `client_id`, `token_url`, `username`, optional `scope`, `client_secret`
 - `oauth2_client_credentials` — `client_id`, `token_url`, optional `scope`, `client_secret`
+- `oauth2_device_code` — `client_id`, `device_authorization_url`, `token_url`, optional `scope`
 
 `client_secret` and the user `password` may be **prompted at login** and are never
 stored on disk. For unattended runs, put `client_secret` in config so dropsh can

package/dist/plugins/oauth2/src/device.d.ts

@@ -0,0 +1,15 @@
+import type { AuthSession, HttpClient } from "dropsh/plugin";
+export interface AcquireDeviceDeps {
+    clientId: string;
+    deviceAuthorizationUrl: string;
+    tokenUrl: string;
+    scope?: string;
+    http: HttpClient;
+    stdout: (s: string) => void;
+    now: () => number;
+    /** Injected in tests so no wall-clock time passes. */
+    _sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
+    /** Injected in tests to drive the cancellation path without a real SIGINT. */
+    signal?: AbortSignal;
+}
+export declare function acquireDeviceSession(deps: AcquireDeviceDeps): Promise<AuthSession>;

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

@@ -0,0 +1,165 @@
+import { AuthError, HttpError } from "dropsh/plugin";
+import { parseTokenResponse, readOAuthError } from "./token.js";
+const DEFAULT_INTERVAL_SEC = 5;
+const SLOW_DOWN_INCREMENT_SEC = 5;
+const DEVICE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
+/** Resolves after `ms`, or rejects immediately once `signal` aborts. */
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal.aborted)
+            return reject(new AuthError("Login cancelled."));
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        function onAbort() {
+            clearTimeout(timer);
+            reject(new AuthError("Login cancelled."));
+        }
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
+async function requestDeviceAuthorization(deps) {
+    const params = new URLSearchParams({ client_id: deps.clientId });
+    if (deps.scope)
+        params.set("scope", deps.scope);
+    let body;
+    try {
+        const res = await deps.http.send({
+            method: "POST",
+            url: deps.deviceAuthorizationUrl,
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: params.toString(),
+        });
+        body = JSON.parse(res.body);
+    }
+    catch (err) {
+        if (err instanceof SyntaxError)
+            throw new AuthError(`Device authorization response from ${deps.deviceAuthorizationUrl} is not valid JSON.`);
+        const code = err instanceof HttpError ? readOAuthError(err.body) : undefined;
+        throw new AuthError(`Device authorization request rejected (client_id "${deps.clientId}") at ` +
+            `${deps.deviceAuthorizationUrl}: ${code ?? "request_failed"}.`, { reason: code ?? "request_failed", client_id: deps.clientId });
+    }
+    const str = (k) => {
+        const v = body[k];
+        if (typeof v !== "string" || v.length === 0)
+            throw new AuthError(`Device authorization response from ${deps.deviceAuthorizationUrl} is missing "${k}".`);
+        return v;
+    };
+    if (typeof body.expires_in !== "number")
+        throw new AuthError(`Device authorization response from ${deps.deviceAuthorizationUrl} is missing "expires_in".`);
+    return {
+        device_code: str("device_code"),
+        user_code: str("user_code"),
+        verification_uri: str("verification_uri"),
+        expires_in: body.expires_in,
+        ...(typeof body.interval === "number" ? { interval: body.interval } : {}),
+        ...(typeof body.verification_uri_complete === "string"
+            ? { verification_uri_complete: body.verification_uri_complete }
+            : {}),
+    };
+}
+/**
+ * Print the activation instructions. Deliberately never opens a browser: the
+ * flow exists for machines whose local browser is on the wrong host, so URL and
+ * code must stay readable and usable on a second device.
+ */
+function announce(auth, stdout) {
+    stdout(`Open ${auth.verification_uri}\nand enter this code:\n\n    ${auth.user_code}\n`);
+    if (auth.verification_uri_complete)
+        stdout(`Or open this link directly:\n${auth.verification_uri_complete}\n`);
+    stdout("Waiting for confirmation ...");
+}
+function deviceErrorMessage(code) {
+    if (code === "access_denied")
+        return "The login was denied on the confirmation page.";
+    if (code === "expired_token")
+        return "The device code expired before the login was confirmed. Run 'dropsh auth login' to try again.";
+    return `Device login failed: ${code}.`;
+}
+/**
+ * RFC 8628 §3.4/§3.5: wait *before* every request, keep waiting on
+ * `authorization_pending`, raise the interval permanently on `slow_down`, and
+ * treat every other OAuth error as terminal so no code is polled forever. A
+ * transport failure carries no OAuth code, so it backs off and retries until the
+ * device code's own lifetime runs out.
+ */
+async function pollForToken(deps, auth, signal) {
+    const wait = deps._sleep ?? sleep;
+    const deadline = deps.now() + auth.expires_in * 1000;
+    let intervalSec = Math.max(auth.interval ?? DEFAULT_INTERVAL_SEC, 1);
+    const params = new URLSearchParams({
+        grant_type: DEVICE_GRANT,
+        device_code: auth.device_code,
+        client_id: deps.clientId,
+    });
+    for (;;) {
+        await wait(intervalSec * 1000, signal);
+        if (deps.now() >= deadline)
+            throw new AuthError("The device code expired before the login was confirmed. " +
+                "Run 'dropsh auth login' to try again.", { reason: "expired_token", client_id: deps.clientId });
+        try {
+            const res = await deps.http.send({
+                method: "POST",
+                url: deps.tokenUrl,
+                headers: { "Content-Type": "application/x-www-form-urlencoded" },
+                body: params.toString(),
+            });
+            return parseTokenResponse(res.body, deps.now);
+        }
+        catch (err) {
+            if (err instanceof AuthError)
+                throw err;
+            if (!(err instanceof HttpError))
+                throw new AuthError(`Token endpoint response from ${deps.tokenUrl} is not valid.`, {
+                    reason: "invalid_response",
+                    client_id: deps.clientId,
+                });
+            const code = readOAuthError(err.body);
+            if (code === "authorization_pending")
+                continue;
+            if (code === "slow_down") {
+                intervalSec += SLOW_DOWN_INCREMENT_SEC;
+                continue;
+            }
+            if (code === undefined) {
+                // No OAuth code: a transport or connection failure. Poll less often
+                // rather than giving up — the deadline above still bounds the loop.
+                intervalSec += SLOW_DOWN_INCREMENT_SEC;
+                continue;
+            }
+            throw new AuthError(deviceErrorMessage(code), { reason: code, client_id: deps.clientId });
+        }
+    }
+}
+export async function acquireDeviceSession(deps) {
+    const auth = await requestDeviceAuthorization(deps);
+    announce(auth, deps.stdout);
+    // Ctrl+C during the wait must end the login with a clear message rather than a
+    // half-finished flow. The listener is temporary: once polling is over the CLI
+    // gets its default SIGINT behaviour back.
+    const controller = new AbortController();
+    const signal = deps.signal ?? controller.signal;
+    const sigintHandler = () => controller.abort();
+    process.on("SIGINT", sigintHandler);
+    // A cancellation promise with its listener registered up front, so an abort
+    // fired from inside a mocked/real wait call is still observed even when that
+    // wait call's own listener was registered too late (AbortSignal does not
+    // replay an event to a listener added after it already fired).
+    let rejectCancelled = () => { };
+    const cancelled = new Promise((_resolve, reject) => {
+        rejectCancelled = reject;
+    });
+    const onAbort = () => rejectCancelled(new AuthError("Login cancelled."));
+    if (signal.aborted)
+        onAbort();
+    else
+        signal.addEventListener("abort", onAbort, { once: true });
+    try {
+        return await Promise.race([pollForToken(deps, auth, signal), cancelled]);
+    }
+    finally {
+        process.off("SIGINT", sigintHandler);
+        signal.removeEventListener("abort", onAbort);
+    }
+}

package/dist/plugins/oauth2/src/index.d.ts

@@ -30,6 +30,12 @@ export type OAuth2Config = OAuth2Common & ({
     token_url: string;
     scope?: string;
     redirect_port?: number;
+} | {
+    type: "oauth2_device_code";
+    client_id: string;
+    device_authorization_url: string;
+    token_url: string;
+    scope?: string;
 });
 export declare function oauth2Plugin(config: OAuth2Config): DropSHPlugin;
 export {};

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

@@ -12,10 +12,10 @@ import { oauth2Provider } from "./provider.js";
  * the scheme separator and must not be mistaken for the defect. A `token_url`
  * that does not parse as an absolute URL is left to the request layer.
  */
-function assertCanonicalTokenUrl(tokenUrl) {
+function assertCanonicalUrl(field, value) {
     let parsed;
     try {
-        parsed = new URL(tokenUrl);
+        parsed = new URL(value);
     }
     catch {
         return;
@@ -23,16 +23,21 @@ function assertCanonicalTokenUrl(tokenUrl) {
     if (!parsed.pathname.includes("//"))
         return;
     parsed.pathname = parsed.pathname.replace(/\/{2,}/g, "/");
-    throw new ConfigError(`oauth2Plugin: token_url must not contain an empty path segment — set it to ${parsed.href}`);
+    throw new ConfigError(`oauth2Plugin: ${field} must not contain an empty path segment — set it to ${parsed.href}`);
 }
 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");
-    assertCanonicalTokenUrl(config.token_url);
+    assertCanonicalUrl("token_url", config.token_url);
     if (config.type === "oauth2_password" && !config.username)
         throw new ConfigError("oauth2Plugin: username required for oauth2_password");
+    if (config.type === "oauth2_device_code") {
+        if (!config.device_authorization_url)
+            throw new ConfigError("oauth2Plugin: device_authorization_url required for oauth2_device_code");
+        assertCanonicalUrl("device_authorization_url", config.device_authorization_url);
+    }
     return config;
 }
 export function oauth2Plugin(config) {

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

@@ -1,6 +1,7 @@
 import { createHash, randomBytes } from "node:crypto";
 import { createServer } from "node:http";
 import { AuthError } from "dropsh/plugin";
+import { parseTokenResponse } from "./token.js";
 const DEFAULT_PORT = 7432;
 const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
 export function generatePkce() {
@@ -101,13 +102,5 @@ export async function acquireAuthCodeSession(deps) {
         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,
-    };
+    return parseTokenResponse(res.body, deps.now);
 }

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

@@ -1,36 +1,16 @@
 import { AuthError, HttpError } from "dropsh/plugin";
+import { acquireDeviceSession } from "./device.js";
 import { acquireAuthCodeSession } from "./login.js";
+import { parseTokenResponse, readOAuthError } from "./token.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)",
+    oauth2_device_code: "OAuth 2.0 (device code)",
 };
 function bearer(req, token) {
     return { ...(req.headers ?? {}), Authorization: `Bearer ${token}` };
 }
-/**
- * Read the RFC 6749 `error` code from a token endpoint's error response. The
- * body may already be an object (as our tests and some clients provide) or the
- * raw JSON string the real http client carries; parse defensively and return
- * the `error` field only when it is a string.
- */
-function readOAuthError(body) {
-    let parsed = body;
-    if (typeof body === "string") {
-        try {
-            parsed = JSON.parse(body);
-        }
-        catch {
-            return undefined;
-        }
-    }
-    if (parsed && typeof parsed === "object" && "error" in parsed) {
-        const code = parsed.error;
-        if (typeof code === "string")
-            return code;
-    }
-    return undefined;
-}
 async function postToken(http, url, params, now, identity) {
     try {
         const res = await http.send({
@@ -39,15 +19,7 @@ async function postToken(http, url, params, now, identity) {
             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,
-        };
+        return parseTokenResponse(res.body, now);
     }
     catch (err) {
         if (err instanceof AuthError)
@@ -121,6 +93,17 @@ export function oauth2Provider(cfg) {
                     now: ctx.now,
                 });
             }
+            if (cfg.type === "oauth2_device_code") {
+                return acquireDeviceSession({
+                    clientId: cfg.client_id,
+                    deviceAuthorizationUrl: cfg.device_authorization_url,
+                    tokenUrl: cfg.token_url,
+                    ...(cfg.scope !== undefined ? { scope: cfg.scope } : {}),
+                    http: ctx.http,
+                    stdout: ctx.stdout,
+                    now: ctx.now,
+                });
+            }
             // The client_secret is config, not a runtime credential: require it up
             // front (throws before any token request if unset/empty) rather than
             // prompting for it or posting an empty secret.
@@ -190,7 +173,7 @@ export function oauth2Provider(cfg) {
                 await rt.save(minted);
             }
             async function renewSession() {
-                if (cfg.type === "oauth2_authcode") {
+                if (cfg.type === "oauth2_authcode" || cfg.type === "oauth2_device_code") {
                     const refresh = current.refresh_token;
                     if (typeof refresh !== "string")
                         throw new AuthError("Session expired. Run 'dropsh auth login'.");

package/dist/plugins/oauth2/src/token.d.ts

@@ -0,0 +1,14 @@
+import type { AuthSession } from "dropsh/plugin";
+/**
+ * Parse an RFC 6749 token response body into an AuthSession. Shared by the
+ * authcode, device and client-credentials paths so the TTL margin and the
+ * missing-access_token guard exist once.
+ */
+export declare function parseTokenResponse(rawBody: string, now: () => number): AuthSession;
+/**
+ * Read the RFC 6749 `error` code from an error response. The body may already be
+ * an object (as our tests and some clients provide) or the raw JSON string the
+ * real http client carries; parse defensively and return the `error` field only
+ * when it is a string.
+ */
+export declare function readOAuthError(body: unknown): string | undefined;

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

@@ -0,0 +1,40 @@
+import { AuthError } from "dropsh/plugin";
+/**
+ * Parse an RFC 6749 token response body into an AuthSession. Shared by the
+ * authcode, device and client-credentials paths so the TTL margin and the
+ * missing-access_token guard exist once.
+ */
+export function parseTokenResponse(rawBody, now) {
+    const body = JSON.parse(rawBody);
+    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,
+    };
+}
+/**
+ * Read the RFC 6749 `error` code from an error response. The body may already be
+ * an object (as our tests and some clients provide) or the raw JSON string the
+ * real http client carries; parse defensively and return the `error` field only
+ * when it is a string.
+ */
+export function readOAuthError(body) {
+    let parsed = body;
+    if (typeof body === "string") {
+        try {
+            parsed = JSON.parse(body);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (parsed && typeof parsed === "object" && "error" in parsed) {
+        const code = parsed.error;
+        if (typeof code === "string")
+            return code;
+    }
+    return undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dropsh/plugin-oauth2",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "type": "module",
   "main": "./dist/plugins/oauth2/src/index.js",
   "types": "./dist/plugins/oauth2/src/index.d.ts",
@@ -23,7 +23,7 @@
   "devDependencies": {
     "typescript": "^5.6.0",
     "vitest": "^4.1.8",
-    "dropsh": "0.7.1"
+    "dropsh": "0.7.3"
   },
   "scripts": {
     "build": "tsc",