@3sln/trove 0.0.2

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

@@ -0,0 +1,210 @@
+// Telling a client where to sign in.
+//
+// Trove doesn't run a login system — it verifies tokens somebody else issued. So every
+// unauthenticated request has the same problem: the client has been refused, and has no
+// idea where to go and get a credential. A bare 401 is a dead end for a browser and an
+// absolute dead end for an agent, which has no human to ask.
+//
+// OAuth 2.0 Protected Resource Metadata (RFC 9728) is the standard answer, and it is
+// what the MCP authorization spec builds on — so implementing it once serves both. A
+// refused request carries a pointer:
+//
+//   WWW-Authenticate: Bearer resource_metadata="https://drive/.well-known/oauth-protected-resource"
+//
+// and that document names the authorization server. ONE authorization server, for the
+// whole drive. It is a property of the deployment — which identity provider sits in
+// front of this thing — not of any particular endpoint, so the MCP endpoint and the JSON
+// API answer with the same value and cannot drift apart.
+//
+// The deployment supplies it (env, or a field on the server config). Where it is not
+// supplied but the JWT issuer is, that is used: for essentially every OIDC provider the
+// issuer URL IS the authorization server, and making someone state the same URL twice
+// is a way to have them disagree.
+
+/** Normalize one-or-many authorization server URLs, trimming trailing slashes. */
+export function normalizeServers(value) {
+  if (!value) return [];
+  const list = Array.isArray(value) ? value : String(value).split(',');
+  return list.map((s) => String(s).trim().replace(/\/+$/, '')).filter(Boolean);
+}
+
+/**
+ * The public origin of this request, as the outside world sees it.
+ *
+ * Behind a reverse proxy the socket says `http://10.0.0.4:8080`, which is not an
+ * identifier any token was ever issued for. The forwarded headers say what the client
+ * actually asked for.
+ */
+export function publicOrigin(req, cfg = {}) {
+  // An explicit public URL wins, and is the only form that is safe without a trusted
+  // proxy in front — see below.
+  if (cfg.publicUrl) {
+    try { return new URL(cfg.publicUrl).origin; } catch { /* fall through to detection */ }
+  }
+  const url = new URL(req.url);
+  // X-Forwarded-* is set by a proxy — and by anyone else who feels like it. This origin
+  // ends up in the WWW-Authenticate challenge and the discovery document, so trusting a
+  // spoofed one hands a client a sign-in URL on somebody else's host. Only honoured when
+  // the deployment says it IS behind a proxy (TROVE_TRUST_PROXY), which is the same
+  // thing every other server makes you opt into.
+  if (cfg.trustProxy) {
+    const proto = req.headers.get('x-forwarded-proto') || url.protocol.replace(':', '');
+    const host = req.headers.get('x-forwarded-host') || req.headers.get('host') || url.host;
+    return `${proto}://${host}`;
+  }
+  return `${url.protocol.replace(':', '')}://${req.headers.get('host') || url.host}`;
+}
+
+/**
+ * Where the metadata document for a resource lives.
+ *
+ * RFC 9728 inserts the well-known segment BETWEEN the host and the path rather than
+ * appending it, so a resource at `https://d/mcp` is described at
+ * `https://d/.well-known/oauth-protected-resource/mcp`, and the drive itself at
+ * `https://d/.well-known/oauth-protected-resource`. Appending instead is a common enough
+ * mistake that clients have had to work around it.
+ */
+export function metadataUrl(resource) {
+  const u = new URL(resource);
+  const path = u.pathname.replace(/\/+$/, '');
+  return `${u.origin}/.well-known/oauth-protected-resource${path}`;
+}
+
+/**
+ * The RFC 9728 document.
+ *
+ * @param {string} resource the canonical URI of what is being protected
+ * @param {object} auth the drive's auth discovery config
+ */
+export function protectedResourceMetadata(resource, auth = {}) {
+  const servers = normalizeServers(auth.authorizationServers);
+  return {
+    resource,
+    // Optional in the RFC, but a client can do nothing without it — so when it is
+    // missing the field is omitted rather than published empty, which would read as
+    // "there are none" instead of "nobody configured this", and the challenge below
+    // says so in words.
+    ...(servers.length ? { authorization_servers: servers } : {}),
+    scopes_supported: auth.scopes?.length ? auth.scopes : ['trove:read', 'trove:write'],
+    bearer_methods_supported: ['header'],
+    resource_name: auth.resourceName || 'Trove',
+    ...(auth.documentation ? { resource_documentation: auth.documentation } : {}),
+  };
+}
+
+/**
+ * The challenge that turns a 401 into directions.
+ *
+ * `error_description` carries the operator-facing half. A client ignores it, but the
+ * person reading a failed connection in a log is the one who can fix a missing
+ * authorization server, and "401" on its own tells them nothing.
+ */
+export function challengeHeaders(resource, auth = {}, { error = 'invalid_token', description } = {}) {
+  const servers = normalizeServers(auth.authorizationServers);
+  // The missing-server note is APPENDED rather than used as a fallback. Whatever went
+  // wrong with this particular request, "there is nowhere configured to get a token" is
+  // the thing that will keep going wrong until someone fixes it, and it must not be
+  // displaced by a more specific message about the immediate failure.
+  const detail = [
+    description || 'Present a bearer token from the configured authorization server.',
+    servers.length ? null
+      : 'No authorization server is configured on this drive. Set TROVE_AUTH_SERVER to the '
+        + 'issuer URL of your identity provider (it defaults to TROVE_JWT_ISSUER when that is set).',
+  ].filter(Boolean).join(' ');
+  return {
+    'www-authenticate': `Bearer realm="Trove", error="${error}", `
+      + `error_description="${headerSafe(detail)}", `
+      + `resource_metadata="${metadataUrl(resource)}"`,
+  };
+}
+
+/**
+ * Make a string safe to put in an HTTP header value.
+ *
+ * Header values are bytes, not text: a curly quote or an em dash — the kind of thing
+ * that shows up the moment a message is written for a person to read — makes the whole
+ * response throw at construction time, turning a helpful 401 into a 500. Quotes would
+ * also end the quoted-string early, so those go too.
+ */
+export function headerSafe(text) {
+  return String(text)
+    .replace(/[\u2018\u2019]/g, "'").replace(/[\u201c\u201d]/g, "'")
+    .replace(/[\u2013\u2014]/g, '-').replace(/\u2026/g, '...')
+    .replace(/["\\]/g, "'")
+    .replace(/[^\x20-\x7e]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+/**
+ * Can this string be published as an authorization server?
+ *
+ * A client will fetch `<value>/.well-known/oauth-authorization-server` and then send a
+ * user — and eventually a bearer token — wherever that leads. So it has to be an
+ * absolute http(s) URL. Plaintext is allowed only on the loopback host, where it is
+ * someone developing rather than a token crossing a network.
+ */
+export function usableAuthServer(value) {
+  let u;
+  try { u = new URL(String(value)); } catch { return false; }
+  if (u.protocol === 'https:') return true;
+  return u.protocol === 'http:' && (u.hostname === 'localhost' || u.hostname === '127.0.0.1' || u.hostname === '[::1]');
+}
+
+/**
+ * Resolve the drive's auth-discovery settings from server config.
+ *
+ * The fallback to the JWT issuer is the useful part: a deployment that already told
+ * Trove which issuer to trust has already told it where the authorization server is,
+ * and asking for the same URL under a second name is a way to get two different answers.
+ *
+ * But it is only sound when the issuer is a URL. A JWT `iss` is StringOrURI — `iss` may
+ * legitimately be `my-gateway` or a URN, and a deployment minting its own tokens often
+ * makes it exactly that. Publishing one of those as an authorization server is WORSE
+ * than publishing nothing: an absent field makes a client report "no authorization
+ * server configured", while a garbage one makes it fail somewhere inside a fetch. So the
+ * inference is filtered, and the reason is reported rather than swallowed.
+ *
+ * @returns {{authorizationServers: string[], source: string, warnings: string[]}}
+ */
+export function resolveAuthDiscovery(config = {}) {
+  const explicit = normalizeServers(config.auth?.authorizationServers ?? config.authServer);
+  const issuer = normalizeServers(config.identity?.jwt?.issuer);
+  const warnings = [];
+
+  // Explicitly configured wins, and is honoured as given — the operator said what they
+  // meant. Plaintext is still called out: the OAuth flow, and the token at the end of
+  // it, travel over whatever this names.
+  const badExplicit = explicit.filter((s) => !usableAuthServer(s));
+  for (const s of badExplicit) {
+    warnings.push(`TROVE_AUTH_SERVER is "${s}", which is not an https URL. Clients will be sent there `
+      + 'to sign in, and a bearer token will travel over it.');
+  }
+  if (explicit.length) {
+    return { authorizationServers: explicit, source: 'configured', warnings, ...passthrough(config) };
+  }
+
+  const inferable = issuer.filter(usableAuthServer);
+  if (issuer.length && !inferable.length) {
+    warnings.push(`TROVE_JWT_ISSUER is "${issuer[0]}", which is not a URL, so it cannot double as an `
+      + 'authorization server. Clients will be told there is nowhere to sign in until you set '
+      + 'TROVE_AUTH_SERVER.');
+  }
+  return {
+    authorizationServers: inferable,
+    // Recorded so a UI can explain where the value came from — "we inferred this from
+    // your JWT issuer" is a different fact from "you set this", and an operator
+    // debugging a mismatch needs to know which.
+    source: inferable.length ? 'jwt-issuer' : 'none',
+    warnings,
+    ...passthrough(config),
+  };
+}
+
+function passthrough(config) {
+  return {
+    scopes: config.auth?.scopes,
+    resourceName: config.auth?.resourceName,
+    documentation: config.auth?.documentation,
+  };
+}

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

@@ -0,0 +1,188 @@
+// Identity — Trove does not run a login system. It expects a trusted identity
+// provider (Cloudflare Access / Zero Trust, an oauth2-proxy, an API gateway…) to
+// authenticate the user and attach proof to each request, and it builds a
+// *profile* (a Principal) around that. An IdentityProvider turns a request into a
+// Principal (or null when anonymous access is allowed).
+//
+// Providers (all injectable into the server):
+//   - JwtIdentityProvider    verify a bearer / Cf-Access-Jwt-Assertion JWT (JWKS)
+//   - HeaderIdentityProvider trust a header a verifying proxy already set
+//   - AnonymousIdentityProvider  everyone is one shared anonymous user (dev)
+//
+// A Principal: { id, email?, name?, picture?, roles?, claims }.
+
+import { TroveError } from '../errors.js';
+import { verifyJwt, JwksClient, StaticJwks } from './jwt.js';
+
+export class IdentityProvider {
+  /** @returns {Promise<Principal|null>} */
+  async authenticate(request) {
+    return null;
+  }
+}
+
+/** Normalize varied IdP claim shapes into a Principal. */
+export function principalFromClaims(claims) {
+  const id = claims.sub || claims.email || claims.user_id || claims.id;
+  if (!id) return null;
+  return {
+    id: String(id),
+    email: claims.email || null,
+    name: claims.name || claims.given_name || claims.preferred_username || (claims.email ? claims.email.split('@')[0] : null),
+    picture: claims.picture || null,
+    roles: claims.roles || claims.groups || [],
+    claims,
+  };
+}
+
+/**
+ * The credential on a request.
+ *
+ * `Cf-Access-Jwt-Assertion` is checked FIRST, and that order matters twice.
+ *
+ * Correctness: with Cloudflare's managed OAuth an agent holds an OPAQUE token, not a
+ * JWT. It sends that in `Authorization: Bearer`, Access resolves it at the edge, and
+ * the origin receives the real signed JWT in the assertion header. Reading Authorization
+ * first means picking up the opaque string, failing to decode it, and refusing a request
+ * that arrived with a perfectly good assertion attached.
+ *
+ * Security: the assertion header is set by the edge that just authenticated the request.
+ * The Authorization header is whatever the client typed. When both are present, the one
+ * we did not have to trust the client for is the one to believe.
+ */
+function bearer(request) {
+  const assertion = request.headers.get('cf-access-jwt-assertion');
+  if (assertion) return assertion;
+  const auth = request.headers.get('authorization') || '';
+  const m = /^Bearer\s+(.+)$/i.exec(auth);
+  return m ? m[1] : null;
+}
+
+/**
+ * Everything Cloudflare Access needs, derived from the team name.
+ *
+ * Access is the deployment Trove was designed around, and configuring it by hand means
+ * writing the team domain into three settings that must agree: a JWKS URL with a
+ * `/cdn-cgi/access/certs` path nobody remembers, an issuer, and — since Access became an
+ * OAuth authorization server for agents — the authorization server too. They are all the
+ * same domain, so ask for it once.
+ *
+ * The audience is the Access **application** AUD tag, which is per-application and the
+ * one value that genuinely cannot be derived. Without it a token minted for any other
+ * app in the same Access account would be accepted here, so it is worth the argument.
+ *
+ * @param {{team: string, audience?: string|string[], required?: boolean}} cfg
+ */
+export function cloudflareAccess({ team, audience, required = true, ...rest } = {}) {
+  const host = accessHost(team);
+  if (!host) throw TroveError.invalid('cloudflareAccess requires a team name, e.g. "myteam" or "myteam.cloudflareaccess.com"');
+  const issuer = `https://${host}`;
+  return {
+    jwksUrl: `${issuer}/cdn-cgi/access/certs`,
+    issuer,
+    audience: audience || undefined,
+    // Behind Access, every request has already been authenticated at the edge. An
+    // "anonymous" fallthrough would only fire when something is misconfigured, and
+    // silently serving the drive to a shared anonymous user is the wrong way to find out.
+    required,
+    ...rest,
+  };
+}
+
+/** Normalize `myteam`, `myteam.cloudflareaccess.com`, or the full URL to a hostname. */
+export function accessHost(team) {
+  if (!team) return null;
+  let t = String(team).trim().replace(/^https?:\/\//, '').replace(/\/.*$/, '').toLowerCase();
+  if (!t) return null;
+  if (!t.includes('.')) t = `${t}.cloudflareaccess.com`;
+  // A team domain that isn't Cloudflare's is a typo we should not paper over: it would
+  // send token verification, and now agent sign-in, to somewhere unintended.
+  if (!t.endsWith('.cloudflareaccess.com')) {
+    throw TroveError.invalid(`"${team}" is not a Cloudflare Access team domain (expected <team>.cloudflareaccess.com)`);
+  }
+  return t;
+}
+
+export class JwtIdentityProvider extends IdentityProvider {
+  /**
+   * @param {object} cfg
+   * @param {string} [cfg.jwksUrl]  e.g. https://<team>.cloudflareaccess.com/cdn-cgi/access/certs
+   * @param {object|object[]} [cfg.jwks]  a JWKS document (or bare JWK array) to trust
+   *   directly — the keychain for a deployment that mints its own tokens and has no
+   *   JWKS endpoint to point at. Takes precedence over `jwksUrl`.
+   * @param {string|Uint8Array} [cfg.secret]  for HS256 (dev)
+   * @param {string} [cfg.issuer]
+   * @param {string|string[]} [cfg.audience]  the Access application AUD
+   * @param {boolean} [cfg.required]  reject anonymous requests (default false)
+   * @param {(req)=>string|null} [cfg.getToken]  override token extraction
+   */
+  constructor(cfg = {}) {
+    super();
+    this.cfg = cfg;
+    // A held key set beats a fetched one: if you named the keys explicitly, that is the
+    // stronger statement of intent, and it can't fail because a network hop did.
+    this.jwks = cfg.jwks ? new StaticJwks(cfg.jwks)
+      : cfg.jwksUrl ? new JwksClient(cfg.jwksUrl, { fetch: cfg.fetch })
+        : null;
+    this.getToken = cfg.getToken || bearer;
+  }
+  async authenticate(request) {
+    const token = this.getToken(request);
+    if (!token) {
+      if (this.cfg.required) throw TroveError.unauthorized('Authentication required');
+      return null;
+    }
+    let claims;
+    try {
+      claims = await verifyJwt(token, {
+        jwks: this.jwks, secret: this.cfg.secret,
+        issuer: this.cfg.issuer, audience: this.cfg.audience,
+        algorithms: this.cfg.algorithms, now: this.cfg.now,
+      });
+    } catch (err) {
+      // A credential we can't parse is an AUTHENTICATION failure, not a malformed
+      // request: `decodeJwt` reports a garbled token as `invalid` (400), which tells a
+      // client "you sent a bad request" when the truth is "sign in again". A transient
+      // failure (the JWKS endpoint being down) is left alone — that is not the user's
+      // token being wrong, and retrying is the right response to it.
+      if (err?.code === 'transient') throw err;
+      throw TroveError.unauthorized(err?.message || 'Authentication failed', { cause: err });
+    }
+    const principal = principalFromClaims(claims);
+    if (!principal) throw TroveError.unauthorized('JWT has no subject');
+    return principal;
+  }
+}
+
+/** Trust a header set by a verifying reverse proxy (already authenticated). */
+export class HeaderIdentityProvider extends IdentityProvider {
+  /** @param {{idHeader?: string, emailHeader?: string, nameHeader?: string, required?: boolean}} cfg */
+  constructor(cfg = {}) {
+    super();
+    this.cfg = { idHeader: 'x-auth-user-id', emailHeader: 'x-auth-email', nameHeader: 'x-auth-name', ...cfg };
+  }
+  async authenticate(request) {
+    const id = request.headers.get(this.cfg.idHeader) || request.headers.get(this.cfg.emailHeader);
+    if (!id) {
+      if (this.cfg.required) throw TroveError.unauthorized('Authentication required');
+      return null;
+    }
+    const email = request.headers.get(this.cfg.emailHeader);
+    return principalFromClaims({ sub: id, email, name: request.headers.get(this.cfg.nameHeader) });
+  }
+}
+
+/** Everyone is the same anonymous user — the zero-config default. */
+export class AnonymousIdentityProvider extends IdentityProvider {
+  constructor({ id = 'anonymous', name = 'Anonymous' } = {}) {
+    super();
+    // `anonymous: true` is what lets everything downstream tell "one shared unnamed
+    // user" apart from "a person who signed in". Without it the shape is identical to a
+    // real principal, and the UI ends up showing a profile for somebody who doesn't
+    // exist — an avatar, a name, a menu, all describing nobody.
+    this.principal = { id, email: null, name, picture: null, roles: [], anonymous: true, claims: {} };
+  }
+  async authenticate() {
+    return this.principal;
+  }
+}

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

@@ -0,0 +1,199 @@
+// JWT verification on Web Crypto — no node crypto, no deps, so it runs on Node,
+// Bun, and Cloudflare Workers. Supports the algorithms an identity provider like
+// Cloudflare Access / Zero Trust actually issues (RS256, ES256 via a JWKS
+// endpoint) plus HS256 (shared secret) for local/dev. Trove never issues tokens;
+// it only VERIFIES the one a trusted IdP put on the request, then builds a
+// profile from the claims.
+
+import { TroveError } from '../errors.js';
+
+const enc = new TextEncoder();
+// How long a `kid` miss suppresses another JWKS refetch. Long enough that a flood of
+// unknown kids costs one request, short enough that a real key rotation is picked up
+// well inside a token's lifetime.
+const MISS_REFRESH_COOLDOWN_MS = 30_000;
+
+export function base64urlToBytes(str) {
+  const b64 = str.replace(/-/g, '+').replace(/_/g, '/').padEnd(Math.ceil(str.length / 4) * 4, '=');
+  const bin = atob(b64);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+function base64urlToString(str) {
+  return new TextDecoder().decode(base64urlToBytes(str));
+}
+
+/** Split & decode without verifying (header + payload only). */
+export function decodeJwt(token) {
+  const parts = token.split('.');
+  if (parts.length !== 3) throw TroveError.invalid('Malformed JWT');
+  let header, payload;
+  try {
+    header = JSON.parse(base64urlToString(parts[0]));
+    payload = JSON.parse(base64urlToString(parts[1]));
+  } catch {
+    throw TroveError.invalid('JWT is not valid JSON');
+  }
+  return { header, payload, parts };
+}
+
+const ALGS = {
+  RS256: { import: { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' }, verify: { name: 'RSASSA-PKCS1-v1_5' } },
+  ES256: { import: { name: 'ECDSA', namedCurve: 'P-256' }, verify: { name: 'ECDSA', hash: 'SHA-256' } },
+  HS256: { import: { name: 'HMAC', hash: 'SHA-256' }, verify: { name: 'HMAC' } },
+};
+
+/** A JWKS resolver with a small in-memory cache; refetches on a kid miss. */
+export class JwksClient {
+  constructor(url, { fetch: f = globalThis.fetch?.bind(globalThis), ttlMs = 3600_000 } = {}) {
+    if (!url) throw TroveError.invalid('JwksClient requires a url');
+    this.url = url;
+    this._fetch = f;
+    this.ttlMs = ttlMs;
+    this.keys = new Map(); // kid -> jwk
+    this.fetchedAt = 0;
+  }
+  async #refresh(force) {
+    const now = this._now();
+    if (!force && this.keys.size && now - this.fetchedAt < this.ttlMs) return;
+    let res;
+    try {
+      res = await this._fetch(this.url);
+    } catch (err) {
+      throw TroveError.transient('Could not fetch JWKS', { cause: err });
+    }
+    if (!res.ok) throw TroveError.transient(`JWKS fetch failed (${res.status})`);
+    const json = await res.json();
+    this.keys = new Map((json.keys || []).map((k) => [k.kid, k]));
+    this.fetchedAt = now;
+  }
+  _now() {
+    // Date.now() is unavailable in some sandboxes; tolerate its absence.
+    try {
+      return Date.now();
+    } catch {
+      return this.fetchedAt || 0;
+    }
+  }
+  async getJwk(kid) {
+    await this.#refresh(false);
+    // A miss forces a refetch so a freshly-rotated key is picked up — but ONLY if we
+    // haven't just done that. Unbounded, this ran during authentication, before any
+    // credential was checked, so anyone who could reach the API pinned one outbound
+    // HTTPS request to the IdP per inbound request simply by varying `kid`.
+    if (!this.keys.has(kid) && Date.now() - (this._lastMissRefresh || 0) > MISS_REFRESH_COOLDOWN_MS) {
+      this._lastMissRefresh = Date.now();
+      await this.#refresh(true);
+    }
+    return this.keys.get(kid) || null;
+  }
+}
+
+/**
+ * A fixed set of trusted keys — a JWKS you hold rather than one you fetch.
+ *
+ * Same interface as JwksClient, so `verifyJwt` can't tell them apart. It exists because
+ * a JWKS URL assumes someone is running an endpoint to serve it, and plenty of
+ * deployments simply mint their own tokens: a small team, a script, a gateway that
+ * signs with a key you already have. Pointing those at a URL means standing up an HTTP
+ * server whose entire job is to hand back a JSON document you could have pasted in.
+ *
+ * A token whose `kid` isn't in the set is refused. A set with exactly one key accepts a
+ * token with no `kid` at all, since there is no ambiguity about which key was meant —
+ * but with several, an unlabelled token is rejected rather than tried against each,
+ * because "try every key until one verifies" turns key rotation into key confusion.
+ */
+export class StaticJwks {
+  /** @param {{keys: object[]}|object[]} jwks a JWKS document or a bare array of JWKs */
+  constructor(jwks) {
+    const keys = Array.isArray(jwks) ? jwks : jwks?.keys;
+    if (!Array.isArray(keys) || !keys.length) throw TroveError.invalid('StaticJwks requires at least one JWK');
+    this.list = keys;
+    this.keys = new Map(keys.filter((k) => k.kid).map((k) => [k.kid, k]));
+  }
+  async getJwk(kid) {
+    if (kid) return this.keys.get(kid) || null;
+    return this.list.length === 1 ? this.list[0] : null;
+  }
+}
+
+async function importVerifyKey(alg, key) {
+  const spec = ALGS[alg];
+  if (!spec) throw TroveError.unsupported(`Unsupported JWT alg ${alg}`);
+  if (alg === 'HS256') {
+    const raw = typeof key === 'string' ? enc.encode(key) : key;
+    return crypto.subtle.importKey('raw', raw, spec.import, false, ['verify']);
+  }
+  // key is a JWK object.
+  return crypto.subtle.importKey('jwk', key, spec.import, false, ['verify']);
+}
+
+/**
+ * Verify a JWT and return its payload, or throw a TroveError.
+ * @param {string} token
+ * @param {object} opts
+ * @param {JwksClient} [opts.jwks]     for RS256/ES256
+ * @param {string|Uint8Array} [opts.secret] for HS256
+ * @param {string} [opts.issuer]       required `iss`
+ * @param {string|string[]} [opts.audience] required `aud` (any match)
+ * @param {string[]} [opts.algorithms] allow-list (default derived from key material)
+ * @param {number} [opts.clockToleranceSec]
+ * @param {number|null} [opts.now]     ms epoch; pass null to say there is no clock
+ */
+export async function verifyJwt(token, opts = {}) {
+  const { header, payload, parts } = decodeJwt(token);
+  const alg = header.alg;
+  const allowed = opts.algorithms || (opts.secret ? ['HS256'] : ['RS256', 'ES256']);
+  if (!allowed.includes(alg)) throw TroveError.unauthorized(`JWT alg ${alg} not allowed`);
+
+  let key;
+  if (alg === 'HS256') {
+    if (!opts.secret) throw TroveError.unauthorized('No secret configured for HS256');
+    key = await importVerifyKey(alg, opts.secret);
+  } else {
+    if (!opts.jwks) throw TroveError.unauthorized('No JWKS configured');
+    const jwk = await opts.jwks.getJwk(header.kid);
+    if (!jwk) throw TroveError.unauthorized(`No JWKS key for kid ${header.kid}`);
+    key = await importVerifyKey(alg, jwk);
+  }
+
+  const signingInput = enc.encode(parts[0] + '.' + parts[1]);
+  const signature = base64urlToBytes(parts[2]);
+  const ok = await crypto.subtle.verify(ALGS[alg].verify, key, signature, signingInput);
+  if (!ok) throw TroveError.unauthorized('JWT signature is invalid');
+
+  // Claims.
+  // undefined means "not specified" (use the real clock); null means "there is no
+  // clock". `??` would collapse the two, hiding the very case being configured — and
+  // callers routinely pass `now: cfg.now` with cfg.now undefined.
+  const nowMs = opts.now === undefined ? safeNow() : opts.now;
+  const skew = opts.clockToleranceSec ?? 60;
+  // No clock means no way to honour `exp`. Refusing is the only safe answer: treating
+  // an unreadable clock as "not expired yet" would accept a token that expired last
+  // year, which is precisely the failure expiry exists to prevent. Tokens carrying no
+  // time claims are unaffected — there is nothing to check.
+  if (nowMs == null && (payload.exp != null || payload.nbf != null)) {
+    throw TroveError.unauthorized('JWT carries time claims but this runtime has no clock to check them against');
+  }
+  const now = Math.floor(nowMs / 1000);
+  if (payload.exp != null && now > payload.exp + skew) throw TroveError.unauthorized('JWT expired');
+  if (payload.nbf != null && now + skew < payload.nbf) throw TroveError.unauthorized('JWT not yet valid');
+  if (opts.issuer && payload.iss !== opts.issuer) throw TroveError.unauthorized('JWT issuer mismatch');
+  if (opts.audience) {
+    const auds = Array.isArray(payload.aud) ? payload.aud : [payload.aud];
+    const want = Array.isArray(opts.audience) ? opts.audience : [opts.audience];
+    if (!auds.some((a) => want.includes(a))) throw TroveError.unauthorized('JWT audience mismatch');
+  }
+  return payload;
+}
+
+/** ms epoch, or null when the runtime has no clock. Null, NOT 0 — see verifyJwt. */
+function safeNow() {
+  try {
+    const t = Date.now();
+    return Number.isFinite(t) && t > 0 ? t : null;
+  } catch {
+    return null;
+  }
+}