@rebasepro/server 0.24.0 → 0.24.1-canary.gcb918fc

package/dist/{keys-GAVZqbqx.js → keys-COzQ2aE8.js}

@@ -2,7 +2,7 @@ import { createRequire as __rebaseCreateRequire } from "module";
 import __rebaseProcess from "process";
 globalThis.process ??= __rebaseProcess;
 __rebaseCreateRequire(import.meta.url);
-import { O as DEFAULT_STORAGE_SOURCE_KEY } from "./src-CatHFUym.js";
+import { O as DEFAULT_STORAGE_SOURCE_KEY } from "./src-D5Y3N-S4.js";
 //#region src/storage/keys.ts
 /**
 * Canonical storage keys and bucket names.
@@ -228,4 +228,4 @@ var InvalidListOptionsError = class extends Error {
 //#endregion
 export { canonicalStorageId as a, listingPrefix as c, canonicalStorageBucket as i, InvalidStorageBucketError as n, canonicalStorageKey as o, InvalidStorageKeyError as r, folderKey as s, InvalidListOptionsError as t };
 
-//# sourceMappingURL=keys-GAVZqbqx.js.map
+//# sourceMappingURL=keys-COzQ2aE8.js.map

package/dist/{keys-GAVZqbqx.js.map → keys-COzQ2aE8.js.map}

@@ -1 +1 @@
-{"version":3,"file":"keys-GAVZqbqx.js","names":[],"sources":["../src/storage/keys.ts"],"sourcesContent":["/**\n * Canonical storage keys and bucket names.\n *\n * Storage is not under RLS, so a `storageAuthorize` hook is the whole access\n * control model — and a hook can only be correct if the key it is shown is the\n * key that is written. That is the invariant this module exists to hold: one\n * canonical string, computed once per request, handed to the hook, to the\n * controller, and to the download token alike.\n *\n * ## Why rejecting beats stripping\n *\n * The previous `sanitizeStorageKey` *stripped* `../` in a single pass. Two\n * things were wrong with that, and only one of them was the obvious one.\n *\n * The obvious one: a single pass is not a fixed point. `....//` contains `../`\n * at offset 2, so removing it leaves `../` behind — the sanitizer manufactured\n * the traversal it was there to remove. `users/alice/....//bob/x` came out as\n * `users/alice/../bob/x`, which a prefix hook reads as alice's (it starts with\n * `users/alice/`) and the filesystem reads as bob's. The hook approved one\n * object and the controller wrote another.\n *\n * The subtler one, and the reason this is a rewrite rather than a loop: even a\n * correct strip is a silent rewrite. A caller who asks to store at `a/../b` and\n * gets an object at `a/b` was not protected, they were misled — and every later\n * read, ownership row and audit line now refers to a path nobody chose. So a key\n * that means something other than what it says is refused (400), not repaired.\n *\n * Note what is NOT traversal under this rule: `....` is an ordinary directory\n * name, and `users/alice/....//bob/x` canonicalizes to\n * `users/alice/..../bob/x` — still comfortably inside alice's prefix, which is\n * exactly right. Only a real `..` segment is refused.\n */\n\nimport { DEFAULT_STORAGE_SOURCE_KEY } from \"@rebasepro/types\";\n\n/**\n * `path.posix.normalize`, without `node:path`.\n *\n * A storage key is a POSIX-shaped string that never touches a filesystem, so\n * reaching for `node:path` to fold `.` and `//` out of it was always a little\n * wrong on its own terms — on Windows the platform `path` would have applied\n * different rules to the same key. It also put the module that every storage\n * read, ownership row and audit line goes through on the list of things that\n * only run in a Node process.\n *\n * This is the algorithm Node implements, transcribed: segments are folded left\n * to right, `..` pops unless it would climb past the root of a relative path,\n * and both the leading and the trailing separator survive the round trip. The\n * `..` branch is unreachable from {@link canonicalStorageKey}, which refuses\n * those keys outright before it gets here — it exists so that this function is\n * *the* normalizer rather than a subset of one, and\n * `storage-keys.property.test.ts` holds it to that with a property test against\n * `path.posix.normalize` itself. Exported for exactly that — nothing outside\n * this module should be normalizing a key.\n */\nexport function normalizePosix(input: string): string {\n    if (input.length === 0) return \".\";\n    const isAbsolute = input.startsWith(\"/\");\n    const trailingSeparator = input.endsWith(\"/\");\n\n    const segments: string[] = [];\n    for (const segment of input.split(\"/\")) {\n        if (segment === \"\" || segment === \".\") continue;\n        if (segment === \"..\") {\n            if (segments.length > 0 && segments[segments.length - 1] !== \"..\") segments.pop();\n            else if (!isAbsolute) segments.push(\"..\");\n            continue;\n        }\n        segments.push(segment);\n    }\n\n    const joined = segments.join(\"/\");\n    if (joined === \"\") {\n        if (isAbsolute) return \"/\";\n        return trailingSeparator ? \"./\" : \".\";\n    }\n    const withTrailing = trailingSeparator ? `${joined}/` : joined;\n    return isAbsolute ? `/${withTrailing}` : withTrailing;\n}\n\n/** Longest key accepted, in UTF-16 code units. Matches the previous cap. */\nexport const MAX_STORAGE_KEY_LENGTH = 1024;\n\n/**\n * A key that cannot be canonicalized. Carries no path back to the caller\n * beyond what they sent, so it is safe to surface as a 400 message.\n */\nexport class InvalidStorageKeyError extends Error {\n    constructor(message: string) {\n        super(message);\n        this.name = \"InvalidStorageKeyError\";\n    }\n}\n\n/**\n * Canonicalize a caller-supplied storage key, or throw\n * {@link InvalidStorageKeyError}.\n *\n * Normalizations applied (safe, idempotent, and meaning-preserving):\n * - leading slashes removed — `/a/b` and `a/b` name the same object\n * - `.` segments and repeated slashes collapsed\n *\n * Refusals (the key means something other than what it says):\n * - any `..` segment, on either separator, at any depth\n * - null bytes\n * - keys longer than {@link MAX_STORAGE_KEY_LENGTH}\n *\n * A trailing slash is preserved: it is how the folder route marks a prefix.\n */\nexport function canonicalStorageKey(rawKey: string): string {\n    if (rawKey.includes(\"\\0\")) {\n        throw new InvalidStorageKeyError(\"Storage key contains a null byte.\");\n    }\n    if (rawKey.length > MAX_STORAGE_KEY_LENGTH) {\n        throw new InvalidStorageKeyError(\n            `Storage key exceeds the maximum length of ${MAX_STORAGE_KEY_LENGTH} characters.`\n        );\n    }\n\n    // Split on both separators: `path.join` treats `\\` as a separator on\n    // Windows, so `..\\` is traversal there even though POSIX reads it as a\n    // filename. Checked against the RAW key, before any normalization — the\n    // whole point is that `a/../b` is refused rather than quietly turned into\n    // `b`.\n    if (rawKey.split(/[\\\\/]/).some((segment) => segment === \"..\")) {\n        throw new InvalidStorageKeyError(\n            \"Storage key contains a '..' path segment. Keys must name an object directly.\"\n        );\n    }\n\n    const withoutLeadingSlashes = rawKey.replace(/^\\/+/, \"\");\n    if (withoutLeadingSlashes === \"\") return \"\";\n\n    // Whether the key names a *directory* rather than an object: it ends with a\n    // separator, or its last segment is the `.` that means \"this directory\".\n    //\n    // Recorded before normalizing, because normalization drops the\n    // distinction in one of those two spellings and not the other: `public/.`\n    // becomes `public` while `public/./` stays `public/`. That asymmetry breaks\n    // the rule this module states — a trailing slash is preserved, because it is\n    // how the folder route marks a prefix — and it is not cosmetic on `list`,\n    // where a prefix of `public` also matches `publicity/` and hands back keys\n    // the caller never asked for.\n    const denotesDirectory = /(?:^|\\/)\\.?$/.test(withoutLeadingSlashes);\n\n    // Safe now: with no `..` segment in the input, `normalize` can only collapse\n    // `.` and duplicate slashes — it cannot climb.\n    const normalized = normalizePosix(withoutLeadingSlashes);\n\n    // `normalize(\".\")`, and `normalize(\"./\")` → `./`; neither names an object.\n    if (normalized === \".\" || normalized === \"./\") return \"\";\n\n    // Defensive: nothing reaching here still carries a leading `./`, since the\n    // leading slashes are already gone and `normalize` only emits `./` for a\n    // key that normalizes to nothing — which returned above.\n    const key = normalized.replace(/^\\.\\//, \"\").replace(/^\\/+/, \"\");\n    if (key === \"\") return \"\";\n    return denotesDirectory && !key.endsWith(\"/\") ? `${key}/` : key;\n}\n\n/**\n * Canonicalize, or return `null` when the key is not canonicalizable.\n *\n * For callers that must fail closed without an exception — the download-token\n * middleware compares a request path against a granted path, and a key it\n * cannot canonicalize simply matches nothing.\n */\nexport function tryCanonicalStorageKey(rawKey: string): string | null {\n    try {\n        return canonicalStorageKey(rawKey);\n    } catch {\n        return null;\n    }\n}\n\n/**\n * Canonicalize the storage *source* a request names (`?storageId=`), so that\n * \"the default source\" has exactly one spelling.\n *\n * The default source can be asked for three ways — the parameter omitted, sent\n * empty, or sent as the literal `(default)` — and all three resolve to the same\n * controller. Without a single spelling, the value derived when a download\n * token is minted and the value derived when it is presented can differ for the\n * same object, which is either a spurious 403 or, if the comparison is dropped\n * to stop those, no scoping at all.\n *\n * Deliberately *not* validated against the registry: this is a naming rule, not\n * an existence check, and it must give the same answer in `auth/` (which has no\n * registry) as in the storage routes. An id that names no source still\n * canonicalizes to itself and simply matches only itself.\n */\nexport function canonicalStorageId(rawStorageId: string | undefined | null): string {\n    if (rawStorageId === undefined || rawStorageId === null) return DEFAULT_STORAGE_SOURCE_KEY;\n    const trimmed = rawStorageId.trim();\n    return trimmed === \"\" ? DEFAULT_STORAGE_SOURCE_KEY : trimmed;\n}\n\n/**\n * Longest bucket name accepted. 63 is the S3/GCS limit, and a local bucket is\n * one directory name, so the tighter of the two bounds everything.\n */\nexport const MAX_STORAGE_BUCKET_LENGTH = 63;\n\n/** A bucket name that does not name a bucket. See {@link canonicalStorageBucket}. */\nexport class InvalidStorageBucketError extends Error {\n    constructor(message: string) {\n        super(message);\n        this.name = \"InvalidStorageBucketError\";\n    }\n}\n\n/**\n * One path segment: letters, digits, `.`, `_`, `-`, first character\n * alphanumeric. Deliberately narrow — it is the intersection of what S3, GCS\n * and a filesystem directory all accept, and it makes `..`, `.tus-uploads`,\n * absolute paths and anything containing a separator unrepresentable.\n */\nconst STORAGE_BUCKET_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;\n\n/**\n * Canonicalize a caller-supplied bucket name, or throw\n * {@link InvalidStorageBucketError}.\n *\n * The bucket is the *other* caller-controlled routing value in an upload\n * request, and it was the one nobody validated. `LocalStorageController`\n * builds `join(basePath, bucket)` and then checks containment against that\n * result, so a bucket of `../../etc` moved the boundary rather than crossing\n * it — the guard passed because the guard's reference point was the attacker's.\n * The containment check now resolves against the storage root, and this is the\n * check at the route boundary that stops the value before it gets there.\n *\n * A bucket is configuration, not user data: there is no legitimate caller that\n * needs a separator, a leading dot, or a `..` in one. So this refuses rather\n * than repairs, exactly as {@link canonicalStorageKey} does — a rewritten\n * bucket would silently store the object somewhere the caller did not ask for.\n *\n * Returns `undefined` when the caller named no bucket (absent, or an empty\n * form field), which is how every controller spells \"use my default\". An empty\n * string used to reach `getFullPath` and resolve to the storage *root* rather\n * than the `default` bucket, which is a third place a bare key did not\n * round-trip.\n */\nexport function canonicalStorageBucket(rawBucket: string | undefined | null): string | undefined {\n    if (rawBucket === undefined || rawBucket === null || rawBucket === \"\") return undefined;\n    if (rawBucket.length > MAX_STORAGE_BUCKET_LENGTH) {\n        throw new InvalidStorageBucketError(\n            `Storage bucket exceeds the maximum length of ${MAX_STORAGE_BUCKET_LENGTH} characters.`\n        );\n    }\n    if (!STORAGE_BUCKET_PATTERN.test(rawBucket)) {\n        throw new InvalidStorageBucketError(\n            \"Storage bucket must be a single name of letters, digits, '.', '_' or '-', \" +\n            \"starting with a letter or digit.\"\n        );\n    }\n    return rawBucket;\n}\n\n/**\n * The prefix an object store's listing should be given for a caller's key, and\n * the key a listing should hand back for a folder.\n *\n * The three controllers answer the same question in two different ways, and\n * they used to disagree about the answer. `LocalStorageController` resolves a\n * *directory* on disk, so `listObjects(\"products/images\")` and\n * `listObjects(\"products/images/\")` both list what is inside it. An object\n * store under `Delimiter: \"/\"` does not: `Prefix: \"products/images\"` matches\n * `products/images.txt` and `productsomething/`, and returns none of the files\n * inside `products/images/`. So the same call — the SDK's own documented one —\n * answered one thing against local dev and another against the S3 bucket in\n * production, which is the worst place for a divergence to live.\n *\n * `listingPrefix` is what to *send*: a trailing slash, always, because that is\n * the only spelling that means \"inside this folder\" to a delimiter listing.\n * `folderKey` is what to *return* for a common prefix: no trailing slash, the\n * form the local controller has always used, so a `fullPath` from a listing is\n * a key you can pass straight back to any of them.\n */\nexport function listingPrefix(rawPrefix: string): string | undefined {\n    const key = rawPrefix.replace(/^\\/+/, \"\").replace(/\\/+$/, \"\");\n    return key === \"\" ? undefined : `${key}/`;\n}\n\n/** @see listingPrefix */\nexport function folderKey(rawPrefix: string): string {\n    return rawPrefix.replace(/^\\/+/, \"\").replace(/\\/+$/, \"\");\n}\n\n/**\n * A listing asked for paging a controller cannot honour: a page size below one,\n * or a page token it never issued.\n *\n * Refused rather than coerced. A page size of 0 answered an empty page whose\n * next token was the one it had been handed, so `while (pageToken)` never\n * ended; a token of `-1` read before the first entry and crashed. The route\n * turns this into a 400.\n */\nexport class InvalidListOptionsError extends Error {\n    constructor(message: string) {\n        super(message);\n        this.name = \"InvalidListOptionsError\";\n    }\n}\n"],"mappings":"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"}
+{"version":3,"file":"keys-COzQ2aE8.js","names":[],"sources":["../src/storage/keys.ts"],"sourcesContent":["/**\n * Canonical storage keys and bucket names.\n *\n * Storage is not under RLS, so a `storageAuthorize` hook is the whole access\n * control model — and a hook can only be correct if the key it is shown is the\n * key that is written. That is the invariant this module exists to hold: one\n * canonical string, computed once per request, handed to the hook, to the\n * controller, and to the download token alike.\n *\n * ## Why rejecting beats stripping\n *\n * The previous `sanitizeStorageKey` *stripped* `../` in a single pass. Two\n * things were wrong with that, and only one of them was the obvious one.\n *\n * The obvious one: a single pass is not a fixed point. `....//` contains `../`\n * at offset 2, so removing it leaves `../` behind — the sanitizer manufactured\n * the traversal it was there to remove. `users/alice/....//bob/x` came out as\n * `users/alice/../bob/x`, which a prefix hook reads as alice's (it starts with\n * `users/alice/`) and the filesystem reads as bob's. The hook approved one\n * object and the controller wrote another.\n *\n * The subtler one, and the reason this is a rewrite rather than a loop: even a\n * correct strip is a silent rewrite. A caller who asks to store at `a/../b` and\n * gets an object at `a/b` was not protected, they were misled — and every later\n * read, ownership row and audit line now refers to a path nobody chose. So a key\n * that means something other than what it says is refused (400), not repaired.\n *\n * Note what is NOT traversal under this rule: `....` is an ordinary directory\n * name, and `users/alice/....//bob/x` canonicalizes to\n * `users/alice/..../bob/x` — still comfortably inside alice's prefix, which is\n * exactly right. Only a real `..` segment is refused.\n */\n\nimport { DEFAULT_STORAGE_SOURCE_KEY } from \"@rebasepro/types\";\n\n/**\n * `path.posix.normalize`, without `node:path`.\n *\n * A storage key is a POSIX-shaped string that never touches a filesystem, so\n * reaching for `node:path` to fold `.` and `//` out of it was always a little\n * wrong on its own terms — on Windows the platform `path` would have applied\n * different rules to the same key. It also put the module that every storage\n * read, ownership row and audit line goes through on the list of things that\n * only run in a Node process.\n *\n * This is the algorithm Node implements, transcribed: segments are folded left\n * to right, `..` pops unless it would climb past the root of a relative path,\n * and both the leading and the trailing separator survive the round trip. The\n * `..` branch is unreachable from {@link canonicalStorageKey}, which refuses\n * those keys outright before it gets here — it exists so that this function is\n * *the* normalizer rather than a subset of one, and\n * `storage-keys.property.test.ts` holds it to that with a property test against\n * `path.posix.normalize` itself. Exported for exactly that — nothing outside\n * this module should be normalizing a key.\n */\nexport function normalizePosix(input: string): string {\n    if (input.length === 0) return \".\";\n    const isAbsolute = input.startsWith(\"/\");\n    const trailingSeparator = input.endsWith(\"/\");\n\n    const segments: string[] = [];\n    for (const segment of input.split(\"/\")) {\n        if (segment === \"\" || segment === \".\") continue;\n        if (segment === \"..\") {\n            if (segments.length > 0 && segments[segments.length - 1] !== \"..\") segments.pop();\n            else if (!isAbsolute) segments.push(\"..\");\n            continue;\n        }\n        segments.push(segment);\n    }\n\n    const joined = segments.join(\"/\");\n    if (joined === \"\") {\n        if (isAbsolute) return \"/\";\n        return trailingSeparator ? \"./\" : \".\";\n    }\n    const withTrailing = trailingSeparator ? `${joined}/` : joined;\n    return isAbsolute ? `/${withTrailing}` : withTrailing;\n}\n\n/** Longest key accepted, in UTF-16 code units. Matches the previous cap. */\nexport const MAX_STORAGE_KEY_LENGTH = 1024;\n\n/**\n * A key that cannot be canonicalized. Carries no path back to the caller\n * beyond what they sent, so it is safe to surface as a 400 message.\n */\nexport class InvalidStorageKeyError extends Error {\n    constructor(message: string) {\n        super(message);\n        this.name = \"InvalidStorageKeyError\";\n    }\n}\n\n/**\n * Canonicalize a caller-supplied storage key, or throw\n * {@link InvalidStorageKeyError}.\n *\n * Normalizations applied (safe, idempotent, and meaning-preserving):\n * - leading slashes removed — `/a/b` and `a/b` name the same object\n * - `.` segments and repeated slashes collapsed\n *\n * Refusals (the key means something other than what it says):\n * - any `..` segment, on either separator, at any depth\n * - null bytes\n * - keys longer than {@link MAX_STORAGE_KEY_LENGTH}\n *\n * A trailing slash is preserved: it is how the folder route marks a prefix.\n */\nexport function canonicalStorageKey(rawKey: string): string {\n    if (rawKey.includes(\"\\0\")) {\n        throw new InvalidStorageKeyError(\"Storage key contains a null byte.\");\n    }\n    if (rawKey.length > MAX_STORAGE_KEY_LENGTH) {\n        throw new InvalidStorageKeyError(\n            `Storage key exceeds the maximum length of ${MAX_STORAGE_KEY_LENGTH} characters.`\n        );\n    }\n\n    // Split on both separators: `path.join` treats `\\` as a separator on\n    // Windows, so `..\\` is traversal there even though POSIX reads it as a\n    // filename. Checked against the RAW key, before any normalization — the\n    // whole point is that `a/../b` is refused rather than quietly turned into\n    // `b`.\n    if (rawKey.split(/[\\\\/]/).some((segment) => segment === \"..\")) {\n        throw new InvalidStorageKeyError(\n            \"Storage key contains a '..' path segment. Keys must name an object directly.\"\n        );\n    }\n\n    const withoutLeadingSlashes = rawKey.replace(/^\\/+/, \"\");\n    if (withoutLeadingSlashes === \"\") return \"\";\n\n    // Whether the key names a *directory* rather than an object: it ends with a\n    // separator, or its last segment is the `.` that means \"this directory\".\n    //\n    // Recorded before normalizing, because normalization drops the\n    // distinction in one of those two spellings and not the other: `public/.`\n    // becomes `public` while `public/./` stays `public/`. That asymmetry breaks\n    // the rule this module states — a trailing slash is preserved, because it is\n    // how the folder route marks a prefix — and it is not cosmetic on `list`,\n    // where a prefix of `public` also matches `publicity/` and hands back keys\n    // the caller never asked for.\n    const denotesDirectory = /(?:^|\\/)\\.?$/.test(withoutLeadingSlashes);\n\n    // Safe now: with no `..` segment in the input, `normalize` can only collapse\n    // `.` and duplicate slashes — it cannot climb.\n    const normalized = normalizePosix(withoutLeadingSlashes);\n\n    // `normalize(\".\")`, and `normalize(\"./\")` → `./`; neither names an object.\n    if (normalized === \".\" || normalized === \"./\") return \"\";\n\n    // Defensive: nothing reaching here still carries a leading `./`, since the\n    // leading slashes are already gone and `normalize` only emits `./` for a\n    // key that normalizes to nothing — which returned above.\n    const key = normalized.replace(/^\\.\\//, \"\").replace(/^\\/+/, \"\");\n    if (key === \"\") return \"\";\n    return denotesDirectory && !key.endsWith(\"/\") ? `${key}/` : key;\n}\n\n/**\n * Canonicalize, or return `null` when the key is not canonicalizable.\n *\n * For callers that must fail closed without an exception — the download-token\n * middleware compares a request path against a granted path, and a key it\n * cannot canonicalize simply matches nothing.\n */\nexport function tryCanonicalStorageKey(rawKey: string): string | null {\n    try {\n        return canonicalStorageKey(rawKey);\n    } catch {\n        return null;\n    }\n}\n\n/**\n * Canonicalize the storage *source* a request names (`?storageId=`), so that\n * \"the default source\" has exactly one spelling.\n *\n * The default source can be asked for three ways — the parameter omitted, sent\n * empty, or sent as the literal `(default)` — and all three resolve to the same\n * controller. Without a single spelling, the value derived when a download\n * token is minted and the value derived when it is presented can differ for the\n * same object, which is either a spurious 403 or, if the comparison is dropped\n * to stop those, no scoping at all.\n *\n * Deliberately *not* validated against the registry: this is a naming rule, not\n * an existence check, and it must give the same answer in `auth/` (which has no\n * registry) as in the storage routes. An id that names no source still\n * canonicalizes to itself and simply matches only itself.\n */\nexport function canonicalStorageId(rawStorageId: string | undefined | null): string {\n    if (rawStorageId === undefined || rawStorageId === null) return DEFAULT_STORAGE_SOURCE_KEY;\n    const trimmed = rawStorageId.trim();\n    return trimmed === \"\" ? DEFAULT_STORAGE_SOURCE_KEY : trimmed;\n}\n\n/**\n * Longest bucket name accepted. 63 is the S3/GCS limit, and a local bucket is\n * one directory name, so the tighter of the two bounds everything.\n */\nexport const MAX_STORAGE_BUCKET_LENGTH = 63;\n\n/** A bucket name that does not name a bucket. See {@link canonicalStorageBucket}. */\nexport class InvalidStorageBucketError extends Error {\n    constructor(message: string) {\n        super(message);\n        this.name = \"InvalidStorageBucketError\";\n    }\n}\n\n/**\n * One path segment: letters, digits, `.`, `_`, `-`, first character\n * alphanumeric. Deliberately narrow — it is the intersection of what S3, GCS\n * and a filesystem directory all accept, and it makes `..`, `.tus-uploads`,\n * absolute paths and anything containing a separator unrepresentable.\n */\nconst STORAGE_BUCKET_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;\n\n/**\n * Canonicalize a caller-supplied bucket name, or throw\n * {@link InvalidStorageBucketError}.\n *\n * The bucket is the *other* caller-controlled routing value in an upload\n * request, and it was the one nobody validated. `LocalStorageController`\n * builds `join(basePath, bucket)` and then checks containment against that\n * result, so a bucket of `../../etc` moved the boundary rather than crossing\n * it — the guard passed because the guard's reference point was the attacker's.\n * The containment check now resolves against the storage root, and this is the\n * check at the route boundary that stops the value before it gets there.\n *\n * A bucket is configuration, not user data: there is no legitimate caller that\n * needs a separator, a leading dot, or a `..` in one. So this refuses rather\n * than repairs, exactly as {@link canonicalStorageKey} does — a rewritten\n * bucket would silently store the object somewhere the caller did not ask for.\n *\n * Returns `undefined` when the caller named no bucket (absent, or an empty\n * form field), which is how every controller spells \"use my default\". An empty\n * string used to reach `getFullPath` and resolve to the storage *root* rather\n * than the `default` bucket, which is a third place a bare key did not\n * round-trip.\n */\nexport function canonicalStorageBucket(rawBucket: string | undefined | null): string | undefined {\n    if (rawBucket === undefined || rawBucket === null || rawBucket === \"\") return undefined;\n    if (rawBucket.length > MAX_STORAGE_BUCKET_LENGTH) {\n        throw new InvalidStorageBucketError(\n            `Storage bucket exceeds the maximum length of ${MAX_STORAGE_BUCKET_LENGTH} characters.`\n        );\n    }\n    if (!STORAGE_BUCKET_PATTERN.test(rawBucket)) {\n        throw new InvalidStorageBucketError(\n            \"Storage bucket must be a single name of letters, digits, '.', '_' or '-', \" +\n            \"starting with a letter or digit.\"\n        );\n    }\n    return rawBucket;\n}\n\n/**\n * The prefix an object store's listing should be given for a caller's key, and\n * the key a listing should hand back for a folder.\n *\n * The three controllers answer the same question in two different ways, and\n * they used to disagree about the answer. `LocalStorageController` resolves a\n * *directory* on disk, so `listObjects(\"products/images\")` and\n * `listObjects(\"products/images/\")` both list what is inside it. An object\n * store under `Delimiter: \"/\"` does not: `Prefix: \"products/images\"` matches\n * `products/images.txt` and `productsomething/`, and returns none of the files\n * inside `products/images/`. So the same call — the SDK's own documented one —\n * answered one thing against local dev and another against the S3 bucket in\n * production, which is the worst place for a divergence to live.\n *\n * `listingPrefix` is what to *send*: a trailing slash, always, because that is\n * the only spelling that means \"inside this folder\" to a delimiter listing.\n * `folderKey` is what to *return* for a common prefix: no trailing slash, the\n * form the local controller has always used, so a `fullPath` from a listing is\n * a key you can pass straight back to any of them.\n */\nexport function listingPrefix(rawPrefix: string): string | undefined {\n    const key = rawPrefix.replace(/^\\/+/, \"\").replace(/\\/+$/, \"\");\n    return key === \"\" ? undefined : `${key}/`;\n}\n\n/** @see listingPrefix */\nexport function folderKey(rawPrefix: string): string {\n    return rawPrefix.replace(/^\\/+/, \"\").replace(/\\/+$/, \"\");\n}\n\n/**\n * A listing asked for paging a controller cannot honour: a page size below one,\n * or a page token it never issued.\n *\n * Refused rather than coerced. A page size of 0 answered an empty page whose\n * next token was the one it had been handed, so `while (pageToken)` never\n * ended; a token of `-1` read before the first entry and crashed. The route\n * turns this into a 400.\n */\nexport class InvalidListOptionsError extends Error {\n    constructor(message: string) {\n        super(message);\n        this.name = \"InvalidListOptionsError\";\n    }\n}\n"],"mappings":"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"}

package/dist/load-failure-L5hvfDoG.js

@@ -0,0 +1,80 @@
+import { createRequire as __rebaseCreateRequire } from "module";
+import __rebaseProcess from "process";
+globalThis.process ??= __rebaseProcess;
+__rebaseCreateRequire(import.meta.url);
+import * as path$1 from "path";
+//#region ../common/src/util/deprecation.ts
+/**
+* Keys already warned about in this process. A deprecated name is usually
+* reached on a hot path — every request, every render — and one line naming
+* the replacement is enough; repeating it buries everything else in the log.
+*/
+var warnedKeys = /* @__PURE__ */ new Set();
+/**
+* Say once, per process, that a deprecated public name was used.
+*
+* `key` identifies the deprecated name (`"client.ws.setAuthTokenGetter"`):
+* the first call with a key prints `message` with `console.warn`, every later
+* call with the same key prints nothing. `message` should name the
+* replacement, so the warning is the whole migration instruction.
+*
+* Node-free and browser-safe: it touches nothing but `console`.
+*
+* @example
+* ```ts
+* // Declared with `@deprecated Use \`newName\` instead.` in its JSDoc.
+* export function oldName(...args: Parameters<typeof newName>) {
+*     warnDeprecated("oldName", "`oldName` is deprecated; use `newName` instead.");
+*     return newName(...args);
+* }
+* ```
+*/
+function warnDeprecated(key, message) {
+	if (warnedKeys.has(key)) return;
+	warnedKeys.add(key);
+	console.warn(`[Rebase] Deprecated: ${message}`);
+}
+//#endregion
+//#region src/utils/dynamic-import.ts
+/**
+* Native ESM dynamic import.
+*
+* Wrapped in `new Function` so TypeScript / bundlers don't down-compile the
+* `import()` to `require()` — the loaders must import user-authored `.ts`/`.js`
+* files at runtime using the host's real ESM loader. This is the production
+* default for {@link loadFunctionsFromDirectory} / {@link loadCronJobsFromDirectory}.
+*
+* @internal
+*/
+var nativeDynamicImport = (() => {
+	const doImport = new Function("url", "return import(url)");
+	return (url) => doImport(url);
+})();
+//#endregion
+//#region src/utils/load-failure.ts
+/**
+* How a function or cron file that failed to import is listed in the boot
+* log: `"<file> (syntax error at <file>:<line>: <message>)"` for a syntax
+* error, `"<file> (threw: <message>)"` for anything else.
+*
+* The two need different remedies. A file that *threw* usually read an
+* undefined env var at module scope; a file with a *syntax error* needs its
+* syntax fixed, and the loaders' advice is keyed on which one this is. Node
+* puts a syntax error's location only in the first line of its stack, so that
+* is where the line number comes from.
+*/
+function describeLoadFailure(file, err) {
+	const message = err instanceof Error ? err.message : String(err);
+	if (err instanceof Error && err.name === "SyntaxError") {
+		const firstLine = err.stack?.split("\n", 1)[0] ?? "";
+		const at = /:(\d+)(?::\d+)?$/.exec(firstLine);
+		return `${file} (syntax error${at ? ` at ${path$1.basename(file)}:${at[1]}` : ""}: ${message})`;
+	}
+	return `${file} (threw: ${message})`;
+}
+/** The advice for {@link describeLoadFailure}'s syntax-error entries. */
+var SYNTAX_ERROR_ADVICE = "  A file with a syntax error never ran: fix the syntax at the line shown (`tsc --noEmit` or your editor will point at it too).";
+//#endregion
+export { warnDeprecated as i, describeLoadFailure as n, nativeDynamicImport as r, SYNTAX_ERROR_ADVICE as t };
+
+//# sourceMappingURL=load-failure-L5hvfDoG.js.map

package/dist/load-failure-L5hvfDoG.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-failure-L5hvfDoG.js","names":[],"sources":["../../common/src/util/deprecation.ts","../src/utils/dynamic-import.ts","../src/utils/load-failure.ts"],"sourcesContent":["/**\n * Keys already warned about in this process. A deprecated name is usually\n * reached on a hot path — every request, every render — and one line naming\n * the replacement is enough; repeating it buries everything else in the log.\n */\nconst warnedKeys = new Set<string>();\n\n/**\n * Say once, per process, that a deprecated public name was used.\n *\n * `key` identifies the deprecated name (`\"client.ws.setAuthTokenGetter\"`):\n * the first call with a key prints `message` with `console.warn`, every later\n * call with the same key prints nothing. `message` should name the\n * replacement, so the warning is the whole migration instruction.\n *\n * Node-free and browser-safe: it touches nothing but `console`.\n *\n * @example\n * ```ts\n * // Declared with `@deprecated Use \\`newName\\` instead.` in its JSDoc.\n * export function oldName(...args: Parameters<typeof newName>) {\n *     warnDeprecated(\"oldName\", \"`oldName` is deprecated; use `newName` instead.\");\n *     return newName(...args);\n * }\n * ```\n */\nexport function warnDeprecated(key: string, message: string): void {\n    if (warnedKeys.has(key)) return;\n    warnedKeys.add(key);\n    console.warn(`[Rebase] Deprecated: ${message}`);\n}\n\n/**\n * Forget which keys have been warned about, so a test can assert that a\n * deprecated name warns — once — regardless of what ran before it.\n *\n * @internal For tests only.\n */\nexport function resetDeprecationWarningsForTests(): void {\n    warnedKeys.clear();\n}\n","/**\n * Shape returned by a dynamic module import: an object whose `default`\n * property holds the module's default export (CJS `module.exports` is exposed\n * as `default` by Node's ESM interop).\n */\nexport interface ImportedModule {\n    default?: unknown;\n    [key: string]: unknown;\n}\n\n/**\n * Imports a module by file URL. Injected into the directory loaders so tests\n * can supply a deterministic importer.\n */\nexport type ModuleImporter = (url: string) => Promise<ImportedModule>;\n\n/**\n * Native ESM dynamic import.\n *\n * Wrapped in `new Function` so TypeScript / bundlers don't down-compile the\n * `import()` to `require()` — the loaders must import user-authored `.ts`/`.js`\n * files at runtime using the host's real ESM loader. This is the production\n * default for {@link loadFunctionsFromDirectory} / {@link loadCronJobsFromDirectory}.\n *\n * @internal\n */\nexport const nativeDynamicImport: ModuleImporter = (() => {\n    const doImport = new Function(\"url\", \"return import(url)\") as (url: string) => Promise<ImportedModule>;\n    return (url: string) => doImport(url);\n})();\n","import * as path from \"path\";\n\n/**\n * How a function or cron file that failed to import is listed in the boot\n * log: `\"<file> (syntax error at <file>:<line>: <message>)\"` for a syntax\n * error, `\"<file> (threw: <message>)\"` for anything else.\n *\n * The two need different remedies. A file that *threw* usually read an\n * undefined env var at module scope; a file with a *syntax error* needs its\n * syntax fixed, and the loaders' advice is keyed on which one this is. Node\n * puts a syntax error's location only in the first line of its stack, so that\n * is where the line number comes from.\n */\nexport function describeLoadFailure(file: string, err: unknown): string {\n    const message = err instanceof Error ? err.message : String(err);\n    // By name, not `instanceof`: the error comes from whatever realm did the\n    // import, and its SyntaxError is not this one's.\n    if (err instanceof Error && err.name === \"SyntaxError\") {\n        const firstLine = err.stack?.split(\"\\n\", 1)[0] ?? \"\";\n        const at = /:(\\d+)(?::\\d+)?$/.exec(firstLine);\n        const where = at ? ` at ${path.basename(file)}:${at[1]}` : \"\";\n        return `${file} (syntax error${where}: ${message})`;\n    }\n    return `${file} (threw: ${message})`;\n}\n\n/** The advice for {@link describeLoadFailure}'s syntax-error entries. */\nexport const SYNTAX_ERROR_ADVICE =\n    \"  A file with a syntax error never ran: fix the syntax at the line shown \" +\n    \"(`tsc --noEmit` or your editor will point at it too).\";\n"],"mappings":";;;;;;;;;;;AAKA,IAAM,6BAAa,IAAI,IAAY;;;;;;;;;;;;;;;;;;;;AAqBnC,SAAgB,eAAe,KAAa,SAAuB;CAC/D,IAAI,WAAW,IAAI,GAAG,GAAG;CACzB,WAAW,IAAI,GAAG;CAClB,QAAQ,KAAK,wBAAwB,SAAS;AAClD;;;;;;;;;;;;;ACJA,IAAa,6BAA6C;CACtD,MAAM,WAAW,IAAI,SAAS,OAAO,oBAAoB;CACzD,QAAQ,QAAgB,SAAS,GAAG;AACxC,EAAA,CAAG;;;;;;;;;;;;;;AChBH,SAAgB,oBAAoB,MAAc,KAAsB;CACpE,MAAM,UAAU,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;CAG/D,IAAI,eAAe,SAAS,IAAI,SAAS,eAAe;EACpD,MAAM,YAAY,IAAI,OAAO,MAAM,MAAM,CAAC,CAAC,CAAC,MAAM;EAClD,MAAM,KAAK,mBAAmB,KAAK,SAAS;EAE5C,OAAO,GAAG,KAAK,gBADD,KAAK,OAAO,OAAK,SAAS,IAAI,EAAE,GAAG,GAAG,OAAO,GACtB,IAAI,QAAQ;CACrD;CACA,OAAO,GAAG,KAAK,WAAW,QAAQ;AACtC;;AAGA,IAAa,sBACT"}

package/dist/mcp/mcp-routes.d.ts

@@ -23,6 +23,7 @@
 import { Hono } from "hono";
 import type { AuthAdapter, CollectionConfig, DataDriver } from "@rebasepro/types";
 import type { HonoEnv } from "../api/types.js";
+import { type JwtService } from "../auth/jwt.js";
 import { type DataRateLimitConfig } from "../auth/rate-limiter.js";
 import type { ApiKeyIdentity, ApiKeyRefusal } from "../auth/api-keys/api-key-middleware.js";
 /**
@@ -37,6 +38,11 @@ import type { ApiKeyIdentity, ApiKeyRefusal } from "../auth/api-keys/api-key-mid
  */
 export declare const MAX_BATCH_MESSAGES = 20;
 export interface McpRoutesConfig {
+    /**
+     * The backend whose MCP access tokens this endpoint accepts — its own key
+     * signed them. The process default when omitted.
+     */
+    jwt?: JwtService;
     /**
      * Verify an `rk_` API key, for clients that are configured with a header
      * rather than an OAuth flow. A key reaches the tools its `data:*` scopes

package/dist/mcp/mcp-tools.d.ts

@@ -51,6 +51,14 @@ export interface McpToolDefinition {
      * to be listed, and on the collection a call names for it to run.
      */
     requiredScope: McpScope;
+    /**
+     * Whether the reply carries the result a second time, as
+     * `structuredContent`. The text block always carries it — it is what a
+     * model reads. A result a program consumes (rows, a count, a write's
+     * outcome) also goes out as typed data; one only a model reads does not,
+     * so the reply is not twice its size. Defaults to true.
+     */
+    structuredContent?: boolean;
     run(args: Record<string, unknown>, ctx: McpToolContext): Promise<unknown>;
 }
 /** An error whose message is safe to hand back to the model. */

package/dist/mcp/oauth-routes.d.ts

@@ -25,10 +25,17 @@
  */
 import { Hono } from "hono";
 import type { HonoEnv } from "../api/types.js";
+import { type JwtService } from "../auth/jwt.js";
 import type { AuthRepository } from "../auth/interfaces.js";
 import type { OAuthStore } from "./oauth-store.js";
 export interface OAuthRoutesConfig {
     store: OAuthStore;
+    /**
+     * The backend this authorization server issues for: its key signs the
+     * MCP access tokens and the authorize-request token, and verifies the
+     * person's session at consent. The process default when omitted.
+     */
+    jwt?: JwtService;
     /** The externally reachable origin of this deployment. */
     publicUrl: string;
     /** Where `/mcp` is mounted, e.g. `/mcp`. */

package/dist/metrics/index.d.ts

@@ -31,11 +31,24 @@ export type MetricSurface = "data" | "auth" | "storage" | "functions" | "admin"
  | "other";
 /** Whether a path is the platform looking in, rather than a request served. */
 export declare function isUncountedPath(pathname: string): boolean;
+/**
+ * How long a query waited for a pooled database connection, in milliseconds —
+ * opening one included, when the pool had to. Labelled by data source. See
+ * `pool-wait.ts`, which records it, and why it matters there.
+ */
+export declare const DB_POOL_WAIT_METRIC = "rebase_db_pool_wait_ms";
+/**
+ * Buckets for {@link DB_POOL_WAIT_METRIC}. A checkout from a pool with an idle
+ * connection takes well under a millisecond, so the low end is finer than a
+ * request's: the interesting number is how much of the tail is above zero.
+ */
+export declare const POOL_WAIT_BUCKETS_MS: number[];
 export declare class MetricsRegistry {
     private requests;
     private latency;
     private gauges;
     private counters;
+    private histograms;
     readonly startedAt: number;
     private static labelKey;
     private static parseLabels;
@@ -51,6 +64,11 @@ export declare class MetricsRegistry {
     recordRequest(labels: Record<string, string>, durationMs: number): void;
     incrementCounter(name: string, labels?: Record<string, string>, by?: number): void;
     setGauge(name: string, value: number, labels?: Record<string, string>): void;
+    /**
+     * Record one observation in a named histogram. `buckets` are its upper
+     * bounds, fixed by the first observation of the series.
+     */
+    observe(name: string, value: number, labels?: Record<string, string>, buckets?: readonly number[]): void;
     /** Prometheus escaping: backslash, quote and newline, in that order. */
     private static formatLabels;
     /** Group `name -> [[labelKey, value]]` for one-HELP-per-metric rendering. */

package/dist/metrics/pool-wait.d.ts

@@ -0,0 +1,50 @@
+/**
+ * How long queries wait for a pooled database connection.
+ *
+ * A write holds its connection — and its transaction, and the locks it has
+ * taken — for as long as its callbacks run: `beforeSave` runs after the
+ * transaction has begun, `afterSave` before it commits. Callbacks that await
+ * something slow therefore take connections out of the pool for that long, and
+ * once enough of them run at once every other request queues for one. Measured
+ * with the default pool of 20: 25 concurrent saves whose `beforeSave` awaited
+ * 300 ms made an unrelated one-row read wait 290 ms for a connection.
+ *
+ * Nothing else shows that queue. Request latency rises, but so it does for a
+ * slow query; this histogram says how much of a request was spent waiting for
+ * a connection at all. Near zero is a healthy pool.
+ *
+ * @module
+ */
+import { type MetricsRegistry } from "./index.js";
+/** `pg.Pool`'s callback form of `connect`, which `pool.query` uses internally. */
+type ConnectCallback = (err: Error | undefined, client: unknown, done: (release?: unknown) => void) => void;
+/**
+ * `connect` as a `pg.Pool` has it: a promise without a callback, the callback
+ * with one. Both are timed — transactions check out with the first,
+ * `pool.query` with the second.
+ */
+export type PoolConnect = (callback?: ConnectCallback) => Promise<unknown> | void;
+/**
+ * Time every checkout from `pool`, from the call to the moment a connection is
+ * handed over, and report it to `record` in milliseconds. A failed checkout is
+ * not recorded: it is an error, not a wait.
+ *
+ * Wraps `connect` on this pool object only. `false` when the pool has no
+ * `connect` to time (a driver that is not pool-based) or is timed already.
+ */
+export declare function timePoolCheckouts(pool: {
+    connect?: PoolConnect;
+}, record: (waitMs: number) => void): boolean;
+/**
+ * Time the checkouts of every pool-based data source into `registry`'s
+ * {@link DB_POOL_WAIT_METRIC} histogram, labelled by the source's key.
+ */
+export declare function recordPoolWaits(registry: MetricsRegistry, sources: readonly {
+    key: string;
+    connection: {
+        pool?: {
+            connect?: PoolConnect;
+        };
+    };
+}[]): void;
+export {};