@blamejs/core 0.14.27 → 0.15.1

package/lib/migrations.js

@@ -41,10 +41,13 @@
 var nodePath = require("node:path");
 var atomicFile = require("./atomic-file");
 var dbSchema = require("./db-schema");
+var frameworkSchema = require("./framework-schema");
 var lazyRequire = require("./lazy-require");
 var { boot } = require("./log");
 var migrationFiles = require("./migration-files");
 var numericBounds = require("./numeric-bounds");
+var safeSql = require("./safe-sql");
+var sql = require("./sql");
 var db = lazyRequire(function () { return require("./db"); });
 var validateOpts = require("./validate-opts");
 var { FrameworkError } = require("./framework-error");
@@ -60,11 +63,29 @@ class MigrationError extends FrameworkError {
   }
 }
 
-var MIGRATIONS_TABLE = "_blamejs_migrations";
-// Always interpolate identifiers wrapped in `"..."` so a reserved-word
-// or whitespace-bearing name resolves correctly (defense-in-depth even
-// though our constant is bare-identifier-shaped).
-var Q_MIGRATIONS_TABLE = '"' + MIGRATIONS_TABLE + '"';
+// Logical names; the physical names resolve through
+// frameworkSchema.tableName so a configured table prefix flows here too.
+// SQL is composed with b.sql (quoteName: true) so the resolved name is
+// quoted by construction — a reserved-word / whitespace-bearing name
+// still emits a valid `"..."` identifier.
+var MIGRATIONS_TABLE = "_blamejs_migrations";  // allow:hand-rolled-sql — logical name declaration; physical name + prefix resolve via frameworkSchema.tableName below
+function _migrationsTable() { return frameworkSchema.tableName(MIGRATIONS_TABLE); }
+// b.sql opts for the migration bookkeeping statements. db.prepare /
+// runSqlOnHandle run these directly against the handle (never
+// clusterStorage), so the dialect must match the handle: db.from()'s local
+// node:sqlite default, or an operator's own Postgres / MySQL handle (which
+// declares `handle.dialect`). The handle-dialect / opts / key-text-type
+// resolution is shared with db-schema's reconciler + seeders.js, so it is
+// composed from db-schema rather than re-derived here. The historical
+// default (sqlite) is byte-identical for every existing local-handle caller.
+var _handleDialect = dbSchema.handleDialect;
+var _sqlOpts = dbSchema.sqlOpts;
+var _keyTextType = dbSchema.keyTextType;
+// A ms-epoch column type. Date.now() exceeds a 32-bit INTEGER, so the
+// lock timestamp needs a 64-bit type on Postgres + MySQL (BIGINT) — b.sql's
+// logical "int" resolves to BIGINT on both and INTEGER on SQLite, so passing
+// the logical name through the handle dialect is enough.
+var _MS_EPOCH_TYPE = "int";
 // Filename grammar: leading numeric prefix (any width), then '-', then a
 // non-empty body, then '.js'. Numeric prefix orders execution. Letters
 // in the body include hyphens, underscores, and alphanumerics; anything
@@ -87,31 +108,36 @@ function _isMigrationFile(name) {
 var _runSql = dbSchema.runSqlOnHandle;
 
 function _ensureTable(db) {
-  _runSql(db,
-    "CREATE TABLE IF NOT EXISTS " + Q_MIGRATIONS_TABLE + " (" +
-    "  name        TEXT PRIMARY KEY," +
-    "  description TEXT," +
-    "  appliedAt   TEXT NOT NULL" +
-    ")"
-  );
+  _runSql(db, sql.createTable(_migrationsTable(), [
+    { name: "name",        type: _keyTextType(db), primaryKey: true },
+    { name: "description", type: "text" },
+    { name: "appliedAt",   type: "text", notNull: true },
+  ], _sqlOpts(db)).sql);
 }
 
 // Single-row advisory-lock table. Two processes running `migrate up`
 // concurrently against the same DB race on this table: the winner of
 // the INSERT acquires the lock; the loser sees a UNIQUE violation and
 // the operator gets a clear "lock held by other process" error.
-var LOCK_TABLE   = "_blamejs_migrations_lock";
-var Q_LOCK_TABLE = '"' + LOCK_TABLE + '"';
+var LOCK_TABLE = "_blamejs_migrations_lock";  // allow:hand-rolled-sql — logical name declaration; physical name + prefix resolve via frameworkSchema.tableName below
+function _lockTable() { return frameworkSchema.tableName(LOCK_TABLE); }
 
 function _ensureLockTable(db) {
-  _runSql(db,
-    "CREATE TABLE IF NOT EXISTS " + Q_LOCK_TABLE + " (" +
-    "  scope     TEXT PRIMARY KEY," +
-    "  lockedAt  INTEGER NOT NULL," +
-    "  lockedBy  TEXT NOT NULL," +
-    "  CHECK (scope = 'lock')" +
-    ")"
-  );
+  // The single-row invariant (CHECK scope = 'lock') is a static,
+  // framework-controlled column constraint — b.sql guards the verbatim
+  // fragment (allowLiterals) and quotes the column by construction. The
+  // CHECK references `scope` with the handle's identifier quoting (backtick
+  // on mysql) so the constraint parses on every dialect. lockedAt is an
+  // ms-epoch value (`int` → BIGINT on Postgres/MySQL, INTEGER on SQLite);
+  // a 32-bit INTEGER would overflow Date.now() and make the lock
+  // unacquirable on Postgres.
+  var dialect = _handleDialect(db);
+  var scopeCheck = "CHECK (" + safeSql.quoteIdentifier("scope", dialect, { allowReserved: true }) + " = 'lock')";
+  _runSql(db, sql.createTable(_lockTable(), [
+    { name: "scope",    type: _keyTextType(db), primaryKey: true, constraints: scopeCheck },
+    { name: "lockedAt", type: _MS_EPOCH_TYPE,   notNull: true },
+    { name: "lockedBy", type: "text",           notNull: true },
+  ], _sqlOpts(db)).sql);
 }
 
 function _lockHolderId() {
@@ -139,23 +165,24 @@ function _acquireLock(db, opts) {
   } else {
     staleAfterMs = opts.staleAfterMs;
   }
+  var insertLock = sql.insert(_lockTable(), _sqlOpts(db))
+    .values({ scope: "lock", lockedAt: nowMs, lockedBy: holder }).toSql();
   // Try to insert; if there's a stale lock, optionally force-replace it.
   try {
-    db.prepare(
-      "INSERT INTO " + Q_LOCK_TABLE + " (scope, lockedAt, lockedBy) VALUES ('lock', ?, ?)"
-    ).run(nowMs, holder);
+    var insStmt = db.prepare(insertLock.sql);
+    insStmt.run.apply(insStmt, insertLock.params);
     return holder;
   } catch {
     // PRIMARY KEY conflict → existing lock. Inspect it.
-    var existing = db.prepare(
-      "SELECT lockedAt, lockedBy FROM " + Q_LOCK_TABLE + " WHERE scope = 'lock'"
-    ).get();
+    var selExisting = sql.select(_lockTable(), _sqlOpts(db))
+      .columns(["lockedAt", "lockedBy"]).where("scope", "lock").toSql();
+    var selStmt = db.prepare(selExisting.sql);
+    var existing = selStmt.get.apply(selStmt, selExisting.params);
     if (!existing) {
       // Race window between INSERT failure and SELECT — try once more.
       try {
-        db.prepare(
-          "INSERT INTO " + Q_LOCK_TABLE + " (scope, lockedAt, lockedBy) VALUES ('lock', ?, ?)"
-        ).run(nowMs, holder);
+        var retryStmt = db.prepare(insertLock.sql);
+        retryStmt.run.apply(retryStmt, insertLock.params);
         return holder;
       } catch (e2) {
         throw new MigrationError("migrations/lock-busy",
@@ -165,25 +192,32 @@ function _acquireLock(db, opts) {
     }
     var ageMs = nowMs - Number(existing.lockedAt);
     if (staleAfterMs > 0 && ageMs > staleAfterMs) {
-      // Force-replace the stale lock. Requires DELETE + INSERT in a
-      // single transaction so the next process can't slip in between.
-      _runSql(db, "BEGIN IMMEDIATE");
+      // Force-replace the stale lock. The DELETE + INSERT run in a single
+      // transaction so the next process can't slip in between. The
+      // transaction boundary is dialect-aware: only SQLite has the
+      // `BEGIN IMMEDIATE` write-lock-up-front form — Postgres + MySQL
+      // reject the `IMMEDIATE` keyword, so the shared runInTransaction
+      // helper emits a plain portable `BEGIN`/`COMMIT`/`ROLLBACK` there.
+      var lockMode = _handleDialect(db) === "sqlite" ? "IMMEDIATE" : null;
       try {
-        db.prepare("DELETE FROM " + Q_LOCK_TABLE + " WHERE scope = 'lock' AND lockedAt = ?")
-          .run(existing.lockedAt);
-        db.prepare(
-          "INSERT INTO " + Q_LOCK_TABLE + " (scope, lockedAt, lockedBy) VALUES ('lock', ?, ?)"
-        ).run(nowMs, holder);
-        _runSql(db, "COMMIT");
-        return holder;
+        return dbSchema.runInTransaction(db, function () {
+          var delStale = sql.delete(_lockTable(), _sqlOpts(db))
+            .where("scope", "lock").where("lockedAt", existing.lockedAt).toSql();
+          var delStaleStmt = db.prepare(delStale.sql);
+          delStaleStmt.run.apply(delStaleStmt, delStale.params);
+          var replStmt = db.prepare(insertLock.sql);
+          replStmt.run.apply(replStmt, insertLock.params);
+          return holder;
+        }, {
+          lockMode: lockMode,
+          onRollbackFail: function (rollbackErr) {
+            log.debug("rollback-failed", {
+              op: "lock-stale-replace",
+              error: rollbackErr && rollbackErr.message,
+            });
+          },
+        });
       } catch (forceErr) {
-        try { _runSql(db, "ROLLBACK"); }
-        catch (rollbackErr) {
-          log.debug("rollback-failed", {
-            op: "lock-stale-replace",
-            error: rollbackErr && rollbackErr.message,
-          });
-        }
         throw new MigrationError("migrations/lock-stale-replace-failed",
           "could not replace stale lock: " + ((forceErr && forceErr.message) || String(forceErr)),
           true);
@@ -202,9 +236,10 @@ function _releaseLock(db, holder) {
   // shouldn't have its lock cleared by an unrelated next deploy unless
   // the operator explicitly used the staleAfterMs nodePath.
   try {
-    db.prepare(
-      "DELETE FROM " + Q_LOCK_TABLE + " WHERE scope = 'lock' AND lockedBy = ?"
-    ).run(holder);
+    var rel = sql.delete(_lockTable(), _sqlOpts(db))
+      .where("scope", "lock").where("lockedBy", holder).toSql();
+    var relStmt = db.prepare(rel.sql);
+    relStmt.run.apply(relStmt, rel.params);
   } catch (_e) { /* best-effort release; operator can DELETE manually */ }
 }
 
@@ -271,10 +306,11 @@ function create(opts) {
   function _appliedRows() {
     var db = _resolveDb(opts);
     _ensureTable(db);
-    return db.prepare(
-      "SELECT name, description, appliedAt FROM " + Q_MIGRATIONS_TABLE +
-      " ORDER BY appliedAt ASC, name ASC"
-    ).all();
+    var q = sql.select(_migrationsTable(), _sqlOpts(db))
+      .columns(["name", "description", "appliedAt"])
+      .orderBy("appliedAt", "asc").orderBy("name", "asc").toSql();
+    var stmt = db.prepare(q.sql);
+    return stmt.all.apply(stmt, q.params);
   }
 
   function status() {
@@ -293,8 +329,10 @@ function create(opts) {
     var db = _resolveDb(opts);
     _ensureTable(db);
     return _withLock(db, opts, function () {
+      var namesQ = sql.select(_migrationsTable(), _sqlOpts(db)).columns(["name"]).toSql();
+      var namesStmt = db.prepare(namesQ.sql);
       var appliedSet = new Set(
-        db.prepare("SELECT name FROM " + Q_MIGRATIONS_TABLE).all()
+        namesStmt.all.apply(namesStmt, namesQ.params)
           .map(function (r) { return r.name; })
       );
       var files = _list(dir);
@@ -307,10 +345,11 @@ function create(opts) {
         try {
           _txn(db, function () {
             mod.up(db);
-            db.prepare(
-              "INSERT INTO " + Q_MIGRATIONS_TABLE +
-              " (name, description, appliedAt) VALUES (?, ?, ?)"
-            ).run(file, mod.description || "", new Date().toISOString());
+            var insQ = sql.insert(_migrationsTable(), _sqlOpts(db))
+              .values({ name: file, description: mod.description || "",
+                        appliedAt: new Date().toISOString() }).toSql();
+            var insStmt = db.prepare(insQ.sql);
+            insStmt.run.apply(insStmt, insQ.params);
           });
         } catch (e) {
           throw new MigrationError("migrations/up-failed",
@@ -336,11 +375,12 @@ function create(opts) {
     return _withLock(db, opts, function () {
       // Most-recent applied first (reverse chronological by appliedAt
       // then by name as a stable tiebreaker for fixtures with identical
-      // timestamps).
-      var rows = db.prepare(
-        "SELECT name FROM " + Q_MIGRATIONS_TABLE +
-        " ORDER BY appliedAt DESC, name DESC LIMIT ?"
-      ).all(steps);
+      // timestamps). steps is a validated positive integer, so b.sql
+      // inlines the LIMIT.
+      var downQ = sql.select(_migrationsTable(), _sqlOpts(db)).columns(["name"])
+        .orderBy("appliedAt", "desc").orderBy("name", "desc").limit(steps).toSql();
+      var downStmt = db.prepare(downQ.sql);
+      var rows = downStmt.all.apply(downStmt, downQ.params);
 
       var reverted = [];
       for (var i = 0; i < rows.length; i++) {
@@ -355,7 +395,9 @@ function create(opts) {
         try {
           _txn(db, function () {
             mod.down(db);
-            db.prepare("DELETE FROM " + Q_MIGRATIONS_TABLE + " WHERE name = ?").run(file);
+            var delQ = sql.delete(_migrationsTable(), _sqlOpts(db)).where("name", file).toSql();
+            var delStmt = db.prepare(delQ.sql);
+            delStmt.run.apply(delStmt, delQ.params);
           });
         } catch (e) {
           throw new MigrationError("migrations/down-failed",

package/lib/network-heartbeat.js

@@ -72,6 +72,13 @@ function _probeHttp(target, timeoutMs) {
         url:        target.url,
         method:     target.method || "GET",
         timeoutMs:  timeoutMs,
+        // Forward the target's protocol/host allowlists so an operator who
+        // opts a cleartext http:// heartbeat in (allowedProtocols:
+        // b.safeUrl.ALLOW_HTTP_ALL) is honoured. Left undefined, httpClient
+        // applies its https-only default (ALLOW_HTTP_TLS) — so an http://
+        // target with no opt-in is still rejected, not silently probed.
+        allowedProtocols: target.allowedProtocols,
+        allowedHosts:     target.allowedHosts,
         allowInternal: target.allowInternal === true ? true : target.allowInternal,
       });
       p.then(function (res) {

package/lib/nonce-store.js

@@ -43,10 +43,30 @@
 
 var clusterStorage = require("./cluster-storage");
 var C = require("./constants");
+var frameworkSchema = require("./framework-schema");
 var safeAsync = require("./safe-async");
+var sql = require("./sql");
 var { defineClass } = require("./framework-error");
 var { boundedMap } = require("./bounded-map");
 
+// Cluster-backend table — resolved through frameworkSchema.tableName so a
+// configured table prefix (b.frameworkSchema.setTablePrefix) is honored.
+// The name is identity-mapped in LOCAL_TO_EXTERNAL, so clusterStorage's
+// resolveTables leaves it untouched at dispatch and the resolved name is
+// what reaches the backend on both sides.
+var NONCE_TABLE = "_blamejs_api_encrypt_nonces";   // allow:hand-rolled-sql — canonical logical table-name declaration
+
+// b.sql opts for every cluster-backend statement: thread the ACTIVE backend
+// dialect (clusterStorage.dialect() — "sqlite" single-node, "postgres" |
+// "mysql" in cluster mode) so the emitted identifier quoting and dialect
+// idioms (ON CONFLICT vs ON DUPLICATE KEY) match the backend the SQL
+// dispatches to. Defaulting to "sqlite" works on Postgres only by accident
+// (both double-quote identifiers) and emits invalid quoting + ON CONFLICT on
+// MySQL. clusterStorage.execute still rewrites table names + translates `?`
+// placeholders at dispatch; this controls only the builder-side quoting +
+// idiom selection.
+function _nonceSqlOpts() { return { dialect: clusterStorage.dialect() }; }
+
 var NonceStoreError = defineClass("NonceStoreError");
 
 var DEFAULT_SWEEP_INTERVAL_MS = C.TIME.minutes(5);
@@ -148,19 +168,21 @@ function _clusterBackend(_opts) {
     // (someone else already inserted the same nonce, i.e. replay).
     // The middleware hashes the raw nonce before passing it here so
     // the table only ever sees hashes, not the originals.
-    var result = await clusterStorage.execute(
-      "INSERT INTO _blamejs_api_encrypt_nonces (nonceHash, expireAt) " +
-      "VALUES (?, ?) ON CONFLICT (nonceHash) DO NOTHING",
-      [nonce, expireAt]
-    );
+    var built = sql.upsert(frameworkSchema.tableName(NONCE_TABLE), _nonceSqlOpts())
+      .columns(["nonceHash", "expireAt"])
+      .values({ nonceHash: nonce, expireAt: expireAt })
+      .onConflict(["nonceHash"])
+      .doNothing()
+      .toSql();
+    var result = await clusterStorage.execute(built.sql, built.params);
     return (result && result.rowCount > 0);
   }
 
   async function purgeExpired() {
-    var result = await clusterStorage.execute(
-      "DELETE FROM _blamejs_api_encrypt_nonces WHERE expireAt <= ?",
-      [Date.now()]
-    );
+    var built = sql.delete(frameworkSchema.tableName(NONCE_TABLE), _nonceSqlOpts())
+      .where("expireAt", "<=", Date.now())
+      .toSql();
+    var result = await clusterStorage.execute(built.sql, built.params);
     return (result && result.rowCount) || 0;
   }
 

package/lib/object-store/azure-blob-bucket-ops.js

@@ -214,6 +214,11 @@ function create(config) {
   var timeoutMs = config.timeoutMs;
   var allowedProtocols = config.allowedProtocols || safeUrl.ALLOW_HTTP_TLS;
   var allowInternal = config.allowInternal != null ? config.allowInternal : null;
+  // Account placement — see azure-blob.js create(). Default host-based; opt
+  // into path-style (Azurite / Azure Stack / private) with config.pathStyle:
+  // true. Default false keeps the host-based wire shape unchanged.
+  var pathStyle = config.pathStyle === true;
+  var pathPrefix = pathStyle ? ("/" + config.accountName) : "";
 
   function _sign(method, url, headers) {
     return azureBlob.signRequest({
@@ -260,7 +265,7 @@ function create(config) {
   async function createContainer(name, opts) {
     _validateContainerName(name);
     opts = opts || {};
-    var url = _internalUrl(endpoint + "/" + name + "?restype=container", allowedProtocols);
+    var url = _internalUrl(endpoint + pathPrefix + "/" + name + "?restype=container", allowedProtocols);
     var headers = { "Content-Length": "0" };
     if (opts.publicAccess) {
       if (opts.publicAccess !== "blob" && opts.publicAccess !== "container") {
@@ -282,7 +287,7 @@ function create(config) {
 
   async function deleteContainer(name) {
     _validateContainerName(name);
-    var url = _internalUrl(endpoint + "/" + name + "?restype=container", allowedProtocols);
+    var url = _internalUrl(endpoint + pathPrefix + "/" + name + "?restype=container", allowedProtocols);
     var signed = _sign("DELETE", url, {});
     var res = await _request("DELETE", url, signed, null, [HTTP_ACCEPTED, HTTP_NOT_FOUND]);
     return res.statusCode === HTTP_ACCEPTED;
@@ -290,7 +295,7 @@ function create(config) {
 
   async function listContainers(opts) {
     opts = opts || {};
-    var url = _internalUrl(endpoint + "/?comp=list", allowedProtocols);
+    var url = _internalUrl(endpoint + pathPrefix + "/?comp=list", allowedProtocols);
     if (opts.prefix)  url.searchParams.set("prefix", opts.prefix);
     if (opts.maxResults != null) url.searchParams.set("maxresults", String(opts.maxResults));
     var signed = _sign("GET", url, {});
@@ -319,7 +324,7 @@ function create(config) {
     rules.forEach(_validateCorsRule);
     var xml = _buildCorsXml(rules);
     var bodyBuf = Buffer.from(xml, "utf8");
-    var url = _internalUrl(endpoint + "/?restype=service&comp=properties", allowedProtocols);
+    var url = _internalUrl(endpoint + pathPrefix + "/?restype=service&comp=properties", allowedProtocols);
     var headers = {
       "Content-Type":   "application/xml",
       "Content-Length": String(bodyBuf.length),

package/lib/object-store/azure-blob.js

@@ -15,6 +15,11 @@
  *     accountKey:   '<base64 storage key>'    // required (REST shared key)
  *     container:    'my-container'            // required
  *     endpoint:     'https://...'             // optional override
+ *     pathStyle:    true                       // optional; account as the first
+ *                                              // URL path segment (Azurite / Azure
+ *                                              // Stack / private endpoints).
+ *                                              // Default false = host-based
+ *                                              // (<account>.blob.core.windows.net).
  *     apiVersion:   '2024-08-04'              // x-ms-version header
  *     timeoutMs:    C.TIME.seconds(30)
  *   }
@@ -141,6 +146,17 @@ function buildStringToSign(opts) {
   var canonicalResource = (function () {
     // /<account>/<rest of path>
     // Plus sorted query params, each "name:value\n"
+    // Canonicalized resource per the Shared Key spec: "/" + account + the
+    // request's absolute path + sorted query. Host-based endpoints
+    // (production <account>.blob.core.windows.net) have url.pathname
+    // "/<container>/<blob>", giving "/<account>/<container>/<blob>".
+    // Path-style endpoints (Azurite / Azure Stack / private) already carry
+    // "/<account>" as the first path segment, so the account appears twice
+    // ("/<account>/<account>/<container>/<blob>") — which is exactly what a
+    // path-style server expects: it prepends the account to the full request
+    // path it received. Verified against Azurite — the doubled form is the
+    // one that authenticates; the URL itself must carry the account in its
+    // path (see pathPrefix in create()).
     var resourcePath = "/" + opts.accountName + url.pathname;
     var paramPairs = [];
     url.searchParams.forEach(function (v, k) {
@@ -225,11 +241,23 @@ function create(config) {
   var allowedProtocols = config.allowedProtocols || safeUrl.ALLOW_HTTP_TLS;
   var allowInternal    = config.allowInternal != null ? config.allowInternal : null;
   safeUrl.parse(endpoint, { allowedProtocols: allowedProtocols, errorClass: ObjectStoreError });
+  // Account placement. Default host-based — production Azure is
+  // https://<account>.blob.core.windows.net/<container>/<blob> (account in the
+  // host). Path-style endpoints (Azurite / Azure Stack / private) carry the
+  // account as the first PATH segment instead —
+  // https://<host>/<account>/<container>/<blob> — opt in with
+  // config.pathStyle:true. Default false keeps the host-based wire shape
+  // unchanged for existing deployments (no silent breaking change). The signed
+  // canonicalized resource is always "/" + account + url.pathname, so for a
+  // path-style URL the account appears twice — which is exactly what a
+  // path-style server expects (see buildStringToSign).
+  var pathStyle = config.pathStyle === true;
+  var pathPrefix = pathStyle ? ("/" + config.accountName) : "";
   var reqOpts = { timeoutMs: timeoutMs, allowedProtocols: allowedProtocols };
   if (allowInternal !== null) reqOpts.allowInternal = allowInternal;
 
   function _blobUrl(key, params) {
-    var u = _internalUrl(endpoint + "/" + config.container + "/" + _encodeBlobKey(key),
+    var u = _internalUrl(endpoint + pathPrefix + "/" + config.container + "/" + _encodeBlobKey(key),
                          allowedProtocols);
     if (params) {
       Object.keys(params).forEach(function (k) { u.searchParams.set(k, params[k]); });
@@ -238,7 +266,7 @@ function create(config) {
   }
 
   function _containerUrl(params) {
-    var u = _internalUrl(endpoint + "/" + config.container, allowedProtocols);
+    var u = _internalUrl(endpoint + pathPrefix + "/" + config.container, allowedProtocols);
     if (params) {
       Object.keys(params).forEach(function (k) { u.searchParams.set(k, params[k]); });
     }
@@ -452,7 +480,7 @@ function create(config) {
     // percent-encoded key so a key with reserved chars (`?` / `#` / space)
     // doesn't truncate the path or corrupt the request line.
     var token = _buildSasToken(permissions, opts);
-    var url = _internalUrl(endpoint + "/" + config.container + "/" + _encodeBlobKey(opts.key) + "?" + token.sas, allowedProtocols);
+    var url = _internalUrl(endpoint + pathPrefix + "/" + config.container + "/" + _encodeBlobKey(opts.key) + "?" + token.sas, allowedProtocols);
 
     var clientHeaders = {};
     if (opts.contentType) clientHeaders["Content-Type"] = opts.contentType;

package/lib/object-store/sigv4.js

@@ -661,6 +661,16 @@ function create(config) {
         etag:         res.headers.etag,
         lastModified: res.headers["last-modified"] ? Date.parse(res.headers["last-modified"]) : null,
       };
+    }, function (e) {
+      // A missing key surfaces as the framework NOT_FOUND code — the same
+      // contract local.js head() exposes and that deleteKey already maps 404
+      // to — so existence probes via head() (e.g. the backup objectStore
+      // adapter's hasKey / statKey) get the uniform missing-key signal instead
+      // of a raw HTTP 404 they don't recognize.
+      if (e && e.statusCode === 404) {
+        throw _err("NOT_FOUND", "key not found: " + key, true);
+      }
+      throw e;
     });
   }