@3sln/trove 0.0.4 → 0.0.7

package/packages/core/src/storage/diagnose.js

@@ -0,0 +1,234 @@
+// Is the backing store actually usable from a browser?
+//
+// This exists because of a failure that cost a day. A drive was serving its file list
+// fine, and every file opened to a spinner that never resolved. The server was healthy,
+// the storage was healthy, the download endpoint returned 200 in 300ms — and the browser
+// still could not read a single byte, because the R2 bucket had no CORS policy. Nothing
+// in the system knew: CORS is enforced in the browser, so the server's own request to
+// the same bucket succeeded, and the only evidence was a console message in one tab.
+//
+// So the check has to be the browser's check. A CORS preflight is an ordinary OPTIONS
+// request that anyone can send, including us — and a preflight never touches the object,
+// so it works against a key that does not exist and costs nothing. Sending it against a
+// presigned URL and reading the response headers is exactly what a browser does before
+// it will hand a response to a page. If it fails for us it fails for them.
+//
+// The point is not detection for its own sake. Each finding carries the command that
+// fixes it: a diagnostic that says "CORS is misconfigured" to someone who did not know
+// buckets had a CORS policy has told them nothing they can act on.
+
+/** A key that need not exist — a preflight is answered without looking one up. */
+const PROBE_KEY = '.trove-cors-probe';
+
+/**
+ * Every code this module can produce.
+ *
+ * Exported because the caller that raises these as issues also has to CLEAR the ones a
+ * later check no longer reports — that is what makes fixing the bucket make the warning
+ * go away. Deriving the clear-set from the same list the checks use means a new finding
+ * cannot be added without becoming clearable.
+ */
+export const STORAGE_ISSUE_CODES = [
+  'storage-unreachable',
+  'cors-missing',
+  'cors-origin',
+  'cors-headers',
+  'cors-expose',
+  'cors-unknown',
+];
+
+/** Headers the client sends on a download, so a policy that omits them breaks reads. */
+const NEEDED_REQUEST_HEADERS = ['range'];
+
+/**
+ * Headers the client must be able to READ off the response.
+ *
+ * Cross-origin responses expose almost nothing by default, and these are not cosmetic:
+ * without `content-range` the text viewer cannot tell a truncated file from a whole one,
+ * and without `accept-ranges` seeking in audio and video is not offered at all.
+ *
+ * Checked against a real GET rather than the preflight — see where this is used.
+ */
+const NEEDED_EXPOSED_HEADERS = ['content-range', 'content-length'];
+
+const csv = (value) => String(value || '').toLowerCase().split(',').map((s) => s.trim()).filter(Boolean);
+
+/**
+ * Diagnose one collection's backing store.
+ *
+ * Ordered: an unreachable store short-circuits, because "CORS is not configured" is a
+ * misleading thing to say about a bucket whose credentials are wrong.
+ *
+ * @param {object} deps
+ * @param {import('./interface.js').StorageBackend} deps.storage
+ * @param {string} [deps.origin]  the browser origin to check against — the drive's own
+ *   public URL. Omitted means the CORS check is skipped rather than guessed at: a policy
+ *   is allowed to be origin-specific, so checking the wrong origin invents a problem.
+ * @param {string} [deps.driver]  store driver key, to word the remedy for it
+ * @param {typeof fetch} [deps.fetchImpl]
+ * @returns {Promise<Array<{code: string, severity: string, title: string, detail: string, remedy?: string}>>}
+ */
+export async function diagnoseStorage({ storage, origin = null, driver = null, fetchImpl = null } = {}) {
+  const findings = [];
+  if (!storage) return findings;
+  const doFetch = fetchImpl || (typeof fetch === 'function' ? fetch : null);
+
+  // --- can we talk to it at all? ---------------------------------------------
+  try {
+    await storage.list({ limit: 1 });
+  } catch (err) {
+    findings.push({
+      code: 'storage-unreachable',
+      severity: 'error',
+      title: 'The backing store could not be reached',
+      detail: err?.message || String(err),
+      remedy:
+        'Check the collection’s store settings: the bucket or directory must exist, and '
+        + 'for an S3-compatible store the endpoint, region and credentials must all be for '
+        + 'that bucket. A wrong endpoint and a wrong key look identical from here.',
+    });
+    return findings;
+  }
+
+  // --- does the browser get to read it? --------------------------------------
+  // Only when downloads go straight from the browser to the store. A drive that proxies
+  // its bytes through the server is same-origin all the way, and CORS never applies —
+  // reporting a bucket policy as missing there would be a problem the admin cannot have.
+  const caps = storage.capabilities || {};
+  if (!caps.presignDownload) return findings;
+  if (!origin || !doFetch) return findings;
+
+  let url;
+  try {
+    url = await storage.presignGet(PROBE_KEY, { expiresIn: 60 });
+  } catch {
+    // A store that claims presignDownload and cannot presign is a bug, not a
+    // configuration problem, and it will surface far more loudly elsewhere.
+    return findings;
+  }
+
+  let res;
+  try {
+    res = await doFetch(url, {
+      method: 'OPTIONS',
+      headers: {
+        origin,
+        'access-control-request-method': 'GET',
+        'access-control-request-headers': NEEDED_REQUEST_HEADERS.join(','),
+      },
+    });
+  } catch (err) {
+    findings.push({
+      code: 'cors-unknown',
+      severity: 'warning',
+      title: 'Could not check whether the store allows browser access',
+      detail: `The preflight request to the store failed: ${err?.message || err}`,
+      remedy: 'This is usually a network or endpoint problem rather than a CORS one — '
+        + 'confirm the store’s endpoint is reachable from the server.',
+    });
+    return findings;
+  }
+
+  const allowOrigin = res.headers.get('access-control-allow-origin');
+  if (!allowOrigin) {
+    findings.push({
+      code: 'cors-missing',
+      severity: 'error',
+      title: 'The store does not allow browser access, so files will not open',
+      detail:
+        `A CORS preflight from ${origin} was answered without an `
+        + `Access-Control-Allow-Origin header (HTTP ${res.status}). Browsers will refuse `
+        + 'every download, including previews and thumbnails, while the file list and '
+        + 'search keep working normally.',
+      remedy: corsRemedy(origin, driver),
+    });
+    return findings;
+  }
+
+  if (allowOrigin !== '*' && allowOrigin.toLowerCase() !== origin.toLowerCase()) {
+    findings.push({
+      code: 'cors-origin',
+      severity: 'error',
+      title: 'The store allows a different origin than this drive',
+      detail: `It allows "${allowOrigin}", but this drive is served from "${origin}". `
+        + 'A policy naming the wrong origin is refused exactly like no policy at all.',
+      remedy: corsRemedy(origin, driver),
+    });
+    return findings;
+  }
+
+  // Allowed, but possibly not for everything we send or need back. These are warnings:
+  // opening a small file will work, so the drive is usable — it is seeking in a video
+  // and reading the head of a large file that break.
+  const allowHeaders = csv(res.headers.get('access-control-allow-headers'));
+  const missingRequest = allowHeaders.includes('*')
+    ? []
+    : NEEDED_REQUEST_HEADERS.filter((h) => !allowHeaders.includes(h));
+  if (missingRequest.length) {
+    findings.push({
+      code: 'cors-headers',
+      severity: 'warning',
+      title: 'The store’s CORS policy blocks ranged reads',
+      detail: `It does not allow the ${missingRequest.join(', ')} request header, so seeking `
+        + 'in audio and video, and previewing the start of a large file, will fail. Whole-file '
+        + 'downloads are unaffected.',
+      remedy: corsRemedy(origin, driver),
+    });
+  }
+
+  // Exposed headers are read off the ACTUAL response, not the preflight — that is where
+  // the spec puts them and where the browser looks. Some stores echo them on a preflight
+  // and some do not, so checking the OPTIONS response reports a correctly configured
+  // bucket as broken. A GET for a key that does not exist is answered 404 WITH the CORS
+  // headers when a policy matches, which is all this needs.
+  let actual;
+  try {
+    actual = await doFetch(url, { method: 'GET', headers: { origin } });
+  } catch {
+    // The preflight already passed, so the policy is in place; failing to complete this
+    // second request says nothing more about it. Warning here would be guessing.
+    return findings;
+  }
+
+  const exposed = csv(actual.headers.get('access-control-expose-headers'));
+  const missingExposed = exposed.includes('*')
+    ? []
+    : NEEDED_EXPOSED_HEADERS.filter((h) => !exposed.includes(h));
+  if (missingExposed.length) {
+    findings.push({
+      code: 'cors-expose',
+      severity: 'warning',
+      title: 'The store hides response headers the viewer needs',
+      detail: `${missingExposed.join(', ')} are not in exposeHeaders, so the browser cannot read `
+        + 'them. Trove cannot then tell a truncated preview from a complete file, and will '
+        + 'not offer seeking.',
+      remedy: corsRemedy(origin, driver),
+    });
+  }
+
+  return findings;
+}
+
+/** The policy this drive needs, as something that can be pasted. */
+export function corsPolicy(origin) {
+  return [{
+    AllowedOrigins: [origin],
+    AllowedMethods: ['GET', 'PUT', 'HEAD'],
+    AllowedHeaders: ['content-type', 'range'],
+    ExposeHeaders: ['ETag', 'Content-Length', 'Content-Type', 'Content-Range', 'Accept-Ranges'],
+    MaxAgeSeconds: 3600,
+  }];
+}
+
+function corsRemedy(origin, driver) {
+  const json = JSON.stringify(corsPolicy(origin), null, 2);
+  // R2 is the common case for a Workers deployment and its tooling is not the AWS CLI,
+  // so name it explicitly rather than leaving the admin to translate.
+  const r2 = driver === 's3'
+    ? '\n\nOn Cloudflare R2, save the JSON above as cors.json and run:\n'
+      + '  wrangler r2 bucket cors put <bucket> --file cors.json\n\n'
+      + 'On AWS S3:\n'
+      + '  aws s3api put-bucket-cors --bucket <bucket> --cors-configuration file://cors.json'
+    : '';
+  return `Allow this origin on the bucket. The policy Trove needs:\n\n${json}${r2}`;
+}

package/packages/core/src/storage/drivers.js

@@ -0,0 +1,83 @@
+// The drivers this package ships, as registrable descriptors.
+//
+// Split by what a runtime can actually run, and that split is the point:
+//
+//   `portableDrivers()` — memory and S3. Both are fetch-and-arithmetic, so they work
+//   identically on Node, Bun, Deno and Cloudflare Workers.
+//
+//   `filesystemDriver()` — lives in filesystem.js and is imported from there, NOT from
+//   this module or the package barrel. That import is what pulls in node:fs, so a Workers
+//   entry point that never mentions it never gets it: the driver is absent from the form
+//   AND absent from the bundle. Re-exporting it here would defeat both.
+//
+// A deployment's driver set is therefore decided by its entry point, which is the only
+// place that knows what it is running on.
+
+import { MemoryStorage } from './memory.js';
+import { S3Storage } from './s3.js';
+
+/** Anything with a `fetch` can run these. */
+export function portableDrivers() {
+  return [
+    {
+      key: 's3',
+      label: 'S3-compatible',
+      description: 'AWS S3, Cloudflare R2, MinIO, Backblaze B2 — anything speaking the S3 API.',
+      fields: [
+        { name: 'bucket', label: 'Bucket', required: true, placeholder: 'my-bucket' },
+        {
+          name: 'region',
+          label: 'Region',
+          placeholder: 'auto',
+          help: 'R2 uses "auto". AWS wants the bucket’s real region.',
+        },
+        {
+          name: 'endpoint',
+          label: 'Endpoint',
+          placeholder: 'https://<account>.r2.cloudflarestorage.com',
+          help: 'Leave blank for AWS S3.',
+        },
+        { name: 'prefix', label: 'Prefix', help: 'Share one bucket between collections.' },
+        // Marked secret so they are never read back out of a collection record: the
+        // record lives in the KV store and is otherwise safe to show an admin.
+        { name: 'accessKeyId', label: 'Access key id', required: true, secret: true },
+        { name: 'secretAccessKey', label: 'Secret access key', type: 'password', required: true, secret: true },
+        {
+          name: 'forcePathStyle',
+          label: 'Path-style addressing',
+          type: 'boolean',
+          help: 'MinIO and most self-hosted endpoints need this.',
+        },
+      ],
+      // Two config shapes reach here and both have to work.
+      //
+      // Flat — `{ driver: 's3', bucket: … }` — is what `fields` above describes and what
+      // the collection form posts. Nested under `s3` is what `configFromEnv` produces and
+      // what every collection record written before this driver existed holds, because the
+      // switch this replaced read `cfg.s3` and nothing else.
+      //
+      // Normalising rather than only handling it in `create` is the point: validation runs
+      // against the normalised shape, so a nested config is no longer refused for a missing
+      // top-level `bucket` that was about to be spread in anyway. That refusal broke every
+      // environment-configured S3 deployment at startup, which is as loud as a bug gets and
+      // still took a local run to see, because no test used the env shape.
+      normalize: (cfg) => ({ ...cfg, ...(cfg.s3 || {}) }),
+      create: (cfg) => new S3Storage({
+        bucket: cfg.bucket,
+        region: cfg.region || 'auto',
+        endpoint: cfg.endpoint || undefined,
+        accessKeyId: cfg.accessKeyId,
+        secretAccessKey: cfg.secretAccessKey,
+        sessionToken: cfg.sessionToken,
+        forcePathStyle: cfg.forcePathStyle === true || cfg.forcePathStyle === 'true',
+      }),
+    },
+    {
+      key: 'memory',
+      label: 'Memory',
+      description: 'Nothing is kept. For demos and tests — a restart empties it.',
+      fields: [],
+      create: () => new MemoryStorage(),
+    },
+  ];
+}

package/packages/core/src/storage/filesystem.js

@@ -281,3 +281,25 @@ export class FilesystemStorage extends StorageBackend {
 function etagOfStat(stat) {
   return `"${stat.size.toString(16)}-${Math.floor(stat.mtimeMs).toString(16)}"`;
 }
+
+/**
+ * This driver as a registrable descriptor.
+ *
+ * Deliberately exported from HERE and not from the package barrel or drivers.js. Importing
+ * it is what pulls node:fs into a bundle, so a Workers entry point that never mentions it
+ * gets neither the form option nor the module — which is also why `core/index.js` no
+ * longer re-exports FilesystemStorage. A Workers build previously needed nodejs_compat
+ * purely because the barrel dragged this file in whether or not it could ever be used.
+ */
+export function filesystemDriver() {
+  return {
+    key: 'filesystem',
+    label: 'Filesystem / NAS',
+    description: 'A directory on this machine, or a mounted network share.',
+    fields: [
+      { name: 'root', label: 'Root directory', required: true, placeholder: './data/team' },
+      { name: 'prefix', label: 'Prefix', help: 'Share one directory between collections.' },
+    ],
+    create: (cfg) => new FilesystemStorage({ root: cfg.root }),
+  };
+}

package/packages/core/src/storage/registry.js

@@ -0,0 +1,162 @@
+// Which kinds of backing store this deployment can have.
+//
+// A collection IS a store config — `{ driver: 's3', bucket: … }` — and something has to
+// turn that into a StorageBackend. That something used to be a three-case `switch` in the
+// server, which had two problems beyond being closed:
+//
+//   Its `default:` arm returned MemoryStorage. So `driver: 'flesystem'` — a typo — built a
+//   store that accepted writes and lost them on restart. A misconfiguration that looks
+//   like it worked is worse than one that refuses to start.
+//
+//   The UI could not know what the server supported, so it hardcoded its own list and
+//   offered Filesystem / NAS on Cloudflare Workers, where there is no filesystem to
+//   point at. A form offering a choice the runtime cannot honour is a form that produces
+//   a broken collection.
+//
+// A registry fixes both by making the set of drivers DATA. Each one declares a globally
+// unique key, a label, and the fields it needs — so the server answers "what can I be
+// configured with" and the client renders that answer instead of guessing. Availability
+// is not a flag on a driver, it is whether the driver was registered at all: an entry
+// point registers what its runtime can actually run, so Filesystem is absent on Workers
+// rather than present-and-refused, and the module is not in the bundle either.
+//
+// The config lives in the collection record; the implementation does not. A driver can be
+// written and registered entirely outside this package.
+
+import { TroveError } from '../errors.js';
+import { StorageBackend } from './interface.js';
+
+/**
+ * One field a driver needs in order to be configured.
+ *
+ * This is what the UI renders and what a deploy script validates against, so it says how
+ * to ASK rather than how to store: `secret` is the interesting one, because a store config
+ * lives in the KV store and a field marked secret should never be echoed back to a client
+ * once written.
+ *
+ * @typedef {object} DriverField
+ * @property {string} name       key in the store config
+ * @property {string} label      what to call it in a form
+ * @property {'text'|'password'|'number'|'boolean'} [type]
+ * @property {boolean} [required]
+ * @property {boolean} [secret]  never returned once stored
+ * @property {string} [placeholder]
+ * @property {string} [help]     one line under the field
+ */
+
+export class StorageDriverRegistry {
+  constructor(drivers = []) {
+    this._drivers = new Map();
+    for (const d of drivers) this.register(d);
+  }
+
+  /**
+   * @param {object} driver
+   * @param {string} driver.key           globally unique, and what goes in `store.driver`
+   * @param {string} driver.label         for a form
+   * @param {string} [driver.description] one line about what it is
+   * @param {DriverField[]} [driver.fields]
+   * @param {(config: object) => object} [driver.normalize] accept an older or alternative
+   *   config shape, returning the one `fields` describes. Runs before validation, so the
+   *   shape checked is the shape built from.
+   * @param {(config: object) => StorageBackend} driver.create
+   */
+  register(driver) {
+    const key = String(driver?.key ?? '').trim();
+    if (!key) throw TroveError.invalid('A storage driver needs a key');
+    if (typeof driver.create !== 'function') {
+      throw TroveError.invalid(`Storage driver "${key}" needs a create(config) function`);
+    }
+    // Refused rather than overwritten. Two drivers claiming one key means one of them is
+    // silently not the one being used, and which one depends on registration order.
+    if (this._drivers.has(key)) {
+      throw TroveError.invalid(`A storage driver is already registered as "${key}"`);
+    }
+    this._drivers.set(key, {
+      key,
+      label: driver.label || key,
+      description: driver.description || '',
+      fields: (driver.fields || []).map((f) => ({
+        name: f.name,
+        label: f.label || f.name,
+        type: f.type || 'text',
+        required: !!f.required,
+        secret: !!f.secret,
+        placeholder: f.placeholder || '',
+        help: f.help || '',
+      })),
+      normalize: driver.normalize || null,
+      create: driver.create,
+    });
+    return this;
+  }
+
+  has(key) {
+    return this._drivers.has(key);
+  }
+
+  keys() {
+    return [...this._drivers.keys()];
+  }
+
+  /**
+   * One registered driver, `create` included — unlike `describe()`, which deliberately
+   * strips it because it answers a client.
+   *
+   * For copying a driver into another registry, which is how a deployment narrows the set
+   * it offers: a registry has no `unregister`, so narrowing rebuilds from what survived
+   * rather than removing from what did not. Keeping removal out of this class is the point
+   * — a driver disappearing from a live registry is a store that stops being buildable
+   * while collections still reference it.
+   */
+  driver(key) {
+    return this._drivers.get(key);
+  }
+
+  /**
+   * What a client needs to render a form.
+   *
+   * Neither `create` nor `normalize`: both are behaviour, not data. JSON.stringify would
+   * drop them anyway, which is exactly why they are removed here instead — a describe()
+   * whose result is only serialisable by accident is one that leaks the next function
+   * somebody adds into every in-process consumer.
+   */
+  describe() {
+    return [...this._drivers.values()].map(({ create, normalize, ...rest }) => rest);
+  }
+
+  /**
+   * Build the backend a store config names.
+   *
+   * An unknown driver throws, and says what IS available. This is the arm that used to
+   * return an in-memory store.
+   *
+   * `normalize` runs FIRST, so a driver that accepts more than one config shape validates
+   * the shape it will actually build from. Without it, required-field checks are performed
+   * against a config the driver was about to rewrite — which is precisely how S3 broke:
+   * `configFromEnv` nests its settings under `s3`, `create` spread that back out, and the
+   * check in between looked for a top-level `bucket` that was never going to be there and
+   * refused every environment-configured S3 deployment at startup.
+   */
+  build(config) {
+    const key = config?.driver;
+    if (!key) throw TroveError.invalid('A store config needs a driver');
+    const driver = this._drivers.get(key);
+    if (!driver) {
+      throw TroveError.invalid(
+        `Unknown storage driver "${key}" — this deployment has: ${this.keys().join(', ') || 'none'}`,
+      );
+    }
+    const cfg = driver.normalize ? driver.normalize(config) : config;
+    for (const f of driver.fields) {
+      if (f.required && (cfg[f.name] == null || cfg[f.name] === '')) {
+        throw TroveError.invalid(`Storage driver "${key}" requires "${f.name}"`);
+      }
+    }
+    const backend = driver.create(cfg);
+    if (!(backend instanceof StorageBackend)) {
+      throw TroveError.invalid(`Storage driver "${key}" did not return a StorageBackend`);
+    }
+    return backend;
+  }
+}

package/packages/server/src/adapters/bun.js

@@ -10,6 +10,11 @@
 
 import { readFileSync } from 'node:fs';
 import { createServer, configFromEnv, warnOnOpenAccess } from '../index.js';
+// This runtime HAS a filesystem, so it registers the filesystem driver. Imported from
+// storage/filesystem.js rather than the package barrel: that import is what pulls in
+// node:fs, and the Workers adapter deliberately never makes it — so there, Filesystem is
+// absent from the collection form and absent from the bundle.
+import { filesystemDriver } from '@3sln/trove/core/storage/filesystem.js';
 import { findWebDist } from './webDist.js';
 import { createStaticAssets } from './staticAssets.js';
 
@@ -47,6 +52,7 @@ const envConfig = configFromEnv();
 warnOnOpenAccess(envConfig);
 const { handle, close } = await createServer({
   ...envConfig,
+  storageDrivers: [filesystemDriver()],
   assets: hasWeb ? staticAssets : undefined,
 });
 

package/packages/server/src/adapters/node.js

@@ -12,6 +12,11 @@ import fs, { readFileSync } from 'node:fs';
 import fsp from 'node:fs/promises';
 import { Readable } from 'node:stream';
 import { createServer, configFromEnv, warnOnOpenAccess } from '../index.js';
+// This runtime HAS a filesystem, so it registers the filesystem driver. Imported from
+// storage/filesystem.js rather than the package barrel: that import is what pulls in
+// node:fs, and the Workers adapter deliberately never makes it — so there, Filesystem is
+// absent from the collection form and absent from the bundle.
+import { filesystemDriver } from '@3sln/trove/core/storage/filesystem.js';
 import { findWebDist } from './webDist.js';
 import { createStaticAssets } from './staticAssets.js';
 
@@ -82,6 +87,7 @@ const envConfig = configFromEnv();
 warnOnOpenAccess(envConfig);
 const { handle, close } = await createServer({
   ...envConfig,
+  storageDrivers: [filesystemDriver()],
   assets: hasWeb ? staticAssets : undefined,
 });
 

package/packages/server/src/engine/index.js

@@ -49,7 +49,7 @@ export function createDriveEngine(config = {}, lifecycleState = { closing: false
 export const BACKBONE = [
   'storage', 'sqlite', 'metadata', 'kv', 'tasks', 'issues', 'notifications',
   'sidecar', 'collections', 'identity', 'auth', 'search', 'vfs', 'plugins',
-  'lifecycle',
+  'apiKeys', 'capabilities', 'lifecycle',
 ];
 
 /** The shape `beginScan` has always returned, so no caller has to change. */

package/packages/server/src/engine/providers/access.js

@@ -76,6 +76,27 @@ const intersect = (held, asked) => new Set([...asked].filter((c) => held.has(c))
  * @param {object} node   already resolved by `stat`
  * @param {string|symbol} granted the capability that was asserted
  */
+/**
+ * Authorize from an API key grant rather than from a principal.
+ *
+ * The same shape as the signature path below it, and for the same reason: a grant is
+ * authority that arrived with the request, so there is nobody to look up in an ACL.
+ *
+ * REFUSED, not narrowed. If the route asked for `write` and the key holds `read`, this
+ * throws — because handing back a read handle to a route that asked for write means the
+ * route believes it has write and acts accordingly. The signature path learned this the
+ * hard way (see its comment); the rule is the same here.
+ */
+function grantedCapabilities(grant, collectionId, capability) {
+  const held = grant.capabilitiesFor(collectionId);
+  if (!held.has(capability)) {
+    throw TroveError.forbidden(
+      `This API key does not hold "${capability}" on this collection`,
+    );
+  }
+  return intersect(held, requested(capability));
+}
+
 function nodeHandle(vfs, sidecar, node, held) {
   const permits = (capability) => held.has(capability);
   const granted = held === ALL ? 'system' : [...held].sort().join(',');
@@ -204,7 +225,7 @@ export class NodeAccessProvider extends Provider {
   // cannot see — restoring and permanently deleting are the only operations on items
   // that are no longer part of the drive. It widens WHAT IS VISIBLE, never what is
   // permitted: the capability is asserted exactly the same way afterwards.
-  async obtain({ principal, id, collectionId, trashed = false, capability = 'read', signature = null } = {}) {
+  async obtain({ principal, grant = null, id, collectionId, trashed = false, capability = 'read', signature = null } = {}) {
     if (!id) throw TroveError.invalid('A node id is required');
     assertCapability(capability);
     const vfs = await this.vfs.obtain();
@@ -238,6 +259,15 @@ export class NodeAccessProvider extends Provider {
     const config = await this.config.obtain();
     if (!enforcing(config)) return nodeHandle(vfs, sidecar, node, requested(capability));
 
+    // A key IS the grant, scoped to the node's own collection. Checked before the ACL
+    // and never alongside it: a request bearing a key is the key's request, and falling
+    // back to whatever principal happens to be attached would let a weak key borrow a
+    // strong session — the confused deputy, arrived at by being helpful.
+    if (grant) {
+      return nodeHandle(vfs, sidecar, node,
+        grantedCapabilities(grant, node.collectionId, capability));
+    }
+
     // `assert` throws when the capability is not held. Nothing here decides from
     // presence: if the service is missing this raises, it does not allow.
     const collections = await this.collections.obtain();
@@ -269,12 +299,18 @@ export class CollectionAccessProvider extends Provider {
     this.config = config;
   }
 
-  async obtain({ principal, id = 'default', capability = 'read' } = {}) {
+  async obtain({ principal, grant = null, id = 'default', capability = 'read' } = {}) {
     assertCapability(capability);
     const vfs = await this.vfs.obtain();
     const config = await this.config.obtain();
     if (!enforcing(config)) return collectionHandle(vfs, id, requested(capability));
 
+    // Same rule as the node path: a key's grant decides, alone, and refuses rather than
+    // narrowing. This is the check that keeps a key scoped to `photos` out of `invoices`.
+    if (grant) {
+      return collectionHandle(vfs, id, grantedCapabilities(grant, id, capability));
+    }
+
     const collections = await this.collections.obtain();
     const collection = await collections.assert(principal, id, capability);
     return collectionHandle(vfs, id,
@@ -306,7 +342,7 @@ export class UploadAccessProvider extends Provider {
     this.config = config;
   }
 
-  async obtain({ principal, id } = {}) {
+  async obtain({ principal, grant = null, id } = {}) {
     if (!id) throw TroveError.invalid('An upload id is required');
     const vfs = await this.vfs.obtain();
     // Resolving first is what makes the check possible at all: only the session knows
@@ -314,8 +350,14 @@ export class UploadAccessProvider extends Provider {
     const session = await vfs.uploadStatus(id);
     const config = await this.config.obtain();
     if (enforcing(config)) {
-      const collections = await this.collections.obtain();
-      await collections.assert(principal, session.collectionId, 'write');
+      // Re-checked on EVERY request of the upload, keys included — the point of this
+      // provider. A key revoked between `POST /api/uploads` and `complete` stops the
+      // upload, which it would not if the grant were only checked when it began.
+      if (grant) grantedCapabilities(grant, session.collectionId, 'write');
+      else {
+        const collections = await this.collections.obtain();
+        await collections.assert(principal, session.collectionId, 'write');
+      }
     }
     return {
       id,