@37signals/basecamp 0.10.0 → 0.11.0

package/dist/oauth/device-login.js

@@ -0,0 +1,118 @@
+/**
+ * RFC 8628 device login orchestration.
+ *
+ * `performDeviceLogin` accepts an ALREADY-SELECTED OAuthConfig (from discovery),
+ * guards the device capability, requests a device code, surfaces it through a
+ * display hook, and polls for the token.
+ */
+import { BasecampError } from "../errors.js";
+import { DeviceFlowError } from "./device-errors.js";
+import { requestDeviceAuthorization, pollDeviceToken, throwIfAborted, validatedClockSample, DEVICE_CODE_GRANT_TYPE, defaultClock, } from "./device.js";
+/**
+ * Runs the full device authorization grant against a selected config.
+ *
+ * @throws DeviceFlowError("unavailable") when the config cannot do device flow;
+ *   other DeviceFlowError reasons on denial/expiry/transport/cancellation.
+ */
+export async function performDeviceLogin(options) {
+    const { config, clientId, scope, display, signal, clock = defaultClock, fetch: customFetch, sleepFn } = options;
+    // Capability guard requires BOTH the endpoint and the advertised grant type.
+    // Require a genuine array: a manually-constructed config could supply
+    // grantTypesSupported as a string, and String.prototype.includes would
+    // substring-match and wrongly pass the guard (the other SDKs defend the same
+    // way — Python/Ruby check the collection type, Go/Kotlin are statically typed).
+    const supportsDeviceGrant = Array.isArray(config.grantTypesSupported) && config.grantTypesSupported.includes(DEVICE_CODE_GRANT_TYPE);
+    if (!config.deviceAuthorizationEndpoint || !supportsDeviceGrant) {
+        throw new DeviceFlowError("unavailable", "The selected authorization server does not support the device authorization grant");
+    }
+    // A non-function display is a usage error, not a late TypeError: it is the
+    // only mechanism surfacing the verification code, so dereferencing it AFTER
+    // the request would mint a code nobody can approve. Reject before any
+    // network activity (matching Go) — a JS caller can pass anything.
+    if (typeof display !== "function") {
+        throw new BasecampError("usage", "performDeviceLogin requires a display callback function");
+    }
+    // Honor a cancellation raised before any work: an already-aborted signal
+    // must not fire the authorization request or surface a code via display.
+    throwIfAborted(signal);
+    const auth = await requestDeviceAuthorization({
+        deviceAuthorizationEndpoint: config.deviceAuthorizationEndpoint,
+        clientId,
+        scope,
+        fetch: customFetch,
+        // Threaded so an abort DURING the request cancels it in flight and
+        // surfaces as the contractual cancelled — never a code shown post-cancel.
+        signal,
+    });
+    // Anchor the code's lifetime at ISSUANCE — the response's arrival, per
+    // SPEC §16 — before the display hook, so a slow display eats into the
+    // deadline instead of resetting it. Expiry past this point is arbitrated
+    // by the server (expired_token), so receipt-anchoring fails safe.
+    // Validated like the poller's samples — a malformed injected clock is the
+    // typed usage error before the code is surfaced.
+    const issuedAt = validatedClockSample(clock(), "performDeviceLogin");
+    // Re-check before surfacing the code: an abort racing the request's
+    // completion — or landing during the clock sample above (itself a callback
+    // seam) — must not reach the display hook.
+    throwIfAborted(signal);
+    // Race an async display hook against the abort signal: a hook awaiting user
+    // interaction must not hold a cancelled flow open until it settles. On
+    // abort the hook's promise is left to settle on its own (JS cannot cancel
+    // it) — the flow rejects promptly and never proceeds to polling.
+    await new Promise((resolve, reject) => {
+        const onAbort = () => reject(new DeviceFlowError("cancelled", "Device flow cancelled"));
+        signal?.addEventListener("abort", onAbort, { once: true });
+        if (signal?.aborted) {
+            // The abort won between the entry throwIfAborted and the registration
+            // above: the event is already spent, so the once-listener would never
+            // fire — and never auto-remove. Drop it before rejecting manually
+            // (same race handling as the sleep helper).
+            signal.removeEventListener("abort", onAbort);
+            onAbort();
+            return;
+        }
+        Promise.resolve()
+            .then(() => {
+            // The abort can win between scheduling and this deferred callback —
+            // the outer promise has already rejected then, but this callback still
+            // runs. Re-check so a cancelled flow never surfaces the code.
+            if (signal?.aborted)
+                return undefined;
+            return display(auth);
+        })
+            .then(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, (err) => {
+            signal?.removeEventListener("abort", onAbort);
+            reject(err);
+        });
+    });
+    // Deduct the elapsed display time from the issuance anchor so polling gets
+    // only the REMAINING lifetime. `expiresIn` is seconds; the clock is ms, so
+    // convert the elapsed span before subtracting.
+    const remainingSeconds = auth.expiresIn - (validatedClockSample(clock(), "performDeviceLogin") - issuedAt) / 1000;
+    // Re-check after the clock read: an abort landing after the display race
+    // settled (its listener is already removed) must still win over expiry —
+    // cancellation beats every other classification.
+    throwIfAborted(signal);
+    if (remainingSeconds <= 0) {
+        throw new DeviceFlowError("expired", "Device code expired before authorization completed");
+    }
+    return pollDeviceToken({
+        tokenEndpoint: config.tokenEndpoint,
+        clientId,
+        deviceCode: auth.deviceCode,
+        interval: auth.interval,
+        expiresIn: remainingSeconds,
+        // Absolute issuance-anchored deadline: clock time elapsing between the
+        // remainingSeconds computation above and pollDeviceToken's own clock()
+        // anchor would otherwise be handed BACK to the code's lifetime.
+        deadlineAtMs: issuedAt + auth.expiresIn * 1000,
+        signal,
+        clock,
+        fetch: customFetch,
+        sleepFn,
+    });
+}
+//# sourceMappingURL=device-login.js.map

package/dist/oauth/device-login.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-login.js","sourceRoot":"","sources":["../../src/oauth/device-login.ts"],"names":[],"mappings":"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"}

package/dist/oauth/device.d.ts

@@ -0,0 +1,112 @@
+/**
+ * RFC 8628 device authorization grant — request + poll.
+ *
+ * `requestDeviceAuthorization` obtains a device/user code pair;
+ * `pollDeviceToken` runs the §3.5 polling loop against the token endpoint. Both
+ * are TLS-guarded. The polling clock is monotonic and injectable for tests.
+ */
+import { MAX_TOKEN_LIFETIME_SECONDS } from "./limits.js";
+export { MAX_TOKEN_LIFETIME_SECONDS };
+import type { DeviceAuthorization, OAuthToken } from "./types.js";
+/** URN grant type for the device authorization grant. */
+export declare const DEVICE_CODE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code";
+/** Monotonic clock in milliseconds. Injectable so tests can advance time. */
+export type MonotonicClock = () => number;
+/**
+ * Default monotonic clock (ms): `performance.now()`, which every supported
+ * Node/browser runtime provides. The `Date.now()` branch is a last resort for
+ * exotic runtimes without `performance` — wall-clock, so not strictly monotonic;
+ * inject a real monotonic clock there if NTP steps matter.
+ */
+export declare const defaultClock: MonotonicClock;
+/**
+ * Validate one sample from an injected clock seam. `Number.isFinite` performs
+ * no coercion, so a bigint, string, or Symbol sample fails exactly like a
+ * NaN/Infinity one — the typed usage error, never a raw TypeError out of later
+ * deadline arithmetic. Shared by the poller and the login orchestrator so both
+ * validate EVERY sample the same way.
+ */
+export declare function validatedClockSample(sample: unknown, entry: string): number;
+/**
+ * Parameters for {@link requestDeviceAuthorization}.
+ */
+export interface RequestDeviceAuthorizationParams {
+    /** The device_authorization_endpoint from discovery. */
+    deviceAuthorizationEndpoint: string;
+    /** The public client id (e.g. "basecamp-cli"). */
+    clientId: string;
+    /** Requested scope. Omitted from the request entirely when unset → server default `read`. */
+    scope?: string;
+    /** Custom fetch (testing). */
+    fetch?: typeof globalThis.fetch;
+    /** Request timeout in milliseconds (default: 30000). */
+    timeoutMs?: number;
+    /** Cancellation signal — aborting rejects with DeviceFlowError("cancelled"). */
+    signal?: AbortSignal;
+}
+/**
+ * Requests a device/user code pair (RFC 8628 §3.1–3.2).
+ *
+ * @throws DeviceFlowError("cancelled") when the signal aborts;
+ *   DeviceFlowError("transport") on a network failure; BasecampError on
+ *   validation / non-2xx.
+ */
+export declare function requestDeviceAuthorization(params: RequestDeviceAuthorizationParams): Promise<DeviceAuthorization>;
+/**
+ * Parameters for {@link pollDeviceToken}.
+ */
+export interface PollDeviceTokenParams {
+    /** The token_endpoint from discovery. */
+    tokenEndpoint: string;
+    /** The public client id. */
+    clientId: string;
+    /** The device_code from {@link requestDeviceAuthorization}. */
+    deviceCode: string;
+    /** Polling interval in seconds. */
+    interval: number;
+    /** Code lifetime in seconds (monotonic deadline). */
+    expiresIn: number;
+    /**
+     * Absolute monotonic deadline (ms, same clock as `clock`) anchoring the
+     * code's expiry at ISSUANCE. When set it overrides the `clock() + expiresIn`
+     * anchoring so time elapsed before this call is never handed back to the
+     * lifetime. Must be finite and no later than `expiresIn` seconds from now —
+     * a deadline can only shorten the validated lifetime, never extend it.
+     */
+    deadlineAtMs?: number;
+    /** Cancellation signal — aborting rejects with DeviceFlowError("cancelled"). */
+    signal?: AbortSignal;
+    /** Injectable monotonic clock (ms). Default performance.now(). */
+    clock?: MonotonicClock;
+    /** Custom fetch (testing). */
+    fetch?: typeof globalThis.fetch;
+    /** Per-request timeout in milliseconds (default: 30000). */
+    timeoutMs?: number;
+    /**
+     * Injectable sleep (testing). Receives the wait in ms and the cancellation
+     * signal; defaults to a real, abortable timer. Lets tests assert the interval
+     * schedule (slow_down, backoff) without real delays.
+     */
+    sleepFn?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+/**
+ * Polls the token endpoint until the user approves, denies, or the codes expire
+ * (RFC 8628 §3.4–3.5). Handles authorization_pending, sustained slow_down (+5s),
+ * a monotonic expiry deadline, exponential backoff on connection timeouts, and
+ * cooperative cancellation.
+ */
+export declare function pollDeviceToken(params: PollDeviceTokenParams): Promise<OAuthToken>;
+/**
+ * Validates a Retry-After delta for the 429 poll contract (SPEC §16): a
+ * positive integral number of seconds. A representable delta beyond
+ * MAX_DEVICE_SECONDS (the shared 32-bit-ms timer bound) CLAMPS to the
+ * ceiling — the wait rule clips to the remaining code lifetime, honoring the
+ * throttle. Anything else — missing, an HTTP-date, fractional, non-positive,
+ * or unrepresentable (beyond 2^53) — returns 0 so the caller falls back to
+ * the current interval. Trimming is ASCII SP/HTAB only (RFC 9110
+ * OWS) — NOT String.prototype.trim(), whose Unicode whitespace (NBSP above
+ * all) would trim a malformed value into validity.
+ */
+export declare function parseRetryAfterSeconds(header: string | null): number;
+export declare function throwIfAborted(signal?: AbortSignal): void;
+//# sourceMappingURL=device.d.ts.map

package/dist/oauth/device.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device.d.ts","sourceRoot":"","sources":["../../src/oauth/device.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AAIzD,OAAO,EAAE,0BAA0B,EAAE,CAAC;AACtC,OAAO,KAAK,EAAE,mBAAmB,EAAE,UAAU,EAAwC,MAAM,YAAY,CAAC;AAExG,yDAAyD;AACzD,eAAO,MAAM,sBAAsB,iDAAiD,CAAC;AAwDrF,6EAA6E;AAC7E,MAAM,MAAM,cAAc,GAAG,MAAM,MAAM,CAAC;AAE1C;;;;;GAKG;AACH,eAAO,MAAM,YAAY,EAAE,cAC0C,CAAC;AAEtE;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAK3E;AAcD;;GAEG;AACH,MAAM,WAAW,gCAAgC;IAC/C,wDAAwD;IACxD,2BAA2B,EAAE,MAAM,CAAC;IACpC,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,6FAA6F;IAC7F,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8BAA8B;IAC9B,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;;GAMG;AACH,wBAAsB,0BAA0B,CAC9C,MAAM,EAAE,gCAAgC,GACvC,OAAO,CAAC,mBAAmB,CAAC,CA+H9B;AA+ED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,yCAAyC;IACzC,aAAa,EAAE,MAAM,CAAC;IACtB,4BAA4B;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,+DAA+D;IAC/D,UAAU,EAAE,MAAM,CAAC;IACnB,mCAAmC;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gFAAgF;IAChF,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,kEAAkE;IAClE,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,8BAA8B;IAC9B,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/D;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,UAAU,CAAC,CA8MxF;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAoBpE;AAoQD,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,IAAI,CAIzD"}