@nifrajs/storage 2.2.0 → 2.3.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * @nifrajs/storage — one blob-storage interface, several adapters. The persistence half of
+ * @nifrajs/storage - one blob-storage interface, several adapters. The persistence half of
  * `@nifrajs/uploads`: `uploads` validates + signs, `storage` puts the bytes somewhere. Adapters cover
  * dev (memory), a long-running server (local disk), and the edge (Cloudflare R2); implement
  * {@link StorageAdapter} for S3/GCS/etc. Dependency-free.
@@ -9,6 +9,7 @@
  *   await storage.put("avatars/u1.png", bytes, { contentType: "image/png" })
  *   const object = await storage.get("avatars/u1.png")
  */
+export { type BeaconingStorageAdapter, type CapabilityBeacon, type StorageBeaconOptions, type StorageCapabilities, withCapabilityBeacon, } from "./capabilities.js";
 export { assertStorageAdapterConformance, StorageAdapterConformanceError, type StorageAdapterConformanceOptions, } from "./conformance.js";
 export { FileStorage } from "./file.js";
 export { assertSafeKey, StorageKeyError } from "./key.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EACL,+BAA+B,EAC/B,8BAA8B,EAC9B,KAAK,gCAAgC,GACtC,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AACvC,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AACzE,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,EAC9B,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,EAC1B,OAAO,GACR,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,oBAAoB,GACrB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EACL,+BAA+B,EAC/B,8BAA8B,EAC9B,KAAK,gCAAgC,GACtC,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AACvC,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AACzE,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,EAC9B,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,EAC1B,OAAO,GACR,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -1,5 +1,5 @@
 /**
- * @nifrajs/storage — one blob-storage interface, several adapters. The persistence half of
+ * @nifrajs/storage - one blob-storage interface, several adapters. The persistence half of
  * `@nifrajs/uploads`: `uploads` validates + signs, `storage` puts the bytes somewhere. Adapters cover
  * dev (memory), a long-running server (local disk), and the edge (Cloudflare R2); implement
  * {@link StorageAdapter} for S3/GCS/etc. Dependency-free.
@@ -9,6 +9,7 @@
  *   await storage.put("avatars/u1.png", bytes, { contentType: "image/png" })
  *   const object = await storage.get("avatars/u1.png")
  */
+export { withCapabilityBeacon, } from "./capabilities.js";
 export { assertStorageAdapterConformance, StorageAdapterConformanceError, } from "./conformance.js";
 export { FileStorage } from "./file.js";
 export { assertSafeKey, StorageKeyError } from "./key.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EACL,+BAA+B,EAC/B,8BAA8B,GAE/B,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AACvC,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,EAAwC,SAAS,EAAE,MAAM,SAAS,CAAA;AACzE,OAAO,EAcL,OAAO,GACR,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAKL,oBAAoB,GACrB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EACL,+BAA+B,EAC/B,8BAA8B,GAE/B,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AACvC,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,EAAwC,SAAS,EAAE,MAAM,SAAS,CAAA;AACzE,OAAO,EAcL,OAAO,GACR,MAAM,YAAY,CAAA"}

package/dist/key.d.ts

@@ -1,6 +1,6 @@
 /**
  * Storage-key safety. A key is a POSIX-ish relative path (`avatars/u1.png`); we reject anything that
- * could escape a `FileStorage` root or otherwise misbehave — absolute paths, `..` traversal, NUL bytes,
+ * could escape a `FileStorage` root or otherwise misbehave - absolute paths, `..` traversal, NUL bytes,
  * and backslashes (Windows traversal). Enforced by EVERY adapter (not just `FileStorage`) so a key is
  * portable across them, and so the check can't be forgotten on the one adapter where it's a vulnerability.
  */

package/dist/key.js

@@ -1,6 +1,6 @@
 /**
  * Storage-key safety. A key is a POSIX-ish relative path (`avatars/u1.png`); we reject anything that
- * could escape a `FileStorage` root or otherwise misbehave — absolute paths, `..` traversal, NUL bytes,
+ * could escape a `FileStorage` root or otherwise misbehave - absolute paths, `..` traversal, NUL bytes,
  * and backslashes (Windows traversal). Enforced by EVERY adapter (not just `FileStorage`) so a key is
  * portable across them, and so the check can't be forgotten on the one adapter where it's a vulnerability.
  */
@@ -13,7 +13,7 @@ export class StorageKeyError extends Error {
 /** Throw {@link StorageKeyError} unless `key` is a safe relative storage key. */
 export function assertSafeKey(key) {
     if (key.length === 0 || key.length > 1024) {
-        throw new StorageKeyError(`storage key must be 1–1024 chars (got ${key.length})`);
+        throw new StorageKeyError(`storage key must be 1-1024 chars (got ${key.length})`);
     }
     if (key.startsWith("/") || key.includes("\\") || key.includes("\0")) {
         throw new StorageKeyError(`unsafe storage key ${JSON.stringify(key)} (absolute, backslash, or NUL)`);

package/dist/memory.js

@@ -1,5 +1,5 @@
 /**
- * In-process {@link StorageAdapter} — a Map of key → bytes + metadata. For dev and tests; not durable
+ * In-process {@link StorageAdapter} - a Map of key → bytes + metadata. For dev and tests; not durable
  * (a restart empties it) and not shared across instances. Methods are `async` so an unsafe key REJECTS
  * (consistent with the disk/R2 adapters), never throws synchronously.
  */

package/dist/r2.js

@@ -1,5 +1,5 @@
 /**
- * Cloudflare R2 {@link StorageAdapter} — wraps an R2 bucket binding. The binding is typed structurally
+ * Cloudflare R2 {@link StorageAdapter} - wraps an R2 bucket binding. The binding is typed structurally
  * (the slice we use), so this stays dependency-free: no `@cloudflare/workers-types`. Pass `env.MY_BUCKET`.
  *
  *   const storage = new R2Storage(env.UPLOADS)

package/dist/types.d.ts

@@ -1,10 +1,10 @@
 /**
- * @nifrajs/storage — one blob-storage interface, several adapters. The persistence half of
+ * @nifrajs/storage - one blob-storage interface, several adapters. The persistence half of
  * `@nifrajs/uploads` (which validates + signs but doesn't store): `uploads` decides what's allowed,
  * `storage` puts the bytes somewhere. Adapters: {@link MemoryStorage} (dev/test), `FileStorage` (local
  * disk), `R2Storage` (Cloudflare R2). Bring your own for S3/GCS by implementing {@link StorageAdapter}.
  */
-/** Accepted `put` payloads — normalized to bytes by each adapter. */
+/** Accepted `put` payloads - normalized to bytes by each adapter. */
 export type StorageData = Uint8Array | ArrayBuffer | string;
 export interface PutOptions {
     /** MIME type stored alongside the object (returned by `get`). */
@@ -12,7 +12,7 @@ export interface PutOptions {
     /** Arbitrary string metadata stored with the object. */
     readonly metadata?: Readonly<Record<string, string>>;
 }
-/** An object read back from storage. `body` is buffered (not streamed) — fine for typical uploads. */
+/** An object read back from storage. `body` is buffered (not streamed) - fine for typical uploads. */
 export interface StorageObject {
     readonly body: Uint8Array;
     readonly size: number;

package/dist/types.js

@@ -1,5 +1,5 @@
 /**
- * @nifrajs/storage — one blob-storage interface, several adapters. The persistence half of
+ * @nifrajs/storage - one blob-storage interface, several adapters. The persistence half of
  * `@nifrajs/uploads` (which validates + signs but doesn't store): `uploads` decides what's allowed,
  * `storage` puts the bytes somewhere. Adapters: {@link MemoryStorage} (dev/test), `FileStorage` (local
  * disk), `R2Storage` (Cloudflare R2). Bring your own for S3/GCS by implementing {@link StorageAdapter}.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nifrajs/storage",
-  "version": "2.2.0",
-  "description": "Blob storage mechanics for nifra — traversal-safe memory, filesystem, and R2 adapters, optional provider capabilities, and executable adapter conformance.",
+  "version": "2.3.0",
+  "description": "Blob storage mechanics for nifra - traversal-safe memory, filesystem, and R2 adapters, optional provider capabilities, and executable adapter conformance.",
   "keywords": [
     "bun",
     "typescript",

package/src/capabilities.ts

@@ -0,0 +1,172 @@
+/**
+ * Capability beacons for a storage adapter.
+ *
+ * `StorageAdapter` is meant to be implemented outside this package - that is the point of the
+ * interface - so a `for(context)` METHOD on it would break every adapter anyone has written. This is a
+ * wrapper instead: it takes any adapter and hands back one that announces what it is doing.
+ *
+ *   import { useCapability } from "@nifrajs/core/capabilities"
+ *   import { R2Storage, withCapabilityBeacon } from "@nifrajs/storage"
+ *
+ *   const storage = withCapabilityBeacon(new R2Storage(env.BUCKET), { beacon: useCapability })
+ *   await storage.for(c).put(key, bytes)   // announces `storage.write` first
+ *
+ * Evidence from the CALL is per-route and exact. Evidence from an import is per-module, so it is as
+ * broad as the module holding it - which is why a beacon can say something a provenance rule cannot.
+ */
+import type { StorageAdapter } from "./types.ts"
+
+/**
+ * `useCapability` from `@nifrajs/core/capabilities`, taken as a parameter rather than imported so this
+ * package keeps its zero dependencies.
+ */
+export type CapabilityBeacon = (context: object, capability: string) => void
+
+/** Tokens the wrapper announces. Defaults: `storage.read` and `storage.write`. */
+export interface StorageCapabilities {
+  readonly read?: string
+  readonly write?: string
+}
+
+export interface StorageBeaconOptions {
+  readonly beacon: CapabilityBeacon
+  readonly capabilities?: StorageCapabilities
+}
+
+/**
+ * Which capability each method announces.
+ *
+ * The five core methods plus the optional extensions an adapter may implement (`listPage` from
+ * `PagedStorageAdapter`, `copy`/`move` from `MovableStorageAdapter`). `presign` is absent on purpose:
+ * its token depends on the `operation` argument, since a PUT URL hands out write access.
+ */
+const ACCESS: Readonly<Record<string, "read" | "write">> = {
+  get: "read",
+  exists: "read",
+  list: "read",
+  listPage: "read",
+  put: "write",
+  delete: "write",
+  copy: "write",
+  move: "write",
+}
+
+/**
+ * A storage adapter that can be bound to a request context.
+ *
+ * Generic over the adapter, so wrapping a `PresignableStorageAdapter` gives back something that still
+ * presigns. The first version returned a plain `StorageAdapter` assembled from five hand-listed
+ * methods, which silently dropped `presign`, `listPage`, `copy` and `move` - so adding beacons to a
+ * certified S3 adapter quietly removed every optional capability it was certified for.
+ */
+export type BeaconingStorageAdapter<A extends StorageAdapter = StorageAdapter> = A & {
+  /**
+   * A view bound to a request context: every operation announces its capability first, and fails
+   * closed when the route did not declare it.
+   */
+  for(context: object): A
+}
+
+/**
+ * Wrap an adapter so `for(context)` announces each operation's capability.
+ *
+ * Forwarding is by Proxy rather than by enumeration, and that is the whole point: a wrapper that lists
+ * the methods it knows about is a wrapper that silently deletes the ones it does not, and an adapter's
+ * optional capabilities are precisely the methods a hand-written list forgets.
+ */
+export function withCapabilityBeacon<A extends StorageAdapter>(
+  adapter: A,
+  options: StorageBeaconOptions,
+): BeaconingStorageAdapter<A> {
+  if (typeof options.beacon !== "function") {
+    throw new TypeError("@nifrajs/storage: withCapabilityBeacon needs a beacon function")
+  }
+  const read = options.capabilities?.read ?? "storage.read"
+  const write = options.capabilities?.write ?? "storage.write"
+
+  /**
+   * The token a call announces. `presign` reads its `operation` argument, because minting a PUT URL
+   * hands the holder write access to the bucket and must not be evidenced as a read.
+   *
+   * An unrecognised method announces WRITE. A declaration describes what a route MAY do, so the
+   * conservative answer is the correct one - an adapter extension nobody mapped should fail closed
+   * against a read-only route rather than slip through unannounced.
+   */
+  const tokenFor = (method: string, args: readonly unknown[]): string => {
+    if (method === "presign") return args[1] === "put" ? write : read
+    return ACCESS[method] === "read" ? read : write
+  }
+
+  /**
+   * Proxy an extensible facade, never the adapter itself. A Proxy may not return a different value for
+   * a frozen non-writable method property; targeting the adapter therefore throws an invariant error
+   * before our wrapper can run. The facade preserves the prototype for `instanceof`, while every read,
+   * write and call still delegates to the real instance (including `#private` brands).
+   */
+  const facade = (read: (prop: PropertyKey) => unknown, hasFor: boolean): A => {
+    const target = Object.create(Object.getPrototypeOf(adapter)) as object
+    return new Proxy(target, {
+      get: (_target, prop) => read(prop),
+      has: (_target, prop) => (hasFor && prop === "for") || Reflect.has(adapter, prop),
+      ownKeys: () => Reflect.ownKeys(adapter),
+      getOwnPropertyDescriptor: (_target, prop) => {
+        const descriptor = Reflect.getOwnPropertyDescriptor(adapter, prop)
+        if (descriptor === undefined) return undefined
+        // The facade is extensible, so expose a configurable data view without copying a frozen
+        // descriptor onto the proxy target (which would recreate the invariant problem).
+        return {
+          configurable: true,
+          enumerable: descriptor.enumerable ?? false,
+          writable: true,
+          value: read(prop),
+        }
+      },
+      set: (_target, prop, value) => Reflect.set(adapter, prop, value, adapter),
+    }) as A
+  }
+
+  // Built per call rather than cached per context: a map keyed by context would hold every request's
+  // context for the process lifetime, which is a leak with a request attached to it.
+  const bind = (context: object): A => {
+    const methods = new Map<PropertyKey, unknown>()
+    return facade((prop) => {
+      const value = Reflect.get(adapter, prop, adapter)
+      if (typeof value !== "function" || typeof prop !== "string") return value
+      const cached = methods.get(prop)
+      if (cached !== undefined) return cached
+      const wrapped = (...args: unknown[]): unknown => {
+        // A refused capability surfaces as a REJECTION, not a synchronous throw: these methods return
+        // promises, so a caller reaching for `.catch(…)` rather than `try` would otherwise miss it.
+        try {
+          options.beacon(context, tokenFor(prop, args))
+        } catch (error) {
+          return Promise.reject(error)
+        }
+        return Reflect.apply(value as (...a: unknown[]) => unknown, adapter, args)
+      }
+      methods.set(prop, wrapped)
+      return wrapped
+    }, false)
+  }
+
+  // The unbound adapter keeps working exactly as before, including for methods this module has never
+  // heard of. Only the `for(...)` path announces anything.
+  //
+  // Methods come back bound to the target for the same reason the getter reads against it. They are
+  // cached per wrapper, so repeated property reads preserve identity and allocate once.
+  //
+  // An adapter with its own `for` method is shadowed by the wrapper's. That is a genuine (if unlikely)
+  // collision, and `for` is the name the sibling beacons already use, so it stays consistent rather
+  // than novel.
+  const methods = new Map<PropertyKey, unknown>()
+  return facade((prop) => {
+    if (prop === "for") return bind
+    const value = Reflect.get(adapter, prop, adapter)
+    if (typeof value !== "function") return value
+    const cached = methods.get(prop)
+    if (cached !== undefined) return cached
+    const bound = value.bind(adapter)
+    methods.set(prop, bound)
+    return bound
+  }, true) as BeaconingStorageAdapter<A>
+}

package/src/conformance.ts

@@ -46,7 +46,7 @@ const hasMove = (storage: StorageAdapter): storage is MovableStorageAdapter =>
  * only after proving byte + metadata round-trips, overwrite, missing/delete semantics, prefix/limit listing,
  * and uniform unsafe-key rejection across every key-taking method. When the adapter also implements an
  * optional capability ({@link PagedStorageAdapter}, {@link PresignableStorageAdapter},
- * {@link MovableStorageAdapter}), that capability's contract is proven too — implementing a capability
+ * {@link MovableStorageAdapter}), that capability's contract is proven too - implementing a capability
  * partially or unsafely fails conformance rather than silently escaping it.
  */
 export async function assertStorageAdapterConformance(

package/src/file.ts

@@ -5,8 +5,8 @@
  * objects created before sidecar support still infer content type from their extension.
  */
 import { constants } from "node:fs"
-import { lstat, mkdir, open, readdir, readFile, rm, stat } from "node:fs/promises"
-import { dirname, join, posix, resolve, sep } from "node:path"
+import { type FileHandle, lstat, mkdir, open, readdir, realpath, unlink } from "node:fs/promises"
+import { basename, dirname, join, posix, resolve, sep } from "node:path"
 import { assertSafeKey, StorageKeyError } from "./key.ts"
 import {
   type ListOptions,
@@ -81,10 +81,54 @@ export class FileStorage implements StorageAdapter {
     )
   }
 
+  private assertTrustedDirectory(info: Awaited<ReturnType<typeof lstat>>, key: string): void {
+    // Node exposes POSIX mode bits on Bun/Node/Deno Unix runtimes. A group/world-writable ancestor lets
+    // another local principal swap path components between otherwise-correct checks; fail closed so
+    // descriptor validation only has to defend against ordinary filesystem races within one principal.
+    if (process.platform === "win32" || !info.isDirectory()) return
+    const uid = typeof process.getuid === "function" ? process.getuid() : undefined
+    const untrustedOwner = uid !== undefined && info.uid !== uid && info.uid !== 0
+    if (untrustedOwner || (Number(info.mode) & 0o022) !== 0) {
+      throw new StorageKeyError(
+        `storage key ${JSON.stringify(key)} crosses an untrusted writable directory`,
+      )
+    }
+  }
+
+  /**
+   * Prove that another local principal cannot rename any directory leading to `base` after validation.
+   * A sticky shared parent (the ordinary `/tmp` case) is safe only while its child belongs to this uid.
+   * Root-owned system directories are trusted; a directory owned by any other uid is not.
+   */
+  private async assertTrustedAncestorChain(base: string, key: string): Promise<void> {
+    if (process.platform === "win32" || typeof process.getuid !== "function") return
+    const uid = process.getuid()
+    let current = await realpath(base)
+    let child = await lstat(current)
+    for (;;) {
+      const parent = dirname(current)
+      if (parent === current) return
+      const info = await lstat(parent)
+      const mode = Number(info.mode)
+      const trustedOwner = info.uid === uid || info.uid === 0
+      const writableByAnotherPrincipal = (mode & 0o022) !== 0
+      const stickyProtectsChild = (mode & 0o1000) !== 0 && child.uid === uid
+      if (!trustedOwner || (writableByAnotherPrincipal && !stickyProtectsChild)) {
+        throw new StorageKeyError(
+          `storage key ${JSON.stringify(key)} crosses an untrusted writable ancestor`,
+        )
+      }
+      current = parent
+      child = info
+    }
+  }
+
   /** Reject existing symbolic links below `base`; missing suffixes are safe for later creation. */
   private async assertNoSymlinkPath(base: string, path: string, key: string): Promise<void> {
     try {
-      if ((await lstat(base)).isSymbolicLink()) throw this.symlinkError(key)
+      const info = await lstat(base)
+      if (info.isSymbolicLink()) throw this.symlinkError(key)
+      this.assertTrustedDirectory(info, key)
     } catch (error) {
       if (error instanceof StorageKeyError) throw error
       if ((error as NodeJS.ErrnoException).code === "ENOENT") return
@@ -95,7 +139,9 @@ export class FileStorage implements StorageAdapter {
     for (const segment of suffix.split(sep)) {
       current = join(current, segment)
       try {
-        if ((await lstat(current)).isSymbolicLink()) throw this.symlinkError(key)
+        const info = await lstat(current)
+        if (info.isSymbolicLink()) throw this.symlinkError(key)
+        this.assertTrustedDirectory(info, key)
       } catch (error) {
         if (error instanceof StorageKeyError) throw error
         if ((error as NodeJS.ErrnoException).code === "ENOENT") return
@@ -104,7 +150,71 @@ export class FileStorage implements StorageAdapter {
     }
   }
 
-  /** Create parents, re-check them, and refuse a final-component symlink at open time. */
+  /**
+   * Open an existing file without following its final component, then prove the descriptor is the file
+   * still reachable through a symlink-free path below the same root inode. Reads use the descriptor,
+   * not the pathname checked earlier, closing their check/open race.
+   */
+  private async openContained(base: string, path: string, key: string): Promise<FileHandle | null> {
+    await this.assertNoSymlinkPath(base, path, key)
+    let baseBefore: Awaited<ReturnType<typeof lstat>>
+    try {
+      baseBefore = await lstat(base)
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return null
+      throw error
+    }
+
+    let handle: FileHandle
+    try {
+      handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW)
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code
+      if (code === "ENOENT") return null
+      if (code === "ELOOP") throw this.symlinkError(key)
+      throw error
+    }
+
+    try {
+      await this.assertOpenedContained(base, path, key, handle, baseBefore)
+      return handle
+    } catch (error) {
+      await handle.close()
+      throw error
+    }
+  }
+
+  private async assertOpenedContained(
+    base: string,
+    path: string,
+    key: string,
+    handle: FileHandle,
+    baseBefore: Awaited<ReturnType<typeof lstat>>,
+  ): Promise<void> {
+    await this.assertNoSymlinkPath(base, path, key)
+    try {
+      const [opened, current, baseAfter, resolvedBase, resolvedPath] = await Promise.all([
+        handle.stat(),
+        lstat(path),
+        lstat(base),
+        realpath(base),
+        realpath(path),
+      ])
+      const baseChanged = baseBefore.dev !== baseAfter.dev || baseBefore.ino !== baseAfter.ino
+      const targetChanged =
+        current.isSymbolicLink() || opened.dev !== current.dev || opened.ino !== current.ino
+      const escaped = resolvedPath !== resolvedBase && !resolvedPath.startsWith(resolvedBase + sep)
+      if (baseChanged || targetChanged || escaped) throw this.symlinkError(key)
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") throw this.symlinkError(key)
+      throw error
+    }
+  }
+
+  /**
+   * Create parents and open without truncating. The opened inode is validated against the current,
+   * fully resolved path before any caller data is written, closing the check/open symlink race.
+   */
   private async writeContained(
     base: string,
     path: string,
@@ -115,12 +225,31 @@ export class FileStorage implements StorageAdapter {
     await mkdir(dirname(path), { recursive: true })
     await this.assertNoSymlinkPath(base, path, key)
     try {
+      const baseBefore = await lstat(base)
       const handle = await open(
         path,
-        constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC | constants.O_NOFOLLOW,
+        constants.O_WRONLY | constants.O_CREAT | constants.O_NOFOLLOW,
         0o666,
       )
       try {
+        // Do not truncate until the descriptor is proven to be the same file currently reachable
+        // through a symlink-free path beneath the same storage-root directory.
+        await this.assertNoSymlinkPath(base, path, key)
+        const [opened, current, baseAfter, resolvedBase, resolvedPath] = await Promise.all([
+          handle.stat(),
+          lstat(path),
+          lstat(base),
+          realpath(base),
+          realpath(path),
+        ])
+        const baseChanged = baseBefore.dev !== baseAfter.dev || baseBefore.ino !== baseAfter.ino
+        const targetChanged =
+          current.isSymbolicLink() || opened.dev !== current.dev || opened.ino !== current.ino
+        const escaped =
+          resolvedPath !== resolvedBase && !resolvedPath.startsWith(resolvedBase + sep)
+        if (baseChanged || targetChanged || escaped) throw this.symlinkError(key)
+
+        await handle.truncate(0)
         await handle.writeFile(data)
       } finally {
         await handle.close()
@@ -146,26 +275,31 @@ export class FileStorage implements StorageAdapter {
         }),
       )
     } else {
-      await this.assertNoSymlinkPath(this.metadataRoot, metadataPath, key)
-      await rm(metadataPath, { force: true })
+      await this.removeContained(this.metadataRoot, metadataPath, key)
     }
   }
 
   async get(key: string): Promise<StorageObject | null> {
     const path = this.pathFor(key)
-    await this.assertNoSymlinkPath(this.root, path, key)
+    const bodyHandle = await this.openContained(this.root, path, key)
+    if (bodyHandle === null) return null
     let body: Uint8Array
     try {
-      body = new Uint8Array(await readFile(path))
-    } catch (error) {
-      if ((error as NodeJS.ErrnoException).code === "ENOENT") return null
-      throw error
+      body = new Uint8Array(await bodyHandle.readFile())
+    } finally {
+      await bodyHandle.close()
     }
     let stored: { contentType?: string; metadata?: Readonly<Record<string, string>> } = {}
     try {
       const metadataPath = this.metadataPathFor(key)
-      await this.assertNoSymlinkPath(this.metadataRoot, metadataPath, key)
-      stored = JSON.parse(await readFile(metadataPath, "utf8")) as typeof stored
+      const metadataHandle = await this.openContained(this.metadataRoot, metadataPath, key)
+      if (metadataHandle !== null) {
+        try {
+          stored = JSON.parse(await metadataHandle.readFile({ encoding: "utf8" })) as typeof stored
+        } finally {
+          await metadataHandle.close()
+        }
+      }
     } catch (error) {
       if (error instanceof StorageKeyError) throw error
       if ((error as NodeJS.ErrnoException).code !== "ENOENT" && !(error instanceof SyntaxError)) {
@@ -186,21 +320,58 @@ export class FileStorage implements StorageAdapter {
     const path = this.pathFor(key)
     const metadataPath = this.metadataPathFor(key)
     await Promise.all([
-      this.assertNoSymlinkPath(this.root, path, key),
-      this.assertNoSymlinkPath(this.metadataRoot, metadataPath, key),
+      this.removeContained(this.root, path, key),
+      this.removeContained(this.metadataRoot, metadataPath, key),
     ])
-    await Promise.all([rm(path, { force: true }), rm(metadataPath, { force: true })])
   }
 
   async exists(key: string): Promise<boolean> {
     const path = this.pathFor(key)
-    await this.assertNoSymlinkPath(this.root, path, key)
+    const handle = await this.openContained(this.root, path, key)
+    if (handle === null) return false
     try {
-      await stat(path)
       return true
-    } catch (error) {
-      if ((error as NodeJS.ErrnoException).code === "ENOENT") return false
-      throw error
+    } finally {
+      await handle.close()
+    }
+  }
+
+  /** Revalidate an opened inode immediately before unlinking its pathname. */
+  private async removeContained(base: string, path: string, key: string): Promise<void> {
+    const handle = await this.openContained(base, path, key)
+    if (handle === null) return
+    try {
+      await this.assertTrustedAncestorChain(base, key)
+      const baseBefore = await lstat(base)
+      await this.assertOpenedContained(base, path, key, handle, baseBefore)
+      if (process.platform === "linux") {
+        // Node exposes no unlinkat(2), but Linux's procfs gives an equivalent descriptor-relative path.
+        // Anchor the final lookup to an opened, validated parent so replacing an intermediate directory
+        // cannot redirect deletion outside the storage root.
+        const parentPath = dirname(path)
+        const parentHandle = await this.openContained(base, parentPath, key)
+        if (parentHandle === null) throw this.symlinkError(key)
+        try {
+          const anchoredPath = join("/proc/self/fd", String(parentHandle.fd), basename(path))
+          const [opened, current] = await Promise.all([handle.stat(), lstat(anchoredPath)])
+          if (
+            current.isSymbolicLink() ||
+            opened.dev !== current.dev ||
+            opened.ino !== current.ino
+          ) {
+            throw this.symlinkError(key)
+          }
+          await unlink(anchoredPath)
+        } finally {
+          await parentHandle.close()
+        }
+      } else {
+        // Other Node-compatible runtimes expose no descriptor-relative unlink. The verified ownership /
+        // permission chain above removes the cross-principal swap capability before this pathname lookup.
+        await unlink(path)
+      }
+    } finally {
+      await handle.close()
     }
   }
 

package/src/index.ts

@@ -1,5 +1,5 @@
 /**
- * @nifrajs/storage — one blob-storage interface, several adapters. The persistence half of
+ * @nifrajs/storage - one blob-storage interface, several adapters. The persistence half of
  * `@nifrajs/uploads`: `uploads` validates + signs, `storage` puts the bytes somewhere. Adapters cover
  * dev (memory), a long-running server (local disk), and the edge (Cloudflare R2); implement
  * {@link StorageAdapter} for S3/GCS/etc. Dependency-free.
@@ -10,6 +10,13 @@
  *   const object = await storage.get("avatars/u1.png")
  */
 
+export {
+  type BeaconingStorageAdapter,
+  type CapabilityBeacon,
+  type StorageBeaconOptions,
+  type StorageCapabilities,
+  withCapabilityBeacon,
+} from "./capabilities.ts"
 export {
   assertStorageAdapterConformance,
   StorageAdapterConformanceError,

package/src/key.ts

@@ -1,6 +1,6 @@
 /**
  * Storage-key safety. A key is a POSIX-ish relative path (`avatars/u1.png`); we reject anything that
- * could escape a `FileStorage` root or otherwise misbehave — absolute paths, `..` traversal, NUL bytes,
+ * could escape a `FileStorage` root or otherwise misbehave - absolute paths, `..` traversal, NUL bytes,
  * and backslashes (Windows traversal). Enforced by EVERY adapter (not just `FileStorage`) so a key is
  * portable across them, and so the check can't be forgotten on the one adapter where it's a vulnerability.
  */
@@ -15,7 +15,7 @@ export class StorageKeyError extends Error {
 /** Throw {@link StorageKeyError} unless `key` is a safe relative storage key. */
 export function assertSafeKey(key: string): void {
   if (key.length === 0 || key.length > 1024) {
-    throw new StorageKeyError(`storage key must be 1–1024 chars (got ${key.length})`)
+    throw new StorageKeyError(`storage key must be 1-1024 chars (got ${key.length})`)
   }
   if (key.startsWith("/") || key.includes("\\") || key.includes("\0")) {
     throw new StorageKeyError(

package/src/memory.ts

@@ -1,5 +1,5 @@
 /**
- * In-process {@link StorageAdapter} — a Map of key → bytes + metadata. For dev and tests; not durable
+ * In-process {@link StorageAdapter} - a Map of key → bytes + metadata. For dev and tests; not durable
  * (a restart empties it) and not shared across instances. Methods are `async` so an unsafe key REJECTS
  * (consistent with the disk/R2 adapters), never throws synchronously.
  */

package/src/r2.ts

@@ -1,5 +1,5 @@
 /**
- * Cloudflare R2 {@link StorageAdapter} — wraps an R2 bucket binding. The binding is typed structurally
+ * Cloudflare R2 {@link StorageAdapter} - wraps an R2 bucket binding. The binding is typed structurally
  * (the slice we use), so this stays dependency-free: no `@cloudflare/workers-types`. Pass `env.MY_BUCKET`.
  *
  *   const storage = new R2Storage(env.UPLOADS)