@3sln/trove 0.0.10 → 0.0.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@3sln/trove",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "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

@@ -26,6 +26,7 @@
 //   nothing replayable. It is shown to the minter exactly once.
 
 import { TroveError } from './errors.js';
+import { timingSafeEqual } from './timingSafe.js';
 import { CAPABILITIES, expand } from './collections/index.js';
 
 const NS = 'api-keys';
@@ -72,19 +73,6 @@ async function sha256(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) {

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

@@ -324,6 +324,30 @@ export class CollectionService {
     return all.every((c) => this.can(principal, c, 'read') && this.can(principal, c, 'write'));
   }
 
+  /**
+   * What this principal may reach across the whole drive, and whether that is anything.
+   *
+   * The ACL as a DECISION rather than as a record, so something outside this library can
+   * ask it — an edge policy deciding whether an email gets through the front door at all,
+   * for instance. Everything it needs is already here; what was missing was a way to ask
+   * without reimplementing `can()` against the grant shape, which is exactly how two
+   * copies of an authorization rule start.
+   *
+   * "Allowed" means: a named admin, or read on at least one collection. Read on nothing is
+   * the honest definition of someone with no business here — note that on a `defaultOpen`
+   * drive the `anyone` grant makes that true for everybody, which is correct, because the
+   * ACL is what says so.
+   */
+  async accessFor(principal) {
+    const admin = this.isAdmin(principal);
+    const collections = await this.list(principal);
+    return {
+      allowed: admin || collections.length > 0,
+      admin,
+      collections: collections.map((c) => ({ id: c.id, name: c.name, capabilities: c.capabilities })),
+    };
+  }
+
   /** Global admin (can do anything, incl. grant admin-only plugin capabilities). */
   isAdmin(principal) {
     return this.#isNamedAdmin(principal);

package/packages/core/src/identity/jwt.js

@@ -141,6 +141,54 @@ async function importVerifyKey(alg, key) {
  * @param {number} [opts.clockToleranceSec]
  * @param {number|null} [opts.now]     ms epoch; pass null to say there is no clock
  */
+/** base64url WITHOUT padding, which is what a JWT wants everywhere. */
+function bytesToBase64url(bytes) {
+  let bin = '';
+  for (const b of bytes) bin += String.fromCharCode(b);
+  return btoa(bin).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+/**
+ * Sign a JWT with a private JWK.
+ *
+ * The mirror of `verifyJwt`, and it exists for one caller: answering an external policy
+ * evaluation, where the asker fetches OUR public key to check the answer. That is why it is
+ * asymmetric where `signedUrls.js` is happy with HMAC — a shared secret would mean handing
+ * the verifier the ability to mint answers.
+ *
+ * RS256 by default, and that is not a preference. Cloudflare Access verifies these, its
+ * documentation says an RSA key pair and that "other key formats are not supported", and
+ * its own reference implementation signs with RSASSA-PKCS1-v1_5 over SHA-256. ES256 is a
+ * better curve and would have been silently rejected by the only thing that reads these.
+ */
+export async function signJwt(payload, { privateJwk, kid, alg = 'RS256', expiresInSec = 60, now = Date.now() } = {}) {
+  if (!privateJwk) throw TroveError.invalid('Signing a JWT needs a private JWK');
+  const spec = ALGS[alg];
+  if (!spec || alg === 'HS256') throw TroveError.unsupported(`Cannot sign a JWT with alg ${alg}`);
+  const iat = Math.floor(now / 1000);
+  const body = { iat, exp: iat + expiresInSec, ...payload };
+  const header = { alg, typ: 'JWT', ...(kid ? { kid } : {}) };
+  const signingInput = `${bytesToBase64url(enc.encode(JSON.stringify(header)))}.`
+    + `${bytesToBase64url(enc.encode(JSON.stringify(body)))}`;
+  const key = await crypto.subtle.importKey('jwk', { ...privateJwk, alg: undefined, key_ops: undefined }, spec.import, false, ['sign']);
+  const sig = new Uint8Array(await crypto.subtle.sign(spec.verify, key, enc.encode(signingInput)));
+  return `${signingInput}.${bytesToBase64url(sig)}`;
+}
+
+/**
+ * The public half of a private JWK, as a JWKS entry.
+ *
+ * Strips `d` — the private scalar — and everything else a signer needs and a verifier must
+ * not have. Written as a subtraction rather than a copy of the public fields so a JWK that
+ * grows a field cannot silently start publishing it.
+ */
+export function publicJwkOf(privateJwk, { kid, alg = 'RS256' } = {}) {
+  const { d, p, q, dp, dq, qi, ...pub } = privateJwk || {};
+  // `alg` is published because Cloudflare's own keys endpoint publishes it, and a verifier
+  // that trusts the JWK's alg over the token header's is the safer of the two.
+  return { ...pub, alg, key_ops: ['verify'], use: 'sig', ...(kid ? { kid } : {}) };
+}
+
 export async function verifyJwt(token, opts = {}) {
   const { header, payload, parts } = decodeJwt(token);
   const alg = header.alg;

package/packages/core/src/index.js

@@ -83,7 +83,8 @@ export {
   AnonymousIdentityProvider, principalFromClaims,
   cloudflareAccess, accessHost,
 } from './identity/index.js';
-export { verifyJwt, decodeJwt, JwksClient, StaticJwks } from './identity/jwt.js';
+export { verifyJwt, signJwt, publicJwkOf, decodeJwt, JwksClient, StaticJwks } from './identity/jwt.js';
+export { timingSafeEqual } from './timingSafe.js';
 // Where an unauthenticated client is told to go — one answer for the whole drive.
 export {
   protectedResourceMetadata, challengeHeaders, metadataUrl, publicOrigin,

package/packages/core/src/signedUrls.js

@@ -18,6 +18,7 @@
 // may see must not be editable into one for a file you may not.
 
 import { TroveError } from './errors.js';
+import { timingSafeEqual } from './timingSafe.js';
 
 const MINUTES = 60;
 const HOURS = 60 * MINUTES;
@@ -132,19 +133,6 @@ export class SignedUrls {
   }
 }
 
-/**
- * Constant-time string compare.
- *
- * `a === b` on a signature leaks where the first differing byte is, which over enough
- * requests is a forgery oracle. The cost of not caring is small and the cost of caring is
- * nothing.
- */
-function timingSafeEqual(a, b) {
-  if (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;
-}
 
 /**
  * A secret that survives a restart and is shared between instances.

package/packages/core/src/timingSafe.js

@@ -0,0 +1,30 @@
+// Comparing a credential without saying how nearly you got it right.
+//
+// `a === b` returns as soon as it finds a difference, so it is fast for a wrong first byte
+// and slower for a wrong last one. Over enough attempts that difference is measurable, and
+// measuring it recovers the secret one byte at a time — which is why credential comparison
+// is never string equality.
+//
+// One copy, and this file exists because there were two: `signedUrls.js` and `apiKeys.js`
+// each grew their own, and the two had already drifted — one guarded its argument types and
+// the other trusted the call site. That is the cheapest possible version of the bug where
+// two copies of a security rule disagree, and it is worth not having.
+
+/**
+ * Do these two strings match, in time that does not depend on where they differ?
+ *
+ * Length is NOT hidden: returning early on a length mismatch leaks how long the secret is,
+ * which for a fixed-width hash or signature is public anyway. Hiding it would mean hashing
+ * both sides first, and every caller here compares values that are already digests.
+ *
+ * A non-string is false rather than a throw. The inputs come off the wire, `undefined` is a
+ * perfectly ordinary thing for a missing header to be, and a comparison that throws on it
+ * turns a failed auth attempt into a 500.
+ */
+export function timingSafeEqual(a, b) {
+  if (typeof a !== 'string' || typeof b !== 'string') return false;
+  if (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;
+}

package/packages/server/src/access/externalEvaluation.js

@@ -0,0 +1,169 @@
+// External policy evaluation — the drive's ACL, answering an identity provider.
+//
+// WHAT THIS IS FOR
+//
+// Cloudflare Access can call out to a service mid-login and ask "should this person be let
+// in?". Point it here and the answer comes from the collection ACLs: whoever has read on
+// at least one collection gets through the front door, and nobody else reaches the drive at
+// all. Access stays the single place you edit — the administration screen — and it now
+// governs two things instead of one:
+//
+//   the EDGE       who gets past Cloudflare, decided here
+//   the BUCKET     what they may do once inside, decided by the same ACL, as it always was
+//
+// The second half is unchanged and still authoritative. This does not replace an internal
+// check anywhere; letting someone through the door does not grant them a collection. If
+// this component is switched off, nothing about the drive's own guarding changes.
+//
+// OPTIONAL, and off unless configured. Mounted exactly like a notification channel — the
+// component contributes routes and `createServer` adds them — so a drive that has not
+// configured it has no `/api/access/*` at all rather than endpoints that answer "no".
+//
+// SETTING IT UP
+//
+//   1. Make a key pair. It is asymmetric because Cloudflare must be able to CHECK our
+//      answer without being able to MINT one — and it is RSA because Access says so:
+//      "other key formats are not supported", and its reference implementation signs
+//      RS256. An EC key here is silently rejected by the only thing that reads these.
+//
+//        node -e "crypto.subtle.generateKey({name:'RSASSA-PKCS1-v1_5',modulusLength:2048,
+//          publicExponent:new Uint8Array([1,0,1]),hash:'SHA-256'},true,['sign','verify'])
+//          .then(k=>crypto.subtle.exportKey('jwk',k.privateKey)).then(j=>console.log(JSON.stringify(j)))"
+//
+//   2. TROVE_ACCESS_EVAL_KEY=<that JSON>   (and TROVE_CF_ACCESS_TEAM if not already set)
+//   3. In the Access policy, add an External Evaluation rule:
+//        Evaluate URL   https://<your drive>/api/access/evaluate
+//        Keys URL       https://<your drive>/api/access/keys
+//
+//   4. AND let Access reach them. If the drive sits behind Access — which is the whole
+//      point — then by default these two paths do as well, and Access would have to
+//      authenticate to itself to call them. It cannot, so it fails with nothing useful to
+//      say. Add a Bypass policy for `/api/access/*`.
+//
+//      Bypassing is safe here rather than a concession, and that is by construction: the
+//      keys endpoint serves a public key, and the evaluate endpoint authenticates its
+//      caller itself by verifying the assertion. Neither ever depended on Access for its
+//      own protection. They are also `public: true`, so this drive's OWN identity
+//      requirement does not apply to them either — Access holds no Trove session and
+//      never will.
+//
+// WHY IT REFUSES TO RUN UNVERIFIED
+//
+// This endpoint answers "does this email have access to this drive". That is a question
+// worth lying to strangers about, so it will not answer one it cannot attribute: the
+// caller's assertion must verify against the configured team's JWKS. Without a team
+// configured the component declines to mount rather than mounting an open oracle that
+// enumerates your users to anyone who can reach it.
+//
+// THE TRANSPORT, CHECKED AGAINST CLOUDFLARE (Aug 2026)
+//
+// Verified against the External Evaluation docs and their reference Worker:
+//
+//   in    POST, JSON body `{ token }`, the JWT signed by the Access account key
+//   out   JSON body `{ token }`, a JWT of `{ success, iat, exp, nonce }`, RS256
+//   keys  `{ keys: [ <public JWK, with kid> ] }`
+//
+// The identity lands at `claims.identity.email` in their example rather than at the top
+// level, which is why `principalOf` looks in both places. `parseAssertion` stays generous
+// about where it finds the incoming JWT: the token is self-authenticating, so accepting it
+// from more than one place costs nothing and survives a small change on their side.
+
+import { TroveError, verifyJwt, signJwt, publicJwkOf, JwksClient } from '@3sln/trove/core';
+
+/** Where Cloudflare publishes the keys for a team's own assertions. */
+const teamJwksUrl = (team) => `https://${team}.cloudflareaccess.com/cdn-cgi/access/certs`;
+
+/**
+ * Find the assertion in whatever shape it arrived.
+ *
+ * Generous on purpose — see the header. The JWT is the only thing that matters and it is
+ * self-authenticating, so accepting it from several places costs nothing: a forgery is
+ * still a forgery wherever it was found.
+ */
+export async function parseAssertion(req) {
+  const header = req.headers?.get?.('cf-access-jwt-assertion');
+  if (header) return header;
+  const text = await req.text();
+  if (!text) return null;
+  try {
+    const body = JSON.parse(text);
+    return body.token || body.jwt || body.assertion || null;
+  } catch {
+    // Not JSON: some callers post the bare token.
+    return text.trim() || null;
+  }
+}
+
+/** The identity Cloudflare is asking about, as a principal this drive understands. */
+export function principalOf(claims) {
+  const email = claims?.email || claims?.identity?.email || claims?.sub || null;
+  if (!email) return null;
+  return { id: email, email, name: claims?.name || email, roles: claims?.groups || claims?.roles || [] };
+}
+
+/**
+ * An external-evaluation component, or null when this drive has not configured one.
+ *
+ * @param {object} cfg
+ * @param {object} cfg.privateJwk  EC P-256 private key, the one whose public half we publish
+ * @param {string} cfg.team        Cloudflare Access team, for verifying the caller
+ * @param {string} [cfg.kid]       key id, so the key can be rotated without an outage
+ */
+export function externalEvaluation({ privateJwk, team, kid = 'trove-access', jwks, now = Date.now } = {}) {
+  if (!privateJwk) return null;
+  // Refusing rather than warning: see the header. An oracle nobody authenticated is worse
+  // than no oracle.
+  if (!team && !jwks) {
+    throw TroveError.invalid(
+      'External evaluation needs a Cloudflare Access team to verify callers against — set TROVE_CF_ACCESS_TEAM',
+    );
+  }
+  const keys = jwks || new JwksClient(teamJwksUrl(team));
+
+  return {
+    name: 'cloudflare-external-evaluation',
+    routes() {
+      return [
+        {
+          method: 'POST',
+          path: '/api/access/evaluate',
+          deps: ['collections'],
+          // No Trove identity: the caller is Cloudflare, not a user of this drive, and it
+          // authenticates by signing the assertion — which `verifyJwt` below checks. A
+          // session requirement here would be asking Access to log in as somebody.
+          public: true,
+          async handler(ctx) {
+            const token = await parseAssertion(ctx.req);
+            if (!token) throw TroveError.invalid('No access assertion in the request');
+            // Verified before it is read. Everything below trusts these claims, so this
+            // line is the whole security of the component.
+            const claims = await verifyJwt(token, { jwks: keys, now: now() });
+            const principal = principalOf(claims);
+
+            // No identity is a "no", not an error: Access is asking about somebody and we
+            // cannot say yes about somebody we cannot name.
+            const decision = principal && ctx.collections
+              ? await ctx.collections.accessFor(principal)
+              : { allowed: false, admin: false, collections: [] };
+
+            const answer = await signJwt(
+              { success: !!decision.allowed, nonce: claims.nonce, email: principal?.email || null },
+              { privateJwk, kid, now: now() },
+            );
+            return { token: answer };
+          },
+        },
+        {
+          method: 'GET',
+          path: '/api/access/keys',
+          deps: [],
+          public: true,
+          // Public by design: it is a public key, and Cloudflare fetches it unauthenticated.
+          handler() {
+            return { keys: [publicJwkOf(privateJwk, { kid })] };
+          },
+        },
+      ];
+    },
+  };
+}

package/packages/server/src/index.js

@@ -23,6 +23,7 @@ import { storageRegistry } from './engine/providers/core.js';
 import { createMcpHandler } from './mcp/index.js';
 import { cacheControlFor } from './cachePolicy.js';
 import { MANIFEST_PATH, webManifest, manifestFromEnv } from './manifest.js';
+import { externalEvaluation } from './access/externalEvaluation.js';
 
 // Every backend is pluggable. Each field of `config` accepts EITHER a ready
 // provider instance (pass your own class) OR a `{ driver, ... }` config object
@@ -325,6 +326,24 @@ export async function createServer(config = {}) {
     }
   }
 
+  // The external policy component, on the same terms: it contributes routes or it does not
+  // exist. A drive that has not configured one has no `/api/access/*` at all, rather than
+  // endpoints that exist to answer "no" — which is the difference between a feature that is
+  // off and a feature that is broken.
+  // Paths a contributed component declared as needing no Trove identity. Exact matches
+  // only, and that is deliberate: the check below runs BEFORE routing, so it cannot know
+  // which parameterised route would have matched. A component that wants a public route
+  // gives it a fixed path.
+  const publicPaths = new Set();
+
+  const accessPolicy = config.accessEvaluation
+    ? externalEvaluation({ ...config.accessEvaluation, team: config.accessEvaluation.team || config.identity?.access?.team })
+    : null;
+  for (const route of accessPolicy?.routes?.(routeHelpers) || []) {
+    router.add(route.method, route.path, route.deps || [], route.handler);
+    if (route.public) publicPaths.add(route.path);
+  }
+
   // Said at boot, because that is when someone is looking and can still fix it. The
   // alternative is discovering it from a client that can't sign in and a 401 that
   // doesn't say why.
@@ -397,8 +416,14 @@ export async function createServer(config = {}) {
       let principal = null;
       let grant = null;
       try {
-        grant = await capabilities.resolve(req);
-        if (!grant) principal = await identity.authenticate(req);
+        // A public route answers to something other than this drive's identity — the
+        // external policy endpoints verify a Cloudflare-signed assertion themselves, and
+        // the keys endpoint serves a public key. Requiring a session on those is asking
+        // the caller to authenticate as a user it is not and does not have.
+        if (!publicPaths.has(url.pathname)) {
+          grant = await capabilities.resolve(req);
+          if (!grant) principal = await identity.authenticate(req);
+        }
       } catch (err) {
         const e = err instanceof TroveError ? err : TroveError.unauthorized('Authentication failed');
         return withChallenge(new Response(JSON.stringify(e.toJSON()), { status: e.status, headers: { 'content-type': 'application/json', 'x-content-type-options': 'nosniff' } }), req);
@@ -850,6 +875,22 @@ export function configFromEnv(env = (typeof process !== 'undefined' ? process.en
   }
 
   // Cross-origin API access is off unless an origin (or '*') is configured.
+  // External policy evaluation: present only when a signing key is. See
+  // access/externalEvaluation.js for how to make one.
+  if (env.TROVE_ACCESS_EVAL_KEY) {
+    let privateJwk;
+    try {
+      privateJwk = JSON.parse(env.TROVE_ACCESS_EVAL_KEY);
+    } catch {
+      throw TroveError.invalid('TROVE_ACCESS_EVAL_KEY must be a private JWK as JSON');
+    }
+    config.accessEvaluation = {
+      privateJwk,
+      team: env.TROVE_CF_ACCESS_TEAM || null,
+      kid: env.TROVE_ACCESS_EVAL_KID || 'trove-access',
+    };
+  }
+
   config.corsOrigin = env.TROVE_CORS_ORIGIN || null;
   // App-shell CSP is opt-in (see SAMPLE_CSP) — provide a full policy string to
   // enable it. Off by default because sandboxed plugin iframes can't satisfy one.

package/packages/server/src/routes.js

@@ -272,6 +272,27 @@ export function createRouter() {
     return collections.remove(params.id, principal);
   });
 
+  /**
+   * Who has access to this collection.
+   *
+   * A separate route rather than a field on `describe()`, which is documented as "a safe,
+   * principal-scoped view (no secrets)" and is returned to everyone who can see the
+   * collection at all. The ACL is not a secret exactly, but it names people, and every
+   * listing would carry it. Asking for it is an explicitly admin-gated act.
+   */
+  r.get('/api/collections/:id/grants', ['collections'], async (ctx) => {
+    requireCollections(ctx);
+    const c = await ctx.collections.assert(ctx.principal, ctx.params.id, 'admin');
+    // Drive administrators come from the DEPLOYMENT (TROVE_ADMINS), not from this ACL, and
+    // returning them alongside rather than inside `grants` is the honest shape: they hold
+    // admin on every collection, `setGrant` cannot touch them, and a UI that listed them as
+    // grants would offer a revoke button that silently does nothing.
+    return {
+      grants: c.acl?.grants || [],
+      admins: [...(ctx.collections.admins || [])],
+    };
+  });
+
   r.post('/api/collections/:id/grants', ['collections'], async (ctx) => {
     requireCollections(ctx);
     return { collection: await ctx.collections.setGrant(ctx.params.id, await body(ctx.req), ctx.principal) };