@adminforth/storage-adapter-local 1.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Devforth.io
+
+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/dist/index.js

@@ -0,0 +1,390 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import fs from "fs/promises";
+import path from "path";
+import crypto from "crypto";
+import { createWriteStream } from 'fs';
+import { Level } from 'level';
+class AdminForthStorageAdapterLocalFilesystem {
+    constructor(options) {
+        this.options = options;
+    }
+    presignUrl(urlPath, expiresIn, payload = {}) {
+        const expires = Math.floor(Date.now() / 1000) + expiresIn;
+        const params = new URLSearchParams(Object.assign(Object.assign({}, payload), { expires: expires.toString(), signature: this.sign(urlPath, expires, payload) }));
+        return `${urlPath}?${params.toString()}`;
+    }
+    sign(urlPath, expires, payload = {}) {
+        const hmac = crypto.createHmac("sha256", this.options.signingSecret);
+        hmac.update(urlPath);
+        hmac.update(expires.toString());
+        hmac.update(JSON.stringify(payload));
+        return hmac.digest("hex");
+    }
+    /**
+     * This method should return the presigned URL for the given key capable of upload (adapter user will call PUT multipart form data to this URL within expiresIn seconds after link generation).
+     * By default file which will be uploaded on PUT should be marked for deletion. So if during 24h it is not marked for not deletion, it adapter should delete it forever.
+     * The PUT method should fail if the file already exists.
+     *
+     * Adapter user will always pass next parameters to the method:
+     * @param key - The key of the file to be uploaded e.g. "uploads/file.txt"
+     * @param expiresIn - The expiration time in seconds for the presigned URL
+     * @param contentType - The content type of the file to be uploaded, e.g. "image/png"
+     *
+     * @returns A promise that resolves to an object containing the upload URL and any extra parameters which should be sent with PUT multipart form data
+     */
+    getUploadSignedUrl(key_1, contentType_1) {
+        return __awaiter(this, arguments, void 0, function* (key, contentType, expiresIn = 3600) {
+            const urlPath = `${this.expressBase}/${key}`;
+            return {
+                uploadUrl: this.presignUrl(urlPath, expiresIn, { contentType }),
+                uploadExtraParams: {}
+            };
+        });
+    }
+    /**
+     * This method should return the URL for the given key capable of download (200 GET request with response body or 200 HEAD request without response body).
+     * If adapter configured to store objects publically, this method should return the public URL of the file.
+     * If adapter configured to no allow public storing of images, this method should return the presigned URL for the file.
+     *
+     * @param key - The key of the file to be downloaded e.g. "uploads/file.txt"
+     * @param expiresIn - The expiration time in seconds for the presigned URL
+     */
+    getDownloadUrl(key_1) {
+        return __awaiter(this, arguments, void 0, function* (key, _expiresIn = 3600) {
+            const urlPath = `${this.expressBase}/${key}`;
+            if (this.options.mode === "public") {
+                return urlPath;
+            }
+            else {
+                return this.presignUrl(key, _expiresIn);
+            }
+        });
+    }
+    markKeyForDeletation(key) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const metadata = yield this.metadataDb.get(key).catch((e) => {
+                console.error(`Could not read metadata from db: ${e}`);
+                throw new Error(`Could not read metadata from db: ${e}`);
+            });
+            if (!metadata) {
+                throw new Error(`Metadata for key ${key} not found`);
+            }
+            const metadataParsed = JSON.parse(metadata);
+            try {
+                yield this.candidatesForDeletionDb.get(key);
+                // if key already exists, do nothing
+                return;
+            }
+            catch (e) {
+                // if key does not exist, continue
+            }
+            try {
+                yield this.candidatesForDeletionDb.put(key, metadataParsed.createdAt);
+            }
+            catch (e) {
+                console.error(`Could not write metadata to db: ${e}`);
+                throw new Error(`Could not write metadata to db: ${e}`);
+            }
+        });
+    }
+    /**
+     * This method should mark the file for deletion.
+     * If file is marked for delation and exists more then 24h (since creation date) it should be deleted.
+     * This method should work even if the file does not exist yet (e.g. only presigned URL was generated).
+     * @param key - The key of the file to be uploaded e.g. "uploads/file.txt"
+     */
+    markKeyForNotDeletation(key) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                // if key exists, delete it
+                yield this.candidatesForDeletionDb.del(key);
+            }
+            catch (e) {
+                // if key does not exist, do nothing
+            }
+        });
+    }
+    setupLifecycle(userUniqueIntanceId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.options.fileSystemFolder) {
+                throw new Error("fileSystemFolder is not set in the options");
+            }
+            if (!this.options.signingSecret) {
+                throw new Error("signingSecret is not set in the options");
+            }
+            // check if folder exists and try to create it if not
+            // if it is not possible to create the folder, throw an error
+            try {
+                yield fs.mkdir(this.options.fileSystemFolder, { recursive: true });
+            }
+            catch (e) {
+                throw new Error(`Could not create folder ${this.options.fileSystemFolder}: ${e}`);
+            }
+            // check if folder is writable
+            try {
+                yield fs.access(this.options.fileSystemFolder, fs.constants.W_OK);
+            }
+            catch (e) {
+                throw new Error(`fileSystemFolder folder ${this.options.fileSystemFolder} is not writable: ${e}`);
+            }
+            // check if folder is readable
+            try {
+                yield fs.access(this.options.fileSystemFolder, fs.constants.R_OK);
+            }
+            catch (e) {
+                throw new Error(`fileSystemFolder folder ${this.options.fileSystemFolder} is not readable: ${e}`);
+            }
+            this.metadataDb = new Level(path.join(this.options.fileSystemFolder, userUniqueIntanceId, 'metadata'));
+            this.candidatesForDeletionDb = new Level(path.join(this.options.fileSystemFolder, userUniqueIntanceId, 'candidatesForDeletion'));
+            const expressInstance = global.adminforth.express.expressApp;
+            const prefix = global.adminforth.config.baseUrl || '/';
+            const slashedPrefix = prefix.endsWith('/') ? prefix : `${prefix}/`;
+            this.adminforthSlashedPrefix = slashedPrefix;
+            if (!this.options.adminServeBaseUrl) {
+                this.expressBase = `${slashedPrefix}uploaded-static/${userUniqueIntanceId}`;
+            }
+            else {
+                if (AdminForthStorageAdapterLocalFilesystem.registredPrexises.includes(this.options.adminServeBaseUrl)) {
+                    throw new Error(`adminServeBaseUrl ${this.options.adminServeBaseUrl} already registered, by another instance of local filesystem adapter. 
+          Each adapter instahce should have unique adminServeBaseUrl by design.
+        `);
+                }
+                AdminForthStorageAdapterLocalFilesystem.registredPrexises.push(this.expressBase);
+                this.expressBase = `${slashedPrefix}${this.options.adminServeBaseUrl}`;
+            }
+            // add express PUT endpoint for uploading files
+            expressInstance.put(`${this.expressBase}/*`, (req, res) => __awaiter(this, void 0, void 0, function* () {
+                const key = req.params[0];
+                // get content type from headers
+                const contentType = req.headers["content-type"];
+                if (!contentType) {
+                    return res.status(400).send("Content type is required");
+                }
+                const filePath = path.resolve(this.options.fileSystemFolder, key);
+                // Ensure filePath is within fileSystemFolder
+                const basePath = path.resolve(this.options.fileSystemFolder);
+                if (!filePath.startsWith(basePath + path.sep)) {
+                    return res.status(400).send("Invalid key, access denied");
+                }
+                //verify presigned URL
+                const expires = parseInt(req.query.expires);
+                const signature = req.query.signature;
+                const payload = {
+                    contentType: contentType,
+                };
+                console.log(`👐👐👐 verify sign for ${key}|${expires}|${JSON.stringify(payload)}`);
+                const expectedSignature = this.sign(`${this.expressBase}/${key}`, expires, payload);
+                if (signature !== expectedSignature) {
+                    return res.status(403).send("Invalid signature");
+                }
+                if (Date.now() / 1000 > expires) {
+                    return res.status(403).send("Signature expired");
+                }
+                // check if content type is valid
+                if (contentType !== req.headers["content-type"]) {
+                    return res.status(400).send("Invalid content type");
+                }
+                // check if file already exists
+                try {
+                    yield fs.access(filePath);
+                    return res.status(409).send("File already exists");
+                }
+                catch (e) {
+                    // file does not exist, continue
+                }
+                // create folder if it does not exist
+                const folderPath = path.dirname(filePath);
+                try {
+                    yield fs.mkdir(folderPath, { recursive: true });
+                }
+                catch (e) {
+                    return res.status(500).send(`Could not create folder ${folderPath}: ${e}`);
+                }
+                // write file to disk
+                const writeStream = createWriteStream(filePath);
+                req.pipe(writeStream);
+                writeStream.on("finish", () => {
+                    // write metadata to db
+                    this.metadataDb.put(key, JSON.stringify({
+                        contentType: contentType,
+                        createdAt: +Date.now(),
+                        size: writeStream.bytesWritten,
+                    })).catch((e) => {
+                        console.error(`Could not write metadata to db: ${e}`);
+                        throw new Error(`Could not write metadata to db: ${e}`);
+                    });
+                    this.markKeyForDeletation(key);
+                    res.status(200).send("File uploaded");
+                });
+            }));
+            console.log(`🎉🎉🎉 registring get endpoint for ${this.expressBase}/*`);
+            // add express GET endpoint for downloading files
+            expressInstance.get(`${this.expressBase}/*`, (req, res) => __awaiter(this, void 0, void 0, function* () {
+                console.log(`🎉🎉🎉 GET ${req.url}`, res, typeof res, Object.keys(res));
+                const key = req.params[0];
+                const filePath = path.resolve(this.options.fileSystemFolder, key);
+                // Ensure filePath is within fileSystemFolder
+                const basePath = path.resolve(this.options.fileSystemFolder);
+                if (!filePath.startsWith(basePath + path.sep)) {
+                    return res.status(400).send("Invalid key, access denied");
+                }
+                // check if file exists
+                try {
+                    yield fs.access(filePath);
+                }
+                catch (e) {
+                    return res.status(404).send("File not found");
+                }
+                // add metadata to response headers
+                const metadata = yield this.metadataDb.get(key).catch((e) => {
+                    throw new Error(`Could not read metadata for ${key} from db: ${e}`);
+                });
+                if (!metadata) {
+                    return res.status(404).send(`Metadata for ${key} not found`);
+                }
+                const metadataParsed = JSON.parse(metadata);
+                // send file to client
+                res.sendFile(filePath, {
+                    headers: {
+                        "Content-Type": metadataParsed.contentType,
+                        "Content-Length": metadataParsed.size,
+                        "Last-Modified": new Date(metadataParsed.createdAt).toUTCString(),
+                        "ETag": crypto.createHash("md5").update(metadata).digest("hex"),
+                    },
+                }, (err) => {
+                    if (err) {
+                        console.error(`Could not send file ${filePath}: ${err}`);
+                        res.status(500).send("Could not send file");
+                    }
+                });
+            }));
+            this.putLastListenerToTheBeginningOfTheStack(expressInstance);
+            // add HEAD endpoint for returning file metadata
+            expressInstance.head(`${this.expressBase}/*`, (req, res) => __awaiter(this, void 0, void 0, function* () {
+                const key = req.params[0];
+                const filePath = path.resolve(this.options.fileSystemFolder, key);
+                // Ensure filePath is within fileSystemFolder
+                const basePath = path.resolve(this.options.fileSystemFolder);
+                if (!filePath.startsWith(basePath + path.sep)) {
+                    return res.status(400).send("Invalid key, access denied");
+                }
+                // check if file exists
+                try {
+                    yield fs.access(filePath);
+                }
+                catch (e) {
+                    return res.status(404).send("File not found");
+                }
+                // add metadata to response headers
+                const metadata = yield this.metadataDb.get(key).catch((e) => {
+                    throw new Error(`Could not read metadata for ${key} from db: ${e}`);
+                });
+                if (!metadata) {
+                    return res.status(404).send(`Metadata for ${key} not found`);
+                }
+                const metadataParsed = JSON.parse(metadata);
+                res.setHeader("Content-Type", metadataParsed.contentType);
+                res.setHeader("Content-Length", metadataParsed.size);
+                res.setHeader("Last-Modified", new Date(metadataParsed.createdAt).toUTCString());
+                res.setHeader("ETag", crypto.createHash("md5").update(metadata).digest("hex"));
+            }));
+            this.putLastListenerToTheBeginningOfTheStack(expressInstance);
+            // run scheduler every 10 minutes to delete files marked for deletion
+            setInterval(() => __awaiter(this, void 0, void 0, function* () {
+                const now = +Date.now();
+                const keys = yield this.candidatesForDeletionDb.keys().all();
+                for (const key of keys) {
+                    const createdAt = yield this.candidatesForDeletionDb.get(key).catch((e) => {
+                        console.error(`Could not read metadata from db: ${e}`);
+                        throw new Error(`Could not read metadata from db: ${e}`);
+                    });
+                    if (now - +createdAt > 24 * 60 * 60 * 1000) {
+                        // delete file
+                        try {
+                            yield fs.unlink(path.resolve(this.options.fileSystemFolder, key));
+                        }
+                        catch (e) {
+                            console.error(`Could not delete file ${key}: ${e}`);
+                            throw new Error(`Could not delete file ${key}: ${e}`);
+                        }
+                        // delete metadata
+                        try {
+                            yield this.metadataDb.del(key);
+                        }
+                        catch (e) {
+                            console.error(`Could not delete metadata from db: ${e}`);
+                            throw new Error(`Could not delete metadata from db: ${e}`);
+                        }
+                    }
+                }
+            }), 10 * 60 * 1000); // every 10 minutes
+        });
+    }
+    objectCanBeAccesedPublicly() {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.options.mode === "public";
+        });
+    }
+    putLastListenerToTheBeginningOfTheStack(expressInstance) {
+        // since adminforth might already registred /* endpoint we need to reorder the routes
+        const stack = expressInstance._router.stack;
+        const adpaterListnerLayer = stack.pop(); // route is last, just pop it
+        // find route with ${this.adminforthSlashedPrefix}assets/*
+        const wildcardIndex = stack.findIndex((layer) => {
+            return layer.route && layer.route.path === `${this.adminforthSlashedPrefix}assets/*`;
+        });
+        if (wildcardIndex === -1) {
+            // if not found, just push it to the end, e.g. if discover databse and this method executed before 
+            // adminforth registered the wildcard route
+            stack.push(adpaterListnerLayer);
+        }
+        else {
+            stack.splice(wildcardIndex, 0, adpaterListnerLayer); // insert before wildcard
+        }
+    }
+    /**
+     * This method should return the key as a data URL (base64 encoded string).
+     * @param key - The key of the file to be converted to a data URL
+     * @returns A promise that resolves to a string containing the data URL
+     */
+    getKeyAsDataURL(key) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const filePath = path.resolve(this.options.fileSystemFolder, key);
+            // Ensure filePath is within fileSystemFolder
+            const basePath = path.resolve(this.options.fileSystemFolder);
+            if (!filePath.startsWith(basePath + path.sep)) {
+                throw new Error("Invalid key, access denied");
+            }
+            // check if file exists
+            try {
+                yield fs.access(filePath);
+            }
+            catch (e) {
+                throw new Error("File not found");
+            }
+            // read file and convert to base64
+            const fileBuffer = yield fs.readFile(filePath);
+            const base64 = fileBuffer.toString("base64");
+            const metadata = yield this.metadataDb.get(key).catch((e) => {
+                console.error(`Could not read metadata from db: ${e}`);
+                throw new Error(`Could not read metadata from db: ${e}`);
+            });
+            if (!metadata) {
+                throw new Error(`Metadata for key ${key} not found`);
+            }
+            const metadataParsed = JSON.parse(metadata);
+            const dataUrl = `data:${metadataParsed.contentType};base64,${base64}`;
+            return dataUrl;
+        });
+    }
+}
+AdminForthStorageAdapterLocalFilesystem.registredPrexises = [];
+export default AdminForthStorageAdapterLocalFilesystem;

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/index.ts

@@ -0,0 +1,440 @@
+import fs from "fs/promises";
+import path from "path";
+import AdminForth, { StorageAdapter } from "adminforth";
+import crypto from "crypto";
+import { createWriteStream } from 'fs';
+import { Level } from 'level';
+import { Express } from "express";
+
+declare global {
+  var adminforth: AdminForth;
+}
+
+interface StorageLocalFilesystemOptions {
+  fileSystemFolder: string; // folder where files will be stored
+  mode: "public" | "private"; // public if all files should be accessible from the web, private only if could be accessed by temporary presigned links
+  signingSecret: string; // secret used to generate presigned URLs
+  adminServeBaseUrl?: string; // base URL for serving files e.g. static/uploads. If not defined will be generated automatically
+    // please note that is adminforth base URL is set, files will be available on `${adminforth.config.baseUrl}/${adminServeBaseUrl}/{key}`
+}
+
+export default class AdminForthStorageAdapterLocalFilesystem implements StorageAdapter {
+  static registredPrexises: string[] = [];
+
+  private options: StorageLocalFilesystemOptions;
+  private expressBase: string;
+  private adminforthSlashedPrefix: string; // slashed prefix of the base URL
+
+  private metadataDb: Level;
+  private candidatesForDeletionDb: Level;
+
+  constructor(options: StorageLocalFilesystemOptions) {
+    this.options = options;
+  }
+
+  presignUrl(urlPath: string, expiresIn: number, payload: Record<string, string> = {}): string {
+    const expires = Math.floor(Date.now() / 1000) + expiresIn;
+
+    const params = new URLSearchParams({
+      ...payload,
+      expires: expires.toString(),
+      signature: this.sign(urlPath, expires, payload),
+    });
+    return `${urlPath}?${params.toString()}`;
+  }
+
+  sign(urlPath: string, expires: number, payload: Record<string, string> = {}): string {
+    const hmac = crypto.createHmac("sha256", this.options.signingSecret);
+    hmac.update(urlPath);
+    hmac.update(expires.toString());
+    hmac.update(JSON.stringify(payload));
+    return hmac.digest("hex");
+  }
+
+
+  /**
+   * This method should return the presigned URL for the given key capable of upload (adapter user will call PUT multipart form data to this URL within expiresIn seconds after link generation).
+   * By default file which will be uploaded on PUT should be marked for deletion. So if during 24h it is not marked for not deletion, it adapter should delete it forever.
+   * The PUT method should fail if the file already exists.
+   * 
+   * Adapter user will always pass next parameters to the method:
+   * @param key - The key of the file to be uploaded e.g. "uploads/file.txt"
+   * @param expiresIn - The expiration time in seconds for the presigned URL
+   * @param contentType - The content type of the file to be uploaded, e.g. "image/png"
+   * 
+   * @returns A promise that resolves to an object containing the upload URL and any extra parameters which should be sent with PUT multipart form data
+   */
+  async getUploadSignedUrl(
+    key: string,
+    contentType: string,
+    expiresIn = 3600
+  ): Promise<{ uploadUrl: string; uploadExtraParams: Record<string, string> }> {
+    const urlPath = `${this.expressBase}/${key}`;
+
+    return {
+      uploadUrl: this.presignUrl(urlPath, expiresIn, { contentType }),
+      uploadExtraParams: {}
+    }
+  }
+
+  
+  /**
+   * This method should return the URL for the given key capable of download (200 GET request with response body or 200 HEAD request without response body).
+   * If adapter configured to store objects publically, this method should return the public URL of the file.
+   * If adapter configured to no allow public storing of images, this method should return the presigned URL for the file.
+   * 
+   * @param key - The key of the file to be downloaded e.g. "uploads/file.txt"
+   * @param expiresIn - The expiration time in seconds for the presigned URL
+   */
+  async getDownloadUrl(key: string, _expiresIn = 3600): Promise<string> {
+    const urlPath = `${this.expressBase}/${key}`;
+    if (this.options.mode === "public") {
+      return urlPath;
+    } else {
+      return this.presignUrl(key, _expiresIn);
+    }
+  }
+
+  async markKeyForDeletation(key: string): Promise<void> {
+    const metadata = await this.metadataDb.get(key).catch((e) => {
+      console.error(`Could not read metadata from db: ${e}`);
+      throw new Error(`Could not read metadata from db: ${e}`);
+    });
+    if (!metadata) {
+      throw new Error(`Metadata for key ${key} not found`);
+    }
+    const metadataParsed = JSON.parse(metadata);
+
+    try {
+      await this.candidatesForDeletionDb.get(key);
+      // if key already exists, do nothing
+      return;
+    } catch (e) {
+      // if key does not exist, continue
+    }
+    try {
+      await this.candidatesForDeletionDb.put(key, metadataParsed.createdAt)
+    } catch (e) {
+      console.error(`Could not write metadata to db: ${e}`);
+      throw new Error(`Could not write metadata to db: ${e}`);
+    }
+  }
+
+  /**
+   * This method should mark the file for deletion.
+   * If file is marked for delation and exists more then 24h (since creation date) it should be deleted.
+   * This method should work even if the file does not exist yet (e.g. only presigned URL was generated).
+   * @param key - The key of the file to be uploaded e.g. "uploads/file.txt"
+   */
+  async markKeyForNotDeletation(key: string): Promise<void> {
+    try {
+      // if key exists, delete it
+      await this.candidatesForDeletionDb.del(key);
+    } catch (e) {
+      // if key does not exist, do nothing
+    }
+  }
+
+  async setupLifecycle(userUniqueIntanceId): Promise<void> {
+
+    if (!this.options.fileSystemFolder) {
+      throw new Error("fileSystemFolder is not set in the options");
+    }
+    if (!this.options.signingSecret) {
+      throw new Error("signingSecret is not set in the options");
+    }
+
+    // check if folder exists and try to create it if not
+    // if it is not possible to create the folder, throw an error
+    try {
+      await fs.mkdir(this.options.fileSystemFolder, { recursive: true });
+    } catch (e) {
+      throw new Error(`Could not create folder ${this.options.fileSystemFolder}: ${e}`);
+    }
+    // check if folder is writable
+    try {
+      await fs.access(this.options.fileSystemFolder, fs.constants.W_OK);
+    } catch (e) {
+      throw new Error(`fileSystemFolder folder ${this.options.fileSystemFolder} is not writable: ${e}`);
+    }
+    // check if folder is readable
+    try {
+      await fs.access(this.options.fileSystemFolder, fs.constants.R_OK);
+    } catch (e) {
+      throw new Error(`fileSystemFolder folder ${this.options.fileSystemFolder} is not readable: ${e}`);
+    }
+
+    this.metadataDb = new Level(path.join(this.options.fileSystemFolder, userUniqueIntanceId, 'metadata'));
+
+    this.candidatesForDeletionDb = new Level(path.join(this.options.fileSystemFolder, userUniqueIntanceId, 'candidatesForDeletion'));
+
+    const expressInstance: Express = global.adminforth.express.expressApp;
+    const prefix = global.adminforth.config.baseUrl || '/';
+
+    const slashedPrefix = prefix.endsWith('/') ? prefix : `${prefix}/`;
+    this.adminforthSlashedPrefix = slashedPrefix;
+    if (!this.options.adminServeBaseUrl) {
+      this.expressBase = `${slashedPrefix}uploaded-static/${userUniqueIntanceId}`
+    } else {
+      if (AdminForthStorageAdapterLocalFilesystem.registredPrexises.includes(this.options.adminServeBaseUrl)) {
+        throw new Error(`adminServeBaseUrl ${this.options.adminServeBaseUrl} already registered, by another instance of local filesystem adapter. 
+          Each adapter instahce should have unique adminServeBaseUrl by design.
+        `);
+      }
+
+      AdminForthStorageAdapterLocalFilesystem.registredPrexises.push(this.expressBase);
+      this.expressBase = `${slashedPrefix}${this.options.adminServeBaseUrl}`;
+
+    }
+    
+
+    // add express PUT endpoint for uploading files
+    expressInstance.put(`${this.expressBase}/*`, async (req: any, res: any) => {
+      const key = req.params[0];
+
+      // get content type from headers
+      const contentType = req.headers["content-type"] as string;
+      if (!contentType) {
+        return res.status(400).send("Content type is required");
+      }
+
+      const filePath = path.resolve(this.options.fileSystemFolder, key);
+
+      // Ensure filePath is within fileSystemFolder
+      const basePath = path.resolve(this.options.fileSystemFolder);
+      if (!filePath.startsWith(basePath + path.sep)) {
+        return res.status(400).send("Invalid key, access denied");
+      }
+
+      //verify presigned URL
+      const expires = parseInt(req.query.expires as string);
+      const signature = req.query.signature as string;
+      const payload = {
+        contentType: contentType,
+      }
+      console.log(`👐👐👐 verify sign for ${key}|${expires}|${JSON.stringify(payload)}`)
+
+      const expectedSignature = this.sign(
+        `${this.expressBase}/${key}`, expires, payload);
+      if (signature !== expectedSignature) {
+        return res.status(403).send("Invalid signature");
+      }
+      if (Date.now() / 1000 > expires) {
+        return res.status(403).send("Signature expired");
+      }
+      // check if content type is valid
+      if (contentType !== req.headers["content-type"]) {
+        return res.status(400).send("Invalid content type");
+      }
+
+      // check if file already exists
+      try {
+        await fs.access(filePath);
+        return res.status(409).send("File already exists");
+      } catch (e) {
+        // file does not exist, continue
+      }
+      // create folder if it does not exist
+      const folderPath = path.dirname(filePath);
+      try {
+        await fs.mkdir(folderPath, { recursive: true });
+      } catch (e) {
+        return res.status(500).send(`Could not create folder ${folderPath}: ${e}`);
+      }
+      // write file to disk
+      const writeStream = createWriteStream(filePath);
+      req.pipe(writeStream);
+      writeStream.on("finish", () => {
+        // write metadata to db
+        this.metadataDb.put(key, 
+          JSON.stringify({
+            contentType: contentType,
+            createdAt: +Date.now(),
+            size: writeStream.bytesWritten,
+          })
+        ).catch((e) => {
+          console.error(`Could not write metadata to db: ${e}`);
+          throw new Error(`Could not write metadata to db: ${e}`);
+        });
+
+        this.markKeyForDeletation(key);
+
+        res.status(200).send("File uploaded");
+      });
+    });
+
+    console.log(`🎉🎉🎉 registring get endpoint for ${this.expressBase}/*`)
+    // add express GET endpoint for downloading files
+    expressInstance.get(`${this.expressBase}/*`, async (req: any, res: any) => {
+      console.log(`🎉🎉🎉 GET ${req.url}`, res, typeof res,  Object.keys(res));
+      const key = req.params[0];
+      const filePath = path.resolve(this.options.fileSystemFolder, key);
+
+      // Ensure filePath is within fileSystemFolder
+      const basePath = path.resolve(this.options.fileSystemFolder);
+      if (!filePath.startsWith(basePath + path.sep)) {
+        return res.status(400).send("Invalid key, access denied");
+      }
+
+      // check if file exists
+      try {
+        await fs.access(filePath);
+      } catch (e) {
+        return res.status(404).send("File not found");
+      }
+
+      // add metadata to response headers
+      const metadata = await this.metadataDb.get(key).catch((e) => {
+        throw new Error(`Could not read metadata for ${key} from db: ${e}`);
+      });
+      if (!metadata) {
+        return res.status(404).send(`Metadata for ${key} not found`);
+      }
+      const metadataParsed = JSON.parse(metadata);
+      // send file to client
+      res.sendFile(
+        filePath, 
+        {
+          headers: {
+            "Content-Type": metadataParsed.contentType,
+            "Content-Length": metadataParsed.size,
+            "Last-Modified": new Date(metadataParsed.createdAt).toUTCString(),
+            "ETag": crypto.createHash("md5").update(metadata).digest("hex"),
+          },
+        },
+        (err) => {
+          if (err) {
+            console.error(`Could not send file ${filePath}: ${err}`);
+            res.status(500).send("Could not send file");
+          }
+        }
+      );
+    });
+
+    this.putLastListenerToTheBeginningOfTheStack(expressInstance);
+
+
+
+    // add HEAD endpoint for returning file metadata
+    expressInstance.head(`${this.expressBase}/*`, async (req: any, res: any) => {
+      const key = req.params[0];
+      const filePath = path.resolve(this.options.fileSystemFolder, key);
+
+      // Ensure filePath is within fileSystemFolder
+      const basePath = path.resolve(this.options.fileSystemFolder);
+      if (!filePath.startsWith(basePath + path.sep)) {
+        return res.status(400).send("Invalid key, access denied");
+      }
+
+      // check if file exists
+      try {
+        await fs.access(filePath);
+      } catch (e) {
+        return res.status(404).send("File not found");
+      }
+
+      // add metadata to response headers
+      const metadata = await this.metadataDb.get(key).catch((e) => {
+        throw new Error(`Could not read metadata for ${key} from db: ${e}`);
+      });
+      if (!metadata) {
+        return res.status(404).send(`Metadata for ${key} not found`);
+      }
+      const metadataParsed = JSON.parse(metadata);
+      res.setHeader("Content-Type", metadataParsed.contentType);
+      res.setHeader("Content-Length", metadataParsed.size);
+      res.setHeader("Last-Modified", new Date(metadataParsed.createdAt).toUTCString());
+      res.setHeader("ETag", crypto.createHash("md5").update(metadata).digest("hex"));
+    });
+    this.putLastListenerToTheBeginningOfTheStack(expressInstance);
+
+
+    // run scheduler every 10 minutes to delete files marked for deletion
+    setInterval(async () => {
+      const now = +Date.now();
+      const keys = await this.candidatesForDeletionDb.keys().all();
+      for (const key of keys) {
+        const createdAt = await this.candidatesForDeletionDb.get(key).catch((e) => {
+          console.error(`Could not read metadata from db: ${e}`);
+          throw new Error(`Could not read metadata from db: ${e}`);
+        });
+        if (now - +createdAt > 24 * 60 * 60 * 1000) {
+          // delete file
+          try {
+            await fs.unlink(path.resolve(this.options.fileSystemFolder, key));
+          } catch (e) {
+            console.error(`Could not delete file ${key}: ${e}`);
+            throw new Error(`Could not delete file ${key}: ${e}`);
+          }
+          // delete metadata
+          try {
+            await this.metadataDb.del(key);
+          } catch (e) {
+            console.error(`Could not delete metadata from db: ${e}`);
+            throw new Error(`Could not delete metadata from db: ${e}`);
+          }
+        }
+      }
+    }
+      , 10 * 60 * 1000); // every 10 minutes
+
+  }
+
+  async objectCanBeAccesedPublicly(): Promise<boolean> {
+    return this.options.mode === "public";
+  }
+
+  putLastListenerToTheBeginningOfTheStack(expressInstance) {
+    // since adminforth might already registred /* endpoint we need to reorder the routes
+    const stack = expressInstance._router.stack;
+    const adpaterListnerLayer = stack.pop(); // route is last, just pop it
+    // find route with ${this.adminforthSlashedPrefix}assets/*
+    const wildcardIndex = stack.findIndex((layer) => {
+      return layer.route && layer.route.path === `${this.adminforthSlashedPrefix}assets/*`;
+    });
+    if (wildcardIndex === -1) {
+      // if not found, just push it to the end, e.g. if discover databse and this method executed before 
+      // adminforth registered the wildcard route
+      stack.push(adpaterListnerLayer);
+    } else {
+      stack.splice(wildcardIndex, 0, adpaterListnerLayer); // insert before wildcard
+    }
+  }
+
+  /**
+   * This method should return the key as a data URL (base64 encoded string).
+   * @param key - The key of the file to be converted to a data URL
+   * @returns A promise that resolves to a string containing the data URL
+   */
+   async getKeyAsDataURL(key: string): Promise<string> {
+    const filePath = path.resolve(this.options.fileSystemFolder, key);
+
+    // Ensure filePath is within fileSystemFolder
+    const basePath = path.resolve(this.options.fileSystemFolder);
+    if (!filePath.startsWith(basePath + path.sep)) {
+      throw new Error("Invalid key, access denied");
+    }
+
+    // check if file exists
+    try {
+      await fs.access(filePath);
+    } catch (e) {
+      throw new Error("File not found");
+    }
+
+    // read file and convert to base64
+    const fileBuffer = await fs.readFile(filePath);
+    const base64 = fileBuffer.toString("base64");
+    const metadata = await this.metadataDb.get(key).catch((e) => {
+      console.error(`Could not read metadata from db: ${e}`);
+      throw new Error(`Could not read metadata from db: ${e}`);
+    });
+    if (!metadata) {
+      throw new Error(`Metadata for key ${key} not found`);
+    }
+    const metadataParsed = JSON.parse(metadata);
+    const dataUrl = `data:${metadataParsed.contentType};base64,${base64}`;
+    return dataUrl;
+  }
+
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@adminforth/storage-adapter-local",
+  "version": "1.0.2",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "scripts": {
+    "build": "tsc && npm version patch",
+    "rollout": "npm run build && npm publish --access public",
+    "prepare": "npm link adminforth"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "description": "",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/devforth/adminforth-storage-adapter-local.git"
+  },
+  "dependencies": {
+    "@types/express": "^4.17.21",
+    "@types/level": "^6.0.3",
+    "adminforth": "^1.21.0",
+    "express": "^4.21.2",
+    "level": "^10.0.0",
+    "typescript": "^5.8.2"
+  }
+}

package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "es2016",                                  /* Set the JavaScript language version for emitted JavaScript and include*/ 
+    "module": "node16",                                /* Specify what module code is generated. */
+    "outDir": "./dist",                                   /* Specify an output folder for all emitted files. */
+    "esModuleInterop": true,                             /* Emit additional JavaScript to ease support for importing CommonJS modules.  */
+    "forceConsistentCasingInFileNames": true,            /* Ensure that casing is correct in imports. */
+    "strict": false,                                     /* Enable all strict type-checking options. */
+    "skipLibCheck": true,                                 /* Skip type checking all .d.ts files. */
+  },
+  "exclude": ["node_modules", "dist", "custom"],           /* Exclude files from compilation. */
+}

package/types.ts

@@ -0,0 +1,3 @@
+export interface AdapterOptions {
+    localPath: string;
+  }