@objectstack/service-storage 4.0.4 → 4.1.0

package/dist/index.cjs

@@ -1,8 +1,13 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
@@ -15,51 +20,349 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
+// src/s3-storage-adapter.ts
+var s3_storage_adapter_exports = {};
+__export(s3_storage_adapter_exports, {
+  S3StorageAdapter: () => S3StorageAdapter
+});
+async function streamToBuffer(stream) {
+  if (Buffer.isBuffer(stream)) return stream;
+  if (stream instanceof Uint8Array) return Buffer.from(stream);
+  const chunks = [];
+  if (typeof stream[Symbol.asyncIterator] === "function") {
+    for await (const chunk of stream) {
+      chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+    }
+  } else if (stream.getReader) {
+    const reader = stream.getReader();
+    let done = false;
+    while (!done) {
+      const result = await reader.read();
+      done = result.done;
+      if (result.value) chunks.push(result.value);
+    }
+  } else {
+    throw new Error("Cannot convert stream to buffer");
+  }
+  return Buffer.concat(chunks);
+}
+var S3StorageAdapter;
+var init_s3_storage_adapter = __esm({
+  "src/s3-storage-adapter.ts"() {
+    "use strict";
+    S3StorageAdapter = class {
+      constructor(options) {
+        this.options = options;
+        this.clientPromise = null;
+        // ---------------------------------------------------------------------------
+        // Internal upload key tracking
+        // ---------------------------------------------------------------------------
+        this._uploadKeys = /* @__PURE__ */ new Map();
+        this.bucket = options.bucket;
+        this.region = options.region;
+        this.endpoint = options.endpoint;
+        this.forcePathStyle = options.forcePathStyle ?? false;
+      }
+      /**
+       * Lazily resolve the AWS S3 client to avoid crashing at import time when
+       * `@aws-sdk/client-s3` isn't installed.
+       */
+      async getClient() {
+        if (!this.clientPromise) {
+          this.clientPromise = (async () => {
+            let s3Mod;
+            try {
+              s3Mod = await import("@aws-sdk/client-s3");
+            } catch {
+              throw new Error(
+                "S3StorageAdapter requires @aws-sdk/client-s3. Install it with: pnpm add @aws-sdk/client-s3 @aws-sdk/s3-request-presigner"
+              );
+            }
+            const { S3Client } = s3Mod;
+            const clientOpts = { region: this.region };
+            if (this.endpoint) clientOpts.endpoint = this.endpoint;
+            if (this.forcePathStyle) clientOpts.forcePathStyle = true;
+            if (this.options.accessKeyId && this.options.secretAccessKey) {
+              clientOpts.credentials = {
+                accessKeyId: this.options.accessKeyId,
+                secretAccessKey: this.options.secretAccessKey
+              };
+            }
+            return new S3Client(clientOpts);
+          })();
+        }
+        return this.clientPromise;
+      }
+      async s3Mod() {
+        try {
+          return await import("@aws-sdk/client-s3");
+        } catch {
+          throw new Error("S3StorageAdapter requires @aws-sdk/client-s3");
+        }
+      }
+      async presignerMod() {
+        try {
+          return await import("@aws-sdk/s3-request-presigner");
+        } catch {
+          throw new Error("S3StorageAdapter requires @aws-sdk/s3-request-presigner");
+        }
+      }
+      // ---------------------------------------------------------------------------
+      // Basic operations
+      // ---------------------------------------------------------------------------
+      async upload(key, data, options) {
+        const client = await this.getClient();
+        const s3 = await this.s3Mod();
+        const body = data instanceof Buffer ? data : await streamToBuffer(data);
+        const cmd = new s3.PutObjectCommand({
+          Bucket: this.bucket,
+          Key: key,
+          Body: body,
+          ContentType: options?.contentType,
+          Metadata: options?.metadata,
+          ACL: options?.acl === "public-read" ? "public-read" : void 0
+        });
+        await client.send(cmd);
+      }
+      async download(key) {
+        const client = await this.getClient();
+        const s3 = await this.s3Mod();
+        const cmd = new s3.GetObjectCommand({ Bucket: this.bucket, Key: key });
+        const res = await client.send(cmd);
+        return streamToBuffer(res.Body);
+      }
+      async delete(key) {
+        const client = await this.getClient();
+        const s3 = await this.s3Mod();
+        const cmd = new s3.DeleteObjectCommand({ Bucket: this.bucket, Key: key });
+        await client.send(cmd);
+      }
+      async exists(key) {
+        const client = await this.getClient();
+        const s3 = await this.s3Mod();
+        try {
+          const cmd = new s3.HeadObjectCommand({ Bucket: this.bucket, Key: key });
+          await client.send(cmd);
+          return true;
+        } catch (err) {
+          if (err.name === "NotFound" || err.$metadata?.httpStatusCode === 404) return false;
+          throw err;
+        }
+      }
+      async getInfo(key) {
+        const client = await this.getClient();
+        const s3 = await this.s3Mod();
+        const cmd = new s3.HeadObjectCommand({ Bucket: this.bucket, Key: key });
+        const res = await client.send(cmd);
+        return {
+          key,
+          size: res.ContentLength ?? 0,
+          contentType: res.ContentType,
+          lastModified: res.LastModified ?? /* @__PURE__ */ new Date(),
+          metadata: res.Metadata
+        };
+      }
+      async list(prefix) {
+        const client = await this.getClient();
+        const s3 = await this.s3Mod();
+        const cmd = new s3.ListObjectsV2Command({ Bucket: this.bucket, Prefix: prefix });
+        const res = await client.send(cmd);
+        return (res.Contents ?? []).map((item) => ({
+          key: item.Key,
+          size: item.Size ?? 0,
+          lastModified: item.LastModified ?? /* @__PURE__ */ new Date()
+        }));
+      }
+      // ---------------------------------------------------------------------------
+      // Presigned URLs
+      // ---------------------------------------------------------------------------
+      async getSignedUrl(key, expiresIn) {
+        const desc = await this.getPresignedDownload(key, expiresIn);
+        return desc.downloadUrl;
+      }
+      async getPresignedUpload(key, expiresIn, options) {
+        const client = await this.getClient();
+        const s3 = await this.s3Mod();
+        const { getSignedUrl } = await this.presignerMod();
+        const cmd = new s3.PutObjectCommand({
+          Bucket: this.bucket,
+          Key: key,
+          ContentType: options?.contentType,
+          Metadata: options?.metadata,
+          ACL: options?.acl === "public-read" ? "public-read" : void 0
+        });
+        const url = await getSignedUrl(client, cmd, { expiresIn });
+        return {
+          uploadUrl: url,
+          method: "PUT",
+          headers: options?.contentType ? { "content-type": options.contentType } : void 0,
+          expiresIn
+        };
+      }
+      async getPresignedDownload(key, expiresIn) {
+        const client = await this.getClient();
+        const s3 = await this.s3Mod();
+        const { getSignedUrl } = await this.presignerMod();
+        const cmd = new s3.GetObjectCommand({ Bucket: this.bucket, Key: key });
+        const url = await getSignedUrl(client, cmd, { expiresIn });
+        return { downloadUrl: url, expiresIn };
+      }
+      // ---------------------------------------------------------------------------
+      // Chunked / multipart upload
+      // ---------------------------------------------------------------------------
+      async initiateChunkedUpload(key, options) {
+        const client = await this.getClient();
+        const s3 = await this.s3Mod();
+        const cmd = new s3.CreateMultipartUploadCommand({
+          Bucket: this.bucket,
+          Key: key,
+          ContentType: options?.contentType,
+          Metadata: options?.metadata
+        });
+        const res = await client.send(cmd);
+        return res.UploadId;
+      }
+      async uploadChunk(uploadId, partNumber, data) {
+        const client = await this.getClient();
+        const s3 = await this.s3Mod();
+        const key = this._uploadKeys?.get(uploadId);
+        if (!key) {
+          throw new Error("S3StorageAdapter: key not found for uploadId. Call setUploadKey() before uploadChunk().");
+        }
+        const cmd = new s3.UploadPartCommand({
+          Bucket: this.bucket,
+          Key: key,
+          UploadId: uploadId,
+          PartNumber: partNumber,
+          Body: data
+        });
+        const res = await client.send(cmd);
+        return res.ETag;
+      }
+      async completeChunkedUpload(uploadId, parts) {
+        const client = await this.getClient();
+        const s3 = await this.s3Mod();
+        const key = this._uploadKeys?.get(uploadId);
+        if (!key) {
+          throw new Error("S3StorageAdapter: key not found for uploadId.");
+        }
+        const cmd = new s3.CompleteMultipartUploadCommand({
+          Bucket: this.bucket,
+          Key: key,
+          UploadId: uploadId,
+          MultipartUpload: {
+            Parts: parts.map((p) => ({ PartNumber: p.partNumber, ETag: p.eTag }))
+          }
+        });
+        await client.send(cmd);
+        this._uploadKeys?.delete(uploadId);
+        return key;
+      }
+      async abortChunkedUpload(uploadId) {
+        const client = await this.getClient();
+        const s3 = await this.s3Mod();
+        const key = this._uploadKeys?.get(uploadId);
+        if (!key) return;
+        const cmd = new s3.AbortMultipartUploadCommand({
+          Bucket: this.bucket,
+          Key: key,
+          UploadId: uploadId
+        });
+        await client.send(cmd);
+        this._uploadKeys?.delete(uploadId);
+      }
+      /**
+       * Register the storage key for a multipart upload session. Must be called
+       * by the StorageServicePlugin after `initiateChunkedUpload()` returns so
+       * that subsequent `uploadChunk` / `completeChunkedUpload` calls can resolve
+       * the S3 key without it being part of the IStorageService contract signature.
+       */
+      setUploadKey(uploadId, key) {
+        this._uploadKeys.set(uploadId, key);
+      }
+    };
+  }
+});
+
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
   LocalStorageAdapter: () => LocalStorageAdapter,
   S3StorageAdapter: () => S3StorageAdapter,
-  StorageServicePlugin: () => StorageServicePlugin
+  StorageMetadataStore: () => StorageMetadataStore,
+  StorageServicePlugin: () => StorageServicePlugin,
+  SwappableStorageService: () => SwappableStorageService,
+  SystemFile: () => SystemFile,
+  SystemUploadSession: () => SystemUploadSession,
+  registerStorageRoutes: () => registerStorageRoutes
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/local-storage-adapter.ts
 var import_node_fs = require("fs");
 var import_node_path = require("path");
+var import_node_crypto = require("crypto");
 var LocalStorageAdapter = class {
   constructor(options) {
     this.rootDir = options.rootDir;
+    this.partsDir = (0, import_node_path.join)(this.rootDir, ".parts");
+    this.baseUrl = options.baseUrl ?? "";
+    this.basePath = options.basePath ?? "/api/v1/storage";
+    this.signingSecret = options.signingSecret ?? (0, import_node_crypto.randomUUID)();
   }
+  // ---------------------------------------------------------------------------
+  // Path helpers
+  // ---------------------------------------------------------------------------
   resolvePath(key) {
+    if (key.includes("..")) {
+      throw new Error(`LocalStorageAdapter: path traversal not allowed (key="${key}")`);
+    }
     return (0, import_node_path.join)(this.rootDir, key);
   }
+  resolvePartPath(uploadId, partNumber) {
+    if (!/^[A-Za-z0-9_-]+$/.test(uploadId)) {
+      throw new Error(`LocalStorageAdapter: invalid uploadId "${uploadId}"`);
+    }
+    return (0, import_node_path.join)(this.partsDir, uploadId, String(partNumber).padStart(8, "0"));
+  }
+  // ---------------------------------------------------------------------------
+  // Basic file operations
+  // ---------------------------------------------------------------------------
   async upload(key, data, _options) {
     const filePath = this.resolvePath(key);
     await import_node_fs.promises.mkdir((0, import_node_path.dirname)(filePath), { recursive: true });
     if (data instanceof Buffer) {
       await import_node_fs.promises.writeFile(filePath, data);
-    } else {
-      const chunks = [];
-      const reader = data.getReader();
-      let done = false;
-      while (!done) {
-        const result = await reader.read();
-        done = result.done;
-        if (result.value) chunks.push(result.value);
-      }
-      await import_node_fs.promises.writeFile(filePath, Buffer.concat(chunks));
+      return;
     }
+    const chunks = [];
+    const reader = data.getReader();
+    let done = false;
+    while (!done) {
+      const result = await reader.read();
+      done = result.done;
+      if (result.value) chunks.push(result.value);
+    }
+    await import_node_fs.promises.writeFile(filePath, Buffer.concat(chunks));
   }
   async download(key) {
-    const filePath = this.resolvePath(key);
-    return import_node_fs.promises.readFile(filePath);
+    return import_node_fs.promises.readFile(this.resolvePath(key));
   }
   async delete(key) {
-    const filePath = this.resolvePath(key);
-    await import_node_fs.promises.unlink(filePath);
+    await import_node_fs.promises.unlink(this.resolvePath(key)).catch((err) => {
+      if (err && err.code === "ENOENT") return;
+      throw err;
+    });
   }
   async exists(key) {
     try {
@@ -72,11 +375,7 @@ var LocalStorageAdapter = class {
   async getInfo(key) {
     const filePath = this.resolvePath(key);
     const stat = await import_node_fs.promises.stat(filePath);
-    return {
-      key,
-      size: stat.size,
-      lastModified: stat.mtime
-    };
+    return { key, size: stat.size, lastModified: stat.mtime };
   }
   async list(prefix) {
     const dirPath = this.resolvePath(prefix);
@@ -84,10 +383,10 @@ var LocalStorageAdapter = class {
       const entries = await import_node_fs.promises.readdir(dirPath);
       const results = [];
       for (const entry of entries) {
+        if (entry.startsWith(".")) continue;
         const fullKey = prefix ? `${prefix}/${entry}` : entry;
         try {
-          const info = await this.getInfo(fullKey);
-          results.push(info);
+          results.push(await this.getInfo(fullKey));
         } catch {
         }
       }
@@ -96,74 +395,1052 @@ var LocalStorageAdapter = class {
       return [];
     }
   }
+  // ---------------------------------------------------------------------------
+  // Presigned URL helpers
+  // ---------------------------------------------------------------------------
+  /**
+   * Sign an opaque token for the given payload.
+   * Format: base64url(JSON.stringify(payload)) + '.' + base64url(HMAC)
+   */
+  signToken(payload) {
+    const b64 = Buffer.from(JSON.stringify(payload), "utf8").toString("base64url");
+    const sig = (0, import_node_crypto.createHmac)("sha256", this.signingSecret).update(b64).digest("base64url");
+    return `${b64}.${sig}`;
+  }
+  /**
+   * Verify and decode a presigned token. Throws on invalid signature or
+   * expiration.
+   */
+  verifyToken(token, expectedOp) {
+    const [b64, sig] = token.split(".");
+    if (!b64 || !sig) throw new Error("Invalid storage token format");
+    const expected = (0, import_node_crypto.createHmac)("sha256", this.signingSecret).update(b64).digest("base64url");
+    if (expected !== sig) throw new Error("Invalid storage token signature");
+    let payload;
+    try {
+      payload = JSON.parse(Buffer.from(b64, "base64url").toString("utf8"));
+    } catch {
+      throw new Error("Malformed storage token payload");
+    }
+    if (payload.op !== expectedOp) {
+      throw new Error(`Storage token op mismatch (expected="${expectedOp}", actual="${payload.op}")`);
+    }
+    if (Date.now() / 1e3 > payload.exp) {
+      throw new Error("Storage token expired");
+    }
+    return payload;
+  }
+  async getPresignedUpload(key, expiresIn, options) {
+    const exp = Math.floor(Date.now() / 1e3) + Math.max(1, expiresIn);
+    const token = this.signToken({ k: key, ct: options?.contentType, exp, op: "put" });
+    return {
+      uploadUrl: `${this.baseUrl}${this.basePath}/_local/raw/${token}`,
+      method: "PUT",
+      headers: options?.contentType ? { "content-type": options.contentType } : { "content-type": "application/octet-stream" },
+      expiresIn,
+      downloadUrl: `${this.baseUrl}${this.basePath}/_local/file/${encodeURIComponent(key)}`
+    };
+  }
+  async getPresignedDownload(key, expiresIn) {
+    const exp = Math.floor(Date.now() / 1e3) + Math.max(1, expiresIn);
+    const token = this.signToken({ k: key, exp, op: "get" });
+    return {
+      downloadUrl: `${this.baseUrl}${this.basePath}/_local/raw/${token}`,
+      expiresIn
+    };
+  }
+  async getSignedUrl(key, expiresIn) {
+    const desc = await this.getPresignedDownload(key, expiresIn);
+    return desc.downloadUrl;
+  }
+  // ---------------------------------------------------------------------------
+  // Chunked / multipart upload
+  // ---------------------------------------------------------------------------
+  async initiateChunkedUpload(key, options) {
+    const uploadId = (0, import_node_crypto.randomUUID)().replace(/-/g, "");
+    const dir = (0, import_node_path.join)(this.partsDir, uploadId);
+    await import_node_fs.promises.mkdir(dir, { recursive: true });
+    const meta = {
+      key,
+      contentType: options?.contentType,
+      metadata: options?.metadata,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    await import_node_fs.promises.writeFile((0, import_node_path.join)(dir, "_meta.json"), JSON.stringify(meta), "utf8");
+    return uploadId;
+  }
+  async uploadChunk(uploadId, partNumber, data) {
+    if (!Number.isInteger(partNumber) || partNumber < 1) {
+      throw new Error(`uploadChunk: partNumber must be a positive integer (got ${partNumber})`);
+    }
+    const partPath = this.resolvePartPath(uploadId, partNumber);
+    await import_node_fs.promises.mkdir((0, import_node_path.dirname)(partPath), { recursive: true });
+    await import_node_fs.promises.writeFile(partPath, data);
+    const { createHash } = await import("crypto");
+    return createHash("md5").update(data).digest("hex");
+  }
+  async completeChunkedUpload(uploadId, parts) {
+    const dir = (0, import_node_path.join)(this.partsDir, uploadId);
+    let meta = {};
+    try {
+      meta = JSON.parse(await import_node_fs.promises.readFile((0, import_node_path.join)(dir, "_meta.json"), "utf8"));
+    } catch {
+      throw new Error(`Upload session "${uploadId}" not found`);
+    }
+    const targetKey = meta.key;
+    if (!targetKey) {
+      throw new Error(`Upload session "${uploadId}" missing target key`);
+    }
+    const sortedParts = [...parts].sort((a, b) => a.partNumber - b.partNumber);
+    const finalPath = this.resolvePath(targetKey);
+    await import_node_fs.promises.mkdir((0, import_node_path.dirname)(finalPath), { recursive: true });
+    const out = (0, import_node_fs.createWriteStream)(finalPath);
+    try {
+      for (const p of sortedParts) {
+        const partPath = this.resolvePartPath(uploadId, p.partNumber);
+        await new Promise((resolve, reject) => {
+          const inp = (0, import_node_fs.createReadStream)(partPath);
+          inp.on("error", reject);
+          inp.on("end", () => resolve());
+          inp.pipe(out, { end: false });
+        });
+      }
+    } finally {
+      await new Promise((resolve) => out.end(() => resolve()));
+    }
+    await import_node_fs.promises.rm(dir, { recursive: true, force: true });
+    return targetKey;
+  }
+  async abortChunkedUpload(uploadId) {
+    await import_node_fs.promises.rm((0, import_node_path.join)(this.partsDir, uploadId), { recursive: true, force: true });
+  }
 };
 
 // src/storage-service-plugin.ts
-var StorageServicePlugin = class {
-  constructor(options = {}) {
-    this.name = "com.objectstack.service.storage";
-    this.version = "1.0.0";
-    this.type = "standard";
-    this.options = { adapter: "local", ...options };
+init_s3_storage_adapter();
+
+// src/metadata-store.ts
+var StorageMetadataStore = class {
+  constructor(engine) {
+    this.engine = engine;
+    this.files = /* @__PURE__ */ new Map();
+    this.sessions = /* @__PURE__ */ new Map();
   }
-  async init(ctx) {
-    const adapter = this.options.adapter;
-    if (adapter === "s3") {
-      throw new Error(
-        'S3 storage adapter is not yet implemented. Use adapter: "local" or provide a custom IStorageService via ctx.registerService("file-storage", impl).'
-      );
+  // ---------------------------------------------------------------------------
+  // Files
+  // ---------------------------------------------------------------------------
+  async createFile(rec) {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const full = { created_at: now, updated_at: now, ...rec };
+    this.files.set(full.id, full);
+    if (this.engine) {
+      try {
+        await this.engine.insert("sys_file", full);
+      } catch {
+      }
+    }
+    return full;
+  }
+  async getFile(id) {
+    if (this.engine) {
+      try {
+        const found = await this.engine.findOne("sys_file", { where: { id } });
+        if (found) return found;
+      } catch {
+      }
+    }
+    return this.files.get(id) ?? null;
+  }
+  async updateFile(id, patch) {
+    const existing = await this.getFile(id);
+    if (!existing) return null;
+    const merged = { ...existing, ...patch, id, updated_at: (/* @__PURE__ */ new Date()).toISOString() };
+    this.files.set(id, merged);
+    if (this.engine) {
+      try {
+        await this.engine.update("sys_file", merged, { where: { id } });
+      } catch {
+      }
+    }
+    return merged;
+  }
+  async deleteFile(id) {
+    this.files.delete(id);
+    if (this.engine) {
+      try {
+        await this.engine.delete("sys_file", { where: { id } });
+      } catch {
+      }
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Upload sessions
+  // ---------------------------------------------------------------------------
+  async createSession(rec) {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const full = {
+      uploaded_chunks: 0,
+      uploaded_size: 0,
+      parts: "[]",
+      started_at: now,
+      updated_at: now,
+      ...rec
+    };
+    this.sessions.set(full.id, full);
+    if (this.engine) {
+      try {
+        await this.engine.insert("sys_upload_session", full);
+      } catch {
+      }
+    }
+    return full;
+  }
+  async getSession(id) {
+    if (this.engine) {
+      try {
+        const found = await this.engine.findOne("sys_upload_session", { where: { id } });
+        if (found) return found;
+      } catch {
+      }
+    }
+    return this.sessions.get(id) ?? null;
+  }
+  async updateSession(id, patch) {
+    const existing = await this.getSession(id);
+    if (!existing) return null;
+    const merged = {
+      ...existing,
+      ...patch,
+      id,
+      updated_at: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    this.sessions.set(id, merged);
+    if (this.engine) {
+      try {
+        await this.engine.update("sys_upload_session", merged, { where: { id } });
+      } catch {
+      }
+    }
+    return merged;
+  }
+  async deleteSession(id) {
+    this.sessions.delete(id);
+    if (this.engine) {
+      try {
+        await this.engine.delete("sys_upload_session", { where: { id } });
+      } catch {
+      }
     }
-    const rootDir = this.options.local?.rootDir ?? "./storage";
-    const storage = new LocalStorageAdapter({ rootDir });
-    ctx.registerService("file-storage", storage);
-    ctx.logger.info(`StorageServicePlugin: registered local storage adapter (root: ${rootDir})`);
   }
 };
 
-// src/s3-storage-adapter.ts
-var S3StorageAdapter = class {
-  constructor(options) {
-    this.bucket = options.bucket;
-    this.region = options.region;
+// src/storage-routes.ts
+var import_node_crypto2 = require("crypto");
+function registerStorageRoutes(httpServer, storage, store, opts = {}) {
+  const basePath = opts.basePath ?? "/api/v1/storage";
+  const presignedTtl = opts.presignedTtl ?? 3600;
+  const sessionTtl = opts.sessionTtl ?? 86400;
+  httpServer.post(`${basePath}/upload/presigned`, async (req, res) => {
+    try {
+      const { filename, mimeType, size, scope, bucket } = req.body ?? {};
+      if (!filename || !mimeType || size == null) {
+        res.status(400).json({ error: "filename, mimeType, and size are required" });
+        return;
+      }
+      const fileId = (0, import_node_crypto2.randomUUID)();
+      const key = buildKey(scope ?? "user", fileId, filename);
+      await store.createFile({
+        id: fileId,
+        key,
+        name: filename,
+        mime_type: mimeType,
+        size,
+        scope: scope ?? "user",
+        bucket,
+        acl: "private",
+        status: "pending"
+      });
+      let uploadUrl;
+      let method = "PUT";
+      let headers = { "content-type": mimeType };
+      let expiresIn = presignedTtl;
+      if (storage.getPresignedUpload) {
+        const desc = await storage.getPresignedUpload(key, presignedTtl, { contentType: mimeType });
+        uploadUrl = desc.uploadUrl;
+        method = desc.method;
+        if (desc.headers) headers = desc.headers;
+        expiresIn = desc.expiresIn;
+      } else {
+        uploadUrl = `${basePath}/_local/raw/${fileId}`;
+      }
+      res.json({
+        data: {
+          uploadUrl,
+          method,
+          headers,
+          fileId,
+          expiresIn,
+          downloadUrl: `${basePath}/files/${fileId}/url`
+        }
+      });
+    } catch (err) {
+      res.status(500).json({ error: err.message ?? "Internal error" });
+    }
+  });
+  httpServer.post(`${basePath}/upload/complete`, async (req, res) => {
+    try {
+      const { fileId, eTag } = req.body ?? {};
+      if (!fileId) {
+        res.status(400).json({ error: "fileId is required" });
+        return;
+      }
+      const file = await store.getFile(fileId);
+      if (!file) {
+        res.status(404).json({ error: "File not found" });
+        return;
+      }
+      const updated = await store.updateFile(fileId, {
+        status: "committed",
+        etag: eTag ?? void 0
+      });
+      res.json({
+        data: {
+          path: updated.key,
+          name: updated.name,
+          size: updated.size ?? 0,
+          mimeType: updated.mime_type ?? "application/octet-stream",
+          lastModified: updated.updated_at ?? (/* @__PURE__ */ new Date()).toISOString(),
+          created: updated.created_at ?? (/* @__PURE__ */ new Date()).toISOString(),
+          etag: updated.etag
+        }
+      });
+    } catch (err) {
+      res.status(500).json({ error: err.message ?? "Internal error" });
+    }
+  });
+  httpServer.post(`${basePath}/upload/chunked`, async (req, res) => {
+    try {
+      const { filename, mimeType, totalSize, chunkSize: reqChunkSize, scope, bucket, metadata } = req.body ?? {};
+      if (!filename || !mimeType || !totalSize) {
+        res.status(400).json({ error: "filename, mimeType, and totalSize are required" });
+        return;
+      }
+      const chunkSize = Math.max(reqChunkSize ?? 5242880, 5242880);
+      const totalChunks = Math.ceil(totalSize / chunkSize);
+      const fileId = (0, import_node_crypto2.randomUUID)();
+      const key = buildKey(scope ?? "user", fileId, filename);
+      await store.createFile({
+        id: fileId,
+        key,
+        name: filename,
+        mime_type: mimeType,
+        size: totalSize,
+        scope: scope ?? "user",
+        bucket,
+        acl: "private",
+        status: "pending",
+        metadata: metadata ? JSON.stringify(metadata) : void 0
+      });
+      let backendUploadId;
+      if (storage.initiateChunkedUpload) {
+        backendUploadId = await storage.initiateChunkedUpload(key, { contentType: mimeType, metadata });
+        if ("setUploadKey" in storage && typeof storage.setUploadKey === "function") {
+          storage.setUploadKey(backendUploadId, key);
+        }
+      }
+      const uploadId = backendUploadId ?? (0, import_node_crypto2.randomUUID)().replace(/-/g, "");
+      const resumeToken = (0, import_node_crypto2.randomUUID)();
+      const expiresAt = new Date(Date.now() + sessionTtl * 1e3).toISOString();
+      await store.createSession({
+        id: uploadId,
+        file_id: fileId,
+        key,
+        filename,
+        mime_type: mimeType,
+        total_size: totalSize,
+        chunk_size: chunkSize,
+        total_chunks: totalChunks,
+        resume_token: resumeToken,
+        backend_upload_id: backendUploadId,
+        scope: scope ?? "user",
+        bucket,
+        metadata: metadata ? JSON.stringify(metadata) : void 0,
+        status: "in_progress",
+        expires_at: expiresAt
+      });
+      res.json({
+        data: {
+          uploadId,
+          resumeToken,
+          fileId,
+          totalChunks,
+          chunkSize,
+          expiresAt
+        }
+      });
+    } catch (err) {
+      res.status(500).json({ error: err.message ?? "Internal error" });
+    }
+  });
+  httpServer.put(`${basePath}/upload/chunked/:uploadId/chunk/:chunkIndex`, async (req, res) => {
+    try {
+      const { uploadId, chunkIndex: chunkIndexStr } = req.params;
+      const chunkIndex = parseInt(chunkIndexStr, 10);
+      if (!uploadId || isNaN(chunkIndex)) {
+        res.status(400).json({ error: "uploadId and chunkIndex are required" });
+        return;
+      }
+      const session = await store.getSession(uploadId);
+      if (!session) {
+        res.status(404).json({ error: "Upload session not found" });
+        return;
+      }
+      const token = req.headers["x-resume-token"] ?? "";
+      if (session.resume_token && token !== session.resume_token) {
+        res.status(403).json({ error: "Invalid resume token" });
+        return;
+      }
+      let data;
+      if (req.rawBody) {
+        data = await req.rawBody();
+      } else if (Buffer.isBuffer(req.body)) {
+        data = req.body;
+      } else if (req.body instanceof ArrayBuffer) {
+        data = Buffer.from(req.body);
+      } else {
+        res.status(400).json({ error: "Binary body required" });
+        return;
+      }
+      let eTag = "";
+      if (storage.uploadChunk) {
+        eTag = await storage.uploadChunk(uploadId, chunkIndex + 1, data);
+      }
+      const currentParts = JSON.parse(session.parts ?? "[]");
+      currentParts.push({ chunkIndex, eTag });
+      const uploadedChunks = (session.uploaded_chunks ?? 0) + 1;
+      const uploadedSize = (session.uploaded_size ?? 0) + data.byteLength;
+      await store.updateSession(uploadId, {
+        uploaded_chunks: uploadedChunks,
+        uploaded_size: uploadedSize,
+        parts: JSON.stringify(currentParts)
+      });
+      res.json({
+        data: {
+          chunkIndex,
+          eTag,
+          bytesReceived: data.byteLength
+        }
+      });
+    } catch (err) {
+      res.status(500).json({ error: err.message ?? "Internal error" });
+    }
+  });
+  httpServer.post(`${basePath}/upload/chunked/:uploadId/complete`, async (req, res) => {
+    try {
+      const { uploadId } = req.params;
+      const session = await store.getSession(uploadId);
+      if (!session) {
+        res.status(404).json({ error: "Upload session not found" });
+        return;
+      }
+      await store.updateSession(uploadId, { status: "completing" });
+      const partsFromBody = req.body?.parts ?? [];
+      const partsForBackend = partsFromBody.map((p) => ({
+        partNumber: p.chunkIndex + 1,
+        eTag: p.eTag
+      }));
+      let finalKey = session.key;
+      if (storage.completeChunkedUpload) {
+        finalKey = await storage.completeChunkedUpload(uploadId, partsForBackend);
+      }
+      await store.updateFile(session.file_id, { status: "committed", key: finalKey });
+      await store.updateSession(uploadId, { status: "completed" });
+      res.json({
+        data: {
+          fileId: session.file_id,
+          key: finalKey,
+          size: session.total_size,
+          mimeType: session.mime_type ?? "application/octet-stream",
+          url: `${basePath}/files/${session.file_id}/url`
+        }
+      });
+    } catch (err) {
+      res.status(500).json({ error: err.message ?? "Internal error" });
+    }
+  });
+  httpServer.get(`${basePath}/upload/chunked/:uploadId/progress`, async (req, res) => {
+    try {
+      const { uploadId } = req.params;
+      const session = await store.getSession(uploadId);
+      if (!session) {
+        res.status(404).json({ error: "Upload session not found" });
+        return;
+      }
+      const uploadedChunks = session.uploaded_chunks ?? 0;
+      const uploadedSize = session.uploaded_size ?? 0;
+      const percentComplete = session.total_size > 0 ? Math.min(100, Math.round(uploadedSize / session.total_size * 100)) : 0;
+      res.json({
+        data: {
+          uploadId: session.id,
+          fileId: session.file_id,
+          filename: session.filename,
+          totalSize: session.total_size,
+          uploadedSize,
+          totalChunks: session.total_chunks,
+          uploadedChunks,
+          percentComplete,
+          status: session.status,
+          startedAt: session.started_at,
+          expiresAt: session.expires_at
+        }
+      });
+    } catch (err) {
+      res.status(500).json({ error: err.message ?? "Internal error" });
+    }
+  });
+  httpServer.get(`${basePath}/files/:fileId/url`, async (req, res) => {
+    try {
+      const { fileId } = req.params;
+      const file = await store.getFile(fileId);
+      if (!file || file.status !== "committed") {
+        res.status(404).json({ error: "File not found or not committed" });
+        return;
+      }
+      let url;
+      if (storage.getPresignedDownload) {
+        const desc = await storage.getPresignedDownload(file.key, presignedTtl);
+        url = desc.downloadUrl;
+      } else if (storage.getSignedUrl) {
+        url = await storage.getSignedUrl(file.key, presignedTtl);
+      } else {
+        url = `${basePath}/_local/file/${encodeURIComponent(file.key)}`;
+      }
+      res.json({ url });
+    } catch (err) {
+      res.status(500).json({ error: err.message ?? "Internal error" });
+    }
+  });
+  httpServer.get(`${basePath}/files/:fileId`, async (req, res) => {
+    try {
+      const { fileId } = req.params;
+      const file = await store.getFile(fileId);
+      if (!file || file.status !== "committed") {
+        res.status(404).json({ error: "File not found or not committed" });
+        return;
+      }
+      let url;
+      if (storage.getPresignedDownload) {
+        const desc = await storage.getPresignedDownload(file.key, presignedTtl);
+        url = desc.downloadUrl;
+      } else if (storage.getSignedUrl) {
+        url = await storage.getSignedUrl(file.key, presignedTtl);
+      } else {
+        url = `${basePath}/_local/file/${encodeURIComponent(file.key)}`;
+      }
+      res.status(302).header("Location", url).send("");
+    } catch (err) {
+      res.status(500).json({ error: err.message ?? "Internal error" });
+    }
+  });
+  httpServer.put(`${basePath}/_local/raw/:token`, async (req, res) => {
+    try {
+      const { token } = req.params;
+      const localAdapter = storage;
+      if (!localAdapter.verifyToken) {
+        res.status(501).json({ error: "Presigned raw upload not supported by this adapter" });
+        return;
+      }
+      const payload = localAdapter.verifyToken(token, "put");
+      let data;
+      if (req.rawBody) {
+        data = await req.rawBody();
+      } else if (Buffer.isBuffer(req.body)) {
+        data = req.body;
+      } else {
+        res.status(400).json({ error: "Binary body required" });
+        return;
+      }
+      await storage.upload(payload.k, data, { contentType: payload.ct });
+      res.json({ ok: true, key: payload.k });
+    } catch (err) {
+      const statusCode = err.message?.includes("expired") || err.message?.includes("signature") ? 403 : 500;
+      res.status(statusCode).json({ error: err.message ?? "Upload failed" });
+    }
+  });
+  httpServer.get(`${basePath}/_local/raw/:token`, async (req, res) => {
+    try {
+      const { token } = req.params;
+      const localAdapter = storage;
+      if (!localAdapter.verifyToken) {
+        res.status(501).json({ error: "Presigned download not supported by this adapter" });
+        return;
+      }
+      const payload = localAdapter.verifyToken(token, "get");
+      const data = await storage.download(payload.k);
+      res.header("content-type", payload.ct ?? "application/octet-stream");
+      res.header("content-length", String(data.byteLength));
+      res.send(data);
+    } catch (err) {
+      const statusCode = err.message?.includes("expired") || err.message?.includes("signature") ? 403 : 500;
+      res.status(statusCode).json({ error: err.message ?? "Download failed" });
+    }
+  });
+}
+function buildKey(scope, fileId, filename) {
+  const ext = filename.includes(".") ? "." + filename.split(".").pop() : "";
+  return `${scope}/${fileId}${ext}`;
+}
+
+// src/objects/system-file.object.ts
+var import_data = require("@objectstack/spec/data");
+var SystemFile = import_data.ObjectSchema.create({
+  name: "sys_file",
+  label: "System File",
+  pluralLabel: "System Files",
+  icon: "file",
+  description: "Storage service file metadata (fileId \u2194 key mapping)",
+  titleFormat: "{name}",
+  compactLayout: ["name", "mime_type", "size", "status", "created_at"],
+  fields: {
+    id: import_data.Field.text({
+      label: "File ID",
+      required: true,
+      readonly: true
+    }),
+    key: import_data.Field.text({
+      label: "Storage Key",
+      required: true,
+      searchable: true
+    }),
+    name: import_data.Field.text({
+      label: "File Name",
+      required: true,
+      searchable: true
+    }),
+    mime_type: import_data.Field.text({
+      label: "MIME Type"
+    }),
+    size: import_data.Field.number({
+      label: "Size (bytes)"
+    }),
+    scope: import_data.Field.select({
+      label: "Scope",
+      options: [
+        { label: "User", value: "user" },
+        { label: "Tenant", value: "tenant" },
+        { label: "Public", value: "public" },
+        { label: "Private", value: "private" },
+        { label: "Temp", value: "temp" }
+      ]
+    }),
+    bucket: import_data.Field.text({
+      label: "Bucket"
+    }),
+    acl: import_data.Field.select({
+      label: "ACL",
+      options: [
+        { label: "Private", value: "private" },
+        { label: "Public Read", value: "public_read" }
+      ]
+    }),
+    status: import_data.Field.select({
+      label: "Status",
+      required: true,
+      options: [
+        { label: "Pending Upload", value: "pending" },
+        { label: "Committed", value: "committed" },
+        { label: "Deleted", value: "deleted" }
+      ]
+    }),
+    etag: import_data.Field.text({
+      label: "ETag"
+    }),
+    owner_id: import_data.Field.text({
+      label: "Owner ID"
+    }),
+    metadata: import_data.Field.text({
+      label: "Metadata (JSON)"
+    }),
+    created_at: import_data.Field.datetime({
+      label: "Created At"
+    }),
+    updated_at: import_data.Field.datetime({
+      label: "Updated At"
+    })
+  }
+});
+
+// src/objects/system-upload-session.object.ts
+var import_data2 = require("@objectstack/spec/data");
+var SystemUploadSession = import_data2.ObjectSchema.create({
+  name: "sys_upload_session",
+  label: "System Upload Session",
+  pluralLabel: "System Upload Sessions",
+  icon: "upload-cloud",
+  description: "Resumable multipart upload sessions tracked by service-storage",
+  titleFormat: "{filename}",
+  compactLayout: ["filename", "status", "uploaded_chunks", "total_chunks", "expires_at"],
+  fields: {
+    id: import_data2.Field.text({
+      label: "Upload Session ID",
+      required: true,
+      readonly: true
+    }),
+    file_id: import_data2.Field.text({
+      label: "File ID",
+      required: true
+    }),
+    key: import_data2.Field.text({
+      label: "Storage Key",
+      required: true
+    }),
+    filename: import_data2.Field.text({
+      label: "Filename",
+      required: true
+    }),
+    mime_type: import_data2.Field.text({
+      label: "MIME Type"
+    }),
+    total_size: import_data2.Field.number({
+      label: "Total Size (bytes)",
+      required: true
+    }),
+    chunk_size: import_data2.Field.number({
+      label: "Chunk Size (bytes)",
+      required: true
+    }),
+    total_chunks: import_data2.Field.number({
+      label: "Total Chunks",
+      required: true
+    }),
+    uploaded_chunks: import_data2.Field.number({
+      label: "Uploaded Chunks"
+    }),
+    uploaded_size: import_data2.Field.number({
+      label: "Uploaded Size (bytes)"
+    }),
+    parts: import_data2.Field.text({
+      label: "Uploaded Parts (JSON)"
+    }),
+    resume_token: import_data2.Field.text({
+      label: "Resume Token"
+    }),
+    backend_upload_id: import_data2.Field.text({
+      label: "Backend Upload ID"
+    }),
+    scope: import_data2.Field.text({
+      label: "Scope"
+    }),
+    bucket: import_data2.Field.text({
+      label: "Bucket"
+    }),
+    metadata: import_data2.Field.text({
+      label: "Metadata (JSON)"
+    }),
+    status: import_data2.Field.select({
+      label: "Status",
+      required: true,
+      options: [
+        { label: "In Progress", value: "in_progress" },
+        { label: "Completing", value: "completing" },
+        { label: "Completed", value: "completed" },
+        { label: "Failed", value: "failed" },
+        { label: "Expired", value: "expired" }
+      ]
+    }),
+    started_at: import_data2.Field.datetime({
+      label: "Started At"
+    }),
+    expires_at: import_data2.Field.datetime({
+      label: "Expires At"
+    }),
+    updated_at: import_data2.Field.datetime({
+      label: "Updated At"
+    })
+  }
+});
+
+// src/swappable-storage-service.ts
+var SwappableStorageService = class {
+  constructor(initial, onSwap) {
+    this.inner = initial;
+    this.onSwap = onSwap;
+  }
+  /** Replace the inner adapter. */
+  swap(next) {
+    const previous = this.inner;
+    this.inner = next;
+    this.onSwap?.(previous, next);
+  }
+  /** Expose the active inner adapter — primarily for tests. */
+  getInner() {
+    return this.inner;
   }
-  async upload(_key, _data, _options) {
-    throw new Error(`S3StorageAdapter not yet implemented (bucket: ${this.bucket}, region: ${this.region})`);
+  upload(key, data, options) {
+    return this.inner.upload(key, data, options);
   }
-  async download(_key) {
-    throw new Error("S3StorageAdapter not yet implemented");
+  download(key) {
+    return this.inner.download(key);
   }
-  async delete(_key) {
-    throw new Error("S3StorageAdapter not yet implemented");
+  delete(key) {
+    return this.inner.delete(key);
   }
-  async exists(_key) {
-    throw new Error("S3StorageAdapter not yet implemented");
+  exists(key) {
+    return this.inner.exists(key);
   }
-  async getInfo(_key) {
-    throw new Error("S3StorageAdapter not yet implemented");
+  getInfo(key) {
+    return this.inner.getInfo(key);
   }
-  async list(_prefix) {
-    throw new Error("S3StorageAdapter not yet implemented");
+  list(prefix) {
+    if (typeof this.inner.list !== "function") {
+      return Promise.reject(new Error("Active storage adapter does not support list()"));
+    }
+    return this.inner.list(prefix);
+  }
+  getSignedUrl(key, expiresIn) {
+    if (typeof this.inner.getSignedUrl !== "function") {
+      return Promise.reject(new Error("Active storage adapter does not support getSignedUrl()"));
+    }
+    return this.inner.getSignedUrl(key, expiresIn);
+  }
+  getPresignedUpload(key, expiresIn, options) {
+    if (typeof this.inner.getPresignedUpload !== "function") {
+      return Promise.reject(new Error("Active storage adapter does not support getPresignedUpload()"));
+    }
+    return this.inner.getPresignedUpload(key, expiresIn, options);
+  }
+  getPresignedDownload(key, expiresIn) {
+    if (typeof this.inner.getPresignedDownload !== "function") {
+      return Promise.reject(new Error("Active storage adapter does not support getPresignedDownload()"));
+    }
+    return this.inner.getPresignedDownload(key, expiresIn);
   }
-  async getSignedUrl(_key, _expiresIn) {
-    throw new Error("S3StorageAdapter not yet implemented");
+  initiateChunkedUpload(key, options) {
+    if (typeof this.inner.initiateChunkedUpload !== "function") {
+      return Promise.reject(new Error("Active storage adapter does not support initiateChunkedUpload()"));
+    }
+    return this.inner.initiateChunkedUpload(key, options);
   }
-  async initiateChunkedUpload(_key, _options) {
-    throw new Error("S3StorageAdapter.initiateChunkedUpload not yet implemented");
+  uploadChunk(uploadId, partNumber, data) {
+    if (typeof this.inner.uploadChunk !== "function") {
+      return Promise.reject(new Error("Active storage adapter does not support uploadChunk()"));
+    }
+    return this.inner.uploadChunk(uploadId, partNumber, data);
   }
-  async uploadChunk(_uploadId, _partNumber, _data) {
-    throw new Error("S3StorageAdapter.uploadChunk not yet implemented");
+  completeChunkedUpload(uploadId, parts) {
+    if (typeof this.inner.completeChunkedUpload !== "function") {
+      return Promise.reject(new Error("Active storage adapter does not support completeChunkedUpload()"));
+    }
+    return this.inner.completeChunkedUpload(uploadId, parts);
   }
-  async completeChunkedUpload(_uploadId, _parts) {
-    throw new Error("S3StorageAdapter.completeChunkedUpload not yet implemented");
+  abortChunkedUpload(uploadId) {
+    if (typeof this.inner.abortChunkedUpload !== "function") {
+      return Promise.reject(new Error("Active storage adapter does not support abortChunkedUpload()"));
+    }
+    return this.inner.abortChunkedUpload(uploadId);
   }
-  async abortChunkedUpload(_uploadId) {
-    throw new Error("S3StorageAdapter.abortChunkedUpload not yet implemented");
+  /**
+   * Verify a presigned HMAC token (LocalStorageAdapter-specific).
+   *
+   * `IStorageService` does not declare this method, but `storage-routes`
+   * type-narrows the active storage to `LocalStorageAdapter` to handle the
+   * `/_local/raw/:token` PUT and GET endpoints. Without a passthrough on
+   * the swappable wrapper, the route sees `verifyToken === undefined` and
+   * returns 501 even though the underlying local adapter supports it.
+   */
+  verifyToken(token, expectedOp) {
+    const inner = this.inner;
+    if (typeof inner.verifyToken !== "function") {
+      throw new Error("Active storage adapter does not support verifyToken()");
+    }
+    return inner.verifyToken(token, expectedOp);
   }
 };
+
+// src/storage-service-plugin.ts
+var StorageServicePlugin = class {
+  constructor(options = {}) {
+    this.name = "com.objectstack.service.storage";
+    this.version = "1.0.0";
+    this.type = "standard";
+    this.storage = null;
+    this.store = null;
+    this.options = { adapter: "local", ...options };
+  }
+  /** Build a concrete adapter from a values map (settings-derived). */
+  async buildAdapterFromValues(values) {
+    const adapter = String(values.adapter ?? "local");
+    if (adapter === "s3") {
+      const bucket = values.s3_bucket;
+      const region = values.s3_region;
+      if (!bucket || !region) {
+        throw new Error("StorageServicePlugin: S3 adapter requires s3_bucket and s3_region");
+      }
+      const opts = {
+        bucket,
+        region,
+        endpoint: values.s3_endpoint || void 0,
+        accessKeyId: values.s3_access_key_id || void 0,
+        secretAccessKey: values.s3_secret_access_key || void 0,
+        forcePathStyle: !!values.s3_force_path_style
+      };
+      return new S3StorageAdapter(opts);
+    }
+    const rootDir = values.local_root || "./storage";
+    return new LocalStorageAdapter({
+      basePath: this.options.basePath ?? "/api/v1/storage",
+      ...this.options.local ?? {},
+      // settings value wins over any constructor-provided local.rootDir
+      rootDir
+    });
+  }
+  async init(ctx) {
+    const adapter = this.options.adapter;
+    let initial;
+    if (adapter === "s3") {
+      const { S3StorageAdapter: S3Ctor } = await Promise.resolve().then(() => (init_s3_storage_adapter(), s3_storage_adapter_exports));
+      const s3Opts = this.options.s3;
+      if (!s3Opts) {
+        throw new Error('StorageServicePlugin: s3 options are required when adapter is "s3"');
+      }
+      initial = new S3Ctor(s3Opts);
+    } else {
+      const rootDir = this.options.local?.rootDir ?? "./storage";
+      const basePath = this.options.basePath ?? "/api/v1/storage";
+      initial = new LocalStorageAdapter({ rootDir, basePath, ...this.options.local });
+    }
+    this.storage = new SwappableStorageService(initial, (prev, next) => {
+      const prevName = prev?.constructor?.name ?? "unknown";
+      const nextName = next?.constructor?.name ?? "unknown";
+      ctx.logger.warn(
+        `StorageServicePlugin: storage adapter swapped (${prevName} \u2192 ${nextName}). Existing files were NOT migrated and may be unreachable through the new adapter.`
+      );
+    });
+    ctx.registerService("file-storage", this.storage);
+    ctx.logger.info(`StorageServicePlugin: registered ${adapter} storage adapter (swappable)`);
+    try {
+      ctx.getService("manifest").register({
+        id: "com.objectstack.service.storage",
+        name: "Storage Service",
+        version: "1.0.0",
+        type: "plugin",
+        scope: "project",
+        objects: [SystemFile, SystemUploadSession]
+      });
+    } catch {
+    }
+  }
+  async start(ctx) {
+    ctx.hook("kernel:ready", async () => {
+      if (this.options.registerRoutes !== false) {
+        let httpServer = null;
+        try {
+          httpServer = ctx.getService("http-server");
+        } catch {
+        }
+        if (httpServer && this.storage) {
+          let engine = null;
+          try {
+            engine = ctx.getService("objectql");
+          } catch {
+          }
+          this.store = new StorageMetadataStore(engine);
+          registerStorageRoutes(httpServer, this.storage, this.store, {
+            basePath: this.options.basePath ?? "/api/v1/storage",
+            presignedTtl: this.options.presignedTtl,
+            sessionTtl: this.options.sessionTtl
+          });
+          ctx.logger.info(
+            "StorageServicePlugin: REST routes registered at " + (this.options.basePath ?? "/api/v1/storage")
+          );
+        } else if (!httpServer) {
+          ctx.logger.warn(
+            'StorageServicePlugin: no HTTP server available \u2014 REST routes not registered. File storage is still accessible programmatically via kernel.getService("file-storage").'
+          );
+        }
+      }
+      if (this.options.bindToSettings === false) return;
+      try {
+        const settings = ctx.getService("settings");
+        if (!settings || typeof settings.createClient !== "function") return;
+        const applySettings = async () => {
+          if (!this.storage) return;
+          try {
+            const payload = await settings.getNamespace("storage");
+            const values = {};
+            for (const [k, v] of Object.entries(payload.values)) {
+              values[k] = v?.value;
+            }
+            const hasAny = Object.values(values).some((v) => v !== void 0 && v !== null && v !== "");
+            if (!hasAny) return;
+            const next = await this.buildAdapterFromValues(values);
+            this.storage.swap(next);
+          } catch (err) {
+            ctx.logger.warn(
+              "StorageServicePlugin: failed to apply storage settings: " + (err?.message ?? err)
+            );
+          }
+        };
+        await applySettings();
+        if (typeof settings.subscribe === "function") {
+          settings.subscribe("storage", () => {
+            void applySettings();
+          });
+          ctx.logger.info("StorageServicePlugin: bound to settings:changed for namespace=storage");
+        }
+        if (typeof settings.registerAction === "function" && this.storage) {
+          const proxy = this.storage;
+          settings.registerAction("storage", "test", async ({ values }) => {
+            const probeKey = `__objectstack_probe__/${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+            const probeBytes = Buffer.from(`probe@${(/* @__PURE__ */ new Date()).toISOString()}`, "utf-8");
+            try {
+              let target = proxy;
+              if (values && Object.keys(values).length > 0) {
+                try {
+                  target = await this.buildAdapterFromValues(values);
+                } catch (err) {
+                  return { ok: false, severity: "error", message: err?.message ?? String(err) };
+                }
+              }
+              await target.upload(probeKey, probeBytes, { contentType: "text/plain" });
+              const got = await target.download(probeKey);
+              if (!got || !Buffer.isBuffer(got) || got.toString("utf-8") !== probeBytes.toString("utf-8")) {
+                return { ok: false, severity: "error", message: "Probe download did not match upload." };
+              }
+              await target.delete(probeKey);
+              const adapter = String(values?.adapter ?? this.options.adapter ?? "local");
+              return {
+                ok: true,
+                severity: "info",
+                message: `Storage round-trip succeeded (adapter=${adapter}).`
+              };
+            } catch (err) {
+              try {
+                await proxy.delete(probeKey);
+              } catch {
+              }
+              return { ok: false, severity: "error", message: err?.message ?? String(err) };
+            }
+          });
+          ctx.logger.info("StorageServicePlugin: registered settings action storage/test");
+        }
+      } catch {
+      }
+    });
+  }
+};
+
+// src/index.ts
+init_s3_storage_adapter();
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   LocalStorageAdapter,
   S3StorageAdapter,
-  StorageServicePlugin
+  StorageMetadataStore,
+  StorageServicePlugin,
+  SwappableStorageService,
+  SystemFile,
+  SystemUploadSession,
+  registerStorageRoutes
 });
 //# sourceMappingURL=index.cjs.map