The best way to control Claude Code, Codex and more from any computer or phone
| 1 | // Alchemy modifications are licensed under Apache-2.0. |
| 2 | // This file includes third-party code; see /THIRD_PARTY_LICENSES.md. |
| 3 | /** |
| 4 | * Canonical normalization for the `assets.base_path` configuration field. |
| 5 | * |
| 6 | * This implements the shared canonical path contract applied by the Asset |
| 7 | * Worker when it receives its final configuration. |
| 8 | * |
| 9 | * The stored canonical form is either the root `"/"` or an absolute pathname |
| 10 | * with both leading and trailing slashes, such as `"/subpath/"`. |
| 11 | */ |
| 12 | |
| 13 | export type BasePathValidationResult = |
| 14 | | { valid: true; value: string } |
| 15 | | { valid: false; error: string }; |
| 16 | |
| 17 | // eslint-disable-next-line no-control-regex -- control characters are matched intentionally so they can be rejected in `base_path` |
| 18 | const CONTROL_CHARACTER = /[\u0000-\u001f\u007f]/; |
| 19 | |
| 20 | /** |
| 21 | * Validate and normalize a raw `base_path` value into its canonical stored form. |
| 22 | * |
| 23 | * Relative and absolute pathname inputs are accepted and interpreted as a fixed |
| 24 | * root-relative request prefix. Empty and dot segments are resolved before a |
| 25 | * leading and trailing slash are applied. URL-shaped values, query or fragment |
| 26 | * delimiters, backslashes, control characters, and percent-encoded sequences |
| 27 | * are rejected. Unicode pathname characters are allowed. |
| 28 | */ |
| 29 | export function normalizeBasePath(value: unknown): BasePathValidationResult { |
| 30 | if (value === "/") { |
| 31 | return { valid: true, value: "/" }; |
| 32 | } |
| 33 | |
| 34 | if (typeof value !== "string") { |
| 35 | return { |
| 36 | valid: false, |
| 37 | error: `Expected a string but got ${typeof value}.`, |
| 38 | }; |
| 39 | } |
| 40 | |
| 41 | if (value.length === 0) { |
| 42 | return { valid: false, error: `The value must not be empty.` }; |
| 43 | } |
| 44 | |
| 45 | if (value.startsWith("//") || /^[a-zA-Z][a-zA-Z\d+.-]*:/.test(value)) { |
| 46 | return { |
| 47 | valid: false, |
| 48 | error: `The value must be a pathname, not a URL.`, |
| 49 | }; |
| 50 | } |
| 51 | |
| 52 | if (value.includes("\\")) { |
| 53 | return { valid: false, error: `The value must not contain backslashes.` }; |
| 54 | } |
| 55 | |
| 56 | if (CONTROL_CHARACTER.test(value)) { |
| 57 | return { |
| 58 | valid: false, |
| 59 | error: `The value must not contain control characters.`, |
| 60 | }; |
| 61 | } |
| 62 | |
| 63 | if (value.includes("?") || value.includes("#")) { |
| 64 | return { |
| 65 | valid: false, |
| 66 | error: `The value must not contain query strings or fragments.`, |
| 67 | }; |
| 68 | } |
| 69 | |
| 70 | if (value.includes("%")) { |
| 71 | return { |
| 72 | valid: false, |
| 73 | error: `The value must not contain percent-encoded sequences.`, |
| 74 | }; |
| 75 | } |
| 76 | |
| 77 | const normalizedSegments: string[] = []; |
| 78 | for (const segment of value.split("/")) { |
| 79 | if (segment === "" || segment === ".") { |
| 80 | continue; |
| 81 | } |
| 82 | if (segment === "..") { |
| 83 | normalizedSegments.pop(); |
| 84 | continue; |
| 85 | } |
| 86 | normalizedSegments.push(segment); |
| 87 | } |
| 88 | |
| 89 | const canonical = normalizedSegments.length === 0 ? "/" : `/${normalizedSegments.join("/")}/`; |
| 90 | return { valid: true, value: canonical }; |
| 91 | } |
| 92 | |
| 93 | /** |
| 94 | * Decode and normalize a URI-encoded `base_path` without decoding reserved URI |
| 95 | * delimiters. In particular, `decodeURI` leaves encoded path separators such |
| 96 | * as `%2F` intact so that `normalizeBasePath` rejects them as ambiguous. |
| 97 | */ |
| 98 | export function normalizeUriEncodedBasePath(value: unknown): BasePathValidationResult { |
| 99 | if (typeof value !== "string") { |
| 100 | return normalizeBasePath(value); |
| 101 | } |
| 102 | |
| 103 | try { |
| 104 | return normalizeBasePath(decodeURI(value)); |
| 105 | } catch { |
| 106 | return { |
| 107 | valid: false, |
| 108 | error: `The value contains malformed URI encoding.`, |
| 109 | }; |
| 110 | } |
| 111 | } |