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

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createLocalStorageProvider, StorageKeyOutsideRootError } from './lib/local-storage-provider';
+export type { LocalStorageConfig } from './lib/local-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,EACH,0BAA0B,EAC1B,0BAA0B,EAC7B,MAAM,8BAA8B,CAAC;AACtC,YAAY,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StorageKeyOutsideRootError = exports.createLocalStorageProvider = void 0;
+var local_storage_provider_1 = require("./lib/local-storage-provider");
+Object.defineProperty(exports, "createLocalStorageProvider", { enumerable: true, get: function () { return local_storage_provider_1.createLocalStorageProvider; } });
+Object.defineProperty(exports, "StorageKeyOutsideRootError", { enumerable: true, get: function () { return local_storage_provider_1.StorageKeyOutsideRootError; } });

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

@@ -0,0 +1,38 @@
+import type { StorageProvider } from '@orthacms/media-server';
+/** Local filesystem provider settings. */
+export interface LocalStorageConfig {
+    /** Directory blobs live under (absolute or project-relative). */
+    rootDir: string;
+    /** Base path the browser hits to stream a blob (reserved for direct URLs). */
+    publicBasePath: string;
+}
+/**
+ * Raised when a storage key resolves outside the provider's `rootDir`.
+ *
+ * Keys are provider-owned and every key this provider *mints* is contained by
+ * construction — but `get`/`remove` are handed keys read back from
+ * `media_asset.storage_key`, which is only as trustworthy as everything that
+ * can write that column (a migration, an import script, a future provider that
+ * mints structured keys). Without this check `remove('../../x')` deletes an
+ * arbitrary file the server user can reach; with it, the traversal is a
+ * rejection instead of an action.
+ */
+export declare class StorageKeyOutsideRootError extends Error {
+    readonly storageKey: string;
+    constructor(storageKey: string);
+}
+/**
+ * The default {@link StorageProvider}: streams blobs to a directory on disk,
+ * keyed `<workspaceId>/<assetId>/<filename>` so they stay workspace-partitioned
+ * and collision-free. Computes size + sha256 as it writes. Bound at the
+ * composition root; the media core depends only on the `StorageProvider` port.
+ *
+ * `put` is **all-or-nothing**, as the port requires: bytes go to a temporary
+ * file and are moved into place with a single `rename` only once the whole body
+ * has been written. A body that errors mid-stream, a full disk, or a failed
+ * rename therefore leave nothing behind — which matters because a rejected
+ * `put` never handed its key back, so anything it left would be garbage no
+ * caller could ever name, let alone reclaim.
+ */
+export declare function createLocalStorageProvider(config: LocalStorageConfig): StorageProvider;
+//# sourceMappingURL=local-storage-provider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"local-storage-provider.d.ts","sourceRoot":"","sources":["../../src/lib/local-storage-provider.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAER,eAAe,EAElB,MAAM,wBAAwB,CAAC;AAEhC,0CAA0C;AAC1C,MAAM,WAAW,kBAAkB;IAC/B,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;IAChB,8EAA8E;IAC9E,cAAc,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;GAUG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;IACrC,QAAQ,CAAC,UAAU,EAAE,MAAM;gBAAlB,UAAU,EAAE,MAAM;CAI1C;AAgFD;;;;;;;;;;;;GAYG;AACH,wBAAgB,0BAA0B,CACtC,MAAM,EAAE,kBAAkB,GAC3B,eAAe,CA2IjB"}

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

@@ -0,0 +1,223 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StorageKeyOutsideRootError = void 0;
+exports.createLocalStorageProvider = createLocalStorageProvider;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const node_stream_1 = require("node:stream");
+const promises_2 = require("node:stream/promises");
+/**
+ * Raised when a storage key resolves outside the provider's `rootDir`.
+ *
+ * Keys are provider-owned and every key this provider *mints* is contained by
+ * construction — but `get`/`remove` are handed keys read back from
+ * `media_asset.storage_key`, which is only as trustworthy as everything that
+ * can write that column (a migration, an import script, a future provider that
+ * mints structured keys). Without this check `remove('../../x')` deletes an
+ * arbitrary file the server user can reach; with it, the traversal is a
+ * rejection instead of an action.
+ */
+class StorageKeyOutsideRootError extends Error {
+    storageKey;
+    constructor(storageKey) {
+        super(`Storage key resolves outside the storage root: ${storageKey}`);
+        this.storageKey = storageKey;
+        this.name = 'StorageKeyOutsideRootError';
+    }
+}
+exports.StorageKeyOutsideRootError = StorageKeyOutsideRootError;
+/**
+ * Longest single path component this provider will produce.
+ *
+ * 255 bytes is the per-component limit on ext4/APFS/NTFS alike. Exceeding it is
+ * an `ENAMETOOLONG` from `fs.open` — a raw node error the caller can only turn
+ * into a 500 — so the provider bounds the segment itself rather than letting a
+ * long name reach the syscall. Truncation (not rejection) is the right shape
+ * here because the key is opaque and provider-owned: the truncated key is what
+ * `put` returns and what the caller persists, so the round-trip still matches.
+ */
+const MAX_SEGMENT_LENGTH = 255;
+/** Longest extension worth preserving when a name has to be truncated. */
+const MAX_PRESERVED_EXTENSION = 16;
+/**
+ * Reduces a file name to a safe key segment.
+ *
+ * Three rules, in order:
+ *
+ * 1. Every run outside `[A-Za-z0-9_.-]` collapses to a single `_`, so no
+ *    separator, control character or NUL can reach the path.
+ * 2. `.`, `..` and the empty string (all three reachable once rule 1 has eaten
+ *    the rest) are **path tokens, not names**: `join` normalises `W/A/..` to
+ *    `W`, so the write lands on the workspace directory itself rather than
+ *    inside the asset — creating a *file* named `W` where every other asset in
+ *    that workspace needs a *directory*. Prefixing with `_` keeps it an
+ *    ordinary leaf name. Three dots or more is just an odd filename and is
+ *    left alone.
+ * 3. The result is bounded by {@link MAX_SEGMENT_LENGTH}, keeping the extension
+ *    when there is a plausible one.
+ *
+ * After rule 1 the segment is ASCII-only (`\w` is ASCII in a non-unicode
+ * regex), so character length and byte length are the same and rule 3 can slice
+ * without splitting a code point.
+ */
+function sanitize(name) {
+    const collapsed = name.replace(/[^\w.-]+/g, '_');
+    const leaf = collapsed === '' || collapsed === '.' || collapsed === '..'
+        ? `_${collapsed}`
+        : collapsed;
+    if (leaf.length <= MAX_SEGMENT_LENGTH)
+        return leaf;
+    const dot = leaf.lastIndexOf('.');
+    const extension = dot > 0 && leaf.length - dot <= MAX_PRESERVED_EXTENSION
+        ? leaf.slice(dot)
+        : '';
+    const stem = dot > 0 ? leaf.slice(0, dot) : leaf;
+    return stem.slice(0, MAX_SEGMENT_LENGTH - extension.length) + extension;
+}
+/**
+ * Removes `from` and each parent up to (but never including) `root`, stopping
+ * at the first directory that is not empty.
+ *
+ * Nothing else ever reclaims `<workspaceId>/<assetId>/`, so without this a
+ * workspace that uploads and deletes a million files keeps a million empty
+ * directories and their inodes forever. Best-effort by design: any error
+ * (`ENOTEMPTY`, `ENOENT`, `EACCES`, a concurrent writer) just ends the walk,
+ * because `remove` must stay idempotent and must not fail over housekeeping.
+ *
+ * The walk only ever moves *upwards* from the removed file's own directory, so
+ * it can never descend into a directory a concurrent `put` has just created.
+ */
+async function pruneEmptyDirectories(from, root) {
+    let directory = from;
+    while (directory !== root && directory.startsWith(root + node_path_1.sep)) {
+        try {
+            await (0, promises_1.rmdir)(directory);
+        }
+        catch {
+            return;
+        }
+        directory = (0, node_path_1.dirname)(directory);
+    }
+}
+/**
+ * The default {@link StorageProvider}: streams blobs to a directory on disk,
+ * keyed `<workspaceId>/<assetId>/<filename>` so they stay workspace-partitioned
+ * and collision-free. Computes size + sha256 as it writes. Bound at the
+ * composition root; the media core depends only on the `StorageProvider` port.
+ *
+ * `put` is **all-or-nothing**, as the port requires: bytes go to a temporary
+ * file and are moved into place with a single `rename` only once the whole body
+ * has been written. A body that errors mid-stream, a full disk, or a failed
+ * rename therefore leave nothing behind — which matters because a rejected
+ * `put` never handed its key back, so anything it left would be garbage no
+ * caller could ever name, let alone reclaim.
+ */
+function createLocalStorageProvider(config) {
+    // Pinned once, at construction. `rootDir` defaults to a *relative* path, so
+    // resolving it per call would silently re-home the whole store the moment
+    // anything called `process.chdir()` — the same key would then name two
+    // different files depending on when it was used.
+    const root = (0, node_path_1.resolve)(config.rootDir);
+    const keyFor = (workspaceId, assetId, fileName, isVariant) => {
+        // The ids are minted server-side (`AssetId.generate()` and the current
+        // workspace) and are uuids today, which `sanitize` leaves untouched.
+        // They are sanitized anyway so that a key this provider mints is
+        // contained by construction, whatever the core hands it — the
+        // containment check below is the backstop, not the only line.
+        const segments = [sanitize(workspaceId), sanitize(assetId)];
+        if (isVariant) {
+            // Derivatives live in a reserved `variants/` sub-namespace, so
+            // they can never collide with the original blob's key.
+            segments.push('variants');
+        }
+        segments.push(sanitize(fileName));
+        return segments.join('/');
+    };
+    const absolute = (storageKey) => {
+        // `resolve`, not `join`: `join(root, '/etc/passwd')` quietly rebases an
+        // absolute key under the root and hides it from a naive prefix check,
+        // whereas `resolve` returns `/etc/passwd` and the check below rejects.
+        const target = (0, node_path_1.resolve)(root, storageKey);
+        const inside = (0, node_path_1.relative)(root, target);
+        if (inside === '' ||
+            inside === '..' ||
+            inside.startsWith(`..${node_path_1.sep}`) ||
+            (0, node_path_1.isAbsolute)(inside)) {
+            throw new StorageKeyOutsideRootError(storageKey);
+        }
+        return target;
+    };
+    return {
+        async put(object) {
+            const storageKey = keyFor(object.workspaceId, object.assetId, object.fileName, object.isVariant ?? false);
+            const target = absolute(storageKey);
+            const directory = (0, node_path_1.dirname)(target);
+            await (0, promises_1.mkdir)(directory, { recursive: true });
+            // A fixed-length name of its own rather than one derived from the
+            // target, so the temporary file can never be the thing that busts
+            // the 255-byte component limit. The leading dot and `.part` suffix
+            // make a leftover self-evidently machine droppings.
+            const temporary = (0, node_path_1.join)(directory, `.${(0, node_crypto_1.randomBytes)(12).toString('hex')}.part`);
+            const hash = (0, node_crypto_1.createHash)('sha256');
+            let size = 0;
+            const meter = new node_stream_1.PassThrough();
+            meter.on('data', (chunk) => {
+                size += chunk.length;
+                hash.update(chunk);
+            });
+            try {
+                await (0, promises_2.pipeline)(object.body, meter, (0, node_fs_1.createWriteStream)(temporary));
+                // Atomic within a filesystem: the key either names the complete
+                // object or names nothing. It also makes two concurrent `put`s
+                // on one key resolve to one *intact* body rather than a mix.
+                await (0, promises_1.rename)(temporary, target);
+            }
+            catch (error) {
+                await (0, promises_1.rm)(temporary, { force: true }).catch(() => undefined);
+                // The directory chain was created for a write that never
+                // landed; leave no trace of it either.
+                await pruneEmptyDirectories(directory, root);
+                throw error;
+            }
+            return { storageKey, size, checksum: hash.digest('hex') };
+        },
+        async get(storageKey) {
+            // The port says `get` rejects when the key is gone.
+            // `createReadStream` cannot honour that: it opens lazily, so a
+            // missing blob resolved fine and then emitted `ENOENT` when the
+            // response was already a streaming 200 that could no longer become
+            // a 404. Opening the descriptor here moves the failure back in
+            // front of the response.
+            const handle = await (0, promises_1.open)(absolute(storageKey), 'r');
+            const stats = await handle.stat();
+            if (!stats.isFile()) {
+                await handle.close();
+                throw Object.assign(new Error(`EISDIR: storage key is not a file: ${storageKey}`), { code: 'EISDIR' });
+            }
+            // `autoClose` defaults to *false* for a FileHandle stream, which
+            // would leak the descriptor on every download.
+            return handle.createReadStream({ autoClose: true });
+        },
+        async remove(storageKey) {
+            const target = absolute(storageKey);
+            await (0, promises_1.rm)(target, { force: true });
+            await pruneEmptyDirectories((0, node_path_1.dirname)(target), root);
+        },
+        async url(storageKey) {
+            // NOTE: no route serves this path today — downloads go through
+            // `GET /api/media/assets/:id/raw`, which resolves the key from the
+            // asset row *after* checking workspace membership. Nothing calls
+            // `url()`; it exists because the port promises a direct URL that a
+            // signed-URL backend (S3) can give and a filesystem cannot.
+            //
+            // Whoever implements the static-serving mode: it must not be an
+            // `express.static` over `rootDir`. That would serve every blob to
+            // anyone who can guess a key and would bypass the membership check
+            // wholesale — the keys are uuids, but they are also handed out in
+            // API responses.
+            return `${config.publicBasePath}/blob/${encodeURIComponent(storageKey)}`;
+        }
+    };
+}

package/package.json

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