@buildinternet/uploads 0.26.0 → 0.27.0

package/dist/session-cli-version.js

@@ -0,0 +1,85 @@
+/**
+ * Keep Better Auth session.cliVersion in sync with the installed package.
+ *
+ * Device login stores UPLOADS_SESSION_TOKEN; later commands POST
+ * /api/auth/update-session when the local version changes (fire-and-forget).
+ */
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { authUrlFromApi } from "./config.js";
+import { loadConfigFile, removeConfigKeys, resolveConfigPath } from "./config-file.js";
+import { packageVersion } from "./package-version.js";
+const POST_TIMEOUT_MS = 1500;
+function defaultCachePath() {
+    const base = process.env.XDG_CACHE_HOME ?? join(homedir(), ".cache");
+    return join(base, "uploads", "cli-version-sync");
+}
+function readLastSyncedVersion(path) {
+    try {
+        const v = readFileSync(path, "utf8").trim();
+        return v || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function writeLastSyncedVersion(path, version) {
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, version + "\n", { mode: 0o600 });
+    }
+    catch {
+        // best-effort
+    }
+}
+/** Best-effort POST; never throws. */
+export async function syncSessionCliVersion(opts = {}) {
+    const version = opts.version ?? packageVersion();
+    const configPath = resolveConfigPath({ envFile: opts.envFile });
+    const fromFile = loadConfigFile(configPath);
+    const sessionToken = opts.sessionToken ?? fromFile.UPLOADS_SESSION_TOKEN;
+    if (!sessionToken)
+        return false;
+    const cachePath = opts.cachePath ?? defaultCachePath();
+    if (!opts.force && readLastSyncedVersion(cachePath) === version)
+        return true;
+    const apiUrl = opts.apiUrl ?? fromFile.UPLOADS_API_URL ?? process.env.UPLOADS_API_URL;
+    const authUrl = (opts.authUrl ??
+        process.env.UPLOADS_AUTH_URL ??
+        (apiUrl ? authUrlFromApi(apiUrl) : "https://auth.uploads.sh")).replace(/\/$/, "");
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), POST_TIMEOUT_MS);
+    try {
+        const fetchImpl = opts.fetchImpl ?? fetch;
+        const res = await fetchImpl(`${authUrl}/api/auth/update-session`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${sessionToken}`,
+                "User-Agent": `@buildinternet/uploads/${version} (session-version)`,
+            },
+            body: JSON.stringify({ cliVersion: version }),
+            signal: controller.signal,
+        });
+        if (res.ok) {
+            writeLastSyncedVersion(cachePath, version);
+            return true;
+        }
+        // Stale session: drop it so we stop retrying every command.
+        if (res.status === 401 || res.status === 403) {
+            removeConfigKeys(configPath, ["UPLOADS_SESSION_TOKEN"]);
+        }
+        return false;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Fire-and-forget for CLI command starts. */
+export function maybeSyncSessionCliVersion(opts = {}) {
+    void syncSessionCliVersion(opts);
+}

package/dist/sidecar.d.ts

@@ -0,0 +1,31 @@
+/** The sidecar path for a given local file — `<file>.uploads.json`. */
+export declare function sidecarPath(filePath: string): string;
+/** Hex-encoded SHA-256 of `bytes`. */
+export declare function sha256Hex(bytes: Uint8Array): string;
+/** Keep only entries whose key is in the closed canonical metadata vocabulary. */
+export declare function restrictToCanonicalMeta(meta: Record<string, string>): Record<string, string>;
+/**
+ * Write a sidecar manifest next to `filePath`, recording `meta` (restricted
+ * to the canonical vocabulary) and the SHA-256 of `bytes` (the exact bytes
+ * being written to `filePath`). No-ops when `meta` is empty — an image with
+ * no derived metadata gets no sidecar. Best-effort: a write failure (e.g. a
+ * read-only directory) is swallowed, matching the rest of the derived-
+ * metadata pipeline's "never fail the primary operation" contract.
+ */
+export declare function writeSidecarMeta(filePath: string, bytes: Uint8Array, meta: Record<string, string>): void;
+/**
+ * Read back a sidecar manifest for `filePath`, only when it is present,
+ * well-formed, and its recorded hash matches `bytes` (the file's current
+ * content, as read for the upload in progress). Returns `undefined` on any
+ * absence, parse failure, malformed shape, or hash mismatch — a sidecar is a
+ * best-effort convenience and must never fail or noise an upload. Returned
+ * keys are always a subset of `CANONICAL_META_KEYS`, so a hand-edited
+ * manifest can never inject arbitrary metadata.
+ */
+export declare function readSidecarMeta(filePath: string, bytes: Uint8Array): Record<string, string> | undefined;
+/**
+ * Merge `filePath`'s sidecar metadata (if any, per {@link readSidecarMeta})
+ * under `baseMeta` — explicit metadata always wins. Shared by the `put` and
+ * `attach` upload loops (issue #469 lever 2).
+ */
+export declare function mergeSidecarMeta(filePath: string, bytes: Uint8Array, baseMeta: Record<string, string> | undefined): Record<string, string> | undefined;

package/dist/sidecar.js

@@ -0,0 +1,111 @@
+/**
+ * Sidecar manifest for `uploads screenshot --out`: derived metadata written
+ * next to a local screenshot file so a later `put`/`attach` of that exact
+ * file can recover the metadata the hosted copy would have gotten at capture
+ * time. See issue #469 lever 2 (the "sidecar manifest" variant — the
+ * alternative, content-hash-keyed server-side inheritance, is out of scope
+ * here).
+ *
+ * File: `<file>.uploads.json` next to `<file>`, e.g. `shot.png.uploads.json`.
+ * Shape: `{ version, sha256, meta }`. `sha256` is the SHA-256 of the exact
+ * bytes written to `<file>` at capture time — read-back compares it against
+ * the file's *current* bytes, so a file that was regenerated or hand-edited
+ * since capture silently loses its sidecar instead of attaching stale
+ * metadata to a different image.
+ *
+ * `meta` is filtered to the closed `CANONICAL_META_KEYS` vocabulary
+ * (metadata-vocab.ts) on both write and read: the sidecar is a plain JSON
+ * file sitting next to the image, so it must never be a channel for
+ * arbitrary metadata even if hand-edited.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { CANONICAL_META_KEYS, mergeDerivedMeta } from "./metadata-vocab.js";
+const SIDECAR_VERSION = 1;
+/** The sidecar path for a given local file — `<file>.uploads.json`. */
+export function sidecarPath(filePath) {
+    return `${filePath}.uploads.json`;
+}
+/** Hex-encoded SHA-256 of `bytes`. */
+export function sha256Hex(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+/** Keep only entries whose key is in the closed canonical metadata vocabulary. */
+export function restrictToCanonicalMeta(meta) {
+    const out = {};
+    for (const key of CANONICAL_META_KEYS) {
+        if (Object.prototype.hasOwnProperty.call(meta, key))
+            out[key] = meta[key];
+    }
+    return out;
+}
+function isPlainStringRecord(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    return Object.values(value).every((v) => typeof v === "string");
+}
+/**
+ * Write a sidecar manifest next to `filePath`, recording `meta` (restricted
+ * to the canonical vocabulary) and the SHA-256 of `bytes` (the exact bytes
+ * being written to `filePath`). No-ops when `meta` is empty — an image with
+ * no derived metadata gets no sidecar. Best-effort: a write failure (e.g. a
+ * read-only directory) is swallowed, matching the rest of the derived-
+ * metadata pipeline's "never fail the primary operation" contract.
+ */
+export function writeSidecarMeta(filePath, bytes, meta) {
+    const restricted = restrictToCanonicalMeta(meta);
+    if (Object.keys(restricted).length === 0)
+        return;
+    try {
+        const manifest = {
+            version: SIDECAR_VERSION,
+            sha256: sha256Hex(bytes),
+            meta: restricted,
+        };
+        writeFileSync(sidecarPath(filePath), `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+    }
+    catch {
+        // best-effort — never fail the screenshot over a sidecar write
+    }
+}
+/**
+ * Read back a sidecar manifest for `filePath`, only when it is present,
+ * well-formed, and its recorded hash matches `bytes` (the file's current
+ * content, as read for the upload in progress). Returns `undefined` on any
+ * absence, parse failure, malformed shape, or hash mismatch — a sidecar is a
+ * best-effort convenience and must never fail or noise an upload. Returned
+ * keys are always a subset of `CANONICAL_META_KEYS`, so a hand-edited
+ * manifest can never inject arbitrary metadata.
+ */
+export function readSidecarMeta(filePath, bytes) {
+    const path = sidecarPath(filePath);
+    try {
+        if (!existsSync(path))
+            return undefined;
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (typeof parsed !== "object" || parsed === null)
+            return undefined;
+        const candidate = parsed;
+        if (candidate.version !== SIDECAR_VERSION ||
+            typeof candidate.sha256 !== "string" ||
+            !isPlainStringRecord(candidate.meta)) {
+            return undefined;
+        }
+        if (candidate.sha256 !== sha256Hex(bytes))
+            return undefined; // stale/regenerated file
+        const restricted = restrictToCanonicalMeta(candidate.meta);
+        return Object.keys(restricted).length > 0 ? restricted : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Merge `filePath`'s sidecar metadata (if any, per {@link readSidecarMeta})
+ * under `baseMeta` — explicit metadata always wins. Shared by the `put` and
+ * `attach` upload loops (issue #469 lever 2).
+ */
+export function mergeSidecarMeta(filePath, bytes, baseMeta) {
+    const sidecarMeta = readSidecarMeta(filePath, bytes);
+    return sidecarMeta ? mergeDerivedMeta(baseMeta ?? {}, sidecarMeta) : baseMeta;
+}

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@buildinternet/uploads",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "CLI and client for uploads.sh — workspace-scoped image hosting for GitHub embeds",
   "type": "module",
   "sideEffects": false,
-  "license": "MIT",
+  "license": "Apache-2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/buildinternet/uploads.git",