@orthacms/media-provider-azure 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-azure
+
+Part of [Ortha CMS](https://github.com/ortha-source/ortha-cms).
+
+```sh
+npm install @orthacms/media-provider-azure
+```

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createAzureStorageProvider } from './lib/azure-storage-provider';
+export type { AzureStorageConfig } from './lib/azure-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,0BAA0B,EAAE,MAAM,8BAA8B,CAAC;AAC1E,YAAY,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC"}

package/dist/index.js

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

package/dist/lib/azure-storage-provider.d.ts

@@ -0,0 +1,43 @@
+import { type ContainerClient } from '@azure/storage-blob';
+import type { StorageProvider } from '@orthacms/media-server';
+/**
+ * Settings for Azure Blob Storage.
+ *
+ * Azure is the one major object store with **no S3 compatibility at all** —
+ * different protocol, different signature, containers instead of buckets — so
+ * it needs its own adapter rather than an endpoint in `provider-s3`.
+ *
+ * Three ways to connect, in the order most deployments reach for them:
+ *
+ * 1. `connectionString` — what the portal hands you, and what Azurite prints.
+ * 2. `accountName` + `accountKey`.
+ * 3. `containerClient` — an already-built client. This is the escape hatch for
+ *    **managed identity**: build a client with `DefaultAzureCredential` from
+ *    `@azure/identity` and pass it, and this package stays free of that
+ *    dependency. It is also what the tests inject.
+ */
+export interface AzureStorageConfig {
+    /** Container every blob lands in. */
+    container: string;
+    /** Full connection string, including the key. */
+    connectionString?: string;
+    /** Account name, when connecting with an explicit key. */
+    accountName?: string;
+    /** Account key, paired with `accountName`. */
+    accountKey?: string;
+    /** Prefix every blob name with this, e.g. to share a container. */
+    keyPrefix?: string;
+    /** An already-built container client — managed identity, or a test stub. */
+    containerClient?: ContainerClient;
+}
+/**
+ * The Azure Blob Storage {@link StorageProvider}.
+ *
+ * `capabilities.directUrl` is **computed, not hardcoded**: a SAS token needs a
+ * shared key to sign, so a deployment on managed identity gets `false` and its
+ * downloads are proxied. Declaring `true` unconditionally would make
+ * `MediaServerPlugin` accept `directServe: 'signed-url'` on a deployment that
+ * cannot honour it, and the failure would land per-request instead of at boot.
+ */
+export declare function createAzureStorageProvider(config: AzureStorageConfig): StorageProvider;
+//# sourceMappingURL=azure-storage-provider.d.ts.map

package/dist/lib/azure-storage-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"azure-storage-provider.d.ts","sourceRoot":"","sources":["../../src/lib/azure-storage-provider.ts"],"names":[],"mappings":"AAEA,OAAO,EAMH,KAAK,eAAe,EACvB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAGR,eAAe,EAElB,MAAM,wBAAwB,CAAC;AAEhC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,kBAAkB;IAC/B,qCAAqC;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,iDAAiD;IACjD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8CAA8C;IAC9C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4EAA4E;IAC5E,eAAe,CAAC,EAAE,eAAe,CAAC;CACrC;AA0FD;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CACtC,MAAM,EAAE,kBAAkB,GAC3B,eAAe,CAsIjB"}

package/dist/lib/azure-storage-provider.js

@@ -0,0 +1,188 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAzureStorageProvider = createAzureStorageProvider;
+const node_crypto_1 = require("node:crypto");
+const node_stream_1 = require("node:stream");
+const storage_blob_1 = require("@azure/storage-blob");
+const media_server_1 = require("@orthacms/media-server");
+/** How much of the stream is buffered per block while uploading. */
+const UPLOAD_BUFFER_BYTES = 4 * 1024 * 1024;
+/** How many blocks are in flight at once. */
+const UPLOAD_CONCURRENCY = 4;
+/** 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 Azure uses to say "no such blob". */
+function isMissing(error) {
+    const candidate = error;
+    return (candidate?.statusCode === 404 ||
+        candidate?.code === 'BlobNotFound' ||
+        candidate?.details?.errorCode === 'BlobNotFound' ||
+        candidate?.details?.errorCode === 'ContainerNotFound');
+}
+/** Builds the container client from whichever credentials were supplied. */
+function resolveContainer(config) {
+    if (config.containerClient) {
+        // A caller-built client may carry any credential — including a managed
+        // identity, which cannot sign a plain SAS. Signing is therefore off
+        // unless the caller also handed us an explicit key.
+        return { container: config.containerClient };
+    }
+    if (config.connectionString) {
+        const service = storage_blob_1.BlobServiceClient.fromConnectionString(config.connectionString);
+        return {
+            container: service.getContainerClient(config.container),
+            ...(sharedKeyFrom(config.connectionString)
+                ? { sharedKey: sharedKeyFrom(config.connectionString) }
+                : {})
+        };
+    }
+    if (config.accountName && config.accountKey) {
+        const sharedKey = new storage_blob_1.StorageSharedKeyCredential(config.accountName, config.accountKey);
+        const service = new storage_blob_1.BlobServiceClient(`https://${config.accountName}.blob.core.windows.net`, sharedKey);
+        return {
+            container: service.getContainerClient(config.container),
+            sharedKey
+        };
+    }
+    throw new Error('createAzureStorageProvider needs credentials: a `connectionString`, an ' +
+        '`accountName` + `accountKey` pair, or a pre-built `containerClient` ' +
+        '(which is how you use a managed identity without this package depending on @azure/identity).');
+}
+/** Pulls the account name/key out of a connection string, when it has them. */
+function sharedKeyFrom(connectionString) {
+    const parts = new Map(connectionString
+        .split(';')
+        .map((pair) => pair.split(/=(.*)/s))
+        .filter((pair) => pair.length >= 2)
+        .map(([key, value]) => [key.trim(), value.trim()]));
+    const name = parts.get('AccountName');
+    const key = parts.get('AccountKey');
+    // A SAS-based connection string carries no key, and that is a legitimate
+    // way to connect — it just cannot mint further SAS tokens.
+    return name && key ? new storage_blob_1.StorageSharedKeyCredential(name, key) : undefined;
+}
+/**
+ * The Azure Blob Storage {@link StorageProvider}.
+ *
+ * `capabilities.directUrl` is **computed, not hardcoded**: a SAS token needs a
+ * shared key to sign, so a deployment on managed identity gets `false` and its
+ * downloads are proxied. Declaring `true` unconditionally would make
+ * `MediaServerPlugin` accept `directServe: 'signed-url'` on a deployment that
+ * cannot honour it, and the failure would land per-request instead of at boot.
+ */
+function createAzureStorageProvider(config) {
+    if (!config.container?.trim()) {
+        throw new Error('createAzureStorageProvider requires a container name.');
+    }
+    const { container, sharedKey } = resolveContainer(config);
+    const prefix = config.keyPrefix?.replace(/^\/+|\/+$/g, '');
+    const blobFor = (storageKey) => container.getBlockBlobClient(storageKey);
+    return {
+        id: 'azure',
+        capabilities: {
+            directUrl: Boolean(sharedKey),
+            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;
+            });
+            object.body.pipe(meter);
+            // Without forwarding this, an upload whose source dies waits
+            // forever on a stream that will never end.
+            object.body.on('error', (error) => meter.destroy(error));
+            const blob = blobFor(storageKey);
+            try {
+                await blob.uploadStream(meter, UPLOAD_BUFFER_BYTES, UPLOAD_CONCURRENCY, {
+                    blobHTTPHeaders: {
+                        blobContentType: object.contentType
+                    }
+                });
+            }
+            catch (error) {
+                // A failed block upload leaves uncommitted blocks charged
+                // against the account and invisible to a blob listing — and the
+                // key never reached a caller, so nothing can reclaim them.
+                // Deleting the (uncommitted) blob is what clears them.
+                await blob.deleteIfExists().catch(() => undefined);
+                throw error;
+            }
+            return { storageKey, size, checksum: hash.digest('hex') };
+        },
+        async get(storageKey) {
+            try {
+                const response = await blobFor(storageKey).download();
+                const body = response.readableStreamBody;
+                if (!body) {
+                    // Node always populates it; a browser bundle would not, and
+                    // an empty body here is not something to stream.
+                    throw new media_server_1.ObjectNotFoundError(storageKey);
+                }
+                return body;
+            }
+            catch (error) {
+                if (isMissing(error)) {
+                    throw new media_server_1.ObjectNotFoundError(storageKey, error);
+                }
+                throw error;
+            }
+        },
+        async remove(storageKey) {
+            // `deleteIfExists` is idempotent by name; the catch covers a
+            // gateway that answers 404 anyway, since reclaim is post-commit and
+            // best-effort.
+            try {
+                await blobFor(storageKey).deleteIfExists();
+            }
+            catch (error) {
+                if (!isMissing(error))
+                    throw error;
+            }
+        },
+        ...(sharedKey
+            ? {
+                async directUrl(storageKey, options) {
+                    // The SAS pins the response headers, exactly as the S3
+                    // adapter pins them on its query string: a redirect
+                    // discards the app's own `Content-Disposition`, `nosniff`
+                    // and CSP, and the stored MIME type is the uploader's
+                    // claim. Without these two, an uploaded `.html` renders
+                    // on the storage account's origin.
+                    const fileName = options.fileName.replace(/"/g, '');
+                    const expiresOn = new Date(Date.now() + options.expiresInSeconds * 1000);
+                    const sas = (0, storage_blob_1.generateBlobSASQueryParameters)({
+                        containerName: container.containerName,
+                        blobName: storageKey,
+                        permissions: storage_blob_1.BlobSASPermissions.parse('r'),
+                        expiresOn,
+                        contentDisposition: `${options.disposition}; filename="${fileName}"`,
+                        contentType: options.contentType
+                    }, sharedKey).toString();
+                    return `${blobFor(storageKey).url}?${sas}`;
+                }
+            }
+            : {}),
+        async verify() {
+            // One properties call at boot: a wrong container, a dead account or
+            // an expired key fails the start rather than the first upload.
+            await container.getProperties();
+        }
+    };
+}

package/dist/lib/fake-container-client.d.ts

@@ -0,0 +1,50 @@
+import { Readable } from 'node:stream';
+import type { ContainerClient } from '@azure/storage-blob';
+/** One blob, as the fake holds it. */
+interface FakeBlob {
+    body: Buffer;
+    contentType?: string;
+}
+/**
+ * A stand-in `ContainerClient` covering the four calls this adapter makes.
+ *
+ * Azure's client is a class tree, so — unlike the S3 adapter, where a real
+ * client with a stubbed `send` keeps the SDK's own middleware in play — the
+ * seam here is the container client itself, which the provider already accepts
+ * for managed-identity deployments. That means these tests drive the same
+ * injection point a real caller uses, rather than a private hook.
+ *
+ * It proves this adapter's logic and nothing about Azure: **Azurite** and one
+ * real storage account are the acceptance step, and are named in `AGENTS.md`.
+ */
+export declare class FakeContainerClient {
+    readonly blobs: Map<string, FakeBlob>;
+    readonly containerName = "media";
+    /** Flip to make `getProperties` fail, as a missing container would. */
+    exists: boolean;
+    /** Make the next upload fail, to exercise the cleanup path. */
+    failNextUpload: boolean;
+    /** Blob names `deleteIfExists` was called for, in order. */
+    readonly deleted: string[];
+    getBlockBlobClient(blobName: string): {
+        url: string;
+        uploadStream: (stream: NodeJS.ReadableStream, _bufferSize?: number, _concurrency?: number, options?: {
+            blobHTTPHeaders?: {
+                blobContentType?: string;
+            };
+        }) => Promise<{}>;
+        download: () => Promise<{
+            readableStreamBody: Readable;
+        }>;
+        deleteIfExists: () => Promise<{
+            succeeded: boolean;
+        }>;
+    };
+    getProperties(): Promise<{}>;
+    /** Blob names currently held, sorted. */
+    keys(): string[];
+    /** Presents as the real thing to a provider that only uses the above. */
+    asContainerClient(): ContainerClient;
+}
+export {};
+//# sourceMappingURL=fake-container-client.d.ts.map

package/dist/lib/fake-container-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fake-container-client.d.ts","sourceRoot":"","sources":["../../src/lib/fake-container-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D,sCAAsC;AACtC,UAAU,QAAQ;IACd,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAmBD;;;;;;;;;;;GAWG;AACH,qBAAa,mBAAmB;IAC5B,QAAQ,CAAC,KAAK,wBAA+B;IAC7C,QAAQ,CAAC,aAAa,WAAW;IACjC,uEAAuE;IACvE,MAAM,UAAQ;IACd,+DAA+D;IAC/D,cAAc,UAAS;IACvB,4DAA4D;IAC5D,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,CAAM;IAEhC,kBAAkB,CAAC,QAAQ,EAAE,MAAM;;+BAKf,MAAM,CAAC,cAAc,gBACf,MAAM,iBACL,MAAM,YACX;YAAE,eAAe,CAAC,EAAE;gBAAE,eAAe,CAAC,EAAE,MAAM,CAAA;aAAE,CAAA;SAAE;;;;;;;;IA8BlE,aAAa;IAKnB,yCAAyC;IACzC,IAAI,IAAI,MAAM,EAAE;IAIhB,yEAAyE;IACzE,iBAAiB,IAAI,eAAe;CAGvC"}

package/dist/lib/fake-container-client.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FakeContainerClient = void 0;
+const node_stream_1 = require("node:stream");
+/** The error shape Azure uses for a blob that is not there. */
+function blobNotFound() {
+    return Object.assign(new Error('BlobNotFound'), {
+        statusCode: 404,
+        details: { errorCode: 'BlobNotFound' }
+    });
+}
+/** Drains an upload stream into one buffer. */
+async function collect(stream) {
+    const chunks = [];
+    for await (const chunk of stream) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks);
+}
+/**
+ * A stand-in `ContainerClient` covering the four calls this adapter makes.
+ *
+ * Azure's client is a class tree, so — unlike the S3 adapter, where a real
+ * client with a stubbed `send` keeps the SDK's own middleware in play — the
+ * seam here is the container client itself, which the provider already accepts
+ * for managed-identity deployments. That means these tests drive the same
+ * injection point a real caller uses, rather than a private hook.
+ *
+ * It proves this adapter's logic and nothing about Azure: **Azurite** and one
+ * real storage account are the acceptance step, and are named in `AGENTS.md`.
+ */
+class FakeContainerClient {
+    blobs = new Map();
+    containerName = 'media';
+    /** Flip to make `getProperties` fail, as a missing container would. */
+    exists = true;
+    /** Make the next upload fail, to exercise the cleanup path. */
+    failNextUpload = false;
+    /** Blob names `deleteIfExists` was called for, in order. */
+    deleted = [];
+    getBlockBlobClient(blobName) {
+        // Arrow properties, so `this` stays the fake without aliasing it.
+        return {
+            url: `https://account.blob.core.windows.net/${this.containerName}/${blobName}`,
+            uploadStream: async (stream, _bufferSize, _concurrency, options) => {
+                // Drained even when the upload is set to fail: a real client
+                // reads the stream before it errors, and not reading it would
+                // leave the provider's meter unfed and its `size` at zero.
+                const body = await collect(stream);
+                if (this.failNextUpload) {
+                    this.failNextUpload = false;
+                    throw Object.assign(new Error('upload failed'), {
+                        statusCode: 500
+                    });
+                }
+                this.blobs.set(blobName, {
+                    body,
+                    contentType: options?.blobHTTPHeaders?.blobContentType
+                });
+                return {};
+            },
+            download: async () => {
+                const blob = this.blobs.get(blobName);
+                if (!blob)
+                    throw blobNotFound();
+                return { readableStreamBody: node_stream_1.Readable.from(blob.body) };
+            },
+            deleteIfExists: async () => {
+                this.deleted.push(blobName);
+                return { succeeded: this.blobs.delete(blobName) };
+            }
+        };
+    }
+    async getProperties() {
+        if (!this.exists)
+            throw blobNotFound();
+        return {};
+    }
+    /** Blob names currently held, sorted. */
+    keys() {
+        return [...this.blobs.keys()].sort();
+    }
+    /** Presents as the real thing to a provider that only uses the above. */
+    asContainerClient() {
+        return this;
+    }
+}
+exports.FakeContainerClient = FakeContainerClient;

package/package.json

@@ -0,0 +1,35 @@
+{
+    "name": "@orthacms/media-provider-azure",
+    "version": "0.4.0",
+    "description": "@orthacms/media-provider-azure — part of Ortha CMS.",
+    "license": "MIT",
+    "homepage": "https://github.com/ortha-source/ortha-cms/tree/main/packages/media/provider-azure",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/ortha-source/ortha-cms.git",
+        "directory": "packages/media/provider-azure"
+    },
+    "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": {
+        "@azure/storage-blob": "^12.26.0",
+        "@orthacms/media-server": "^0.4.0",
+        "tslib": "^2.3.0"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}