@devdogsuga/devtools 0.1.0

package/dist/oauth/loopback.js

@@ -0,0 +1,162 @@
+/**
+ * The loopback HTTP listener the one-click connect flow waits on.
+ *
+ * `devtools oauth`'s connect flow opens the platform's `/tools/oauth/connect`
+ * page in the contributor's browser, and the platform redirects back to a
+ * `redirect_uri` of `http://127.0.0.1:<port>/callback` this process itself
+ * is listening on — a random, ephemeral port, requested by passing `0` to
+ * `listen()`, so two `devtools oauth` runs on the same machine never
+ * collide. `127.0.0.1` specifically, not `0.0.0.0`: this must never accept a
+ * connection from anything but the browser running ON this machine.
+ *
+ * Every exit path — success, `error=access_denied` (or any other `error=`),
+ * a request with neither, and the 5-minute timeout — closes the server
+ * exactly once. That is the one invariant every caller of `start()` may
+ * lean on: `close()` (also exposed for a caller that gives up early, e.g.
+ * Ctrl-C) is always safe to call more than once, and the server is never
+ * left listening after `result` settles.
+ */
+import { createServer } from "node:http";
+/** Default: as long as this repo's OAuth wizard reasonably keeps a browser tab open unattended. */
+export const DEFAULT_CALLBACK_TIMEOUT_MS = 5 * 60_000;
+/** The platform denied the request, or reported some other OAuth `error=`. */
+export class CallbackDeniedError extends Error {
+    errorCode;
+    state;
+    constructor(errorCode, state, description) {
+        super(description ? `${errorCode}: ${description}` : errorCode);
+        this.errorCode = errorCode;
+        this.state = state;
+        this.name = "CallbackDeniedError";
+    }
+}
+/** No callback arrived within the timeout — the browser was never opened, or the tab was abandoned. */
+export class CallbackTimeoutError extends Error {
+    constructor(timeoutMs) {
+        super(`No response from the browser after ${Math.round(timeoutMs / 1000)}s. ` +
+            "Run the command again, and complete the connection in the browser tab it opens.");
+        this.name = "CallbackTimeoutError";
+    }
+}
+/** The callback hit `/callback` but had neither `code` nor `error` — not a shape this flow expects. */
+export class CallbackMalformedError extends Error {
+    constructor() {
+        super("The browser's callback had neither a code nor an error.");
+        this.name = "CallbackMalformedError";
+    }
+}
+/**
+ * The callback's `state` did not match the one this run generated (see
+ * `pkce.ts`'s `generateState`) — the defining CSRF defense of this whole
+ * flow. Any mismatch is treated the same regardless of cause (a stale tab
+ * from a previous run, a forged callback, or a bug): refuse and say so,
+ * never silently proceed with the wrong request.
+ */
+export class StateMismatchError extends Error {
+    constructor() {
+        super("The browser's callback carried a different state than this run generated " +
+            "— the connection may have been tampered with. Run the command again.");
+        this.name = "StateMismatchError";
+    }
+}
+/** Throws `StateMismatchError` unless `callback.state` matches `expected`; returns `callback` unchanged otherwise. */
+export function verifyState(expected, callback) {
+    if (callback.state !== expected)
+        throw new StateMismatchError();
+    return callback;
+}
+function renderCallbackPage(heading, body) {
+    return ("<!doctype html><html><head><meta charset=\"utf-8\"><title>DevDogs devtools</title></head>" +
+        `<body style="font-family: system-ui, sans-serif; max-width: 32rem; margin: 4rem auto; text-align: center;">` +
+        `<h1>${heading}</h1><p>${body}</p></body></html>`);
+}
+const SUCCESS_PAGE = renderCallbackPage("Connected", "You can close this tab and return to your terminal.");
+const DENIED_PAGE = renderCallbackPage("Connection not completed", "You can close this tab and return to your terminal.");
+/**
+ * Starts the listener and resolves once it is actually accepting
+ * connections (i.e. once the real port is known). `result` is the separate
+ * promise that settles once a callback (or the timeout) has been handled —
+ * most callers `await start(...)` once, then `await listener.result`.
+ */
+export function start(opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_CALLBACK_TIMEOUT_MS;
+    return new Promise((resolveListener, rejectListener) => {
+        let settled = false;
+        let resolveResult;
+        let rejectResult;
+        const result = new Promise((res, rej) => {
+            resolveResult = res;
+            rejectResult = rej;
+        });
+        // `result` settles the instant the callback request arrives, which can
+        // be before the caller gets around to `await`ing it (e.g. this
+        // function's own `start(...)` promise has to resolve first). Node
+        // reports an unhandled rejection for any promise that goes a full
+        // microtask turn with no listener at all, even one a caller attaches
+        // moments later — this dummy handler exists purely to be that first
+        // listener; it does not consume the rejection for real callers, who
+        // still get their own `await`/`.catch` on the same promise.
+        result.catch(() => { });
+        const server = createServer((req, res) => {
+            const url = new URL(req.url ?? "/", "http://127.0.0.1");
+            if (url.pathname !== "/callback") {
+                res.writeHead(404).end();
+                return;
+            }
+            const code = url.searchParams.get("code");
+            const state = url.searchParams.get("state") ?? undefined;
+            const error = url.searchParams.get("error");
+            if (error) {
+                res.writeHead(200, { "content-type": "text/html; charset=utf-8" }).end(DENIED_PAGE);
+                settle(() => rejectResult(new CallbackDeniedError(error, state, url.searchParams.get("error_description") ?? undefined)));
+                return;
+            }
+            if (!code || !state) {
+                res.writeHead(400, { "content-type": "text/html; charset=utf-8" }).end(DENIED_PAGE);
+                settle(() => rejectResult(new CallbackMalformedError()));
+                return;
+            }
+            res.writeHead(200, { "content-type": "text/html; charset=utf-8" }).end(SUCCESS_PAGE);
+            settle(() => resolveResult({ code, state }));
+        });
+        const timer = setTimeout(() => {
+            settle(() => rejectResult(new CallbackTimeoutError(timeoutMs)));
+        }, timeoutMs);
+        // Never keep the process alive on this timer alone — a caller that
+        // already got its result (or gave up and called close()) must be able
+        // to exit immediately.
+        timer.unref();
+        const close = () => {
+            clearTimeout(timer);
+            server.close();
+        };
+        /** Runs `settleFn` exactly once, always closing the listener. */
+        function settle(settleFn) {
+            if (settled)
+                return;
+            settled = true;
+            settleFn();
+            close();
+        }
+        server.once("error", (err) => {
+            if (!settled) {
+                settled = true;
+                rejectListener(err);
+                return;
+            }
+            // An error after the listener already started (e.g. a second request
+            // racing the close()) has nowhere useful to go; `result` already
+            // settled, so this is not the caller's problem.
+        });
+        server.listen(0, "127.0.0.1", () => {
+            const address = server.address();
+            const port = typeof address === "object" && address !== null ? address.port : 0;
+            resolveListener({
+                port,
+                redirectUri: `http://127.0.0.1:${port}/callback`,
+                result,
+                close,
+            });
+        });
+    });
+}

package/dist/oauth/pkce.d.ts

@@ -0,0 +1,6 @@
+/** A cryptographically random PKCE code verifier: 32 bytes, base64url-encoded (43 characters). */
+export declare function generateCodeVerifier(): string;
+/** The S256 code challenge for `verifier` — `BASE64URL(SHA256(verifier))`. */
+export declare function codeChallengeFor(verifier: string): string;
+/** A random `state` value, opaque to the caller, tying an authorization request to its callback. */
+export declare function generateState(): string;

package/dist/oauth/pkce.js

@@ -0,0 +1,34 @@
+/**
+ * PKCE (RFC 7636) helpers for the one-click OAuth connect flow.
+ *
+ * `devtools oauth` is a public client with no way to hold a secret (it is a
+ * CLI running on a contributor's machine), so the platform's `/tools/oauth/
+ * connect` flow relies on PKCE instead: a random verifier stays local, only
+ * its SHA-256 challenge crosses the network in the authorization request,
+ * and the verifier itself is sent once, at the very end, to the token
+ * exchange — see `exchange.ts`. `state` is the separate, unrelated defense
+ * against a forged callback (`loopback.ts` checks it), not part of PKCE
+ * proper, but generated the same way and kept here since every caller wants
+ * both together.
+ */
+import { createHash, randomBytes } from "node:crypto";
+/** Base64url, no padding — the encoding both the verifier and challenge use (RFC 7636 §4.1, §4.2). */
+function base64url(buf) {
+    return buf
+        .toString("base64")
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+$/, "");
+}
+/** A cryptographically random PKCE code verifier: 32 bytes, base64url-encoded (43 characters). */
+export function generateCodeVerifier() {
+    return base64url(randomBytes(32));
+}
+/** The S256 code challenge for `verifier` — `BASE64URL(SHA256(verifier))`. */
+export function codeChallengeFor(verifier) {
+    return base64url(createHash("sha256").update(verifier).digest());
+}
+/** A random `state` value, opaque to the caller, tying an authorization request to its callback. */
+export function generateState() {
+    return base64url(randomBytes(16));
+}

package/dist/oauth/target.d.ts

@@ -0,0 +1,54 @@
+import type { DeployEnvironment } from "@devdogsuga/env";
+import { type LocalSupabaseConfig } from "./db.js";
+export type TargetKind = "local" | "hosted";
+export interface ConnectTarget extends LocalSupabaseConfig {
+    kind: TargetKind;
+}
+/** The env var names a hosted target's URL/service-role key carry OUTSIDE a checkout. */
+export declare const HOSTED_TARGET_ENV_KEYS: {
+    readonly url: "SUPABASE_URL";
+    readonly serviceRoleKey: "SUPABASE_SERVICE_ROLE_KEY";
+};
+/** `supabase status` failed, or the two keys it reports are incomplete — see `db.ts`. */
+export declare function resolveLocalTarget(cwd: string): Promise<ConnectTarget>;
+/**
+ * Reads a hosted target's URL/service-role key from `.env.local`, then
+ * `.env`, in `cwd`. Returns an empty object (not a throw) when neither file
+ * has both keys — that is the ordinary "prompt for them" case, not an error.
+ */
+export declare function readHostedTargetFromEnvFiles(cwd: string): Partial<LocalSupabaseConfig>;
+/** A checkout's env handling has no `API_URL`/`SECRET_KEY` for the chosen tier. */
+export declare class HostedCredentialsMissingError extends Error {
+    readonly tier: DeployEnvironment;
+    constructor(tier: DeployEnvironment);
+}
+/** The chosen tier had no tier to resolve to (declined the picker, or none available). */
+export declare class NoTierResolvedError extends Error {
+    constructor();
+}
+export interface RepoHostedTargetDeps {
+    /** `tier.ts`'s `resolveTier`, or a test double with the same shape. */
+    resolveTier: (tierArg: string | undefined, message: string) => Promise<DeployEnvironment | null>;
+    /**
+     * Loads the chosen tier's env into `process.env` (or `env`, when given) —
+     * `@devdogsuga/env/session`'s `enterEnvironment`, called with
+     * `override: true`: the launcher already entered `development` for this
+     * envFree command (see `launch.ts`), and a DELIBERATE, later choice of a
+     * different tier here must win over that earlier one, not lose to it.
+     */
+    enterEnvironment: (tier: DeployEnvironment) => Promise<void>;
+    /** Injectable for tests; defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Resolves a hosted target from INSIDE a DevDogsUGA checkout: asks which
+ * tier (via `resolveTier`, which itself only prompts when more than one
+ * tier's env file is present), enters that tier's environment, and reads
+ * the platform app's `API_URL`/`SECRET_KEY` back out of it.
+ *
+ * Throws `NoTierResolvedError` when no tier was resolved (an invalid
+ * `--tier`, or a declined picker — `resolveTier` already reported the
+ * reason on stderr) and `HostedCredentialsMissingError` when the resolved
+ * tier's env has no `API_URL`/`SECRET_KEY` at all.
+ */
+export declare function resolveHostedTargetInRepo(tierArg: string | undefined, deps: RepoHostedTargetDeps): Promise<ConnectTarget>;

package/dist/oauth/target.js

@@ -0,0 +1,102 @@
+/**
+ * Resolving the Supabase project `devtools oauth` configures — the "target".
+ *
+ * Two kinds:
+ *
+ *   * `local` — whatever Supabase project `supabase status` reports for
+ *     `cwd` (`db.ts`'s `detectLocalSupabase`, unchanged from the original
+ *     wizard).
+ *   * `hosted` — a Supabase project this machine has no local stack for at
+ *     all: staging, production, or someone else's. Its URL and service-role
+ *     key come from wherever devtools already knows to look, in order:
+ *
+ *       1. Inside a DevDogsUGA checkout, from the checked-out repo's own env
+ *          handling: the platform app's `API_URL`/`SECRET_KEY` for a tier
+ *          the contributor picks (TASK-345's forward note — tier resolution
+ *          stays LAZY, done here rather than by the launcher, and only when
+ *          "hosted" is actually chosen).
+ *       2. Outside a checkout — a workshop repo, most likely — from
+ *          `.env.local` or `.env` in `cwd`, read for `SUPABASE_URL` /
+ *          `SUPABASE_SERVICE_ROLE_KEY` (the names the wider Supabase
+ *          ecosystem already uses for exactly this pair, so a project that
+ *          already has them needs no new convention).
+ *       3. Neither: the wizard prompts, same as the original manual flow
+ *          always did for local.
+ *
+ * Every function below returns data or throws; none of them prompt. Prompting
+ * is `wizard.ts`'s job — this module stays testable without `@clack/prompts`
+ * in the loop.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse } from "dotenv";
+import { detectLocalSupabase } from "./db.js";
+/** The env var names a hosted target's URL/service-role key carry OUTSIDE a checkout. */
+export const HOSTED_TARGET_ENV_KEYS = {
+    url: "SUPABASE_URL",
+    serviceRoleKey: "SUPABASE_SERVICE_ROLE_KEY",
+};
+/** `supabase status` failed, or the two keys it reports are incomplete — see `db.ts`. */
+export async function resolveLocalTarget(cwd) {
+    const config = detectLocalSupabase(cwd);
+    return { ...config, kind: "local" };
+}
+/**
+ * Reads a hosted target's URL/service-role key from `.env.local`, then
+ * `.env`, in `cwd`. Returns an empty object (not a throw) when neither file
+ * has both keys — that is the ordinary "prompt for them" case, not an error.
+ */
+export function readHostedTargetFromEnvFiles(cwd) {
+    for (const file of [".env.local", ".env"]) {
+        const path = join(cwd, file);
+        if (!existsSync(path))
+            continue;
+        const parsed = parse(readFileSync(path, "utf-8"));
+        const apiUrl = parsed[HOSTED_TARGET_ENV_KEYS.url];
+        const serviceRoleKey = parsed[HOSTED_TARGET_ENV_KEYS.serviceRoleKey];
+        if (apiUrl && serviceRoleKey)
+            return { apiUrl, serviceRoleKey };
+    }
+    return {};
+}
+/** A checkout's env handling has no `API_URL`/`SECRET_KEY` for the chosen tier. */
+export class HostedCredentialsMissingError extends Error {
+    tier;
+    constructor(tier) {
+        super(`${tier}'s API_URL/SECRET_KEY are not available in this checkout — run ` +
+            `\`pnpm devtools env pull --target ${tier}\` first.`);
+        this.tier = tier;
+        this.name = "HostedCredentialsMissingError";
+    }
+}
+/** The chosen tier had no tier to resolve to (declined the picker, or none available). */
+export class NoTierResolvedError extends Error {
+    constructor() {
+        super("No tier was resolved for the hosted Supabase project.");
+        this.name = "NoTierResolvedError";
+    }
+}
+/**
+ * Resolves a hosted target from INSIDE a DevDogsUGA checkout: asks which
+ * tier (via `resolveTier`, which itself only prompts when more than one
+ * tier's env file is present), enters that tier's environment, and reads
+ * the platform app's `API_URL`/`SECRET_KEY` back out of it.
+ *
+ * Throws `NoTierResolvedError` when no tier was resolved (an invalid
+ * `--tier`, or a declined picker — `resolveTier` already reported the
+ * reason on stderr) and `HostedCredentialsMissingError` when the resolved
+ * tier's env has no `API_URL`/`SECRET_KEY` at all.
+ */
+export async function resolveHostedTargetInRepo(tierArg, deps) {
+    const tier = await deps.resolveTier(tierArg, "Which tier's Supabase project are you connecting?");
+    if (!tier)
+        throw new NoTierResolvedError();
+    await deps.enterEnvironment(tier);
+    const env = deps.env ?? process.env;
+    const apiUrl = env.API_URL;
+    const serviceRoleKey = env.SECRET_KEY;
+    if (!apiUrl || !serviceRoleKey) {
+        throw new HostedCredentialsMissingError(tier);
+    }
+    return { apiUrl, serviceRoleKey, kind: "hosted" };
+}

package/dist/oauth/transport.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Chooses which connect transport `devtools oauth`'s one-click branch uses:
+ * `loopback` (TASK-351 — a local HTTP listener catches the platform's
+ * redirect) or `device` (TASK-352 — a short code, approved in a browser
+ * running anywhere, polled for). The device flow's browser step need not run
+ * on this machine at all, which is exactly what a loopback redirect cannot
+ * offer: nothing can redirect back to a listener the approving browser can't
+ * reach.
+ *
+ * Three ways this gets decided, in order:
+ *
+ *   1. `--device`/`--loopback` on the command line — an explicit, later
+ *      choice always wins over any inference below.
+ *   2. The environment: SSH (`SSH_CONNECTION`/`SSH_TTY`), a GitHub Codespace
+ *      (`CODESPACES=true`), or a dev container (`REMOTE_CONTAINERS`/
+ *      `DEVCONTAINER`) all mean the browser that will approve the
+ *      connection is almost certainly NOT running on this machine, so a
+ *      loopback redirect would just hang.
+ *   3. Neither of the above: try loopback. `wizard.ts` itself handles the
+ *      remaining case — the loopback listener failing to start — by
+ *      falling back to device at that point, since that failure is only
+ *      known once `loopback.ts`'s `start()` has actually been tried.
+ */
+export type ConnectTransport = "loopback" | "device";
+export interface TransportDecision {
+    transport: ConnectTransport;
+    reason: string;
+}
+/** Human-readable reason a remote/headless environment was detected, or `null` if none was. */
+export declare function detectRemoteEnvironmentReason(env?: NodeJS.ProcessEnv): string | null;
+/**
+ * Resolves the transport BEFORE a loopback listener is ever attempted.
+ * `forceDevice`/`forceLoopback` come from `--device`/`--loopback`; `cli.ts`
+ * refuses both being set at once before this is ever called, so at most one
+ * is true here.
+ */
+export declare function decideTransport({ forceDevice, forceLoopback, env, }: {
+    forceDevice?: boolean;
+    forceLoopback?: boolean;
+    env?: NodeJS.ProcessEnv;
+}): TransportDecision;

package/dist/oauth/transport.js

@@ -0,0 +1,32 @@
+/** Human-readable reason a remote/headless environment was detected, or `null` if none was. */
+export function detectRemoteEnvironmentReason(env = process.env) {
+    if (env.SSH_CONNECTION || env.SSH_TTY) {
+        return "an SSH session (SSH_CONNECTION/SSH_TTY is set)";
+    }
+    if (env.CODESPACES === "true") {
+        return "a GitHub Codespace (CODESPACES=true)";
+    }
+    if (env.REMOTE_CONTAINERS || env.DEVCONTAINER) {
+        return "a dev container (REMOTE_CONTAINERS/DEVCONTAINER is set)";
+    }
+    return null;
+}
+/**
+ * Resolves the transport BEFORE a loopback listener is ever attempted.
+ * `forceDevice`/`forceLoopback` come from `--device`/`--loopback`; `cli.ts`
+ * refuses both being set at once before this is ever called, so at most one
+ * is true here.
+ */
+export function decideTransport({ forceDevice, forceLoopback, env = process.env, }) {
+    if (forceDevice) {
+        return { transport: "device", reason: "--device was passed" };
+    }
+    if (forceLoopback) {
+        return { transport: "loopback", reason: "--loopback was passed" };
+    }
+    const remoteReason = detectRemoteEnvironmentReason(env);
+    if (remoteReason) {
+        return { transport: "device", reason: `detected ${remoteReason}` };
+    }
+    return { transport: "loopback", reason: "no remote environment detected" };
+}

package/dist/oauth/wizard.d.ts

@@ -0,0 +1,33 @@
+import { type ExchangeResult } from "./exchange.js";
+import { type ConnectTransport } from "./transport.js";
+import { type ConnectTarget } from "./target.js";
+/**
+ * Step 2 (one-click branch): decides loopback vs. device (see `transport.ts`)
+ * and runs it.
+ *
+ * `transportOverride` is `--device`/`--loopback` (see `commands.ts`'s `oauth`
+ * node); `cli.ts` refuses passing both, so at most one is set here. Left
+ * undefined, the transport is auto-detected from the environment.
+ *
+ * `startLoopback()` is called HERE, not inside `connectOneClick`, and ONLY
+ * its failure falls back to device — every failure that can happen once the
+ * listener is actually up (denial, timeout, a bad exchange — all of which
+ * `connectOneClick` reports via `bail()`, or an unexpected rethrow) is that
+ * flow's own and must propagate unchanged, not be mistaken for "the listener
+ * never started" and silently rerouted to a different transport with a
+ * misleading warning. Loopback forced via `--loopback` never falls back at
+ * all: a start failure there is left to propagate as-is.
+ */
+export declare function connectViaOneClick(target: ConnectTarget, platformUrl: string, cwd: string, transportOverride: ConnectTransport | undefined): Promise<ExchangeResult>;
+/**
+ * The wizard. `baseUrlOverride`/`platformUrlOverride`, when given, skip
+ * their respective prompts (only reachable via "Paste credentials instead"
+ * and the one-click flow respectively). `transportOverride` (`--device`/
+ * `--loopback`) forces the one-click flow's transport — see
+ * `connectViaOneClick` — and is ignored on the "Paste credentials instead"
+ * branch, which has no transport of its own.
+ *
+ * Intro and outro are the caller's, so this composes into the devtools menu
+ * without drawing a second box inside the first.
+ */
+export declare function runOAuthSetup(baseUrlOverride?: string, platformUrlOverride?: string, transportOverride?: ConnectTransport): Promise<void>;