@rebasepro/server 0.14.0 → 0.14.1

package/dist/{jwt-_IFqfTOg.js → jwt-VJyXTdQQ.js}

@@ -2,8 +2,123 @@ import { createRequire as __createRequire } from "module";
 import process from "process";
 __createRequire(import.meta.url);
 import { i as __toESM, n as __exportAll, r as __require, t as __commonJSMin } from "./rolldown-runtime-DSJWtz9O.js";
+import "./src-Cz9nMgUR.js";
 import { t as logger } from "./logger-DfvF_8r-.js";
-import { createHash, randomBytes } from "crypto";
+import { createHash, createPrivateKey, createPublicKey, randomBytes } from "crypto";
+import path from "node:path";
+//#region ../types/src/types/storage_source.ts
+/**
+* Describes a named storage backend — a place files live.
+*
+* Declared once and shared front + back: the frontend uses it to decide
+* transport (HTTP proxy vs direct SDK), the backend uses the same `key`
+* to resolve a StorageController, and collection properties reference
+* a definition by its `key` via `StorageConfig.storageSource`.
+*
+* This mirrors the {@link DataSourceDefinition} pattern used for databases.
+*
+* @group Models
+*/
+/**
+* The default storage source key, used when a property does not specify
+* a `storageSource`. Shared by the frontend and backend registries so
+* both agree on "the default storage backend".
+* @group Models
+*/
+var DEFAULT_STORAGE_SOURCE_KEY = "(default)";
+/**
+* The environment-variable suffix for a storage or data source key.
+*
+* `""` for the default source — so a single-bucket project keeps configuring
+* plain `S3_BUCKET` — and `__<KEY>` for every named one, uppercased with
+* non-alphanumerics collapsed to underscores: `media-cdn` → `S3_BUCKET__MEDIA_CDN`.
+*
+* The rule derives the variable name from the declared key rather than
+* discovering keys by scanning the environment. Scanning would have to guess how
+* `S3_BUCKET__MEDIA_CDN` splits into a key; deriving cannot be ambiguous, and a
+* typo surfaces as a missing source at boot instead of a silently ignored
+* variable.
+*
+* It lives in this package, with no dependencies, because four things must agree
+* on it exactly: the CLI (validating a build), the runtime (reading its own
+* environment), the control plane (writing a tenant's Secret), and the docs. A
+* second implementation of a naming convention is a second chance to disagree.
+*
+* @group Models
+*/
+function storageEnvSuffix(key, defaultKey = DEFAULT_STORAGE_SOURCE_KEY) {
+	if (!key || key === defaultKey) return "";
+	const normalized = key.replace(/[^A-Za-z0-9]+/g, "_").replace(/^_+|_+$/g, "").toUpperCase();
+	if (!normalized) throw new Error(`Source key "${key}" cannot be turned into an environment variable name. Use a key containing at least one letter or digit.`);
+	return `__${normalized}`;
+}
+/**
+* Two distinct keys that collapse onto the same variable name, or `null`.
+*
+* `media-cdn` and `media_cdn` are different source keys but the same suffix, so
+* without this one of them silently reads the other's configuration. Returns the
+* offending pair rather than throwing, so each caller can raise it in its own
+* idiom — a `BundleError` at boot, a build failure in the CLI, a rejected deploy
+* in a control plane.
+*
+* @group Models
+*/
+function findStorageSuffixCollision(keys, defaultKey = DEFAULT_STORAGE_SOURCE_KEY) {
+	const seen = /* @__PURE__ */ new Map();
+	for (const key of keys) {
+		const suffix = storageEnvSuffix(key, defaultKey);
+		const existing = seen.get(suffix);
+		if (existing !== void 0 && existing !== key) return {
+			a: existing,
+			b: key,
+			suffix
+		};
+		seen.set(suffix, key);
+	}
+	return null;
+}
+/**
+* Merge the two places a project may declare storage sources into one list.
+*
+* `rebase.json` is authoritative for every field it states. Config code may add
+* sources it does not mention and fill in fields it left out, but may not
+* contradict it: the manifest is what a host reads to decide which buckets need
+* configuring, and a runtime that quietly disagreed with it would put the
+* console back to describing a topology the tenant does not have — the exact
+* failure this whole mechanism exists to end.
+*
+* Note what is *not* here: no default source is invented when both inputs are
+* empty. That decision belongs to the resolver, which knows whether declaring
+* nothing means "one plain bucket" (it does) or "no storage at all".
+*
+* @group Models
+*/
+function normalizeStorageSources(declared, exported) {
+	const merged = /* @__PURE__ */ new Map();
+	const declaredEntries = Array.isArray(declared) ? declared.filter((d) => d?.key).map((d) => [d.key, d]) : Object.entries(declared ?? {});
+	for (const [key, config] of declaredEntries) merged.set(key, {
+		key,
+		engine: config.engine,
+		transport: config.transport ?? "server",
+		...config.label !== void 0 ? { label: config.label } : {}
+	});
+	for (const definition of exported ?? []) {
+		if (!definition?.key) continue;
+		const existing = merged.get(definition.key);
+		if (!existing) {
+			merged.set(definition.key, {
+				key: definition.key,
+				engine: definition.engine,
+				transport: definition.transport ?? "server",
+				...definition.label !== void 0 ? { label: definition.label } : {}
+			});
+			continue;
+		}
+		if (existing.label === void 0 && definition.label !== void 0) existing.label = definition.label;
+	}
+	return Array.from(merged.values());
+}
+//#endregion
 //#region ../../node_modules/.pnpm/safe-buffer@5.2.1/node_modules/safe-buffer/index.js
 var require_safe_buffer = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 	/*! safe-buffer. MIT License. Feross Aboukhadijeh <https://feross.org/opensource> */
@@ -3904,7 +4019,7 @@ var require_sign = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 	var isPlainObject = require_lodash_isplainobject();
 	var isString = require_lodash_isstring();
 	var once = require_lodash_once();
-	var { KeyObject, createSecretKey, createPrivateKey } = __require("crypto");
+	var { KeyObject, createSecretKey, createPrivateKey: createPrivateKey$1 } = __require("crypto");
 	var SUPPORTED_ALGS = [
 		"RS256",
 		"RS384",
@@ -4045,7 +4160,7 @@ var require_sign = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 		}
 		if (!secretOrPrivateKey && options.algorithm !== "none") return failure(/* @__PURE__ */ new Error("secretOrPrivateKey must have a value"));
 		if (secretOrPrivateKey != null && !(secretOrPrivateKey instanceof KeyObject)) try {
-			secretOrPrivateKey = createPrivateKey(secretOrPrivateKey);
+			secretOrPrivateKey = createPrivateKey$1(secretOrPrivateKey);
 		} catch (_) {
 			try {
 				secretOrPrivateKey = createSecretKey(typeof secretOrPrivateKey === "string" ? Buffer.from(secretOrPrivateKey) : secretOrPrivateKey);
@@ -4147,6 +4262,264 @@ var require_jsonwebtoken = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 	};
 }));
 //#endregion
+//#region src/storage/keys.ts
+var import_jsonwebtoken = /* @__PURE__ */ __toESM(require_jsonwebtoken(), 1);
+/**
+* Canonical storage keys and bucket names.
+*
+* Storage is not under RLS, so a `storageAuthorize` hook is the whole access
+* control model — and a hook can only be correct if the key it is shown is the
+* key that is written. That is the invariant this module exists to hold: one
+* canonical string, computed once per request, handed to the hook, to the
+* controller, and to the download token alike.
+*
+* ## Why rejecting beats stripping
+*
+* The previous `sanitizeStorageKey` *stripped* `../` in a single pass. Two
+* things were wrong with that, and only one of them was the obvious one.
+*
+* The obvious one: a single pass is not a fixed point. `....//` contains `../`
+* at offset 2, so removing it leaves `../` behind — the sanitizer manufactured
+* the traversal it was there to remove. `users/alice/....//bob/x` came out as
+* `users/alice/../bob/x`, which a prefix hook reads as alice's (it starts with
+* `users/alice/`) and the filesystem reads as bob's. The hook approved one
+* object and the controller wrote another.
+*
+* The subtler one, and the reason this is a rewrite rather than a loop: even a
+* correct strip is a silent rewrite. A caller who asks to store at `a/../b` and
+* gets an object at `a/b` was not protected, they were misled — and every later
+* read, ownership row and audit line now refers to a path nobody chose. So a key
+* that means something other than what it says is refused (400), not repaired.
+*
+* Note what is NOT traversal under this rule: `....` is an ordinary directory
+* name, and `users/alice/....//bob/x` canonicalizes to
+* `users/alice/..../bob/x` — still comfortably inside alice's prefix, which is
+* exactly right. Only a real `..` segment is refused.
+*/
+/** Longest key accepted, in UTF-16 code units. Matches the previous cap. */
+var MAX_STORAGE_KEY_LENGTH = 1024;
+/**
+* A key that cannot be canonicalized. Carries no path back to the caller
+* beyond what they sent, so it is safe to surface as a 400 message.
+*/
+var InvalidStorageKeyError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "InvalidStorageKeyError";
+	}
+};
+/**
+* Canonicalize a caller-supplied storage key, or throw
+* {@link InvalidStorageKeyError}.
+*
+* Normalizations applied (safe, idempotent, and meaning-preserving):
+* - leading slashes removed — `/a/b` and `a/b` name the same object
+* - `.` segments and repeated slashes collapsed
+*
+* Refusals (the key means something other than what it says):
+* - any `..` segment, on either separator, at any depth
+* - null bytes
+* - keys longer than {@link MAX_STORAGE_KEY_LENGTH}
+*
+* A trailing slash is preserved: it is how the folder route marks a prefix.
+*/
+function canonicalStorageKey(rawKey) {
+	if (rawKey.includes("\0")) throw new InvalidStorageKeyError("Storage key contains a null byte.");
+	if (rawKey.length > 1024) throw new InvalidStorageKeyError(`Storage key exceeds the maximum length of ${MAX_STORAGE_KEY_LENGTH} characters.`);
+	if (rawKey.split(/[\\/]/).some((segment) => segment === "..")) throw new InvalidStorageKeyError("Storage key contains a '..' path segment. Keys must name an object directly.");
+	const withoutLeadingSlashes = rawKey.replace(/^\/+/, "");
+	if (withoutLeadingSlashes === "") return "";
+	const denotesDirectory = /(?:^|\/)\.?$/.test(withoutLeadingSlashes);
+	const normalized = path.posix.normalize(withoutLeadingSlashes);
+	if (normalized === "." || normalized === "./") return "";
+	const key = normalized.replace(/^\.\//, "").replace(/^\/+/, "");
+	if (key === "") return "";
+	return denotesDirectory && !key.endsWith("/") ? `${key}/` : key;
+}
+/**
+* Canonicalize, or return `null` when the key is not canonicalizable.
+*
+* For callers that must fail closed without an exception — the download-token
+* middleware compares a request path against a granted path, and a key it
+* cannot canonicalize simply matches nothing.
+*/
+function tryCanonicalStorageKey(rawKey) {
+	try {
+		return canonicalStorageKey(rawKey);
+	} catch {
+		return null;
+	}
+}
+/**
+* Canonicalize the storage *source* a request names (`?storageId=`), so that
+* "the default source" has exactly one spelling.
+*
+* The default source can be asked for three ways — the parameter omitted, sent
+* empty, or sent as the literal `(default)` — and all three resolve to the same
+* controller. Without a single spelling, the value derived when a download
+* token is minted and the value derived when it is presented can differ for the
+* same object, which is either a spurious 403 or, if the comparison is dropped
+* to stop those, no scoping at all.
+*
+* Deliberately *not* validated against the registry: this is a naming rule, not
+* an existence check, and it must give the same answer in `auth/` (which has no
+* registry) as in the storage routes. An id that names no source still
+* canonicalizes to itself and simply matches only itself.
+*/
+function canonicalStorageId(rawStorageId) {
+	if (rawStorageId === void 0 || rawStorageId === null) return DEFAULT_STORAGE_SOURCE_KEY;
+	const trimmed = rawStorageId.trim();
+	return trimmed === "" ? DEFAULT_STORAGE_SOURCE_KEY : trimmed;
+}
+/** A bucket name that does not name a bucket. See {@link canonicalStorageBucket}. */
+var InvalidStorageBucketError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "InvalidStorageBucketError";
+	}
+};
+/**
+* One path segment: letters, digits, `.`, `_`, `-`, first character
+* alphanumeric. Deliberately narrow — it is the intersection of what S3, GCS
+* and a filesystem directory all accept, and it makes `..`, `.tus-uploads`,
+* absolute paths and anything containing a separator unrepresentable.
+*/
+var STORAGE_BUCKET_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/**
+* Canonicalize a caller-supplied bucket name, or throw
+* {@link InvalidStorageBucketError}.
+*
+* The bucket is the *other* caller-controlled routing value in an upload
+* request, and it was the one nobody validated. `LocalStorageController`
+* builds `join(basePath, bucket)` and then checks containment against that
+* result, so a bucket of `../../etc` moved the boundary rather than crossing
+* it — the guard passed because the guard's reference point was the attacker's.
+* The containment check now resolves against the storage root, and this is the
+* check at the route boundary that stops the value before it gets there.
+*
+* A bucket is configuration, not user data: there is no legitimate caller that
+* needs a separator, a leading dot, or a `..` in one. So this refuses rather
+* than repairs, exactly as {@link canonicalStorageKey} does — a rewritten
+* bucket would silently store the object somewhere the caller did not ask for.
+*
+* Returns `undefined` when the caller named no bucket (absent, or an empty
+* form field), which is how every controller spells "use my default". An empty
+* string used to reach `getFullPath` and resolve to the storage *root* rather
+* than the `default` bucket, which is a third place a bare key did not
+* round-trip.
+*/
+function canonicalStorageBucket(rawBucket) {
+	if (rawBucket === void 0 || rawBucket === null || rawBucket === "") return void 0;
+	if (rawBucket.length > 63) throw new InvalidStorageBucketError(`Storage bucket exceeds the maximum length of 63 characters.`);
+	if (!STORAGE_BUCKET_PATTERN.test(rawBucket)) throw new InvalidStorageBucketError("Storage bucket must be a single name of letters, digits, '.', '_' or '-', starting with a letter or digit.");
+	return rawBucket;
+}
+//#endregion
+//#region src/auth/jwt-keys.ts
+/**
+* The algorithm a key type implies.
+*
+* Rejecting anything else here rather than defaulting is deliberate: an Ed25519
+* key configured by someone expecting it to work would otherwise be signed with
+* `RS256` in the header and fail verification everywhere, at runtime, on tokens
+* already handed to users.
+*/
+function algorithmForKey(key, kid) {
+	switch (key.asymmetricKeyType) {
+		case "rsa":
+		case "rsa-pss": return "RS256";
+		case "ec": return "ES256";
+		default: throw new Error(`JWT signing key "${kid}" is a ${key.asymmetricKeyType ?? "non-asymmetric"} key. Supported: RSA (RS256) and EC P-256 (ES256). Generate one with: openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -out jwt-key.pem`);
+	}
+}
+/**
+* An EC key of the wrong curve is the other way a key parses cleanly and then
+* fails to verify: `ES256` means P-256 specifically, and a P-384 key signs a
+* token whose header says P-256's algorithm.
+*/
+function assertCurveMatches(publicKey, kid) {
+	const jwk = publicKey.export({ format: "jwk" });
+	if (jwk.crv && jwk.crv !== "P-256") throw new Error(`JWT signing key "${kid}" uses curve ${jwk.crv}, but ES256 requires P-256. Generate one with: openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -out jwt-key.pem`);
+}
+/**
+* Parse the configured keys, deriving each public half from its private key.
+*
+* Throws on anything malformed. This runs at boot, from `configureJwt`, so a
+* key that cannot sign takes the process down at start rather than at the first
+* login — the same bargain every other credential in this file makes.
+*/
+function resolveSigningKeys(configs) {
+	const seen = /* @__PURE__ */ new Set();
+	return configs.map((config) => {
+		if (!config.kid) throw new Error("Every JWT signing key needs a `kid`; it is what the JWKS and the token header agree on.");
+		if (seen.has(config.kid)) throw new Error(`Duplicate JWT signing key id "${config.kid}". A \`kid\` selects exactly one key at verification time, so two keys sharing one is a token that verifies or does not depending on order.`);
+		seen.add(config.kid);
+		let privateKey;
+		try {
+			privateKey = createPrivateKey(config.privateKey);
+		} catch (error) {
+			throw new Error(`JWT signing key "${config.kid}" is not a readable PEM private key: ${error instanceof Error ? error.message : String(error)}`);
+		}
+		const publicKey = createPublicKey(privateKey);
+		const derived = algorithmForKey(privateKey, config.kid);
+		const algorithm = config.algorithm ?? derived;
+		if (algorithm !== derived) throw new Error(`JWT signing key "${config.kid}" is declared as ${algorithm} but is a ${privateKey.asymmetricKeyType} key, which signs ${derived}.`);
+		if (algorithm === "ES256") assertCurveMatches(publicKey, config.kid);
+		return {
+			kid: config.kid,
+			algorithm,
+			privateKey,
+			publicKey
+		};
+	});
+}
+/**
+* The key a token names, or `null` if it names none we hold.
+*
+* The returned algorithm is the *key's*, and the caller must verify with that
+* one alone. See the module docblock for what happens otherwise.
+*/
+function resolveVerificationKey(keys, kid) {
+	if (!kid) return null;
+	return keys.find((key) => key.kid === kid) ?? null;
+}
+/**
+* A PEM as an environment variable can actually carry it.
+*
+* A PEM is multi-line and environment variables are not, so every deployment
+* tool solves it differently: `.env` files and most secret managers escape the
+* newlines to `\n`, Kubernetes and Docker secrets pass the bytes through
+* intact, and CI systems that mangle both are usually fed base64. All three
+* arrive here, and guessing wrong produces "not a readable PEM private key" at
+* boot with a key the operator can see is perfectly valid.
+*
+* Detection is on content, not on a flag: a PEM says so on its first line, and
+* anything that does not is tried as base64.
+*/
+function normalizePemFromEnv(value) {
+	const trimmed = value.trim();
+	if (trimmed.includes("-----BEGIN")) return trimmed.replace(/\\n/g, "\n");
+	return Buffer.from(trimmed, "base64").toString("utf8");
+}
+/**
+* The public halves, in JWKS form.
+*
+* Node exports a JWK containing only public parameters for a public
+* `KeyObject` — no `d`, no primes — so the private material cannot leak
+* through this path even if a private key were passed by mistake. The keys are
+* derived from `publicKey` regardless, and this is asserted in the tests,
+* because "cannot" is worth checking on the one endpoint whose entire job is to
+* be world-readable.
+*/
+function toJwks(keys) {
+	return { keys: keys.map((key) => ({
+		...key.publicKey.export({ format: "jwk" }),
+		kid: key.kid,
+		alg: key.algorithm,
+		use: "sig"
+	})) };
+}
+//#endregion
 //#region src/auth/jwt.ts
 var jwt_exports = /* @__PURE__ */ __exportAll({
 	MAX_COOKIE_AGE_MS: () => MAX_COOKIE_AGE_MS,
@@ -4158,21 +4531,31 @@ var jwt_exports = /* @__PURE__ */ __exportAll({
 	generateRefreshToken: () => generateRefreshToken,
 	getAccessTokenExpiry: () => getAccessTokenExpiry,
 	getAccessTokenExpiryMs: () => getAccessTokenExpiryMs,
+	getJwks: () => getJwks,
 	getRefreshTokenExpiry: () => getRefreshTokenExpiry,
 	getRefreshTokenTtlMs: () => getRefreshTokenTtlMs,
+	hasAsymmetricSigningKey: () => hasAsymmetricSigningKey,
 	hashRefreshToken: () => hashRefreshToken,
 	isJwtConfigured: () => isJwtConfigured,
 	verifyAccessToken: () => verifyAccessToken,
 	verifyDownloadToken: () => verifyDownloadToken,
 	verifyMfaPendingToken: () => verifyMfaPendingToken
 });
-var import_jsonwebtoken = /* @__PURE__ */ __toESM(require_jsonwebtoken(), 1);
 var jwtConfig = {
 	secret: "",
 	accessExpiresIn: "1h",
 	refreshExpiresIn: "400d"
 };
 /**
+* The parsed signing keys, and which one mints new access tokens.
+*
+* Both are module state beside `jwtConfig` for the same reason it is: every
+* signing and verifying path in the server reads them through this file, and
+* there is exactly one JWT configuration per process.
+*/
+var signingKeys = [];
+var activeSigningKey = null;
+/**
 * Configure JWT settings - call this during initialization.
 * Validates the secret strength to prevent deployment with default/weak secrets.
 */
@@ -4200,10 +4583,33 @@ function configureJwt(config) {
 	]);
 	if (!config.secret || config.secret.length < 32) throw new Error("JWT secret is too short. Must be at least 32 characters. Generate one with: node -e \"logger.info(require('crypto').randomBytes(48).toString('base64'))\"");
 	if (weakSecrets.has(config.secret.toLowerCase())) throw new Error("JWT secret is a known default/weak value. Please use a strong, randomly generated secret. Generate one with: node -e \"logger.info(require('crypto').randomBytes(48).toString('base64'))\"");
+	const resolved = config.signingKeys ? resolveSigningKeys(config.signingKeys) : [];
+	let active = null;
+	if (resolved.length > 0) if (config.activeKid) {
+		active = resolved.find((key) => key.kid === config.activeKid) ?? null;
+		if (!active) throw new Error(`auth.activeKid is "${config.activeKid}", which is not among the configured signing keys (${resolved.map((k) => `"${k.kid}"`).join(", ")}). Signing with a key nobody published produces tokens no verifier can check.`);
+	} else active = resolved[0];
 	jwtConfig = {
 		...jwtConfig,
 		...config
 	};
+	signingKeys = resolved;
+	activeSigningKey = active;
+}
+/**
+* The public keys, in JWKS form, for `/.well-known/jwks.json`.
+*
+* An empty `keys` array on a backend with no asymmetric keys configured is the
+* correct answer rather than a 404: it says "this issuer publishes none",
+* which a verifier can act on, where a 404 is indistinguishable from a
+* misconfigured URL.
+*/
+function getJwks() {
+	return toJwks(signingKeys);
+}
+/** Is this backend signing access tokens asymmetrically? */
+function hasAsymmetricSigningKey() {
+	return activeSigningKey !== null;
 }
 /**
 * Has this server been given a JWT secret?
@@ -4230,6 +4636,11 @@ function generateAccessToken(uid, roles, aal = "aal1", customClaims) {
 		...customClaims,
 		aal
 	};
+	if (activeSigningKey) return import_jsonwebtoken.default.sign(payload, activeSigningKey.privateKey, {
+		expiresIn: jwtConfig.accessExpiresIn,
+		algorithm: activeSigningKey.algorithm,
+		keyid: activeSigningKey.kid
+	});
 	return import_jsonwebtoken.default.sign(payload, jwtConfig.secret, {
 		expiresIn: jwtConfig.accessExpiresIn,
 		algorithm: "HS256"
@@ -4273,7 +4684,9 @@ function getAccessTokenExpiry() {
 function verifyAccessToken(token) {
 	if (!jwtConfig.secret) throw new Error("JWT secret not configured. Call configureJwt() first.");
 	try {
-		const decoded = import_jsonwebtoken.default.verify(token, jwtConfig.secret, { algorithms: ["HS256"] });
+		const header = import_jsonwebtoken.default.decode(token, { complete: true })?.header;
+		const namedKey = resolveVerificationKey(signingKeys, header?.kid);
+		const decoded = namedKey ? import_jsonwebtoken.default.verify(token, namedKey.publicKey, { algorithms: [namedKey.algorithm] }) : import_jsonwebtoken.default.verify(token, jwtConfig.secret, { algorithms: ["HS256"] });
 		if (decoded.purpose) {
 			logger.error("[JWT] Verification failed: a purpose-scoped token is not an access token", { purpose: decoded.purpose });
 			return null;
@@ -4392,12 +4805,27 @@ function verifyMfaPendingToken(token) {
 }
 /**
 * Generate a short-lived download token scoped to a specific file path or prefix
+* *within one storage source*.
+*
+* Both halves of that scope are load-bearing. A key is only unique inside its
+* own bucket, and a project with more than one source routinely holds the same
+* key in several of them — `avatars/u1.png` in `(default)` and in `media` are
+* different objects, quite possibly with different owners. A token that names
+* only the path is therefore a grant on every source at once: authorize a read
+* on the source whose `storageAuthorize` hook says yes, then spend the token
+* against `?storageId=` pointing somewhere else.
+*
+* `storageId` is optional here only because omitting it *is* the default
+* source, which is what the overwhelming majority of deployments have. A mint
+* site that forgets to pass a named source produces a default-scoped token,
+* which fails closed at `/file/*` rather than over-granting.
 */
-function generateDownloadToken(path, expiresInSeconds = 300) {
+function generateDownloadToken(path, expiresInSeconds = 300, storageId) {
 	if (!jwtConfig.secret) throw new Error("JWT secret not configured. Call configureJwt() first.");
 	const payload = {
 		purpose: "file-read",
-		path
+		path,
+		storageId: canonicalStorageId(storageId)
 	};
 	return import_jsonwebtoken.default.sign(payload, jwtConfig.secret, {
 		expiresIn: expiresInSeconds,
@@ -4405,7 +4833,14 @@ function generateDownloadToken(path, expiresInSeconds = 300) {
 	});
 }
 /**
-* Verify and decode a download token
+* Verify and decode a download token.
+*
+* A token minted before `storageId` existed carries no such claim. It is read
+* as a grant on the **default source** rather than on all of them: that is the
+* fail-closed reading, and it is what such a token almost always was, since a
+* named source has to be asked for explicitly. The cost is bounded by the
+* five-minute TTL — for at most that long after a deploy, an in-flight token
+* for a *named* source is refused and the client re-fetches `/metadata`.
 */
 function verifyDownloadToken(token) {
 	if (!jwtConfig.secret) throw new Error("JWT secret not configured. Call configureJwt() first.");
@@ -4413,7 +4848,8 @@ function verifyDownloadToken(token) {
 		const decoded = import_jsonwebtoken.default.verify(token, jwtConfig.secret, { algorithms: ["HS256"] });
 		if (decoded && decoded.purpose === "file-read" && typeof decoded.path === "string") return {
 			purpose: "file-read",
-			path: decoded.path
+			path: decoded.path,
+			storageId: canonicalStorageId(typeof decoded.storageId === "string" ? decoded.storageId : null)
 		};
 		return null;
 	} catch (error) {
@@ -4422,6 +4858,6 @@ function verifyDownloadToken(token) {
 	}
 }
 //#endregion
-export { generateMfaPendingToken as a, getRefreshTokenExpiry as c, isJwtConfigured as d, jwt_exports as f, require_jsonwebtoken as g, verifyMfaPendingToken as h, generateDownloadToken as i, getRefreshTokenTtlMs as l, verifyDownloadToken as m, configureJwt as n, generateRefreshToken as o, verifyAccessToken as p, generateAccessToken as r, getAccessTokenExpiry as s, MAX_COOKIE_AGE_MS as t, hashRefreshToken as u };
+export { canonicalStorageKey as C, findStorageSuffixCollision as D, DEFAULT_STORAGE_SOURCE_KEY as E, normalizeStorageSources as O, canonicalStorageId as S, require_jsonwebtoken as T, verifyMfaPendingToken as _, generateMfaPendingToken as a, InvalidStorageKeyError as b, getJwks as c, hasAsymmetricSigningKey as d, hashRefreshToken as f, verifyDownloadToken as g, verifyAccessToken as h, generateDownloadToken as i, storageEnvSuffix as k, getRefreshTokenExpiry as l, jwt_exports as m, configureJwt as n, generateRefreshToken as o, isJwtConfigured as p, generateAccessToken as r, getAccessTokenExpiry as s, MAX_COOKIE_AGE_MS as t, getRefreshTokenTtlMs as u, normalizePemFromEnv as v, tryCanonicalStorageKey as w, canonicalStorageBucket as x, InvalidStorageBucketError as y };
 
-//# sourceMappingURL=jwt-_IFqfTOg.js.map
+//# sourceMappingURL=jwt-VJyXTdQQ.js.map