@devdogsuga/devtools 0.1.0

package/dist/newsletter/oauth.js

@@ -0,0 +1,130 @@
+/**
+ * Sign-in for the club mailbox, borrowing Thunderbird's app registration.
+ *
+ * UGA's tenant blocks user consent for every Microsoft Graph mail scope (the
+ * Microsoft-managed default policy), so the clean path — a Graph-created
+ * draft — needs an EITS-approved app registration. The same policy, though,
+ * allowlists a handful of mail clients by application ID for the legacy
+ * IMAP/SMTP scopes, Thunderbird among them. This module runs the standard
+ * authorization-code flow as that client: the officer signs in as the mailbox
+ * in a browser, and the refresh token is theirs — the same grant Thunderbird
+ * itself would hold. Presenting another client's ID is a documented
+ * convention in open-source mail tooling (mbsync, OfflineIMAP, DavMail), but
+ * it is Microsoft's allowlist, and this stops working the day they prune it.
+ *
+ * The redirect comes back two ways. Entra ignores the port when matching a
+ * localhost redirect URI, so the ordinary path is `loopback.ts`: a throwaway
+ * server on an ephemeral port that catches the code itself. When that server
+ * cannot bind, the flow falls back to Thunderbird's registered
+ * `https://localhost` — a dead page whose address bar holds the code, pasted
+ * back by hand.
+ *
+ * No PKCE and no client secret: Thunderbird is registered as a public client,
+ * and the code exchange happens entirely on this machine.
+ */
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+const CLIENT_ID = "9e5f94bc-e8a4-4e73-b8be-63364c29d753";
+/** The fallback redirect when no loopback server could bind. */
+export const PASTE_REDIRECT_URI = "https://localhost";
+// IMAP places drafts; SMTP.Send is `--send`. Both are on the same consent
+// allowlist for the borrowed client, so one grant covers both, and a stored
+// IMAP-only grant upgrades silently on its next refresh.
+const SCOPE = "https://outlook.office365.com/IMAP.AccessAsUser.All https://outlook.office365.com/SMTP.Send offline_access";
+const AUTHORITY = "https://login.microsoftonline.com/organizations/oauth2/v2.0";
+export function authorizeUrl(mailbox, redirectUri, state) {
+    const query = new URLSearchParams({
+        client_id: CLIENT_ID,
+        response_type: "code",
+        redirect_uri: redirectUri,
+        scope: SCOPE,
+        login_hint: mailbox,
+        ...(state ? { state } : {}),
+    });
+    return `${AUTHORITY}/authorize?${query}`;
+}
+/**
+ * The code out of whatever the officer pastes: the whole `https://localhost/?
+ * code=…` address (the intended gesture — the browser shows a dead page and
+ * they copy its location) or the bare code itself.
+ */
+export function codeFromRedirect(pasted) {
+    const input = pasted.trim();
+    const error = /[?&#]error=([^&\s]+)/.exec(input);
+    if (error) {
+        const description = /[?&#]error_description=([^&\s]+)/.exec(input);
+        return new Error(description
+            ? decodeURIComponent(description[1].replace(/\+/g, " "))
+            : decodeURIComponent(error[1]));
+    }
+    const inUrl = /[?&#]code=([^&\s]+)/.exec(input);
+    if (inUrl)
+        return decodeURIComponent(inUrl[1]);
+    // Bare codes are opaque but never contain URL structure or whitespace.
+    if (input && !/[\s/?&=]/.test(input))
+        return input;
+    return new Error("That has no ?code= in it. Paste the whole address bar of the localhost page.");
+}
+async function tokenRequest(grant) {
+    const response = await fetch(`${AUTHORITY}/token`, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+            client_id: CLIENT_ID,
+            scope: SCOPE,
+            ...grant,
+        }),
+    });
+    const body = (await response.json());
+    if (!response.ok || !body.access_token || !body.refresh_token) {
+        throw new Error(body.error_description ??
+            body.error ??
+            `Token endpoint answered ${response.status}.`);
+    }
+    return { accessToken: body.access_token, refreshToken: body.refresh_token };
+}
+export function redeemCode(code, redirectUri) {
+    return tokenRequest({
+        grant_type: "authorization_code",
+        code,
+        // Must be byte-for-byte the redirect the code was issued against.
+        redirect_uri: redirectUri,
+    });
+}
+export function refreshTokens(refreshToken) {
+    return tokenRequest({
+        grant_type: "refresh_token",
+        refresh_token: refreshToken,
+    });
+}
+/**
+ * Outside the repo on purpose: the refresh token opens the club mailbox, and
+ * nothing that opens the club mailbox belongs anywhere `git add` can reach.
+ */
+export function grantPath() {
+    const configHome = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+    return join(configHome, "devdogsuga", "newsletter-mailbox.json");
+}
+export async function readGrant() {
+    try {
+        const parsed = JSON.parse(await readFile(grantPath(), "utf8"));
+        return typeof parsed.mailbox === "string" &&
+            typeof parsed.refreshToken === "string"
+            ? { mailbox: parsed.mailbox, refreshToken: parsed.refreshToken }
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeGrant(grant) {
+    const path = grantPath();
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify(grant, null, 2)}\n`, {
+        mode: 0o600,
+    });
+    // writeFile's mode only applies on create; an existing file keeps its old
+    // bits, so tighten explicitly on the rotation path too.
+    await chmod(path, 0o600);
+}

package/dist/newsletter/smtp.d.ts

@@ -0,0 +1,23 @@
+/**
+ * RFC 5322 origination headers for a message built as a draft. `buildEml`
+ * deliberately emits none of these — draft-ness is their absence — so the
+ * send path prepends them. The submission server stamps `Message-ID`.
+ */
+export declare function originationHeaders(from: string, to: readonly string[], date?: Date): string;
+/** RFC 5321 §4.5.2 transparency: a line-leading `.` doubles inside DATA. */
+export declare function dotStuff(message: string): string;
+/**
+ * `true` when an SMTP reply line ends its reply: `250 done` rather than the
+ * `250-more coming` continuation form (RFC 5321 §4.2.1).
+ */
+export declare function endsReply(line: string): boolean;
+export declare function submitMessage(options: {
+    user: string;
+    accessToken: string;
+    /** The envelope sender — must be the authenticated mailbox on Exchange. */
+    from: string;
+    recipients: readonly string[];
+    /** The full MIME message, origination headers included, CRLF endings. */
+    message: string;
+    host?: string;
+}): Promise<void>;

package/dist/newsletter/smtp.js

@@ -0,0 +1,133 @@
+/**
+ * One-shot SMTP submission: send a finished MIME message byte-for-byte.
+ *
+ * This exists because a draft cannot survive being sent from Outlook. The
+ * web Outlook composer is a rich-text editor with a style whitelist, and
+ * sending a pushed draft re-serializes whatever that editor kept: forensics
+ * on a received copy showed the head `<style>` replaced with Outlook's own,
+ * every `background-image` and `bgcolor` gone, and most class attributes
+ * dropped — all of the newsletter's dark-mode defenses, stripped in transit.
+ * (Classic Outlook mangles differently, into Word HTML, but just as surely.)
+ * Submitting over SMTP bypasses every composer: recipients get the authored
+ * document, stylesheet and all. Like `imap.ts`, this speaks just the sliver
+ * of the protocol the workflow needs — EHLO, STARTTLS, AUTH, one message.
+ */
+import { createConnection } from "node:net";
+import { connect as connectTls } from "node:tls";
+import { xoauth2 } from "./imap.js";
+const DEFAULT_HOST = "smtp.office365.com";
+const TIMEOUT_MS = 30_000;
+/**
+ * RFC 5322 origination headers for a message built as a draft. `buildEml`
+ * deliberately emits none of these — draft-ness is their absence — so the
+ * send path prepends them. The submission server stamps `Message-ID`.
+ */
+export function originationHeaders(from, to, date = new Date()) {
+    return [
+        `From: <${from}>`,
+        `To: ${to.map((address) => `<${address}>`).join(", ")}`,
+        // toUTCString is RFC 5322's fixed-length date form, save the zone name.
+        `Date: ${date.toUTCString().replace(/GMT$/, "+0000")}`,
+        "",
+    ].join("\r\n");
+}
+/** RFC 5321 §4.5.2 transparency: a line-leading `.` doubles inside DATA. */
+export function dotStuff(message) {
+    return message.replace(/(^|\r\n)\./g, "$1..");
+}
+/**
+ * `true` when an SMTP reply line ends its reply: `250 done` rather than the
+ * `250-more coming` continuation form (RFC 5321 §4.2.1).
+ */
+export function endsReply(line) {
+    return /^\d{3}(?: |$)/.test(line);
+}
+export async function submitMessage(options) {
+    const host = options.host ?? DEFAULT_HOST;
+    if (!options.recipients.length)
+        throw new Error("No recipients.");
+    let buffer = "";
+    const pending = [];
+    let wake = null;
+    let failure = null;
+    const fail = (err) => {
+        failure ??= err;
+        socket.destroy();
+        wake?.();
+    };
+    /** (Re)binds the line reader — once to the TCP socket, again after TLS. */
+    const adopt = (next) => {
+        next.setTimeout(TIMEOUT_MS);
+        next.on("data", (chunk) => {
+            buffer += chunk.toString("utf8");
+            let index;
+            while ((index = buffer.indexOf("\r\n")) !== -1) {
+                pending.push(buffer.slice(0, index));
+                buffer = buffer.slice(index + 2);
+            }
+            wake?.();
+        });
+        next.on("error", (err) => fail(err));
+        next.on("timeout", () => fail(new Error(`${host} stopped answering.`)));
+        next.on("close", () => fail(new Error(`${host} closed the connection.`)));
+        return next;
+    };
+    let socket = adopt(createConnection({ host, port: 587 }));
+    const nextLine = async () => {
+        for (;;) {
+            if (pending.length)
+                return pending.shift();
+            if (failure)
+                throw failure;
+            await new Promise((resolvePromise) => {
+                wake = resolvePromise;
+            });
+            wake = null;
+        }
+    };
+    /** Reads one full reply; throws unless its code is in `expect`. */
+    const reply = async (expect, doing) => {
+        let line;
+        do {
+            line = await nextLine();
+        } while (!endsReply(line));
+        const code = Number(line.slice(0, 3));
+        if (!expect.includes(code)) {
+            throw new Error(`${doing}: ${line}`);
+        }
+        return line;
+    };
+    const command = (line, expect, doing) => {
+        socket.write(`${line}\r\n`);
+        return reply(expect, doing);
+    };
+    try {
+        await reply([220], `${host} refused the connection`);
+        await command(`EHLO [127.0.0.1]`, [250], "EHLO was refused");
+        await command("STARTTLS", [220], "STARTTLS was refused");
+        // The server speaks next only after the handshake, so nothing is in
+        // flight — but the plaintext socket's reader has to come off before the
+        // wrap, or it would keep pushing what is now ciphertext into the line
+        // buffer (and its close fires only when the whole connection does).
+        for (const event of ["data", "timeout", "close"]) {
+            socket.removeAllListeners(event);
+        }
+        socket.setTimeout(0);
+        socket = adopt(connectTls({ socket, servername: host }));
+        await command(`EHLO [127.0.0.1]`, [250], "EHLO after STARTTLS was refused");
+        await command(`AUTH XOAUTH2 ${xoauth2(options.user, options.accessToken)}`, [235], `${options.user} was refused. Sign in again if the stored grant lacks ` +
+            "SMTP.Send — grants from before --send existed only asked for IMAP");
+        await command(`MAIL FROM:<${options.from}>`, [250], `The sender ${options.from} was refused`);
+        for (const recipient of options.recipients) {
+            await command(`RCPT TO:<${recipient}>`, [250, 251], `The recipient ${recipient} was refused`);
+        }
+        await command("DATA", [354], "DATA was refused");
+        const body = dotStuff(options.message);
+        socket.write(body.endsWith("\r\n") ? body : `${body}\r\n`);
+        await command(".", [250], "The message was refused");
+        socket.write("QUIT\r\n");
+    }
+    finally {
+        socket.destroy();
+    }
+}

package/dist/oauth/browser.d.ts

@@ -0,0 +1 @@
+export declare function openBrowser(url: string): void;

package/dist/oauth/browser.js

@@ -0,0 +1,13 @@
+/** Opens `url` in the user's default browser, cross-platform. */
+import { execFile } from "node:child_process";
+export function openBrowser(url) {
+    if (process.platform === "win32") {
+        execFile("cmd", ["/c", "start", "", url]);
+    }
+    else if (process.platform === "darwin") {
+        execFile("open", [url]);
+    }
+    else {
+        execFile("xdg-open", [url]);
+    }
+}

package/dist/oauth/config.d.ts

@@ -0,0 +1,24 @@
+/** Default Supabase project that hosts the "Sign in with DevDogs" OAuth server. */
+export declare const DEFAULT_API_URL = "https://api.devdogsuga.org";
+/**
+ * DevDogs website — human-facing links, and (since TASK-351) the origin
+ * that serves the one-click connect flow's `/tools/oauth/connect` and
+ * `/tools/oauth/connect/exchange` endpoints. Overridable via `--platform-url`
+ * / `DEVDOGS_PLATFORM_URL` for local testing against a platform dev server —
+ * see `commands.ts`'s `oauth` node and `wizard.ts`.
+ */
+export declare const WEBSITE_URL = "https://devdogsuga.org";
+/**
+ * Custom OAuth/OIDC provider identifier. Supabase requires custom provider
+ * identifiers to be prefixed with "custom:".
+ */
+export declare const PROVIDER_IDENTIFIER = "custom:devdogsuga";
+export declare const PROVIDER_NAME = "DevDogs";
+export declare const PROVIDER_SCOPES: string[];
+export declare const ENV_KEYS: {
+    readonly baseUrl: "OAUTH_BASE_URL";
+    readonly providerName: "OAUTH_PROVIDER_NAME";
+    readonly clientId: "OAUTH_CLIENT_ID";
+    readonly clientSecret: "OAUTH_CLIENT_SECRET";
+    readonly platformUrl: "DEVDOGS_PLATFORM_URL";
+};

package/dist/oauth/config.js

@@ -0,0 +1,24 @@
+/** Default Supabase project that hosts the "Sign in with DevDogs" OAuth server. */
+export const DEFAULT_API_URL = "https://api.devdogsuga.org";
+/**
+ * DevDogs website — human-facing links, and (since TASK-351) the origin
+ * that serves the one-click connect flow's `/tools/oauth/connect` and
+ * `/tools/oauth/connect/exchange` endpoints. Overridable via `--platform-url`
+ * / `DEVDOGS_PLATFORM_URL` for local testing against a platform dev server —
+ * see `commands.ts`'s `oauth` node and `wizard.ts`.
+ */
+export const WEBSITE_URL = "https://devdogsuga.org";
+/**
+ * Custom OAuth/OIDC provider identifier. Supabase requires custom provider
+ * identifiers to be prefixed with "custom:".
+ */
+export const PROVIDER_IDENTIFIER = "custom:devdogsuga";
+export const PROVIDER_NAME = "DevDogs";
+export const PROVIDER_SCOPES = ["openid", "email", "profile"];
+export const ENV_KEYS = {
+    baseUrl: "OAUTH_BASE_URL",
+    providerName: "OAUTH_PROVIDER_NAME",
+    clientId: "OAUTH_CLIENT_ID",
+    clientSecret: "OAUTH_CLIENT_SECRET",
+    platformUrl: "DEVDOGS_PLATFORM_URL",
+};

package/dist/oauth/connect-url.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Builds the platform's `/tools/oauth/connect` URL — the page a browser
+ * opens to approve a `devtools oauth` connection. See this repo's launch
+ * instructions for the fixed wire contract: `redirect_uri`, `code_challenge`
+ * (base64url SHA-256 of the PKCE verifier, no padding — `pkce.ts`),
+ * `code_challenge_method=S256`, `state`, `label` (1–100 characters), and
+ * `callback_uri` (the TARGET Supabase project's own `/auth/v1/callback` —
+ * NOT this loopback listener's URL; that is `redirect_uri`).
+ */
+export declare function buildConnectUrl({ platformUrl, redirectUri, codeChallenge, state, label, callbackUri, }: {
+    platformUrl: string;
+    redirectUri: string;
+    codeChallenge: string;
+    state: string;
+    label: string;
+    callbackUri: string;
+}): string;

package/dist/oauth/connect-url.js

@@ -0,0 +1,23 @@
+/**
+ * Builds the platform's `/tools/oauth/connect` URL — the page a browser
+ * opens to approve a `devtools oauth` connection. See this repo's launch
+ * instructions for the fixed wire contract: `redirect_uri`, `code_challenge`
+ * (base64url SHA-256 of the PKCE verifier, no padding — `pkce.ts`),
+ * `code_challenge_method=S256`, `state`, `label` (1–100 characters), and
+ * `callback_uri` (the TARGET Supabase project's own `/auth/v1/callback` —
+ * NOT this loopback listener's URL; that is `redirect_uri`).
+ */
+export function buildConnectUrl({ platformUrl, redirectUri, codeChallenge, state, label, callbackUri, }) {
+    const url = new URL(`${platformUrl.replace(/\/+$/, "")}/tools/oauth/connect`);
+    url.searchParams.set("redirect_uri", redirectUri);
+    url.searchParams.set("code_challenge", codeChallenge);
+    url.searchParams.set("code_challenge_method", "S256");
+    url.searchParams.set("state", state);
+    // The wire contract caps this at 100 characters; truncated here rather
+    // than left for the platform to reject, since the label is a cosmetic
+    // default (project name / directory name — see `label.ts`), not something
+    // worth failing the whole connect flow over.
+    url.searchParams.set("label", label.slice(0, 100));
+    url.searchParams.set("callback_uri", callbackUri);
+    return url.toString();
+}

package/dist/oauth/db.d.ts

@@ -0,0 +1,37 @@
+export type LocalSupabaseConfig = {
+    apiUrl: string;
+    serviceRoleKey: string;
+};
+/**
+ * Runs `supabase status -o env` in `cwd` and extracts the local API URL and
+ * service role key. Throws a descriptive error if Supabase isn't running or
+ * the CLI isn't installed.
+ *
+ * Two invocations are tried, because this wizard runs in two different worlds:
+ * a sibling project, where the Supabase CLI is normally installed globally, and
+ * this monorepo, where it is a workspace devDependency and not on PATH at all.
+ * A global install wins, since `pnpm exec` in a non-pnpm project would fail for
+ * reasons that have nothing to do with Supabase.
+ */
+export declare function detectLocalSupabase(cwd: string): LocalSupabaseConfig;
+/**
+ * Looks up a custom auth provider on a local Supabase instance through the
+ * Admin SDK, and reports whether it exists along with its name and issuer.
+ *
+ * A 404 means it does not exist yet. Any other error is real and rethrown.
+ */
+export declare function checkProvider({ apiUrl, serviceRoleKey }: LocalSupabaseConfig, identifier: string): Promise<{
+    exists: boolean;
+    name?: string;
+    issuer?: string;
+}>;
+export declare function upsertDevDogsProvider({ apiUrl, serviceRoleKey }: LocalSupabaseConfig, { identifier, name, clientId, clientSecret, issuer, }: {
+    identifier: string;
+    name: string;
+    clientId: string;
+    clientSecret: string;
+    issuer: string;
+}): Promise<{
+    identifier: string;
+    issuer: string;
+}>;

package/dist/oauth/db.js

@@ -0,0 +1,108 @@
+import { createClient } from "@supabase/supabase-js";
+import { execFileSync } from "node:child_process";
+import { parse } from "dotenv";
+import { PROVIDER_SCOPES } from "./config.js";
+function runStatus(argv, cwd) {
+    return execFileSync(argv[0], argv.slice(1), {
+        cwd,
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"],
+    });
+}
+/**
+ * Runs `supabase status -o env` in `cwd` and extracts the local API URL and
+ * service role key. Throws a descriptive error if Supabase isn't running or
+ * the CLI isn't installed.
+ *
+ * Two invocations are tried, because this wizard runs in two different worlds:
+ * a sibling project, where the Supabase CLI is normally installed globally, and
+ * this monorepo, where it is a workspace devDependency and not on PATH at all.
+ * A global install wins, since `pnpm exec` in a non-pnpm project would fail for
+ * reasons that have nothing to do with Supabase.
+ */
+export function detectLocalSupabase(cwd) {
+    let output;
+    try {
+        output = runStatus(["supabase", "status", "-o", "env"], cwd);
+    }
+    catch (first) {
+        try {
+            output = runStatus(["pnpm", "exec", "supabase", "status", "-o", "env"], cwd);
+        }
+        catch {
+            // The first failure is the one worth reporting: it is the one that says
+            // "not installed" rather than "pnpm could not find a workspace".
+            if (first.code === "ENOENT") {
+                throw new Error("supabase CLI not found — install it from https://supabase.com/docs/guides/cli");
+            }
+            const stderr = first.stderr?.trim();
+            throw new Error(stderr || (first instanceof Error ? first.message : String(first)));
+        }
+    }
+    const env = parse(output);
+    const apiUrl = env["API_URL"];
+    const serviceRoleKey = env["SERVICE_ROLE_KEY"];
+    if (!apiUrl || !serviceRoleKey) {
+        throw new Error("Could not find API_URL or SERVICE_ROLE_KEY in `supabase status` output");
+    }
+    return { apiUrl, serviceRoleKey };
+}
+/**
+ * Looks up a custom auth provider on a local Supabase instance through the
+ * Admin SDK, and reports whether it exists along with its name and issuer.
+ *
+ * A 404 means it does not exist yet. Any other error is real and rethrown.
+ */
+export async function checkProvider({ apiUrl, serviceRoleKey }, identifier) {
+    const supabase = createClient(apiUrl, serviceRoleKey, {
+        auth: { autoRefreshToken: false, persistSession: false },
+    });
+    const { data, error } = await supabase.auth.admin.customProviders.getProvider(identifier);
+    if (error && error.status !== 404)
+        throw error;
+    return {
+        exists: !!data,
+        name: data?.name ?? undefined,
+        issuer: data?.issuer ?? undefined,
+    };
+}
+export async function upsertDevDogsProvider({ apiUrl, serviceRoleKey }, { identifier, name, clientId, clientSecret, issuer, }) {
+    const supabase = createClient(apiUrl, serviceRoleKey, {
+        auth: { autoRefreshToken: false, persistSession: false },
+    });
+    const { data: existing, error: getError } = await supabase.auth.admin.customProviders.getProvider(identifier);
+    // 404 just means the provider doesn't exist yet. Any other error is real.
+    if (getError && getError.status !== 404) {
+        throw getError;
+    }
+    if (existing) {
+        const { data, error } = await supabase.auth.admin.customProviders.updateProvider(identifier, {
+            name,
+            client_id: clientId,
+            client_secret: clientSecret,
+            issuer,
+            scopes: PROVIDER_SCOPES,
+            enabled: true,
+        });
+        if (error)
+            throw error;
+        if (!data)
+            throw new Error("updateProvider returned no data");
+        return { identifier: data.identifier, issuer: data.issuer ?? issuer };
+    }
+    const { data, error } = await supabase.auth.admin.customProviders.createProvider({
+        provider_type: "oidc",
+        identifier,
+        name,
+        client_id: clientId,
+        client_secret: clientSecret,
+        issuer,
+        scopes: PROVIDER_SCOPES,
+        enabled: true,
+    });
+    if (error)
+        throw error;
+    if (!data)
+        throw new Error("createProvider returned no data");
+    return { identifier: data.identifier, issuer: data.issuer ?? issuer };
+}

package/dist/oauth/device.d.ts

@@ -0,0 +1,93 @@
+/**
+ * The device-code fallback for the one-click connect flow (TASK-352): for a
+ * contributor whose terminal cannot open a browser tab that can complete a
+ * loopback redirect back to THIS machine — SSH, a Codespace, a dev container,
+ * or any environment where the loopback listener itself fails to start (see
+ * `transport.ts`) — this trades a short user code, approved in a browser
+ * running anywhere, for the same OAuth client credentials `exchange.ts`
+ * hands back. The server side of this (TASK-352) lives in the DevDogsUGA
+ * repo, at `apps/platform/src/app/(site)/tools/oauth/device/` — this is the
+ * fixed wire contract the two sides agreed on:
+ *
+ *   POST <platform>/tools/oauth/device/code
+ *   { "label", "callback_uri" }
+ *
+ *   200 { "device_code", "user_code", "verification_uri",
+ *         "verification_uri_complete", "expires_in", "interval" }
+ *   400 { "error": "invalid_request", "error_description" }
+ *   429 { "error": "rate_limited" }  (+ Retry-After header)
+ *
+ *   POST <platform>/tools/oauth/device/token
+ *   { "device_code" }
+ *
+ *   200 { "client_id", "client_secret", "issuer" }
+ *   400 { "error": "authorization_pending" | "slow_down" | "access_denied" |
+ *                   "expired_token" | "invalid_grant" | "invalid_request",
+ *         "error_description" }
+ *   429 { "error": "rate_limited" }  (+ Retry-After header)
+ *
+ * `requestDeviceCode` mints the code; `pollForToken` polls `.../token` on
+ * the server's own cadence until it settles one way or the other. Both take
+ * an injectable `fetchImpl` so tests never touch the network, and
+ * `pollForToken` additionally takes injectable `sleep`/`now` so tests never
+ * touch the wall clock either.
+ */
+import type { ExchangeResult } from "./exchange.js";
+export type DeviceErrorKind = "invalid_request" | "rate_limited" | "network" | "malformed";
+export declare class DeviceError extends Error {
+    readonly kind: DeviceErrorKind;
+    readonly retryAfterSeconds?: number | undefined;
+    constructor(kind: DeviceErrorKind, message: string, retryAfterSeconds?: number | undefined);
+}
+export interface DeviceCodeResult {
+    deviceCode: string;
+    userCode: string;
+    verificationUri: string;
+    verificationUriComplete: string;
+    expiresIn: number;
+    interval: number;
+}
+/** The `/token` endpoint's terminal (non-retryable) outcomes, plus `network`/`malformed`. */
+export type PollErrorKind = "access_denied" | "expired_token" | "invalid_grant" | "invalid_request" | "network" | "malformed";
+export declare class PollError extends Error {
+    readonly kind: PollErrorKind;
+    constructor(kind: PollErrorKind, message: string);
+}
+/**
+ * Requests a device code. Mirrors `exchange.ts`'s `exchangeCode` in shape:
+ * every failure is a distinct `DeviceError` kind, a 429 carries
+ * `Retry-After` when the platform sent one, and a 200 whose body is not
+ * valid JSON or is missing a required field is `malformed` rather than
+ * handing the caller `undefined` fields.
+ */
+export declare function requestDeviceCode({ platformUrl, label, callbackUri, fetchImpl, }: {
+    platformUrl: string;
+    label: string;
+    callbackUri: string;
+    fetchImpl?: typeof fetch;
+}): Promise<DeviceCodeResult>;
+/**
+ * Polls `.../tools/oauth/device/token` on the server's cadence until the
+ * user approves (or denies) the request in their browser, the device code
+ * expires, or the server rejects it outright.
+ *
+ * `authorization_pending` keeps polling at the current interval;
+ * `slow_down` adds 5 seconds to it and keeps polling (per the wire
+ * contract); a 429 waits out `Retry-After` (or the current interval, if the
+ * platform sent none) and keeps polling; every other error is terminal.
+ * Local expiry (`now() - start >= expiresInSeconds`) is reported the same
+ * way as the server's own `expired_token` — the caller does not need to
+ * tell the two apart.
+ *
+ * A network failure while polling retries with backoff up to
+ * `MAX_NETWORK_RETRIES` times before it is reported as `PollError("network")`.
+ */
+export declare function pollForToken({ platformUrl, deviceCode, intervalSeconds, expiresInSeconds, fetchImpl, sleep, now, }: {
+    platformUrl: string;
+    deviceCode: string;
+    intervalSeconds: number;
+    expiresInSeconds: number;
+    fetchImpl?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+}): Promise<ExchangeResult>;