@buildinternet/uploads 0.21.0 → 0.22.0

package/dist/client.d.ts

@@ -41,6 +41,8 @@ export interface ListOptions {
     prefix?: string;
     limit?: number;
     cursor?: string;
+    /** Hydrate each row's queryable D1 metadata (`?metadata=1`). */
+    metadata?: boolean;
 }
 export interface FindFilesOptions {
     prefix?: string;
@@ -90,6 +92,8 @@ export interface ListItem {
     pageUrl?: string;
     size?: number;
     uploaded?: string;
+    /** Present only when listed with `metadata: true`, and only for keys that have rows. */
+    metadata?: Record<string, string>;
 }
 export interface ListResult {
     items: ListItem[];
@@ -351,7 +355,14 @@ export interface DeviceCodeResponse {
     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>;
+export declare function requestDeviceCode(authUrl: string, clientId?: string, 
+/**
+ * RFC 8628 `scope`. Carries the requested workspace (`workspace:<slug>`,
+ * plus `create`) so the approval page can validate it before approving —
+ * issue #362. Stored on the device-code row and echoed back at token
+ * exchange, possibly rewritten by the page.
+ */
+scope?: 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

package/dist/client.js

@@ -56,14 +56,21 @@ export function cliUserAgent(purpose = "device-login") {
     return `@buildinternet/uploads/${packageVersion()} (${purpose})`;
 }
 /** POST /api/auth/device/code — start a device flow. Throws on a non-2xx. */
-export function requestDeviceCode(authUrl, clientId = DEVICE_CLIENT_ID) {
+export function requestDeviceCode(authUrl, clientId = DEVICE_CLIENT_ID, 
+/**
+ * RFC 8628 `scope`. Carries the requested workspace (`workspace:<slug>`,
+ * plus `create`) so the approval page can validate it before approving —
+ * issue #362. Stored on the device-code row and echoed back at token
+ * exchange, possibly rewritten by the page.
+ */
+scope) {
     return jsonRequest(`${authUrl.replace(/\/$/, "")}/api/auth/device/code`, {
         method: "POST",
         headers: {
             "Content-Type": "application/json",
             "User-Agent": cliUserAgent("device-code"),
         },
-        body: JSON.stringify({ client_id: clientId }),
+        body: JSON.stringify({ client_id: clientId, ...(scope ? { scope } : {}) }),
     });
 }
 export async function requestDeviceToken(authUrl, input) {
@@ -296,6 +303,8 @@ export function createUploadsClient(config) {
             params.set("limit", String(opts.limit));
         if (opts.cursor)
             params.set("cursor", opts.cursor);
+        if (opts.metadata)
+            params.set("metadata", "1");
         const qs = params.toString();
         const page = await request("GET", `${filesBase(config)}${qs ? `?${qs}` : ""}`);
         return {

package/dist/commands/login.d.ts

@@ -1,5 +1,16 @@
 import { parseCommandArgs } from "../cli-args.js";
 export declare function validateEnrollmentCode(raw: string): string;
+/** The scope the CLI sends with its device-code request. No workspace requested → no scope. */
+export declare function formatDeviceScope(workspace: string | undefined, create: boolean): string | undefined;
+/**
+ * Read back what the approval page decided. A surviving `create` token means
+ * the page left the scope alone and deferred provisioning to the CLI; a bare
+ * `workspace:<slug>` means the browser recorded a choice and wins.
+ */
+export declare function parseDeviceScope(scope: string | undefined): {
+    workspace: string | undefined;
+    create: boolean;
+};
 export declare function resolveEnrollmentCode(parsed: ReturnType<typeof parseCommandArgs>, io?: {
     isTTY: boolean;
     readLine: () => Promise<string>;
@@ -23,10 +34,21 @@ export interface DeviceLoginIo {
     promptWorkspaceName: () => Promise<string>;
 }
 export declare const defaultDeviceIo: DeviceLoginIo;
+/** A completed device authorization: the session bearer plus the (possibly rewritten) scope. */
+export interface DeviceSession {
+    accessToken: string;
+    scope: string;
+}
 /**
  * Browser device-authorization session only (no workspace token mint).
  * Shared by `uploads login` and `uploads invite create`.
  */
+export declare function obtainDeviceSession(authUrl: string, opts?: {
+    noOpen?: boolean;
+    prompt?: string;
+    scope?: string;
+}, io?: DeviceLoginIo): Promise<DeviceSession>;
+/** Session bearer only — `invite create` has no workspace to resolve. */
 export declare function obtainDeviceAccessToken(authUrl: string, opts?: {
     noOpen?: boolean;
     prompt?: string;
@@ -36,7 +58,7 @@ export declare function pollForDeviceToken(authUrl: string, code: {
     device_code: string;
     interval: number;
     expires_in: number;
-}, io: DeviceLoginIo): Promise<string>;
+}, io: DeviceLoginIo): Promise<DeviceSession>;
 export declare function runLogin(args: string[], opts: {
     json?: boolean;
     apiUrl?: string;

package/dist/commands/login.js

@@ -7,15 +7,17 @@ import { createUploadsClient, createWorkspaceRequest, exchangeEnrollment, listMi
 import { flagBool, flagString, parseCommandArgs, UsageError } from "../cli-args.js";
 import { parseScopes } from "./admin-enrollment.js";
 import { writeCommandHelp } from "../cli-style.js";
+import { UploadsError } from "../errors.js";
 const HELP = `uploads login [options]
 
 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).
+authorize this device — the recommended way to sign in. The browser asks which
+workspace to sign in to, so --workspace is optional. Pass an enrollment code
+only if you were given one from before device login (fallback path).
 
 Options:
-  --workspace <name>  Workspace to mint a token for (device flow; required if
-                      your account can access more than one)
+  --workspace <name>  Preselect this workspace in the browser (device flow);
+                      you can still change it there
   --create            With --workspace: create the workspace first if your
                       account doesn't have it yet (device flow only) — lets
                       scripted/agent logins provision without a prompt
@@ -46,6 +48,34 @@ export function validateEnrollmentCode(raw) {
         throw new UsageError("invalid enrollment code");
     return code;
 }
+/**
+ * Device-code scope vocabulary (issue #362). Mirrors `parseDeviceScope` /
+ * `workspaceScopeValue` in apps/auth/src/device-workspace.ts — this package
+ * ships with no workspace dependencies, so the two copies are deliberately
+ * independent. Keep the vocabulary in sync.
+ */
+const WORKSPACE_SCOPE_PREFIX = "workspace:";
+const CREATE_SCOPE_TOKEN = "create";
+/** The scope the CLI sends with its device-code request. No workspace requested → no scope. */
+export function formatDeviceScope(workspace, create) {
+    if (!workspace)
+        return undefined;
+    return create
+        ? `${WORKSPACE_SCOPE_PREFIX}${workspace} ${CREATE_SCOPE_TOKEN}`
+        : `${WORKSPACE_SCOPE_PREFIX}${workspace}`;
+}
+/**
+ * Read back what the approval page decided. A surviving `create` token means
+ * the page left the scope alone and deferred provisioning to the CLI; a bare
+ * `workspace:<slug>` means the browser recorded a choice and wins.
+ */
+export function parseDeviceScope(scope) {
+    const tokens = (scope ?? "").split(/\s+/).filter(Boolean);
+    const slug = tokens
+        .find((t) => t.startsWith(WORKSPACE_SCOPE_PREFIX))
+        ?.slice(WORKSPACE_SCOPE_PREFIX.length) ?? "";
+    return { workspace: slug || undefined, create: tokens.includes(CREATE_SCOPE_TOKEN) };
+}
 async function readLine() {
     let out = "";
     for await (const chunk of stdin) {
@@ -187,8 +217,8 @@ export const defaultDeviceIo = {
  * Browser device-authorization session only (no workspace token mint).
  * Shared by `uploads login` and `uploads invite create`.
  */
-export async function obtainDeviceAccessToken(authUrl, opts = {}, io = defaultDeviceIo) {
-    const code = await requestDeviceCode(authUrl);
+export async function obtainDeviceSession(authUrl, opts = {}, io = defaultDeviceIo) {
+    const code = await requestDeviceCode(authUrl, undefined, opts.scope);
     const verifyUrl = code.verification_uri_complete ?? code.verification_uri;
     const prompt = opts.prompt ?? "To sign in, open:";
     io.write(`${prompt}\n\n  ${verifyUrl}\n\nand confirm this code:\n\n  ${code.user_code}\n\n`);
@@ -197,6 +227,31 @@ export async function obtainDeviceAccessToken(authUrl, opts = {}, io = defaultDe
     io.write("Waiting for approval…\n");
     return pollForDeviceToken(authUrl, code, io);
 }
+/** Session bearer only — `invite create` has no workspace to resolve. */
+export async function obtainDeviceAccessToken(authUrl, opts = {}, io = defaultDeviceIo) {
+    return (await obtainDeviceSession(authUrl, opts, io)).accessToken;
+}
+/**
+ * Turn the API's deliberately opaque 403 (`no access to this workspace` — it
+ * refuses to distinguish "doesn't exist" from "you're not a member", see
+ * apps/api/src/routes/tokens.ts) into something the user can act on, by
+ * listing the workspaces their own account CAN reach. Backstop only: since
+ * #362 the approval page catches this before approving.
+ */
+async function describeMintFailure(apiUrl, accessToken, workspace, err) {
+    if (!(err instanceof UploadsError) || err.status !== 403)
+        throw err;
+    let names = [];
+    try {
+        names = (await listMintWorkspaces(apiUrl, accessToken)).workspaces.map((w) => w.workspace);
+    }
+    catch {
+        // Listing is best-effort — fall through to the generic hint below.
+    }
+    throw new UsageError(names.length
+        ? `no access to workspace "${workspace}" — this account can use: ${names.join(", ")}`
+        : `no access to workspace "${workspace}" — this account has no workspaces yet; pass --workspace <name> --create to provision one`);
+}
 /**
  * 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.
@@ -217,9 +272,22 @@ async function runDeviceLogin(parsed, opts, io) {
     // Make the target explicit: a bare `uploads login` on a self-hosted install
     // would otherwise silently sign in to the cloud service.
     io.write(`signing in to ${opts.authUrl} (self-hosted? pass --api-url or set UPLOADS_API_URL)\n\n`);
-    const accessToken = await obtainDeviceAccessToken(opts.authUrl, { noOpen: opts.noOpen }, io);
-    const workspace = await resolveMintWorkspace(opts.apiUrl, accessToken, requestedWorkspace, io, flagBool(parsed.flags, "--create"));
-    const minted = await mintWorkspaceToken(opts.apiUrl, accessToken, { workspace, scopes, label });
+    const create = flagBool(parsed.flags, "--create");
+    const session = await obtainDeviceSession(opts.authUrl, { noOpen: opts.noOpen, scope: formatDeviceScope(requestedWorkspace, create) }, io);
+    // The approval page is authoritative: it validated the workspace against the
+    // signed-in account's memberships (and may have created a new one) before
+    // approving. A scope that still carries `create` means the page deferred to
+    // the CLI, and an empty one means an older server that doesn't echo a
+    // choice — both fall back to the local resolution below.
+    const chosen = parseDeviceScope(session.scope);
+    const workspace = chosen.workspace && !chosen.create
+        ? chosen.workspace
+        : await resolveMintWorkspace(opts.apiUrl, session.accessToken, requestedWorkspace, io, create);
+    const minted = await mintWorkspaceToken(opts.apiUrl, session.accessToken, {
+        workspace,
+        scopes,
+        label,
+    }).catch((err) => describeMintFailure(opts.apiUrl, session.accessToken, workspace, err));
     return { workspace: minted.workspace, token: minted.token, apiUrl: opts.apiUrl };
 }
 function safeHostname() {
@@ -247,7 +315,7 @@ export async function pollForDeviceToken(authUrl, code, io) {
         }
         switch (result.status) {
             case "ok":
-                return result.accessToken;
+                return { accessToken: result.accessToken, scope: result.scope };
             case "pending":
                 continue;
             case "slow_down":

package/dist/commands.js

@@ -464,12 +464,27 @@ export async function syncAttachmentsComment(client, target, run, workspace) {
         }
     }
     // gh fallback: gather from this workspace's own data and post via local `gh`.
-    // Note (issue #304): this CLI process has no server-side WorkspaceRecord in
-    // scope, so it cannot honor a workspace's githubCommentLinkToFilePage=false
-    // — it always links to the file page here, matching the default. This only
-    // diverges from the bot-posted comment for a workspace that both sets the
-    // flag false and falls through to this gh-fallback path.
-    const items = (await client.listAll({ prefix: ghKeyPrefix(target) })).map(({ key, url, embedUrl, pageUrl }) => ({ key, url, embedUrl, pageUrl }));
+    // Note (issues #304, #365): this CLI process has no server-side
+    // WorkspaceRecord in scope, so it cannot honor a workspace's
+    // githubCommentLinkToFilePage=false or githubCommentShowMetadata=false — it
+    // always links to the file page and always shows metadata here, matching the
+    // defaults. This only diverges from the bot-posted comment for a workspace
+    // that both sets one of those flags false and falls through to this path.
+    const items = (await client.listAll({ prefix: ghKeyPrefix(target), metadata: true })).map(({ key, url, embedUrl, pageUrl, metadata }) => {
+        // The list endpoint returns every metadata key; the comment renders only
+        // these two. Narrowing here keeps both render paths byte-identical.
+        const path = metadata?.path;
+        const state = metadata?.state;
+        return {
+            key,
+            url,
+            embedUrl,
+            pageUrl,
+            ...(path || state
+                ? { meta: { ...(path ? { path } : {}), ...(state ? { state } : {}) } }
+                : {}),
+        };
+    });
     const galleries = [];
     let cursor;
     do {

package/dist/github.d.ts

@@ -75,6 +75,17 @@ export interface AttachmentItem {
     embedUrl?: string | null;
     /** Canonical `/f/` file-page URL (server-computed). Preferred click-through target; falls back to `url`. */
     pageUrl?: string | null;
+    /**
+     * The only canonical metadata the managed comment renders (issue #365).
+     * Deliberately two named fields rather than `Record<string, string>`: the
+     * comment is posted publicly, and keeping the set narrow at the type level
+     * mirrors the server-side query filter that never fetches EXIF-derived
+     * keys like `device`/`software` for this path.
+     */
+    meta?: {
+        path?: string;
+        state?: string;
+    };
 }
 /** A public gallery linked to the PR or issue whose managed comment is syncing. */
 export interface GalleryCommentItem {

package/dist/github.js

@@ -177,6 +177,51 @@ function escapeHtmlAttr(s) {
 function escapeHtmlText(s) {
     return escapeHtmlAttr(s).replace(/'/g, "'").replace(/>/g, ">");
 }
+/**
+ * Backslash-escape the markdown metacharacters that can appear in a metadata
+ * value. `~` is in the set because GitHub's strikethrough extension treats a
+ * matching pair of ONE or two tildes as markup, so an unescaped `/a~b~c` would
+ * render with `b` struck through.
+ */
+function escapeMarkdownText(s) {
+    return s.replace(/([\\`*_[\]~])/g, "\\$1");
+}
+/**
+ * An attachment's caption parts — `path`, then `state` (issue #365). Empty
+ * when neither is usable, so callers emit nothing at all and a body with no
+ * metadata stays byte-identical to the pre-#365 render.
+ *
+ * Neither value is pre-sanitized: metadata values are printable ASCII up to
+ * 512 chars, and while the CLI validates `--state` against a closed enum,
+ * `PATCH /v1/:workspace/files/:key` can set any valid metadata value. A
+ * whitespace-only value passes that validation (length-1 printable ASCII), so
+ * treat it as absent rather than rendering a dangling separator.
+ */
+function metaCaptionParts(meta) {
+    const parts = [];
+    for (const value of [meta?.path, meta?.state]) {
+        const trimmed = value?.trim();
+        if (trimmed)
+            parts.push(trimmed);
+    }
+    return parts;
+}
+/** `<sub>` caption body for an inline image, or null when there is nothing to say. */
+function metaCaptionHtml(meta) {
+    const parts = metaCaptionParts(meta);
+    return parts.length > 0 ? parts.map(escapeHtmlText).join(" · ") : null;
+}
+/**
+ * ` · …` suffix for a markdown list row, or `""` when there is nothing to add.
+ * HTML-escapes first, then markdown-escapes: HTML escaping introduces no
+ * backslashes or brackets, so the markdown pass cannot corrupt its entities.
+ */
+function metaCaptionMarkdown(meta) {
+    const parts = metaCaptionParts(meta);
+    if (parts.length === 0)
+        return "";
+    return ` · ${parts.map((p) => escapeMarkdownText(escapeHtmlText(p))).join(" · ")}`;
+}
 /**
  * Render the one marker-owned GitHub comment. When there are no galleries this
  * intentionally preserves the legacy attachment-only body byte-for-byte.
@@ -224,13 +269,16 @@ export function attachmentsCommentBody(items, galleries = [], marker = ATTACHMEN
             const href = escapeHtmlAttr(link ?? src);
             const imgSrc = escapeHtmlAttr(src);
             lines.push(`<a href="${href}"><img width="${w}" alt="${alt}" src="${imgSrc}"></a>`);
+            const caption = metaCaptionHtml(item.meta);
+            if (caption)
+                lines.push(`<sub>${caption}</sub>`);
             lines.push("");
         }
         else if (link) {
-            lines.push(`- [${name}](${link})`);
+            lines.push(`- [${name}](${link})${metaCaptionMarkdown(item.meta)}`);
         }
         else {
-            lines.push(`- ${name}`);
+            lines.push(`- ${name}${metaCaptionMarkdown(item.meta)}`);
         }
     }
     if (overflowImages.length > 0) {
@@ -239,7 +287,8 @@ export function attachmentsCommentBody(items, galleries = [], marker = ATTACHMEN
         for (const item of overflowImages) {
             const name = item.key.slice(item.key.lastIndexOf("/") + 1);
             const link = item.pageUrl ?? item.url;
-            lines.push(link ? `- [${name}](${link})` : `- ${name}`);
+            const suffix = metaCaptionMarkdown(item.meta);
+            lines.push(link ? `- [${name}](${link})${suffix}` : `- ${name}${suffix}`);
         }
         lines.push("", "</details>", "");
     }

package/package.json

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