@3sln/trove 0.0.4 → 0.0.7

package/README.md

@@ -163,6 +163,12 @@ TROVE_S3_ACCESS_KEY_ID=…            # or AWS_ACCESS_KEY_ID
 TROVE_S3_SECRET_ACCESS_KEY=…        # or AWS_SECRET_ACCESS_KEY
 TROVE_S3_PATH_STYLE=true            # MinIO / custom endpoints
 
+# Which store types a COLLECTION may be created on. Defaults to everything this
+# runtime registered; naming a subset takes the rest off the collection form and
+# refuses them. Worth setting on Workers, where `memory` is offered because it is
+# portable but produces a collection that loses its uploads on isolate recycle.
+TROVE_STORAGE_DRIVERS=s3            # subset of: memory | filesystem | s3
+
 # Metadata (file tree + facets)
 TROVE_METADATA=sqlite               # memory | sqlite
 TROVE_DB_PATH=./data/trove.db

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@3sln/trove",
-  "version": "0.0.4",
+  "version": "0.0.7",
   "type": "module",
   "description": "Trove — a self-hostable, plugin-extensible Google Drive. Semantic search, pluggable storage (S3 / filesystem / NAS), and a VS Code-style contribution system with sandboxed plugins.",
   "repository": {

package/packages/core/src/apiKeys.js

@@ -0,0 +1,326 @@
+// API keys: a credential that carries CAPABILITIES and no identity.
+//
+// This is deliberately not "log in as a robot user". An API key does not answer "who is
+// this", it answers "what may this request do" — and those are different questions that
+// the rest of the drive already keeps apart: IdentityProvider says who, the collection
+// ACL says what. A key skips the first question entirely.
+//
+// The pattern is not new here. Signed URLs (signedUrls.js) already work this way: a valid
+// signature is served WITHOUT a principal because it was minted by someone who held the
+// capability it grants. A key is that idea with a longer life, a broader scope, and a
+// record you can revoke. Both are grants; neither is a login.
+//
+// Consequences worth being deliberate about:
+//
+//   Attribution is to the KEY, not a person. `createdBy` records who minted it, so an
+//   audit trail exists, but a write made with a key is the key's write. If you need
+//   per-person attribution, that is what identity is for — do not hand one key to five
+//   people and expect the log to tell them apart.
+//
+//   Scope is per collection and explicit. A key names the collections it may touch and
+//   the capabilities it holds on each. Drive-wide access exists but has to be asked for
+//   ('*'), because the difference between "this one bucket" and "everything" should never
+//   be a thing you get by leaving a field blank.
+//
+//   The secret is never stored. Only a SHA-256 of it, so a dump of the KV store yields
+//   nothing replayable. It is shown to the minter exactly once.
+
+import { TroveError } from './errors.js';
+import { CAPABILITIES, expand } from './collections/index.js';
+
+const NS = 'api-keys';
+
+/** Every collection, rather than a named one. Spelled out so it cannot be a typo. */
+export const ANY_COLLECTION = '*';
+
+// `trv_<id>_<secret>`. The id travels in the credential so verification is a single
+// keyed read rather than a scan-and-compare over every key in the store — which is both
+// slower and a timing oracle over how many keys exist.
+const PREFIX = 'trv';
+const ID_PREFIX = 'key';
+const SECRET_BYTES = 32;
+
+const enc = new TextEncoder();
+
+function b64url(bytes) {
+  let s = '';
+  for (const b of bytes) s += String.fromCharCode(b);
+  return btoa(s).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+function randomB64(bytes) {
+  const buf = new Uint8Array(bytes);
+  crypto.getRandomValues(buf);
+  return b64url(buf);
+}
+
+/**
+ * Hex, for the id half only.
+ *
+ * base64url would be shorter but its alphabet includes `_`, which is the separator —
+ * so an id could contain one and the credential would no longer parse into id and
+ * secret. Hex has no such overlap, and the id is not the part carrying the entropy.
+ */
+function randomHex(bytes) {
+  const buf = new Uint8Array(bytes);
+  crypto.getRandomValues(buf);
+  return [...buf].map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+
+async function sha256(text) {
+  const digest = await crypto.subtle.digest('SHA-256', enc.encode(text));
+  return b64url(new Uint8Array(digest));
+}
+
+/**
+ * Compare without leaking where two strings diverge.
+ *
+ * The hash of a presented secret against the stored hash. A `===` here would return
+ * faster the earlier it finds a difference, which over enough attempts is a way to learn
+ * a prefix — the classic reason credential comparison is not string equality.
+ */
+function timingSafeEqual(a, b) {
+  if (typeof a !== 'string' || typeof b !== 'string' || a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}
+
+/** Normalise and validate one `{ collectionId, capabilities }` entry. */
+function normalizeScope(scope) {
+  const collectionId = String(scope?.collectionId ?? '').trim();
+  if (!collectionId) throw TroveError.invalid('Every scope needs a collectionId (or "*")');
+  const caps = [...new Set(scope?.capabilities ?? [])];
+  if (!caps.length) throw TroveError.invalid(`Scope for "${collectionId}" grants no capabilities`);
+  for (const c of caps) {
+    if (!CAPABILITIES.includes(c)) {
+      throw TroveError.invalid(`Unknown capability "${c}" — expected one of: ${CAPABILITIES.join(', ')}`);
+    }
+  }
+  return { collectionId, capabilities: caps };
+}
+
+/**
+ * A resolved key, as the authorization layer sees it.
+ *
+ * Shaped to be the answer to one question — "what may this request do to this
+ * collection" — so the access layer never has to know it came from a key rather than
+ * from a signature or an ACL.
+ */
+export class ApiKeyGrant {
+  constructor({ keyId, name, scopes }) {
+    this.kind = 'api-key';
+    this.keyId = keyId;
+    this.name = name;
+    this.scopes = scopes;
+  }
+
+  /**
+   * The capabilities this key holds on one collection, `admin` expanded to everything
+   * it implies (the same expansion the collection ACL uses, so a key and a grant mean
+   * the same thing by the word "admin").
+   *
+   * @returns {Set<string>}
+   */
+  capabilitiesFor(collectionId) {
+    const held = new Set();
+    for (const scope of this.scopes) {
+      if (scope.collectionId !== ANY_COLLECTION && scope.collectionId !== collectionId) continue;
+      for (const c of scope.capabilities) held.add(c);
+    }
+    return expand(held);
+  }
+
+  /** Whether this key may do `capability` to `collectionId` at all. */
+  can(collectionId, capability) {
+    return this.capabilitiesFor(collectionId).has(capability);
+  }
+}
+
+/**
+ * Mint, verify and revoke API keys.
+ *
+ * Records live in the pluggable KV store, so this works on every backend the drive runs
+ * on and survives restarts without a migration.
+ */
+export class ApiKeyService {
+  /**
+   * @param {object} deps
+   * @param {import('./kv.js').KeyValueStore} deps.kv
+   * @param {() => number} [deps.now] injected clock, for tests
+   */
+  constructor({ kv, now = () => Date.now() } = {}) {
+    if (!kv) throw TroveError.invalid('ApiKeyService requires a kv store');
+    this.kv = kv;
+    this.now = now;
+  }
+
+  /**
+   * Create a key. The secret is returned ONCE and never stored.
+   *
+   * @param {object} spec
+   * @param {string} spec.name              what it is for, so a list of keys is readable
+   * @param {Array<{collectionId: string, capabilities: string[]}>} spec.scopes
+   * @param {number|null} [spec.expiresAt]  epoch ms; null never expires
+   * @param {string|null} [spec.createdBy]  principal id of the minter, for the audit trail
+   * @returns {Promise<{record: object, secret: string}>}
+   */
+  async mint({ name, scopes, expiresAt = null, createdBy = null } = {}) {
+    const label = String(name ?? '').trim();
+    if (!label) throw TroveError.invalid('An API key needs a name');
+    if (!Array.isArray(scopes) || !scopes.length) {
+      throw TroveError.invalid('An API key needs at least one scope — a key that grants nothing is not useful');
+    }
+    const normalized = scopes.map(normalizeScope);
+    if (expiresAt != null && (!Number.isFinite(expiresAt) || expiresAt <= this.now())) {
+      throw TroveError.invalid('expiresAt must be a future timestamp');
+    }
+
+    const id = `${ID_PREFIX}_${randomHex(8)}`;
+    const secret = `${PREFIX}_${id}_${randomB64(SECRET_BYTES)}`;
+    const record = {
+      id,
+      name: label,
+      // The hash of the WHOLE credential, so a stolen record cannot be turned back into
+      // something presentable even by someone who knows the id.
+      hash: await sha256(secret),
+      scopes: normalized,
+      createdAt: this.now(),
+      createdBy,
+      expiresAt,
+      lastUsedAt: null,
+      revokedAt: null,
+    };
+    await this.kv.set(NS, id, record);
+    return { record: redact(record), secret };
+  }
+
+  /**
+   * Resolve a presented secret into a grant, or null.
+   *
+   * Null for every failure — unknown, revoked, expired, malformed, wrong secret. The
+   * caller turns that into one 401; distinguishing them in the response would tell an
+   * attacker which key ids exist.
+   *
+   * @returns {Promise<ApiKeyGrant|null>}
+   */
+  async verify(secret) {
+    if (typeof secret !== 'string') return null;
+    // `trv_key_<hex id>_<secret>`. Parsed by prefix rather than by splitting on `_`,
+    // because the secret half is base64url and may contain underscores of its own —
+    // only the id is guaranteed not to.
+    const head = `${PREFIX}_${ID_PREFIX}_`;
+    if (!secret.startsWith(head)) return null;
+    const rest = secret.slice(head.length);
+    const boundary = rest.indexOf('_');
+    if (boundary < 1 || boundary === rest.length - 1) return null;
+    const id = `${ID_PREFIX}_${rest.slice(0, boundary)}`;
+
+    const record = await this.kv.get(NS, id);
+    if (!record || record.revokedAt) return null;
+    if (record.expiresAt != null && record.expiresAt <= this.now()) return null;
+    if (!timingSafeEqual(await sha256(secret), record.hash)) return null;
+
+    return new ApiKeyGrant({ keyId: record.id, name: record.name, scopes: record.scopes });
+  }
+
+  /** Every key, without hashes. Newest first. */
+  async list() {
+    const rows = await this.kv.list(NS);
+    return rows
+      .map((r) => r.value)
+      .filter(Boolean)
+      .map(redact)
+      .sort((a, b) => b.createdAt - a.createdAt);
+  }
+
+  async get(id) {
+    const record = await this.kv.get(NS, id);
+    return record ? redact(record) : null;
+  }
+
+  /**
+   * Revoke by marking, not deleting.
+   *
+   * The record is what explains a key that used to work, and "why did this stop" is a
+   * question worth being able to answer. It also keeps the id from being reissued.
+   */
+  async revoke(id) {
+    const record = await this.kv.get(NS, id);
+    if (!record) throw TroveError.notFound('API key');
+    if (record.revokedAt) return redact(record);
+    record.revokedAt = this.now();
+    await this.kv.set(NS, id, record);
+    return redact(record);
+  }
+
+  /**
+   * Record that a key was used. Best-effort and never on the request path's critical
+   * section: a failure to write "last used" must not fail the request it describes.
+   */
+  async touch(id) {
+    try {
+      const record = await this.kv.get(NS, id);
+      if (!record || record.revokedAt) return;
+      record.lastUsedAt = this.now();
+      await this.kv.set(NS, id, record);
+    } catch { /* the timestamp is a convenience, not a control */ }
+  }
+}
+
+/** A record safe to send to a client: everything except the hash. */
+function redact(record) {
+  const { hash, ...rest } = record;
+  return rest;
+}
+
+// --- the injection point -------------------------------------------------------
+
+/**
+ * How a request becomes a capability grant.
+ *
+ * The counterpart to IdentityProvider, and the reason it is separate: identity and
+ * authority are different questions, and some credentials only answer the second.
+ * Implement this to authorize from something other than a key — a mutual-TLS
+ * certificate, a signed webhook, a service mesh header.
+ */
+export class CapabilityProvider {
+  /**
+   * @param {Request} request
+   * @returns {Promise<ApiKeyGrant|null>} a grant, or null to abstain
+   */
+  async resolve(request) { // eslint-disable-line no-unused-vars
+    return null;
+  }
+}
+
+/** `Authorization: Bearer trv_key_…`, verified against the key store. */
+export class ApiKeyCapabilityProvider extends CapabilityProvider {
+  constructor({ apiKeys } = {}) {
+    super();
+    if (!apiKeys) throw TroveError.invalid('ApiKeyCapabilityProvider requires an ApiKeyService');
+    this.apiKeys = apiKeys;
+  }
+
+  async resolve(request) {
+    const header = request?.headers?.get?.('authorization') || '';
+    const match = /^Bearer\s+(\S+)$/i.exec(header);
+    // Only OUR prefix. A bearer token that is someone's OIDC access token must fall
+    // through to the identity provider untouched, not be spent as a failed key lookup.
+    if (!match || !match[1].startsWith(`${PREFIX}_`)) return null;
+
+    const grant = await this.apiKeys.verify(match[1]);
+    // Presented one of ours and it did not verify. That is a 401, not a fall-through to
+    // anonymous: a caller who sent a credential is telling us they expect to be
+    // authorized by it, and quietly serving them as the public would turn a revoked key
+    // into "works, but with less access" — which is how a revocation goes unnoticed.
+    if (!grant) throw TroveError.unauthorized('This API key is not valid');
+
+    // Not awaited. "Last used" is what tells an admin which key nobody needs any more,
+    // so it is worth recording — but it is a convenience, and a slow or failing KV write
+    // must not add latency to, or fail, the request it is describing. `touch` swallows
+    // its own errors for the same reason.
+    this.apiKeys.touch(grant.keyId);
+    return grant;
+  }
+}

package/packages/core/src/collections/index.js

@@ -20,7 +20,9 @@ export const CAPABILITIES = ['read', 'write', 'delete', 'admin'];
 const NS = 'collections';
 
 // admin implies everything; a simple implication table keeps checks declarative.
-function expand(caps) {
+// Exported because API keys grant capabilities too, and "admin" has to mean the same
+// thing in a key as it does in an ACL — two implication tables would eventually diverge.
+export function expand(caps) {
   const set = new Set(caps);
   if (set.has('admin')) for (const c of CAPABILITIES) set.add(c);
   return set;
@@ -50,17 +52,21 @@ export class CollectionService {
     this._storage = new Map(Object.entries(storageOverrides || {}));
   }
 
-  async init() {
-    const existing = await this.kv.get(NS, 'default');
-    if (!existing) {
-      await this.kv.set(NS, 'default', {
-        id: 'default', name: 'My Drive', description: 'Default collection',
-        store: this.defaultStore,
-        acl: { grants: this.defaultOpen ? [{ type: 'anyone', capabilities: ['read', 'write', 'delete', 'admin'] }] : [] },
-        createdAt: Date.now(), createdBy: 'system', system: true,
-      });
-    }
-  }
+  /**
+   * Nothing is created here any more.
+   *
+   * There used to be a `default` collection, minted on first boot and named by every
+   * unscoped request. It made a fresh drive feel ready, and it cost more than it was
+   * worth: `'default'` became a hardcoded assumption in routing, in maintenance, in the
+   * metadata schema and in four core signatures, and on a multi-user drive it was a
+   * collection most people could not read — so the fallback pointed new users at a
+   * permission error and called it their drive.
+   *
+   * A drive with no collections now says so, and the client asks for one to be created.
+   * That is a real first-run step rather than a magic id, and every request names the
+   * collection it means.
+   */
+  async init() {}
 
   async list(principal) {
     const rows = await this.kv.list(NS);
@@ -71,6 +77,22 @@ export class CollectionService {
       .sort((a, b) => (a.name || '').localeCompare(b.name || ''));
   }
 
+  /**
+   * Every collection record, with no principal and no ACL filtering.
+   *
+   * For system work — a scheduled scan, a storage self-check — which has no user and must
+   * not pretend to have one. `list(null)` is the wrong tool for that, and quietly so: it
+   * asks what the ANONYMOUS principal may read, which on a drive that is not open to the
+   * public is nothing. Maintenance that called it looked like it ran and scanned no
+   * collection at all.
+   *
+   * Never hand the result to a request — these records carry store configuration,
+   * credentials included. `list(principal)` is the answer to "what may you see".
+   */
+  async all() {
+    return (await this.kv.list(NS)).map((r) => r.value).filter(Boolean);
+  }
+
   async get(id) {
     const c = await this.kv.get(NS, id);
     if (!c) throw TroveError.notFound('Collection');
@@ -198,6 +220,55 @@ export class CollectionService {
    * Create a collection from a store config. Requires the create capability.
    * The creator is granted admin on the new collection.
    */
+  /**
+   * Create a collection if it is absent; leave it alone if it is present.
+   *
+   * Idempotent, and that is the point: this is the shape a deploy script, a boot hook or
+   * a test setup wants — "make sure this exists" — where `create` throws the second time
+   * and forces every caller to write the same try/ignore around it.
+   *
+   * Unlike `create` this takes an explicit `id` and no principal. It is a server-side
+   * operation, the way `init()` used to be, so anything exposing it over HTTP does its
+   * own authorization first. `store` defaults to the service's configured store, so the
+   * common case — one collection on the drive's own storage — is a name and nothing else.
+   *
+   * @param {object} spec
+   * @param {string} spec.id
+   * @param {string} [spec.name]
+   * @param {object} [spec.store] defaults to the configured defaultStore
+   * @param {object} [spec.acl] defaults to open when the service was built with defaultOpen
+   * @returns {Promise<{record: object, created: boolean}>}
+   */
+  async ensure({ id, name, description, store, acl, system = false } = {}) {
+    if (!id) throw TroveError.invalid('ensure needs a collection id');
+    const existing = await this.kv.get(NS, id);
+    if (existing) return { record: existing, created: false };
+
+    const config = store || this.defaultStore;
+    if (!config?.driver) throw TroveError.invalid('A backing store (driver + config) is required');
+    try {
+      this.storageFactory(config);
+    } catch (err) {
+      throw TroveError.invalid(`Invalid store config: ${err.message}`, { cause: err });
+    }
+    const record = {
+      id,
+      name: (name || id).trim(),
+      description: description || '',
+      store: config,
+      acl: acl || {
+        grants: this.defaultOpen
+          ? [{ type: 'anyone', capabilities: [...CAPABILITIES] }]
+          : [],
+      },
+      createdAt: Date.now(),
+      createdBy: 'system',
+      system,
+    };
+    await this.kv.set(NS, id, record);
+    return { record, created: true };
+  }
+
   async create({ name, description, store, acl }, principal) {
     if (!this.canCreate(principal)) throw TroveError.forbidden('You cannot create collections');
     if (!name?.trim()) throw TroveError.invalid('Collection name is required');
@@ -232,7 +303,6 @@ export class CollectionService {
 
   /** Remove the collection record. Caller is responsible for its nodes/objects. */
   async remove(id, principal) {
-    if (id === 'default') throw TroveError.invalid('The default collection cannot be deleted');
     await this.assert(principal, id, 'admin');
     await this.kv.delete(NS, id);
     this._storage.delete(id);

package/packages/core/src/index.js

@@ -8,7 +8,14 @@ export * from './links.js';
 
 export { StorageBackend } from './storage/interface.js';
 export { MemoryStorage } from './storage/memory.js';
-export { FilesystemStorage } from './storage/filesystem.js';
+// FilesystemStorage is NOT exported here on purpose. It imports node:fs at the top level,
+// so re-exporting it from the barrel put node:fs into every bundle that touched core —
+// including Cloudflare Workers, which is the only reason a Workers build needed
+// nodejs_compat. Import it (and `filesystemDriver`) from
+// '@3sln/trove/core/storage/filesystem.js' in an entry point that has a filesystem.
+export { StorageDriverRegistry } from './storage/registry.js';
+export { portableDrivers } from './storage/drivers.js';
+export { diagnoseStorage, corsPolicy, STORAGE_ISSUE_CODES } from './storage/diagnose.js';
 export { S3Storage } from './storage/s3.js';
 export { PrefixedStorage } from './storage/prefixed.js';
 
@@ -16,7 +23,7 @@ export { MetadataStore } from './metadata/interface.js';
 export { MemoryStore } from './metadata/memory.js';
 export { SqliteStore } from './metadata/sqlite.js';
 
-export { CollectionService, CAPABILITIES } from './collections/index.js';
+export { CollectionService, CAPABILITIES, expand as expandCapabilities } from './collections/index.js';
 
 export { SearchService } from './search/index.js';
 export { SearchTransformer, ParsingSearchTransformer, WorkersAiSearchTransformer, parseTagFilters, matchTagFilters } from './search/transformer.js';
@@ -45,6 +52,11 @@ export { VectorizeVectorStore } from './search/vectorize.js';
 // Server-side key/value store (subscriptions, inboxes, profiles).
 export { KeyValueStore, MemoryKV, SqliteKV } from './kv.js';
 export { SignedUrls, resolveUrlSecret, URL_PURPOSES } from './signedUrls.js';
+// API keys: capability without identity. CapabilityProvider is the injection point —
+// the counterpart to IdentityProvider, for credentials that say what rather than who.
+export {
+  ApiKeyService, ApiKeyGrant, ApiKeyCapabilityProvider, CapabilityProvider, ANY_COLLECTION,
+} from './apiKeys.js';
 export { SqliteDatabase, SqliteProvider, LocalSqliteProvider, assertSafePluginSql, stripSqlLiterals } from './sqlite.js';
 // SQLite on Cloudflare D1, so a Worker deployment has a metadata store that exists.
 export { D1SqliteProvider } from './sqlite-d1.js';

package/packages/core/src/issues.js

@@ -67,6 +67,9 @@ export class IssueRegistry {
    * @param {string} [spec.subject]     what it is about (a node id); omit for drive-wide
    * @param {string} spec.title         one line, in the user's terms
    * @param {string} [spec.detail]      the underlying error, for someone who wants it
+   * @param {string} [spec.remedy]      what to DO about it, kept separate from `detail`
+   *   because it is the part a client should render as something copyable — a remedy is
+   *   often a policy or a command, and folded into prose it stops being pasteable.
    * @param {string} [spec.severity]    'error' (default) | 'warning'
    * @param {string} [spec.collectionId] scopes visibility; null = drive-wide (admin)
    * @param {{op: string}} [spec.retry] declarative retry, executed by a registered handler
@@ -82,6 +85,7 @@ export class IssueRegistry {
       subject: spec.subject ?? null,
       title: spec.title,
       detail: spec.detail ?? null,
+      remedy: spec.remedy ?? null,
       severity: spec.severity || 'error',
       collectionId: spec.collectionId ?? null,
       retry: spec.retry ?? null,