@buildinternet/uploads 0.6.0 → 0.7.0

package/dist/cli.js

@@ -48,7 +48,7 @@ Commands:
   purge-expired       Delete objects past retentionDays
   setup               Inspect/configure advanced CLI settings
   install             Install the agent skill + register the remote MCP server
-  login               Exchange an enrollment code and configure credentials
+  login               Sign in via browser (or an enrollment code) and save credentials
   admin               Admin invitation management
   config              Show path, init, or set shared config
   doctor              Health + auth + workspace checks

package/dist/client.d.ts

@@ -63,6 +63,8 @@ export interface GalleryItem {
     createdAt: string;
     status: "available" | "missing";
     url: string | null;
+    /** Standalone web page for this item (gallery URL + item id). Absent on older API deployments. */
+    pageUrl?: string;
     contentType: string | null;
     size: number | null;
 }
@@ -189,6 +191,72 @@ export declare function createEnrollment(apiUrl: string, adminToken: string, inp
     tokenExpiresInSeconds?: number;
     scopes?: Array<"files:read" | "files:write" | "files:delete">;
 }): Promise<EnrollmentCreateResult>;
+/** Static OAuth client id allowlisted by the auth worker's `validateClient`. */
+export declare const DEVICE_CLIENT_ID = "uploads-cli";
+export interface DeviceCodeResponse {
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    verification_uri_complete?: string;
+    expires_in: number;
+    interval: number;
+}
+/** POST /api/auth/device/code — start a device flow. Throws on a non-2xx. */
+export declare function requestDeviceCode(authUrl: string, clientId?: string): Promise<DeviceCodeResponse>;
+/**
+ * One poll of POST /api/auth/device/token. Unlike most calls, the "not ready
+ * yet" outcomes (`authorization_pending`, `slow_down`) are EXPECTED 400s, so
+ * this returns a discriminated result instead of throwing — the caller's poll
+ * loop branches on `status`.
+ */
+export type DeviceTokenResult = {
+    status: "ok";
+    accessToken: string;
+    tokenType: string;
+    expiresIn: number;
+    scope: string;
+} | {
+    status: "pending";
+} | {
+    status: "slow_down";
+} | {
+    status: "expired";
+} | {
+    status: "denied";
+} | {
+    status: "error";
+    error: string;
+    description?: string;
+};
+export declare function requestDeviceToken(authUrl: string, input: {
+    deviceCode: string;
+    clientId?: string;
+}): Promise<DeviceTokenResult>;
+export interface MintWorkspaceSummary {
+    workspace: string;
+    role: string;
+}
+/** GET /v1/tokens — workspaces the signed-in user can mint tokens for. */
+export declare function listMintWorkspaces(apiUrl: string, accessToken: string): Promise<{
+    workspaces: MintWorkspaceSummary[];
+}>;
+export interface MintTokenResult {
+    token: string;
+    workspace: string;
+    scopes: Array<"files:read" | "files:write" | "files:delete">;
+    label: string | null;
+    expiresAt: string | null;
+}
+/**
+ * POST /v1/tokens — mint a `up_<workspace>_…` workspace token from a device-flow
+ * session (presented as a bearer). v1 sends exactly one grant.
+ */
+export declare function mintWorkspaceToken(apiUrl: string, accessToken: string, input: {
+    workspace: string;
+    scopes?: Array<"files:read" | "files:write" | "files:delete">;
+    label?: string;
+    ttlSeconds?: number;
+}): Promise<MintTokenResult>;
 export declare function createUploadsClient(config: UploadsClientConfig): {
     put(body: Uint8Array, opts: PutOptions & {
         filename: string;

package/dist/client.js

@@ -27,6 +27,87 @@ export function createEnrollment(apiUrl, adminToken, input) {
         body: JSON.stringify(input),
     });
 }
+// --- Device authorization (RFC 8628) — the `uploads login` device flow ---
+//
+// The CLI speaks the auth worker's OAuth-shaped endpoints directly with plain
+// `fetch` (no better-auth client dependency in the published package, per plan
+// D5). Better Auth's `device.code`/`device.token` endpoints take
+// `application/json` bodies, NOT the RFC's form-encoding — the JSON shapes
+// below are what the worker expects.
+/** Static OAuth client id allowlisted by the auth worker's `validateClient`. */
+export const DEVICE_CLIENT_ID = "uploads-cli";
+/** POST /api/auth/device/code — start a device flow. Throws on a non-2xx. */
+export function requestDeviceCode(authUrl, clientId = DEVICE_CLIENT_ID) {
+    return jsonRequest(`${authUrl.replace(/\/$/, "")}/api/auth/device/code`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ client_id: clientId }),
+    });
+}
+export async function requestDeviceToken(authUrl, input) {
+    let res;
+    try {
+        res = await fetch(`${authUrl.replace(/\/$/, "")}/api/auth/device/token`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+                device_code: input.deviceCode,
+                client_id: input.clientId ?? DEVICE_CLIENT_ID,
+            }),
+        });
+    }
+    catch (err) {
+        throw new UploadsError(err instanceof Error ? err.message : "network request failed", "NETWORK");
+    }
+    const body = (await res.json().catch(() => null));
+    if (res.ok && body?.access_token) {
+        return {
+            status: "ok",
+            accessToken: body.access_token,
+            tokenType: body.token_type ?? "Bearer",
+            expiresIn: typeof body.expires_in === "number" ? body.expires_in : 0,
+            scope: body.scope ?? "",
+        };
+    }
+    switch (body?.error) {
+        case "authorization_pending":
+            return { status: "pending" };
+        case "slow_down":
+            return { status: "slow_down" };
+        case "expired_token":
+            return { status: "expired" };
+        case "access_denied":
+            return { status: "denied" };
+        default:
+            return {
+                status: "error",
+                error: body?.error ?? "unknown",
+                description: body?.error_description,
+            };
+    }
+}
+/** GET /v1/tokens — workspaces the signed-in user can mint tokens for. */
+export function listMintWorkspaces(apiUrl, accessToken) {
+    return jsonRequest(`${apiUrl.replace(/\/$/, "")}/v1/tokens`, {
+        headers: { Authorization: `Bearer ${accessToken}` },
+    });
+}
+/**
+ * POST /v1/tokens — mint a `up_<workspace>_…` workspace token from a device-flow
+ * session (presented as a bearer). v1 sends exactly one grant.
+ */
+export function mintWorkspaceToken(apiUrl, accessToken, input) {
+    return jsonRequest(`${apiUrl.replace(/\/$/, "")}/v1/tokens`, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${accessToken}`, "Content-Type": "application/json" },
+        body: JSON.stringify({
+            grants: [{ workspace: input.workspace, ...(input.scopes ? { scopes: input.scopes } : {}) }],
+            ...(input.label ? { label: input.label } : {}),
+            ...(input.ttlSeconds ? { ttlSeconds: input.ttlSeconds } : {}),
+        }),
+    });
+}
 function encodeKeyPath(key) {
     return key.split("/").map(encodeURIComponent).join("/");
 }

package/dist/commands/login.d.ts

@@ -5,7 +5,20 @@ export declare function resolveEnrollmentCode(parsed: ReturnType<typeof parseCom
     readLine: () => Promise<string>;
     hiddenPrompt: () => Promise<string>;
 }): Promise<string>;
+/**
+ * Auth worker base URL: explicit flag > UPLOADS_AUTH_URL > swap an `api.` host
+ * label for `auth.` > the production default. Local multi-worker dev (where
+ * auth runs on a different loopback port than the API) needs an explicit
+ * --auth-url / UPLOADS_AUTH_URL.
+ */
+export declare function resolveAuthUrl(parsed: ReturnType<typeof parseCommandArgs>, apiUrl: string): string;
+export interface DeviceLoginIo {
+    sleep: (ms: number) => Promise<void>;
+    now: () => number;
+    openUrl: (url: string) => void;
+    write: (text: string) => void;
+}
 export declare function runLogin(args: string[], opts: {
     json?: boolean;
     apiUrl?: string;
-}, help?: boolean): Promise<number>;
+}, help?: boolean, deviceIo?: DeviceLoginIo): Promise<number>;

package/dist/commands/login.js

@@ -1,15 +1,26 @@
+import { hostname } from "node:os";
+import { spawn } from "node:child_process";
 import { stdin, stdout } from "node:process";
 import { loadConfigFile, redactToken, resolveConfigPath, writeConfigKeys, workspaceFromToken, } from "../config.js";
-import { exchangeEnrollment, createUploadsClient } from "../client.js";
+import { createUploadsClient, exchangeEnrollment, listMintWorkspaces, mintWorkspaceToken, requestDeviceCode, requestDeviceToken, } from "../client.js";
 import { flagBool, flagString, parseCommandArgs, UsageError } from "../cli-args.js";
+import { parseScopes } from "./admin-enrollment.js";
 const HELP = `uploads login [options]
 
-Exchange a one-time enrollment code for workspace credentials, save them, and
-verify access. Ask your uploads.sh administrator for an enrollment code.
+Sign in and save workspace credentials. With no flags, opens a browser to
+authorize this device — the recommended way to sign in. Pass an enrollment
+code only if you were given one from before device login (fallback path).
 
 Options:
-  --code <code>       Code in argv (may be visible in shell history/process lists)
-  --code-stdin        Read one line from stdin
+  --workspace <name>  Workspace to mint a token for (device flow; required if
+                      your account can access more than one)
+  --scopes <list>     Comma-separated scopes (default: files:read,files:write)
+  --label <text>      Token label (default: this machine's hostname)
+  --auth-url <url>    Auth base (default: https://auth.uploads.sh)
+  --no-open           Don't try to open a browser automatically
+  --code <code>       Fallback: use a pre-existing enrollment code instead of
+                      device login (visible in shell history)
+  --code-stdin        Fallback: read a pre-existing enrollment code from stdin
   --non-interactive   Never prompt
   --api-url <url>     API base (default: https://api.uploads.sh)
   --path <file>       Config destination
@@ -17,10 +28,10 @@ Options:
   --no-check          Skip doctor verification
 
 Examples:
-  uploads login --code upe_…
-  uploads login --code-stdin --non-interactive < code.txt
+  uploads login
+  uploads login --workspace acme
+  uploads login --code upe_… --force              # fallback: pre-existing invite
   printf '%s' upe_… | uploads login --code-stdin --non-interactive
-  uploads login --code upe_… --force --no-check
 `;
 export function validateEnrollmentCode(raw) {
     const code = raw.trim();
@@ -104,7 +115,135 @@ export async function resolveEnrollmentCode(parsed, io = {
         return validateEnrollmentCode(await io.readLine());
     return validateEnrollmentCode(await io.hiddenPrompt());
 }
-export async function runLogin(args, opts, help = false) {
+/** True when the caller supplied an enrollment code (via flag, stdin, or env). */
+function hasEnrollmentSource(parsed) {
+    return (Boolean(flagString(parsed.flags, "--code")) ||
+        flagBool(parsed.flags, "--code-stdin") ||
+        Boolean(process.env.UPLOADS_ENROLLMENT_CODE));
+}
+/**
+ * Auth worker base URL: explicit flag > UPLOADS_AUTH_URL > swap an `api.` host
+ * label for `auth.` > the production default. Local multi-worker dev (where
+ * auth runs on a different loopback port than the API) needs an explicit
+ * --auth-url / UPLOADS_AUTH_URL.
+ */
+export function resolveAuthUrl(parsed, apiUrl) {
+    const explicit = flagString(parsed.flags, "--auth-url") ?? process.env.UPLOADS_AUTH_URL;
+    if (explicit)
+        return explicit.replace(/\/$/, "");
+    try {
+        const url = new URL(apiUrl);
+        if (url.hostname.startsWith("api.")) {
+            url.hostname = `auth.${url.hostname.slice(4)}`;
+            return url.origin;
+        }
+    }
+    catch {
+        // fall through to the default
+    }
+    return "https://auth.uploads.sh";
+}
+/** Best-effort browser open. The URL is always printed too, so failures are silent. */
+function openUrl(url) {
+    try {
+        const isWin = process.platform === "win32";
+        const command = process.platform === "darwin" ? "open" : isWin ? "cmd" : "xdg-open";
+        const args = isWin ? ["/c", "start", "", url] : [url];
+        const child = spawn(command, args, { stdio: "ignore", detached: true });
+        child.on("error", () => { });
+        child.unref();
+    }
+    catch {
+        // ignore — the URL is printed for manual navigation.
+    }
+}
+const defaultDeviceIo = {
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    now: () => Date.now(),
+    openUrl,
+    write: (text) => {
+        process.stderr.write(text);
+    },
+};
+/**
+ * Device-authorization login (RFC 8628): request a code, have the user approve
+ * it in a browser, poll for the session token, then mint a workspace token.
+ */
+async function runDeviceLogin(parsed, opts, io) {
+    const scopes = parseScopes(flagString(parsed.flags, "--scopes"));
+    const label = flagString(parsed.flags, "--label") ?? safeHostname();
+    const requestedWorkspace = flagString(parsed.flags, "--workspace");
+    const code = await requestDeviceCode(opts.authUrl);
+    const verifyUrl = code.verification_uri_complete ?? code.verification_uri;
+    io.write(`To sign in, open:\n\n  ${verifyUrl}\n\nand confirm this code:\n\n  ${code.user_code}\n\n`);
+    if (!opts.noOpen)
+        io.openUrl(verifyUrl);
+    io.write("Waiting for approval…\n");
+    const accessToken = await pollForDeviceToken(opts.authUrl, code, io);
+    const workspace = await resolveMintWorkspace(opts.apiUrl, accessToken, requestedWorkspace);
+    const minted = await mintWorkspaceToken(opts.apiUrl, accessToken, { workspace, scopes, label });
+    return { workspace: minted.workspace, token: minted.token, apiUrl: opts.apiUrl };
+}
+function safeHostname() {
+    try {
+        return hostname() || "cli";
+    }
+    catch {
+        return "cli";
+    }
+}
+/** Poll device/token honoring interval / slow_down / pending until approved or expired. */
+async function pollForDeviceToken(authUrl, code, io) {
+    let intervalMs = Math.max(1, code.interval) * 1000;
+    const deadline = io.now() + Math.max(1, code.expires_in) * 1000;
+    while (io.now() < deadline) {
+        await io.sleep(intervalMs);
+        let result;
+        try {
+            result = await requestDeviceToken(authUrl, { deviceCode: code.device_code });
+        }
+        catch {
+            // A transient network blip mid-poll shouldn't abort a login the user may
+            // already have approved — keep polling until the device code's deadline.
+            continue;
+        }
+        switch (result.status) {
+            case "ok":
+                return result.accessToken;
+            case "pending":
+                continue;
+            case "slow_down":
+                // RFC 8628 §3.5: back off by 5s and keep polling.
+                intervalMs += 5000;
+                continue;
+            case "denied":
+                throw new UsageError("device authorization was denied");
+            case "expired":
+                throw new UsageError("the device code expired before it was approved");
+            default:
+                throw new UsageError(`device authorization failed: ${result.error}${result.description ? ` — ${result.description}` : ""}`);
+        }
+    }
+    throw new UsageError("timed out waiting for device authorization");
+}
+/**
+ * Pick the workspace to mint for. An explicit --workspace wins; otherwise, if
+ * the account can access exactly one workspace, use it — and if it can access
+ * several, require the flag rather than guessing.
+ */
+async function resolveMintWorkspace(apiUrl, accessToken, requested) {
+    if (requested)
+        return requested;
+    const { workspaces } = await listMintWorkspaces(apiUrl, accessToken);
+    if (workspaces.length === 1)
+        return workspaces[0].workspace;
+    if (workspaces.length === 0) {
+        throw new UsageError("your account has no workspace access yet — ask an administrator for an invitation");
+    }
+    const names = workspaces.map((w) => w.workspace).join(", ");
+    throw new UsageError(`multiple workspaces available (${names}); pass --workspace <name>`);
+}
+export async function runLogin(args, opts, help = false, deviceIo = defaultDeviceIo) {
     const parsed = parseCommandArgs(args);
     if (help || parsed.help) {
         process.stderr.write(HELP);
@@ -118,11 +257,24 @@ export async function runLogin(args, opts, help = false) {
         throw new UsageError(`credentials already exist in ${path}; use --force to replace them`);
     if (process.env.UPLOADS_TOKEN && !force)
         throw new UsageError("UPLOADS_TOKEN is already set in the environment; unset it or use --force");
-    const code = await resolveEnrollmentCode(parsed);
-    const result = await exchangeEnrollment(apiUrl, code);
+    let result;
+    if (hasEnrollmentSource(parsed)) {
+        const code = await resolveEnrollmentCode(parsed);
+        result = await exchangeEnrollment(apiUrl, code);
+    }
+    else {
+        // The device flow is inherently interactive (browser approval, then a poll
+        // that runs to the device code's ~30-min deadline). Fail fast rather than
+        // hanging a non-interactive/CI invocation that has no code to fall back on.
+        if (flagBool(parsed.flags, "--non-interactive")) {
+            throw new UsageError("device login requires a browser; run interactively, or pass --code for the enrollment path");
+        }
+        const authUrl = resolveAuthUrl(parsed, apiUrl);
+        result = await runDeviceLogin(parsed, { apiUrl, authUrl, noOpen: flagBool(parsed.flags, "--no-open") }, deviceIo);
+    }
     const encoded = workspaceFromToken(result.token);
     if (!encoded || encoded !== result.workspace || /[\r\n]/.test(result.token))
-        throw new UsageError("enrollment returned invalid credentials");
+        throw new UsageError("login returned invalid credentials");
     const savedApiUrl = result.apiUrl ?? apiUrl;
     const write = writeConfigKeys(path, {
         UPLOADS_API_URL: savedApiUrl,

package/dist/commands/setup.js

@@ -64,8 +64,10 @@ function formatWizard(status) {
     lines.push("");
     if (!status.token) {
         lines.push("Step 1 — Sign in");
-        lines.push("  Ask your uploads.sh administrator for a one-time enrollment code, then run:");
+        lines.push("  Run:");
         lines.push("    uploads login");
+        lines.push("  This opens a browser to authorize this device.");
+        lines.push("  Have a pre-existing enrollment code instead? uploads login --code upe_…");
         lines.push("  If you already have a bearer token:");
         lines.push("    uploads setup --token up_<workspace>_…");
         lines.push("");
@@ -207,7 +209,7 @@ export async function runSetup(args, opts, help = false) {
         process.stderr.write("hint: run uploads doctor to verify\n");
     }
     else {
-        process.stderr.write("hint: run uploads login with an admin-provided enrollment code\n");
+        process.stderr.write("hint: run uploads login (or uploads login --code <code> if you have one)\n");
     }
     return doctorOk === false ? 1 : 0;
 }

package/dist/commands.js

@@ -181,7 +181,11 @@ export async function syncAttachmentsComment(client, target, run) {
                 previews: detail.items
                     .filter((item) => item.status === "available" && item.url && item.contentType?.startsWith("image/"))
                     .slice(0, 3)
-                    .map((item) => ({ url: item.url, alt: item.altText ?? item.objectKey })),
+                    .map((item) => ({
+                    url: item.url,
+                    alt: item.altText ?? item.objectKey,
+                    itemUrl: item.pageUrl,
+                })),
             };
         }
         catch {

package/dist/github.d.ts

@@ -33,10 +33,11 @@ export interface GalleryCommentItem {
     title: string;
     /** Canonical URL returned by the API; callers must not synthesize it. */
     url: string;
-    /** A bounded set of available images, all of which link back to the gallery. */
+    /** A bounded set of available images; each links to its item page when known, else the gallery. */
     previews?: {
         url: string;
         alt: string;
+        itemUrl?: string;
     }[];
 }
 /** Default max width for images in the managed attachments comment (HTML img). */

package/dist/github.js

@@ -106,7 +106,8 @@ export function attachmentsCommentBody(items, galleries = []) {
             const href = escapeHtmlAttr(gallery.url);
             lines.push(`#### <a href="${href}">${escapeHtmlText(gallery.title)}</a>`);
             for (const preview of gallery.previews ?? []) {
-                lines.push(`<a href="${href}"><img width="320" alt="${escapeHtmlAttr(preview.alt)}" src="${escapeHtmlAttr(preview.url)}"></a>`);
+                const previewHref = preview.itemUrl ? escapeHtmlAttr(preview.itemUrl) : href;
+                lines.push(`<a href="${previewHref}"><img width="320" alt="${escapeHtmlAttr(preview.alt)}" src="${escapeHtmlAttr(preview.url)}"></a>`);
             }
             lines.push(`<sub><a href="${href}">Open gallery</a></sub>`, "");
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildinternet/uploads",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "CLI and client for uploads.sh — workspace-scoped image hosting for GitHub embeds",
   "type": "module",
   "sideEffects": false,