@orthacms/media-provider-vercel-blob 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ortha CMS contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,7 @@
+# @orthacms/media-provider-vercel-blob
+
+Part of [Ortha CMS](https://github.com/ortha-source/ortha-cms).
+
+```sh
+npm install @orthacms/media-provider-vercel-blob
+```

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createVercelBlobStorageProvider } from './lib/vercel-blob-storage-provider';
+export type { VercelBlobApi, VercelBlobStorageConfig } from './lib/vercel-blob-storage-provider';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,+BAA+B,EAAE,MAAM,oCAAoC,CAAC;AACrF,YAAY,EACR,aAAa,EACb,uBAAuB,EAC1B,MAAM,oCAAoC,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createVercelBlobStorageProvider = void 0;
+var vercel_blob_storage_provider_1 = require("./lib/vercel-blob-storage-provider");
+Object.defineProperty(exports, "createVercelBlobStorageProvider", { enumerable: true, get: function () { return vercel_blob_storage_provider_1.createVercelBlobStorageProvider; } });

package/dist/lib/fake-blob-api.d.ts

@@ -0,0 +1,35 @@
+import type { VercelBlobApi } from './vercel-blob-storage-provider';
+/** One blob, as the fake holds it. */
+interface FakeBlob {
+    body: Buffer;
+    contentType?: string;
+}
+/**
+ * A stand-in for the three `@vercel/blob` functions this adapter calls, plus a
+ * `fetch` that serves what they stored.
+ *
+ * The SDK exports free functions rather than a client, so the seam is the small
+ * `VercelBlobApi` interface the provider already accepts — the same one a
+ * caller could substitute to route through their own transport.
+ *
+ * It proves this adapter's logic and nothing about Vercel Blob. A real store is
+ * the acceptance step, and `AGENTS.md` says so.
+ */
+export declare class FakeBlobApi {
+    readonly blobs: Map<string, FakeBlob>;
+    /** Base the fake's public URLs hang off. */
+    readonly host = "https://fake.public.blob.vercel-storage.com";
+    /** Make the next `put` fail, to exercise the cleanup path. */
+    failNextPut: boolean;
+    /** Pathnames `del` was called for, in order. */
+    readonly deleted: string[];
+    /** Raised by `head` when set — anything that is not "missing". */
+    headError: Error | undefined;
+    readonly api: VercelBlobApi;
+    /** Serves the fake's blobs, so `get` can be exercised end to end. */
+    fetch: (input: string | URL) => Promise<Response>;
+    /** Pathnames currently held, sorted. */
+    keys(): string[];
+}
+export {};
+//# sourceMappingURL=fake-blob-api.d.ts.map

package/dist/lib/fake-blob-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fake-blob-api.d.ts","sourceRoot":"","sources":["../../src/lib/fake-blob-api.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAEpE,sCAAsC;AACtC,UAAU,QAAQ;IACd,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAaD;;;;;;;;;;GAUG;AACH,qBAAa,WAAW;IACpB,QAAQ,CAAC,KAAK,wBAA+B;IAC7C,4CAA4C;IAC5C,QAAQ,CAAC,IAAI,iDAAiD;IAC9D,8DAA8D;IAC9D,WAAW,UAAS;IACpB,gDAAgD;IAChD,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,CAAM;IAChC,kEAAkE;IAClE,SAAS,EAAE,KAAK,GAAG,SAAS,CAAC;IAE7B,QAAQ,CAAC,GAAG,EAAE,aAAa,CA0CzB;IAEF,qEAAqE;IACrE,KAAK,GAAI,OAAO,MAAM,GAAG,GAAG,KAAG,OAAO,CAAC,QAAQ,CAAC,CAU9C;IAEF,wCAAwC;IACxC,IAAI,IAAI,MAAM,EAAE;CAGnB"}

package/dist/lib/fake-blob-api.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FakeBlobApi = void 0;
+const blob_1 = require("@vercel/blob");
+/** Drains an upload body into one buffer. */
+async function collect(body) {
+    if (Buffer.isBuffer(body))
+        return body;
+    if (typeof body === 'string')
+        return Buffer.from(body);
+    const chunks = [];
+    for await (const chunk of body) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks);
+}
+/**
+ * A stand-in for the three `@vercel/blob` functions this adapter calls, plus a
+ * `fetch` that serves what they stored.
+ *
+ * The SDK exports free functions rather than a client, so the seam is the small
+ * `VercelBlobApi` interface the provider already accepts — the same one a
+ * caller could substitute to route through their own transport.
+ *
+ * It proves this adapter's logic and nothing about Vercel Blob. A real store is
+ * the acceptance step, and `AGENTS.md` says so.
+ */
+class FakeBlobApi {
+    blobs = new Map();
+    /** Base the fake's public URLs hang off. */
+    host = 'https://fake.public.blob.vercel-storage.com';
+    /** Make the next `put` fail, to exercise the cleanup path. */
+    failNextPut = false;
+    /** Pathnames `del` was called for, in order. */
+    deleted = [];
+    /** Raised by `head` when set — anything that is not "missing". */
+    headError;
+    api = {
+        put: (async (pathname, body, options) => {
+            const bytes = await collect(body);
+            if (this.failNextPut) {
+                this.failNextPut = false;
+                throw new Error('put failed');
+            }
+            this.blobs.set(pathname, {
+                body: bytes,
+                contentType: options?.contentType
+            });
+            return {
+                url: `${this.host}/${pathname}`,
+                pathname,
+                contentType: options?.contentType
+            };
+        }),
+        head: (async (pathname) => {
+            if (this.headError)
+                throw this.headError;
+            const blob = this.blobs.get(pathname);
+            if (!blob) {
+                throw new blob_1.BlobNotFoundError();
+            }
+            return {
+                url: `${this.host}/${pathname}`,
+                pathname,
+                size: blob.body.byteLength,
+                contentType: blob.contentType
+            };
+        }),
+        del: (async (pathname) => {
+            for (const one of Array.isArray(pathname) ? pathname : [pathname]) {
+                this.deleted.push(one);
+                this.blobs.delete(one);
+            }
+        })
+    };
+    /** Serves the fake's blobs, so `get` can be exercised end to end. */
+    fetch = (input) => {
+        const url = typeof input === 'string' ? input : input.toString();
+        const pathname = url.slice(this.host.length + 1);
+        const blob = this.blobs.get(pathname);
+        if (!blob) {
+            return Promise.resolve(new Response(null, { status: 404 }));
+        }
+        return Promise.resolve(new Response(new Uint8Array(blob.body), { status: 200 }));
+    };
+    /** Pathnames currently held, sorted. */
+    keys() {
+        return [...this.blobs.keys()].sort();
+    }
+}
+exports.FakeBlobApi = FakeBlobApi;

package/dist/lib/vercel-blob-storage-provider.d.ts

@@ -0,0 +1,50 @@
+import { del, head, put } from '@vercel/blob';
+import type { StorageProvider } from '@orthacms/media-server';
+/**
+ * The three calls this adapter makes, as an injectable seam.
+ *
+ * `@vercel/blob` exports free functions rather than a client, so there is no
+ * object to hand in — this is the shape the tests substitute, and the shape a
+ * caller could substitute to route through their own fetch stack.
+ */
+export interface VercelBlobApi {
+    put: typeof put;
+    head: typeof head;
+    del: typeof del;
+}
+/** Settings for Vercel Blob. */
+export interface VercelBlobStorageConfig {
+    /**
+     * Read-write token. Omit on Vercel itself, where `BLOB_READ_WRITE_TOKEN` is
+     * injected into the environment and the SDK reads it.
+     */
+    token?: string;
+    /** Prefix every pathname with this, e.g. to share a store. */
+    keyPrefix?: string;
+    /** The SDK functions, for tests or a custom transport. */
+    api?: VercelBlobApi;
+}
+/**
+ * Vercel Blob.
+ *
+ * **Read this before choosing it: every blob is world-readable.** Vercel Blob
+ * has one access mode, `public`, and the URL it returns is a permanent,
+ * unguessable, unauthenticated link to the bytes. Anyone who obtains that URL —
+ * from a copied `<img src>`, a browser extension, a proxy log, a forwarded
+ * email — can fetch the asset forever, with no reference to who they are.
+ *
+ * The Media Library is otherwise **private by default**: `GET
+ * /media/assets/:id/raw` checks workspace membership on every request, and a
+ * non-member gets the same 404 as a missing asset. This backend cannot uphold
+ * that for anyone holding the underlying URL. The app keeps enforcing its own
+ * rules — the API never returns the blob URL, only `/media/assets/:id/raw` —
+ * but the second copy of the bytes is public and that cannot be revoked short
+ * of deleting the blob.
+ *
+ * Fine for a marketing site's images. Not fine for a workspace whose media is
+ * confidential. That is a deployment decision, not something this adapter can
+ * paper over — so it is stated here, in `AGENTS.md`, and in the scaffolder's
+ * own hint.
+ */
+export declare function createVercelBlobStorageProvider(config?: VercelBlobStorageConfig): StorageProvider;
+//# sourceMappingURL=vercel-blob-storage-provider.d.ts.map

package/dist/lib/vercel-blob-storage-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vercel-blob-storage-provider.d.ts","sourceRoot":"","sources":["../../src/lib/vercel-blob-storage-provider.ts"],"names":[],"mappings":"AAGA,OAAO,EAAqB,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAEjE,OAAO,KAAK,EAER,eAAe,EAElB,MAAM,wBAAwB,CAAC;AAEhC;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC1B,GAAG,EAAE,OAAO,GAAG,CAAC;IAChB,IAAI,EAAE,OAAO,IAAI,CAAC;IAClB,GAAG,EAAE,OAAO,GAAG,CAAC;CACnB;AAED,gCAAgC;AAChC,MAAM,WAAW,uBAAuB;IACpC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,GAAG,CAAC,EAAE,aAAa,CAAC;CACvB;AAkBD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,+BAA+B,CAC3C,MAAM,GAAE,uBAA4B,GACrC,eAAe,CA4HjB"}

package/dist/lib/vercel-blob-storage-provider.js

@@ -0,0 +1,161 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createVercelBlobStorageProvider = createVercelBlobStorageProvider;
+const node_crypto_1 = require("node:crypto");
+const node_stream_1 = require("node:stream");
+const promises_1 = require("node:stream/promises");
+const blob_1 = require("@vercel/blob");
+const media_server_1 = require("@orthacms/media-server");
+/** Reduces a file name to one safe key segment. Mirrors the other providers. */
+function sanitize(fileName) {
+    const cleaned = fileName.replace(/[^A-Za-z0-9_.-]+/g, '_');
+    return cleaned === '.' || cleaned === '..' ? `_${cleaned}` : cleaned;
+}
+/** True for the shapes the SDK and its CDN use to say "no such blob". */
+function isMissing(error) {
+    const candidate = error;
+    return (error instanceof blob_1.BlobNotFoundError ||
+        candidate?.name === 'BlobNotFoundError' ||
+        candidate?.status === 404);
+}
+/**
+ * Vercel Blob.
+ *
+ * **Read this before choosing it: every blob is world-readable.** Vercel Blob
+ * has one access mode, `public`, and the URL it returns is a permanent,
+ * unguessable, unauthenticated link to the bytes. Anyone who obtains that URL —
+ * from a copied `<img src>`, a browser extension, a proxy log, a forwarded
+ * email — can fetch the asset forever, with no reference to who they are.
+ *
+ * The Media Library is otherwise **private by default**: `GET
+ * /media/assets/:id/raw` checks workspace membership on every request, and a
+ * non-member gets the same 404 as a missing asset. This backend cannot uphold
+ * that for anyone holding the underlying URL. The app keeps enforcing its own
+ * rules — the API never returns the blob URL, only `/media/assets/:id/raw` —
+ * but the second copy of the bytes is public and that cannot be revoked short
+ * of deleting the blob.
+ *
+ * Fine for a marketing site's images. Not fine for a workspace whose media is
+ * confidential. That is a deployment decision, not something this adapter can
+ * paper over — so it is stated here, in `AGENTS.md`, and in the scaffolder's
+ * own hint.
+ */
+function createVercelBlobStorageProvider(config = {}) {
+    const api = config.api ?? { put: blob_1.put, head: blob_1.head, del: blob_1.del };
+    const prefix = config.keyPrefix?.replace(/^\/+|\/+$/g, '');
+    const token = config.token ? { token: config.token } : {};
+    /** The public URL behind a stored pathname, via the metadata call. */
+    const urlFor = async (storageKey) => {
+        try {
+            const meta = await api.head(storageKey, token);
+            return meta.url;
+        }
+        catch (error) {
+            if (isMissing(error)) {
+                throw new media_server_1.ObjectNotFoundError(storageKey, error);
+            }
+            throw error;
+        }
+    };
+    return {
+        id: 'vercel-blob',
+        capabilities: {
+            // The store's URL is public and **permanent** — it neither expires
+            // nor carries a disposition we can pin per request. The port's
+            // `directUrl` promises both, so declaring it here would be a lie
+            // that hands out an unrevocable link and serves an uploaded `.html`
+            // inline from the blob host. Downloads stay proxied, which is also
+            // what keeps the app's membership check on the request path.
+            directUrl: false,
+            contentTypeMetadata: true,
+            streamingPut: true
+        },
+        async put(object) {
+            const storageKey = [
+                prefix,
+                object.workspaceId,
+                object.assetId,
+                object.isVariant ? 'variants' : undefined,
+                sanitize(object.fileName)
+            ]
+                .filter(Boolean)
+                .join('/');
+            const hash = (0, node_crypto_1.createHash)('sha256');
+            let size = 0;
+            const meter = new node_stream_1.PassThrough();
+            meter.on('data', (chunk) => {
+                hash.update(chunk);
+                size += chunk.byteLength;
+            });
+            // `pipeline` so a source that dies destroys the meter too, rather
+            // than leaving the upload waiting on a stream that never ends.
+            //
+            // Awaited **together** with the upload, not after it: whichever
+            // fails first, both promises already carry a handler. Awaiting them
+            // in sequence meant that when the upload rejected first, the
+            // pipeline's own rejection had nobody attached yet — an unhandled
+            // rejection, which in Node is a killed process rather than a failed
+            // request.
+            try {
+                await Promise.all([
+                    api.put(storageKey, meter, {
+                        access: 'public',
+                        contentType: object.contentType,
+                        // The pathname we computed **is** the storage key. With
+                        // the default suffix on, the stored blob would live
+                        // somewhere this adapter cannot name, and `get` /
+                        // `remove` would miss every object they were handed.
+                        addRandomSuffix: false,
+                        ...token
+                    }),
+                    (0, promises_1.pipeline)(object.body, meter)
+                ]);
+            }
+            catch (error) {
+                await api.del(storageKey, token).catch(() => undefined);
+                throw error;
+            }
+            return { storageKey, size, checksum: hash.digest('hex') };
+        },
+        async get(storageKey) {
+            // Two steps, and the first is the important one: `head` turns a
+            // missing blob into a rejection *before* any stream exists, which
+            // is what the port promises and what lets the route answer 404
+            // rather than a streaming 200 it cannot take back.
+            const url = await urlFor(storageKey);
+            const response = await fetch(url);
+            if (!response.ok || !response.body) {
+                if (response.status === 404) {
+                    throw new media_server_1.ObjectNotFoundError(storageKey);
+                }
+                throw new Error(`Vercel Blob refused to serve ${storageKey}: ${response.status} ${response.statusText}`);
+            }
+            return node_stream_1.Readable.fromWeb(response.body);
+        },
+        async remove(storageKey) {
+            try {
+                await api.del(storageKey, token);
+            }
+            catch (error) {
+                // Reclaim is post-commit and best-effort, so a blob that is
+                // already gone is a success, not something to report.
+                if (!isMissing(error))
+                    throw error;
+            }
+        },
+        async verify() {
+            // There is no store-level metadata call, so this asks about a
+            // pathname that will not exist: a missing blob proves the token and
+            // the store are good, while a bad token raises something else and
+            // fails the boot.
+            try {
+                await api.head('__ortha_verify__/does-not-exist', token);
+            }
+            catch (error) {
+                if (isMissing(error))
+                    return;
+                throw error;
+            }
+        }
+    };
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+    "name": "@orthacms/media-provider-vercel-blob",
+    "version": "0.4.0",
+    "description": "@orthacms/media-provider-vercel-blob — part of Ortha CMS.",
+    "license": "MIT",
+    "homepage": "https://github.com/ortha-source/ortha-cms/tree/main/packages/media/provider-vercel-blob",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/ortha-source/ortha-cms.git",
+        "directory": "packages/media/provider-vercel-blob"
+    },
+    "bugs": {
+        "url": "https://github.com/ortha-source/ortha-cms/issues"
+    },
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "default": "./dist/index.js"
+        },
+        "./package.json": "./package.json"
+    },
+    "files": [
+        "dist"
+    ],
+    "dependencies": {
+        "@orthacms/media-server": "^0.4.0",
+        "@vercel/blob": "^0.27.0",
+        "tslib": "^2.3.0"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}