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

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createGcsStorageProvider } from './lib/gcs-storage-provider';
+export type { GcsStorageConfig } from './lib/gcs-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,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AACtE,YAAY,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC"}

package/dist/index.js

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

package/dist/lib/fake-bucket.d.ts

@@ -0,0 +1,48 @@
+import { PassThrough, Readable } from 'node:stream';
+import type { Bucket } from '@google-cloud/storage';
+/** One object, as the fake holds it. */
+interface FakeObject {
+    body: Buffer;
+    contentType?: string;
+}
+/**
+ * A stand-in `Bucket` covering the five calls this adapter makes.
+ *
+ * The seam is the bucket handle, which the provider already accepts for
+ * deployments with hand-built auth — so these tests drive the same entry point
+ * a real caller uses rather than a private hook.
+ *
+ * It proves this adapter's logic and nothing about GCS: the fake agrees with
+ * whatever the code does. `AGENTS.md` names the acceptance step.
+ */
+export declare class FakeBucket {
+    readonly objects: Map<string, FakeObject>;
+    /** Flip to make `getMetadata` fail, as a missing bucket would. */
+    exists: boolean;
+    /** Make the next upload fail part-way, to exercise the cleanup path. */
+    failNextUpload: boolean;
+    /** Object names `delete` was called for, in order. */
+    readonly deleted: string[];
+    /** Options the last `getSignedUrl` was asked for. */
+    lastSignedUrlOptions: Record<string, unknown> | undefined;
+    file(name: string): {
+        createWriteStream: (options?: {
+            contentType?: string;
+        }) => PassThrough;
+        createReadStream: () => Readable;
+        getMetadata: () => Promise<{
+            size: number;
+        }[]>;
+        delete: (options?: {
+            ignoreNotFound?: boolean;
+        }) => Promise<{}[]>;
+        getSignedUrl: (options: Record<string, unknown>) => Promise<string[]>;
+    };
+    getMetadata(): Promise<{}[]>;
+    /** Object names currently held, sorted. */
+    keys(): string[];
+    /** Presents as the real thing to a provider that only uses the above. */
+    asBucket(): Bucket;
+}
+export {};
+//# sourceMappingURL=fake-bucket.d.ts.map

package/dist/lib/fake-bucket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fake-bucket.d.ts","sourceRoot":"","sources":["../../src/lib/fake-bucket.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAY,MAAM,aAAa,CAAC;AAC9D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAEpD,wCAAwC;AACxC,UAAU,UAAU;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAOD;;;;;;;;;GASG;AACH,qBAAa,UAAU;IACnB,QAAQ,CAAC,OAAO,0BAAiC;IACjD,kEAAkE;IAClE,MAAM,UAAQ;IACd,wEAAwE;IACxE,cAAc,UAAS;IACvB,sDAAsD;IACtD,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,CAAM;IAChC,qDAAqD;IACrD,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAE1D,IAAI,CAAC,IAAI,EAAE,MAAM;sCAEqB;YAAE,WAAW,CAAC,EAAE,MAAM,CAAA;SAAE,KAqBxB,WAAW;;;;;2BAkBhB;YAAE,cAAc,CAAC,EAAE,OAAO,CAAA;SAAE;gCAQvB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;IAOvD,WAAW;IAKjB,2CAA2C;IAC3C,IAAI,IAAI,MAAM,EAAE;IAIhB,yEAAyE;IACzE,QAAQ,IAAI,MAAM;CAGrB"}

package/dist/lib/fake-bucket.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FakeBucket = void 0;
+const node_stream_1 = require("node:stream");
+/** The error shape the GCS client raises for a missing object. */
+function objectNotFound() {
+    return Object.assign(new Error('No such object'), { code: 404 });
+}
+/**
+ * A stand-in `Bucket` covering the five calls this adapter makes.
+ *
+ * The seam is the bucket handle, which the provider already accepts for
+ * deployments with hand-built auth — so these tests drive the same entry point
+ * a real caller uses rather than a private hook.
+ *
+ * It proves this adapter's logic and nothing about GCS: the fake agrees with
+ * whatever the code does. `AGENTS.md` names the acceptance step.
+ */
+class FakeBucket {
+    objects = new Map();
+    /** Flip to make `getMetadata` fail, as a missing bucket would. */
+    exists = true;
+    /** Make the next upload fail part-way, to exercise the cleanup path. */
+    failNextUpload = false;
+    /** Object names `delete` was called for, in order. */
+    deleted = [];
+    /** Options the last `getSignedUrl` was asked for. */
+    lastSignedUrlOptions;
+    file(name) {
+        return {
+            createWriteStream: (options) => {
+                const chunks = [];
+                const sink = new node_stream_1.Writable({
+                    write: (chunk, _encoding, done) => {
+                        if (this.failNextUpload) {
+                            this.failNextUpload = false;
+                            done(new Error('upload failed'));
+                            return;
+                        }
+                        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+                        done();
+                    }
+                });
+                sink.on('finish', () => {
+                    this.objects.set(name, {
+                        body: Buffer.concat(chunks),
+                        contentType: options?.contentType
+                    });
+                });
+                return sink;
+            },
+            createReadStream: () => {
+                const object = this.objects.get(name);
+                // Lazily, exactly like the real client — which is why the
+                // provider reads metadata first rather than trusting this.
+                if (object)
+                    return node_stream_1.Readable.from(object.body);
+                return new node_stream_1.Readable({
+                    read() {
+                        this.destroy(objectNotFound());
+                    }
+                });
+            },
+            getMetadata: async () => {
+                const object = this.objects.get(name);
+                if (!object)
+                    throw objectNotFound();
+                return [{ size: object.body.byteLength }];
+            },
+            delete: async (options) => {
+                this.deleted.push(name);
+                const existed = this.objects.delete(name);
+                if (!existed && !options?.ignoreNotFound) {
+                    throw objectNotFound();
+                }
+                return [{}];
+            },
+            getSignedUrl: async (options) => {
+                this.lastSignedUrlOptions = options;
+                return [`https://storage.test/${name}?signed=1`];
+            }
+        };
+    }
+    async getMetadata() {
+        if (!this.exists)
+            throw objectNotFound();
+        return [{}];
+    }
+    /** Object names currently held, sorted. */
+    keys() {
+        return [...this.objects.keys()].sort();
+    }
+    /** Presents as the real thing to a provider that only uses the above. */
+    asBucket() {
+        return this;
+    }
+}
+exports.FakeBucket = FakeBucket;

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

@@ -0,0 +1,50 @@
+import { type Bucket } from '@google-cloud/storage';
+import type { StorageProvider } from '@orthacms/media-server';
+/**
+ * Settings for Google Cloud Storage.
+ *
+ * **You may not need this package.** GCS speaks the S3 XML API in
+ * interoperability mode, so `@orthacms/media-provider-s3` reaches it today with
+ * `endpoint: 'https://storage.googleapis.com'` and an HMAC key. This adapter
+ * exists for the deployment that cannot use that: HMAC keys are a long-lived
+ * secret that many organizations forbid by policy, and they rule out Workload
+ * Identity. Native GCS auth is the reason to be here — if you are happy with an
+ * HMAC key, the S3 adapter is one less package to keep.
+ */
+export interface GcsStorageConfig {
+    /** Bucket every object lands in. */
+    bucket: string;
+    /** Project the bucket belongs to. Optional under ADC. */
+    projectId?: string;
+    /** Path to a service-account key file. */
+    keyFilename?: string;
+    /** Inline service-account credentials, when a file is not an option. */
+    credentials?: {
+        client_email: string;
+        private_key: string;
+    };
+    /** Prefix every object name with this, e.g. to share a bucket. */
+    keyPrefix?: string;
+    /**
+     * Sign URLs through the IAM `signBlob` API instead of a local private key.
+     *
+     * This is how a Workload Identity deployment signs: it has no key, and the
+     * library asks IAM to sign for it. Opt-in because it needs the
+     * `iam.serviceAccounts.signBlob` permission — declaring the capability
+     * without it would mean minting URLs that fail at request time.
+     */
+    signWithIam?: boolean;
+    /** An already-built bucket handle — custom auth, or a test stub. */
+    bucketClient?: Bucket;
+}
+/**
+ * The Google Cloud Storage {@link StorageProvider}.
+ *
+ * Like the Azure adapter, `capabilities.directUrl` is **computed**: signing
+ * needs either a private key or an explicit opt-in to IAM `signBlob`, and a
+ * bare Application Default Credentials deployment has neither. A hardcoded
+ * `true` would let `MediaServerPlugin` accept `directServe: 'signed-url'` on a
+ * deployment that cannot honour it.
+ */
+export declare function createGcsStorageProvider(config: GcsStorageConfig): StorageProvider;
+//# sourceMappingURL=gcs-storage-provider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gcs-storage-provider.d.ts","sourceRoot":"","sources":["../../src/lib/gcs-storage-provider.ts"],"names":[],"mappings":"AAGA,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAE7D,OAAO,KAAK,EAGR,eAAe,EAElB,MAAM,wBAAwB,CAAC;AAEhC;;;;;;;;;;GAUG;AACH,MAAM,WAAW,gBAAgB;IAC7B,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0CAA0C;IAC1C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,WAAW,CAAC,EAAE;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5D,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,oEAAoE;IACpE,YAAY,CAAC,EAAE,MAAM,CAAC;CACzB;AAkBD;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACpC,MAAM,EAAE,gBAAgB,GACzB,eAAe,CAkIjB"}

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

@@ -0,0 +1,143 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createGcsStorageProvider = createGcsStorageProvider;
+const node_crypto_1 = require("node:crypto");
+const node_stream_1 = require("node:stream");
+const promises_1 = require("node:stream/promises");
+const storage_1 = require("@google-cloud/storage");
+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 GCS uses to say "no such object". */
+function isMissing(error) {
+    const candidate = error;
+    return (candidate?.code === 404 ||
+        candidate?.status === 404 ||
+        candidate?.code === 'ENOENT');
+}
+/**
+ * The Google Cloud Storage {@link StorageProvider}.
+ *
+ * Like the Azure adapter, `capabilities.directUrl` is **computed**: signing
+ * needs either a private key or an explicit opt-in to IAM `signBlob`, and a
+ * bare Application Default Credentials deployment has neither. A hardcoded
+ * `true` would let `MediaServerPlugin` accept `directServe: 'signed-url'` on a
+ * deployment that cannot honour it.
+ */
+function createGcsStorageProvider(config) {
+    if (!config.bucket?.trim()) {
+        throw new Error('createGcsStorageProvider requires a bucket name.');
+    }
+    const bucket = config.bucketClient ??
+        new storage_1.Storage({
+            ...(config.projectId ? { projectId: config.projectId } : {}),
+            ...(config.keyFilename ? { keyFilename: config.keyFilename } : {}),
+            ...(config.credentials ? { credentials: config.credentials } : {})
+        }).bucket(config.bucket);
+    const prefix = config.keyPrefix?.replace(/^\/+|\/+$/g, '');
+    const canSign = Boolean(config.keyFilename || config.credentials || config.signWithIam);
+    return {
+        id: 'gcs',
+        capabilities: {
+            directUrl: canSign,
+            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;
+            });
+            const file = bucket.file(storageKey);
+            try {
+                // `pipeline` rather than hand-wired events: it propagates a
+                // source error into the write stream and destroys both, which
+                // is what stops a dead upload hanging on a stream that will
+                // never end.
+                await (0, promises_1.pipeline)(object.body, meter, file.createWriteStream({
+                    resumable: true,
+                    contentType: object.contentType
+                }));
+            }
+            catch (error) {
+                // A resumable upload that dies part-way leaves an incomplete
+                // object the bucket will keep until its lifecycle rules sweep
+                // it — and the key never reached a caller, so nothing else can
+                // reclaim it.
+                await file
+                    .delete({ ignoreNotFound: true })
+                    .catch(() => undefined);
+                throw error;
+            }
+            return { storageKey, size, checksum: hash.digest('hex') };
+        },
+        async get(storageKey) {
+            const file = bucket.file(storageKey);
+            // The metadata read is deliberate. `createReadStream` opens lazily,
+            // so a missing object surfaces as an error *on the stream* — by
+            // which point the response is already a streaming 200 that can no
+            // longer become the 404 the route owes the caller. One HEAD-shaped
+            // call buys that back.
+            try {
+                await file.getMetadata();
+            }
+            catch (error) {
+                if (isMissing(error)) {
+                    throw new media_server_1.ObjectNotFoundError(storageKey, error);
+                }
+                throw error;
+            }
+            return file.createReadStream();
+        },
+        async remove(storageKey) {
+            // Idempotent by flag; the catch covers a gateway that answers 404
+            // anyway, since reclaim is post-commit and best-effort.
+            try {
+                await bucket.file(storageKey).delete({ ignoreNotFound: true });
+            }
+            catch (error) {
+                if (!isMissing(error))
+                    throw error;
+            }
+        },
+        ...(canSign
+            ? {
+                async directUrl(storageKey, options) {
+                    // Same rule as every signing provider: the disposition
+                    // and content type are pinned onto the URL, because the
+                    // redirect discards the app's own headers and the stored
+                    // MIME type is the uploader's claim.
+                    const fileName = options.fileName.replace(/"/g, '');
+                    const [url] = await bucket.file(storageKey).getSignedUrl({
+                        version: 'v4',
+                        action: 'read',
+                        expires: Date.now() + options.expiresInSeconds * 1000,
+                        responseDisposition: `${options.disposition}; filename="${fileName}"`,
+                        responseType: options.contentType
+                    });
+                    return url;
+                }
+            }
+            : {}),
+        async verify() {
+            // A wrong bucket or a credential that cannot see it fails the boot
+            // rather than the first upload.
+            await bucket.getMetadata();
+        }
+    };
+}

package/package.json

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