Files
reverse-engineering-anything/src/domain/artifactPathSyntax.ts
T

94 lines
3.8 KiB
TypeScript

import { strictUtf8Decoder } from "./strictUtf8.js";
/**
* Pure string predicates for artifact path syntax. The local artifact
* resolver, the Electron native specifier check, and (by reference) the
* live-DOM and source-map URL handling share these character-level rules.
*
* Policy divergence (deliberate, not yet unified):
* - Local artifact paths resolve against an inventoried container root and
* report rejected | external | not-found. Confinement is lexical
* (normalizeJoinedLogicalPath must stay inside the root).
* - Live DOM destinations resolve against the document base URL and report
* approved | outside_policy | unsupported against allowedOrigins
* (see CdpCaptureDocuments.domDestination).
* - Source-map fetches require exact-origin http(s) without credentials
* (see WebSourceMapFetcher.approvedUrl).
* Unifying those outcome vocabularies is a separate, observable change.
*/
/** Whether a reference carries a URI scheme (`https:`, `file:`, …). */
export const hasScheme = (value: string): boolean =>
/^[A-Za-z][A-Za-z0-9+.-]*:/u.test(value);
/** Whether a reference is scheme-qualified or protocol-relative. */
export const looksExternal = (value: string): boolean =>
hasScheme(value) || value.startsWith("//");
/** Drop any query string and fragment from a declared reference. */
export const stripQueryAndFragment = (value: string): string =>
value.split("#", 1)[0]?.split("?", 1)[0] ?? "";
/** Path syntax admitted for a canonical artifact path. */
export const admitsCanonicalPathSyntax = (value: string): boolean =>
!value.includes("\0") &&
!value.includes("\\") &&
!/%(?:2e|2f|5c)/iu.test(value);
/** C0 controls and space, which the URL parser strips around its input. */
const isUrlTrimmed = (code: number): boolean => code <= 0x20;
/**
* The URL text a browser parses from an HTML URL attribute: HTML strips
* surrounding ASCII whitespace, and the URL parser strips surrounding C0
* controls and spaces and removes every tab and newline.
*/
export const htmlUrlText = (value: string): string => {
let start = 0;
let end = value.length;
while (start < end && isUrlTrimmed(value.charCodeAt(start))) start += 1;
while (end > start && isUrlTrimmed(value.charCodeAt(end - 1))) end -= 1;
return value.slice(start, end).replace(/[\t\n\r]/gu, "");
};
const UTF8 = strictUtf8Decoder("preserve");
const hexNibble = (byte: number): number => {
if (byte >= 0x30 && byte <= 0x39) return byte - 0x30;
const lower = byte | 0x20;
return lower >= 0x61 && lower <= 0x66 ? lower - 0x61 + 10 : -1;
};
/**
* Percent-decode a URL path as the URL standard does: valid `%XX` sequences
* become bytes and any other `%` stays literal. Returns null when the bytes
* are not UTF-8 or include NUL, because no canonical artifact path can match
* them. Callers refuse encoded dot and separator bytes before decoding.
*/
export const percentDecodeUrlPath = (value: string): string | null => {
if (!/%[0-9a-f]{2}/iu.test(value)) return value;
// Percent escapes are ASCII, so their markers cannot be confused with a
// UTF-8 code unit. Compact the encoded path into its own byte buffer.
const bytes = Buffer.from(value, "utf8");
let written = 0;
for (let read = 0; read < bytes.length; read++) {
const byte = bytes[read]!;
if (byte === 0x25 && read + 2 < bytes.length) {
const high = hexNibble(bytes[read + 1]!);
const low = hexNibble(bytes[read + 2]!);
if (high >= 0 && low >= 0) {
bytes[written++] = (high << 4) | low;
read += 2;
continue;
}
}
bytes[written++] = byte;
}
try {
const decoded = UTF8.decode(bytes.subarray(0, written));
return decoded.includes("\0") ? null : decoded;
} catch (cause: unknown) {
// Invalid UTF-8 cannot name an inventoried path.
void cause;
return null;
}
};