@hraness/kb 0.17.1

package/dist/index-7fzc32gf.js

@@ -0,0 +1,712 @@
+// @bun
+import {
+  assertSafeNetworkUrl,
+  decodeBytes,
+  isPrivateHostname,
+  safeFetch
+} from "./index-e5fbsywq.js";
+import {
+  sanitizeArtifactUrl
+} from "./index-mxxxytys.js";
+
+// src/clip/url-intelligence.ts
+var MAX_METADATA_SEARCH_RESULTS = 20;
+var MAX_METADATA_SEARCH_ENGINES = 8;
+var MAX_METADATA_SEARCH_QUERY_UTF8_BYTES = 4 * 1024;
+var MAX_METADATA_SEARCH_TITLE_UTF8_BYTES = 2 * 1024;
+var MAX_METADATA_SEARCH_SNIPPET_UTF8_BYTES = 8 * 1024;
+var MAX_URL_INTELLIGENCE_URL_UTF8_BYTES = 16 * 1024;
+var MAX_METADATA_SEARCH_TEXT_UTF8_BYTES = 512 * 1024;
+var MAX_METADATA_SEARCH_RESPONSE_BYTES = 2 * 1024 * 1024;
+var MAX_ARCHIVE_TIMEMAP_UTF8_BYTES = 512 * 1024;
+var MAX_ARCHIVE_TIMEMAP_ENTRIES = 512;
+var MAX_ARCHIVE_TIMEMAP_PARAMETERS_PER_ENTRY = 16;
+var ARCHIVE_TODAY_HOSTS = Object.freeze([
+  "archive.today",
+  "archive.is",
+  "archive.ph",
+  "archive.fo",
+  "archive.li",
+  "archive.md",
+  "archive.vn"
+]);
+var archiveTodayHosts = new Set(ARCHIVE_TODAY_HOSTS);
+var tokenCharacter = /^[!#$%&'*+.^_`|~0-9A-Za-z-]$/u;
+var engineName = /^[a-z0-9][a-z0-9._-]{0,127}$/u;
+function fail(label, message) {
+  throw new TypeError(`${label} ${message}`);
+}
+function isUnsafeControlCodePoint(codePoint, rejectSurrogates = false, allowLinkWhitespace = false) {
+  return codePoint <= 31 && !(allowLinkWhitespace && (codePoint === 9 || codePoint === 10 || codePoint === 13)) || codePoint >= 127 && codePoint <= 159 || codePoint === 1564 || codePoint === 8206 || codePoint === 8207 || codePoint >= 8234 && codePoint <= 8238 || codePoint >= 8294 && codePoint <= 8297 || rejectSurrogates && codePoint >= 55296 && codePoint <= 57343;
+}
+function hasUnsafeControls(value, rejectSurrogates = false, allowLinkWhitespace = false) {
+  return Array.from(value).some((character) => isUnsafeControlCodePoint(character.codePointAt(0), rejectSurrogates, allowLinkWhitespace));
+}
+function record(value, label) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return fail(label, "must be an object.");
+  }
+  return value;
+}
+function strictKeys(value, allowed, label) {
+  const allowedKeys = new Set(allowed);
+  const unknown = Object.keys(value).filter((key) => !allowedKeys.has(key)).toSorted();
+  if (unknown.length > 0)
+    fail(label, `has unknown fields: ${unknown.join(", ")}.`);
+}
+function boundedString(value, label, maximumBytes, budget) {
+  if (typeof value !== "string")
+    return fail(label, "must be a string.");
+  const bytes = Buffer.byteLength(value, "utf8");
+  if (bytes > maximumBytes)
+    fail(label, `must be at most ${maximumBytes} UTF-8 bytes.`);
+  if (budget !== undefined) {
+    budget.bytes += bytes;
+    if (budget.bytes > MAX_METADATA_SEARCH_TEXT_UTF8_BYTES) {
+      fail("Metadata search response", `may contain at most ${MAX_METADATA_SEARCH_TEXT_UTF8_BYTES} UTF-8 bytes of text.`);
+    }
+  }
+  return value;
+}
+function cleanDisplayText(value, label, maximumBytes, budget) {
+  const text = boundedString(value, label, maximumBytes, budget);
+  return Array.from(text, (character) => isUnsafeControlCodePoint(character.codePointAt(0)) ? " " : character).join("").replace(/ +/gu, " ").trim();
+}
+function checkedEngine(value, label, budget) {
+  const engine = boundedString(value, label, 128, budget);
+  if (!engineName.test(engine))
+    fail(label, "must be a lowercase engine identifier.");
+  return engine;
+}
+function uniqueEngineArray(value, label, budget, allowEmpty) {
+  if (!Array.isArray(value) || value.length > MAX_METADATA_SEARCH_ENGINES || !allowEmpty && value.length === 0) {
+    return fail(label, `must be ${allowEmpty ? "an" : "a non-empty"} array with at most ${MAX_METADATA_SEARCH_ENGINES} entries.`);
+  }
+  const engines = value.map((entry, index) => checkedEngine(entry, `${label}[${index}]`, budget));
+  if (new Set(engines).size !== engines.length)
+    fail(label, "must not contain duplicates.");
+  return Object.freeze(engines);
+}
+function publicHttpUrl(value) {
+  const raw = value instanceof URL ? value.href : value;
+  if (typeof raw !== "string" || raw === "" || raw !== raw.trim() || hasUnsafeControls(raw) || Buffer.byteLength(raw, "utf8") > MAX_URL_INTELLIGENCE_URL_UTF8_BYTES)
+    return null;
+  let parsed;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    return null;
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:" || parsed.username !== "" || parsed.password !== "" || parsed.hostname === "" || isPrivateHostname(parsed.hostname))
+    return null;
+  return parsed;
+}
+function normalizeSourceUrlIdentity(value) {
+  const parsed = publicHttpUrl(value);
+  if (parsed === null)
+    return null;
+  parsed.hash = "";
+  return parsed.href;
+}
+function isExactSourceTarget(candidate, target) {
+  const candidateIdentity = normalizeSourceUrlIdentity(candidate);
+  const targetIdentity = normalizeSourceUrlIdentity(target);
+  return candidateIdentity !== null && targetIdentity !== null && candidateIdentity === targetIdentity;
+}
+function parseMetadataResult(value, index, queried, failed, budget) {
+  const label = `Metadata search response.results[${index}]`;
+  const input = record(value, label);
+  strictKeys(input, ["title", "url", "snippet", "engines", "score"], label);
+  const title = cleanDisplayText(input.title, `${label}.title`, MAX_METADATA_SEARCH_TITLE_UTF8_BYTES, budget);
+  if (title === "")
+    fail(`${label}.title`, "must contain visible text.");
+  const rawUrl = boundedString(input.url, `${label}.url`, MAX_URL_INTELLIGENCE_URL_UTF8_BYTES, budget);
+  const url = normalizeSourceUrlIdentity(rawUrl);
+  if (url === null)
+    fail(`${label}.url`, "must be a public HTTP or HTTPS URL without credentials or controls.");
+  const cleanedSnippet = input.snippet === null ? null : cleanDisplayText(input.snippet, `${label}.snippet`, MAX_METADATA_SEARCH_SNIPPET_UTF8_BYTES, budget);
+  const snippet = cleanedSnippet === "" ? null : cleanedSnippet;
+  const engines = uniqueEngineArray(input.engines, `${label}.engines`, budget, false);
+  for (const engine of engines) {
+    if (!queried.has(engine))
+      fail(`${label}.engines`, `contains unqueried engine ${engine}.`);
+    if (failed.has(engine))
+      fail(`${label}.engines`, `contains failed engine ${engine}.`);
+  }
+  if (typeof input.score !== "number" || !Number.isFinite(input.score) || input.score <= 0) {
+    fail(`${label}.score`, "must be a positive finite number.");
+  }
+  return Object.freeze({ title, url, snippet, engines, score: input.score });
+}
+function parseMetadataSearchResponse(value) {
+  const input = record(value, "Metadata search response");
+  strictKeys(input, ["query", "results", "engines_queried", "engines_failed"], "Metadata search response");
+  const budget = { bytes: 0 };
+  const query = boundedString(input.query, "Metadata search response.query", MAX_METADATA_SEARCH_QUERY_UTF8_BYTES, budget);
+  if (query === "" || query !== query.trim() || hasUnsafeControls(query)) {
+    fail("Metadata search response.query", "must be non-empty, trimmed, and free of controls.");
+  }
+  const enginesQueried = uniqueEngineArray(input.engines_queried, "Metadata search response.engines_queried", budget, false);
+  const enginesFailed = uniqueEngineArray(input.engines_failed, "Metadata search response.engines_failed", budget, true);
+  const queried = new Set(enginesQueried);
+  for (const engine of enginesFailed) {
+    if (!queried.has(engine))
+      fail("Metadata search response.engines_failed", `contains unqueried engine ${engine}.`);
+  }
+  if (!Array.isArray(input.results) || input.results.length > MAX_METADATA_SEARCH_RESULTS) {
+    fail("Metadata search response.results", `must be an array with at most ${MAX_METADATA_SEARCH_RESULTS} entries.`);
+  }
+  const failed = new Set(enginesFailed);
+  const results = Object.freeze(input.results.map((result, index) => parseMetadataResult(result, index, queried, failed, budget)));
+  return Object.freeze({
+    query,
+    results,
+    enginesQueried,
+    enginesFailed,
+    engineStatus: enginesFailed.length === 0 ? "complete" : enginesFailed.length === enginesQueried.length ? "unavailable" : "partial"
+  });
+}
+function rankMetadataSearchResults(results, options = {}) {
+  const limit = options.limit ?? MAX_METADATA_SEARCH_RESULTS;
+  if (!Number.isSafeInteger(limit) || limit < 0 || limit > MAX_METADATA_SEARCH_RESULTS) {
+    throw new RangeError(`Metadata search rank limit must be from 0 through ${MAX_METADATA_SEARCH_RESULTS}.`);
+  }
+  if (limit === 0)
+    return Object.freeze([]);
+  const targetIdentity = options.targetUrl === undefined ? null : normalizeSourceUrlIdentity(options.targetUrl);
+  const decorated = results.flatMap((result, index) => {
+    const sourceIdentity = normalizeSourceUrlIdentity(result.url);
+    return sourceIdentity === null ? [] : [{ result, index, sourceIdentity, exactTarget: sourceIdentity === targetIdentity }];
+  }).toSorted((left, right) => Number(right.exactTarget) - Number(left.exactTarget) || right.result.score - left.result.score || left.index - right.index);
+  const seen = new Set;
+  const ranked = [];
+  for (const item of decorated) {
+    if (seen.has(item.sourceIdentity))
+      continue;
+    seen.add(item.sourceIdentity);
+    ranked.push(Object.freeze({
+      ...item.result,
+      rank: ranked.length + 1,
+      sourceIdentity: item.sourceIdentity,
+      exactTarget: item.exactTarget
+    }));
+    if (ranked.length === limit)
+      break;
+  }
+  return Object.freeze(ranked);
+}
+function isWhitespace(character) {
+  return character === " " || character === "\t" || character === "\r" || character === `
+`;
+}
+function parseLinkFormat(source) {
+  let cursor = 0;
+  const links = [];
+  const skipWhitespace = () => {
+    while (isWhitespace(source[cursor]))
+      cursor += 1;
+  };
+  const syntax = (message) => fail("Archive.today TimeMap", `${message} at offset ${cursor}.`);
+  skipWhitespace();
+  while (cursor < source.length) {
+    if (links.length >= MAX_ARCHIVE_TIMEMAP_ENTRIES) {
+      fail("Archive.today TimeMap", `may contain at most ${MAX_ARCHIVE_TIMEMAP_ENTRIES} entries.`);
+    }
+    if (source[cursor] !== "<")
+      syntax("must start each link with '<'");
+    cursor += 1;
+    const targetStart = cursor;
+    while (cursor < source.length && source[cursor] !== ">") {
+      const character = source[cursor];
+      if (character === "<" || character === '"' || character === "\\" || isWhitespace(character)) {
+        syntax("contains an invalid target character");
+      }
+      cursor += 1;
+    }
+    if (cursor >= source.length)
+      syntax("has an unterminated target");
+    const target = source.slice(targetStart, cursor);
+    cursor += 1;
+    if (target === "" || Buffer.byteLength(target, "utf8") > MAX_URL_INTELLIGENCE_URL_UTF8_BYTES) {
+      syntax("has an empty or oversized target");
+    }
+    const parameters = new Map;
+    skipWhitespace();
+    while (source[cursor] === ";") {
+      if (parameters.size >= MAX_ARCHIVE_TIMEMAP_PARAMETERS_PER_ENTRY) {
+        fail("Archive.today TimeMap", `entries may contain at most ${MAX_ARCHIVE_TIMEMAP_PARAMETERS_PER_ENTRY} parameters.`);
+      }
+      cursor += 1;
+      skipWhitespace();
+      const nameStart = cursor;
+      while (tokenCharacter.test(source[cursor] ?? ""))
+        cursor += 1;
+      if (cursor === nameStart)
+        syntax("has an invalid parameter name");
+      const name = source.slice(nameStart, cursor).toLowerCase();
+      skipWhitespace();
+      if (source[cursor] !== "=")
+        syntax("requires '=' after a parameter name");
+      cursor += 1;
+      skipWhitespace();
+      let parameterValue = "";
+      if (source[cursor] === '"') {
+        cursor += 1;
+        let terminated = false;
+        while (cursor < source.length) {
+          const character = source[cursor] ?? "";
+          cursor += 1;
+          if (character === '"') {
+            terminated = true;
+            break;
+          }
+          if (character === "\\") {
+            if (cursor >= source.length)
+              syntax("has an unterminated quoted escape");
+            const escaped = source[cursor] ?? "";
+            if (hasUnsafeControls(escaped))
+              syntax("has a control in a quoted escape");
+            parameterValue += escaped;
+            cursor += 1;
+          } else {
+            if (hasUnsafeControls(character))
+              syntax("has a control in a quoted value");
+            parameterValue += character;
+          }
+        }
+        if (!terminated)
+          syntax("has an unterminated quoted value");
+      } else {
+        const valueStart = cursor;
+        while (tokenCharacter.test(source[cursor] ?? ""))
+          cursor += 1;
+        if (cursor === valueStart)
+          syntax("has an invalid parameter value");
+        parameterValue = source.slice(valueStart, cursor);
+      }
+      if (Buffer.byteLength(parameterValue, "utf8") > MAX_URL_INTELLIGENCE_URL_UTF8_BYTES) {
+        syntax("has an oversized parameter value");
+      }
+      if (parameters.has(name))
+        syntax(`repeats parameter ${name}`);
+      parameters.set(name, parameterValue);
+      skipWhitespace();
+    }
+    links.push(Object.freeze({ target, parameters }));
+    if (cursor === source.length)
+      break;
+    if (source[cursor] !== ",")
+      syntax("must separate links with ','");
+    cursor += 1;
+    skipWhitespace();
+    if (cursor === source.length)
+      syntax("must not end with ','");
+  }
+  return Object.freeze(links);
+}
+var months = new Map([
+  ["Jan", 0],
+  ["Feb", 1],
+  ["Mar", 2],
+  ["Apr", 3],
+  ["May", 4],
+  ["Jun", 5],
+  ["Jul", 6],
+  ["Aug", 7],
+  ["Sep", 8],
+  ["Oct", 9],
+  ["Nov", 10],
+  ["Dec", 11]
+]);
+var weekdays = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+function epochFromTimestamp(timestamp, label) {
+  const match = /^(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})$/u.exec(timestamp);
+  if (match === null)
+    return fail(label, "must contain a 14-digit UTC timestamp.");
+  const [year, month, day, hour, minute, second] = match.slice(1).map(Number);
+  const epoch = Date.UTC(year, month - 1, day, hour, minute, second);
+  const date = new Date(epoch);
+  if (year < 1900 || date.getUTCFullYear() !== year || date.getUTCMonth() !== month - 1 || date.getUTCDate() !== day || date.getUTCHours() !== hour || date.getUTCMinutes() !== minute || date.getUTCSeconds() !== second)
+    return fail(label, "contains an invalid UTC timestamp.");
+  return epoch;
+}
+function epochFromHttpDate(value, label) {
+  const match = /^(Sun|Mon|Tue|Wed|Thu|Fri|Sat), (\d{2}) (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) (\d{4}) (\d{2}):(\d{2}):(\d{2}) GMT$/u.exec(value);
+  if (match === null)
+    return fail(label, "must be an RFC 1123 date in GMT.");
+  const month = months.get(match[3] ?? "");
+  if (month === undefined)
+    return fail(label, "has an invalid month.");
+  const year = Number(match[4]);
+  const day = Number(match[2]);
+  const hour = Number(match[5]);
+  const minute = Number(match[6]);
+  const second = Number(match[7]);
+  const epoch = Date.UTC(year, month, day, hour, minute, second);
+  const date = new Date(epoch);
+  if (year < 1900 || date.getUTCFullYear() !== year || date.getUTCMonth() !== month || date.getUTCDate() !== day || date.getUTCHours() !== hour || date.getUTCMinutes() !== minute || date.getUTCSeconds() !== second || weekdays[date.getUTCDay()] !== match[1])
+    return fail(label, "contains an invalid RFC 1123 date.");
+  return epoch;
+}
+function checkedNow(now) {
+  if (!(now instanceof Date) || !Number.isFinite(now.getTime())) {
+    return fail("Archive.today now", "must be a valid injected Date.");
+  }
+  return now.getTime();
+}
+function parsedArchiveTodayMementoUrl(value, originalIdentity, nowEpoch, expectedEpoch) {
+  const raw = value instanceof URL ? value.href : value;
+  if (typeof raw !== "string" || raw !== raw.trim() || hasUnsafeControls(raw) || Buffer.byteLength(raw, "utf8") > MAX_URL_INTELLIGENCE_URL_UTF8_BYTES) {
+    return fail("Archive.today memento URL", "must be a bounded control-free URL.");
+  }
+  let archiveUrl;
+  try {
+    archiveUrl = new URL(raw);
+  } catch {
+    return fail("Archive.today memento URL", "must be a valid URL.");
+  }
+  if (archiveUrl.protocol !== "http:" && archiveUrl.protocol !== "https:" || archiveUrl.username !== "" || archiveUrl.password !== "" || archiveUrl.port !== "" || archiveUrl.hash !== "" || !archiveTodayHosts.has(archiveUrl.hostname))
+    return fail("Archive.today memento URL", "must use an allowlisted archive host without credentials, a port, or a fragment.");
+  const path = /^\/(\d{14})\/(https?:\/\/.*)$/u.exec(archiveUrl.pathname);
+  if (path === null || path[1] === undefined || path[2] === undefined) {
+    return fail("Archive.today memento URL", "must use a timestamped read-only snapshot path.");
+  }
+  const timestamp = path[1];
+  const capturedEpoch = epochFromTimestamp(timestamp, "Archive.today memento URL timestamp");
+  if (capturedEpoch > nowEpoch)
+    fail("Archive.today memento URL timestamp", "must not be in the future.");
+  if (expectedEpoch !== undefined && capturedEpoch !== expectedEpoch) {
+    fail("Archive.today memento URL timestamp", "must equal its Memento datetime.");
+  }
+  const embeddedIdentity = normalizeSourceUrlIdentity(`${path[2]}${archiveUrl.search}`);
+  if (embeddedIdentity === null || embeddedIdentity !== originalIdentity) {
+    fail("Archive.today memento URL", "must embed the exact bound original URL.");
+  }
+  const archiveHost = archiveUrl.hostname;
+  archiveUrl.protocol = "https:";
+  return Object.freeze({
+    url: archiveUrl.href,
+    archiveHost,
+    timestamp,
+    capturedAt: new Date(capturedEpoch).toISOString(),
+    originalUrl: originalIdentity
+  });
+}
+function parseArchiveTodayMementoUrl(value, options) {
+  const originalIdentity = normalizeSourceUrlIdentity(options.originalUrl);
+  if (originalIdentity === null)
+    fail("Archive.today original URL", "must be a public HTTP or HTTPS URL without credentials.");
+  return parsedArchiveTodayMementoUrl(value, originalIdentity, checkedNow(options.now));
+}
+function selectNewestArchiveTodayMemento(mementos) {
+  return mementos.toSorted((left, right) => right.timestamp.localeCompare(left.timestamp) || left.url.localeCompare(right.url))[0] ?? null;
+}
+function parseArchiveTodayTimeMap(value, options) {
+  if (typeof value !== "string")
+    fail("Archive.today TimeMap", "must be text.");
+  if (Buffer.byteLength(value, "utf8") > MAX_ARCHIVE_TIMEMAP_UTF8_BYTES) {
+    fail("Archive.today TimeMap", `must be at most ${MAX_ARCHIVE_TIMEMAP_UTF8_BYTES} UTF-8 bytes.`);
+  }
+  if (hasUnsafeControls(value, true, true)) {
+    fail("Archive.today TimeMap", "contains forbidden controls.");
+  }
+  const originalIdentity = normalizeSourceUrlIdentity(options.originalUrl);
+  if (originalIdentity === null)
+    fail("Archive.today original URL", "must be a public HTTP or HTTPS URL without credentials.");
+  const nowEpoch = checkedNow(options.now);
+  const links = parseLinkFormat(value);
+  const originals = links.filter((link) => link.parameters.get("rel")?.toLowerCase() === "original");
+  if (originals.length !== 1)
+    fail("Archive.today TimeMap", "must contain exactly one rel=original link.");
+  const declaredOriginal = normalizeSourceUrlIdentity(originals[0]?.target ?? "");
+  if (declaredOriginal === null || declaredOriginal !== originalIdentity) {
+    fail("Archive.today TimeMap rel=original", "must exactly match the requested original URL.");
+  }
+  const mementos = [];
+  const seen = new Set;
+  for (const [index, link] of links.entries()) {
+    const relations = (link.parameters.get("rel") ?? "").trim().toLowerCase().split(/[ \t]+/u).filter(Boolean);
+    if (!relations.includes("memento"))
+      continue;
+    if (relations.includes("original"))
+      fail(`Archive.today TimeMap entry ${index}`, "cannot be both original and memento.");
+    const datetime = link.parameters.get("datetime");
+    if (datetime === undefined)
+      fail(`Archive.today TimeMap entry ${index}`, "requires a datetime parameter.");
+    const expectedEpoch = epochFromHttpDate(datetime, `Archive.today TimeMap entry ${index} datetime`);
+    if (expectedEpoch > nowEpoch)
+      fail(`Archive.today TimeMap entry ${index} datetime`, "must not be in the future.");
+    const memento = parsedArchiveTodayMementoUrl(link.target, originalIdentity, nowEpoch, expectedEpoch);
+    if (!seen.has(memento.url)) {
+      seen.add(memento.url);
+      mementos.push(memento);
+    }
+  }
+  const sorted = Object.freeze(mementos.toSorted((left, right) => right.timestamp.localeCompare(left.timestamp) || left.url.localeCompare(right.url)));
+  return Object.freeze({
+    originalUrl: originalIdentity,
+    mementos: sorted,
+    newest: selectNewestArchiveTodayMemento(sorted)
+  });
+}
+
+// src/clip/archive-today.ts
+var archiveTodayDiscoveryOrigin = "https://archive.ph";
+var archiveTodayDiscoveryPrefix = `${archiveTodayDiscoveryOrigin}/newest/`;
+var defaultUserAgent = "@hraness/kb archive-today fallback";
+var defaultTimeoutMs = 1e4;
+var defaultMaximumBytes = 8 * 1024 * 1024;
+var discoveryMaximumBytes = 256 * 1024;
+var maximumSourceUrlBytes = 16 * 1024;
+var maximumUserAgentBytes = 512;
+var failureMessages = Object.freeze({
+  "invalid-source-url": "Archive.today requires a bounded public HTTP(S) source URL.",
+  "invalid-snapshot": "Archive.today returned a snapshot that could not be bound to the source URL.",
+  "invalid-clock": "Archive.today validation requires a valid current time.",
+  "invalid-options": "Archive.today adapter options are outside their supported bounds.",
+  "request-failed": "Archive.today could not be reached.",
+  "not-found": "The validated Archive.today snapshot is no longer available.",
+  throttled: "Archive.today throttled the request.",
+  "unexpected-response": "Archive.today returned an unexpected response.",
+  "unsupported-content": "Archive.today did not return a non-empty HTML document."
+});
+
+class ArchiveTodayFailure extends Error {
+  code;
+  constructor(code) {
+    super(failureMessages[code]);
+    this.name = "ArchiveTodayFailure";
+    this.code = code;
+  }
+}
+function utf8Length(value) {
+  return new TextEncoder().encode(value).byteLength;
+}
+function containsUnsafeLocationControl(value) {
+  for (const character of value) {
+    const codePoint = character.codePointAt(0) ?? 0;
+    if (codePoint <= 31 || codePoint >= 127 && codePoint <= 159 || codePoint === 1564 || codePoint === 8206 || codePoint === 8207 || codePoint >= 8234 && codePoint <= 8238 || codePoint >= 8294 && codePoint <= 8297)
+      return true;
+  }
+  return false;
+}
+function boundedInteger(value, fallback, minimum, maximum) {
+  const selected = value ?? fallback;
+  if (!Number.isSafeInteger(selected) || selected < minimum || selected > maximum) {
+    throw new ArchiveTodayFailure("invalid-options");
+  }
+  return selected;
+}
+function resolveDependencies(dependencies) {
+  let now;
+  try {
+    now = dependencies.now?.() ?? new Date;
+  } catch {
+    throw new ArchiveTodayFailure("invalid-clock");
+  }
+  if (!(now instanceof Date) || !Number.isFinite(now.getTime())) {
+    throw new ArchiveTodayFailure("invalid-clock");
+  }
+  const userAgent = dependencies.userAgent ?? defaultUserAgent;
+  if (userAgent.trim() === "" || utf8Length(userAgent) > maximumUserAgentBytes || containsUnsafeLocationControl(userAgent)) {
+    throw new ArchiveTodayFailure("invalid-options");
+  }
+  return Object.freeze({
+    fetch: dependencies.fetch ?? safeFetch,
+    assertNetworkUrl: dependencies.assertNetworkUrl ?? assertSafeNetworkUrl,
+    now: new Date(now.getTime()),
+    monotonicNow: dependencies.monotonicNow ?? Date.now,
+    timeoutMs: boundedInteger(dependencies.timeoutMs, defaultTimeoutMs, 250, 60000),
+    maxBytes: boundedInteger(dependencies.maxBytes, defaultMaximumBytes, 1, 64 * 1024 * 1024),
+    userAgent
+  });
+}
+function monotonicTime(resolved) {
+  let value;
+  try {
+    value = resolved.monotonicNow();
+  } catch {
+    throw new ArchiveTodayFailure("invalid-clock");
+  }
+  if (!Number.isFinite(value))
+    throw new ArchiveTodayFailure("invalid-clock");
+  return value;
+}
+function remainingTimeout(deadline, resolved) {
+  return Math.floor(deadline - monotonicTime(resolved));
+}
+function normalizeSourceUrl(value) {
+  const identity = normalizeSourceUrlIdentity(value);
+  if (identity === null || utf8Length(identity) > maximumSourceUrlBytes) {
+    throw new ArchiveTodayFailure("invalid-source-url");
+  }
+  if (sanitizeArtifactUrl(identity) !== identity) {
+    throw new ArchiveTodayFailure("invalid-source-url");
+  }
+  return new URL(identity);
+}
+function parseMemento(value, source, now) {
+  try {
+    return parseArchiveTodayMementoUrl(value, { originalUrl: source, now });
+  } catch {
+    throw new ArchiveTodayFailure("invalid-snapshot");
+  }
+}
+function snapshotFromMemento(memento) {
+  return Object.freeze({
+    url: memento.url,
+    capturedAt: memento.capturedAt,
+    sourceUrl: memento.originalUrl,
+    discovery: "newest"
+  });
+}
+function unavailable(sourceUrl, reason) {
+  return Object.freeze({ status: "unavailable", sourceUrl, reason });
+}
+async function discoverArchiveTodaySnapshot(sourceUrl, dependencies = {}) {
+  if (dependencies.fetch !== undefined && dependencies.assertNetworkUrl === undefined) {
+    throw new ArchiveTodayFailure("invalid-options");
+  }
+  const source = normalizeSourceUrl(sourceUrl);
+  const resolved = resolveDependencies(dependencies);
+  const deadline = monotonicTime(resolved) + resolved.timeoutMs;
+  try {
+    await resolved.assertNetworkUrl(source, false, resolved.timeoutMs);
+  } catch {
+    return unavailable(source.href, "request-failed");
+  }
+  const remaining = remainingTimeout(deadline, resolved);
+  if (remaining <= 0)
+    return unavailable(source.href, "request-failed");
+  const lookupUrl = new URL(`${archiveTodayDiscoveryPrefix}${source.href}`);
+  let response;
+  try {
+    response = await resolved.fetch(lookupUrl, {
+      timeoutMs: remaining,
+      maxBytes: discoveryMaximumBytes,
+      allowPrivateNetwork: false,
+      userAgent: resolved.userAgent,
+      accept: "text/html,application/xhtml+xml;q=0.9,*/*;q=0.1",
+      retries: 0,
+      maxRedirects: 0,
+      redirect: "manual",
+      acceptStatuses: [403, 404, 429]
+    });
+  } catch {
+    return unavailable(source.href, "request-failed");
+  }
+  if (response.status === 404) {
+    return Object.freeze({ status: "not-found", sourceUrl: source.href });
+  }
+  if (response.status === 403 || response.status === 429) {
+    return Object.freeze({ status: "throttled", sourceUrl: source.href });
+  }
+  if (response.status < 300 || response.status >= 400) {
+    return unavailable(source.href, "unexpected-response");
+  }
+  if (typeof response.location !== "string" || response.location.trim() === "") {
+    return unavailable(source.href, "invalid-snapshot");
+  }
+  try {
+    if (response.location !== response.location.trim() || containsUnsafeLocationControl(response.location) || utf8Length(response.location) > MAX_URL_INTELLIGENCE_URL_UTF8_BYTES)
+      throw new ArchiveTodayFailure("invalid-snapshot");
+    const location = new URL(response.location, lookupUrl);
+    const memento = parseMemento(location, source, resolved.now);
+    return Object.freeze({
+      status: "found",
+      sourceUrl: source.href,
+      snapshot: snapshotFromMemento(memento)
+    });
+  } catch {
+    return unavailable(source.href, "invalid-snapshot");
+  }
+}
+function isHtmlContentType(value) {
+  if (value === null)
+    return false;
+  const mediaType = value.split(";", 1)[0]?.trim().toLowerCase();
+  return mediaType === "text/html" || mediaType === "application/xhtml+xml";
+}
+async function acquireArchiveTodaySnapshot(sourceUrl, snapshotUrl, dependencies = {}) {
+  if (dependencies.fetch !== undefined && dependencies.assertNetworkUrl === undefined) {
+    throw new ArchiveTodayFailure("invalid-options");
+  }
+  const source = normalizeSourceUrl(sourceUrl);
+  const resolved = resolveDependencies(dependencies);
+  const requested = parseMemento(snapshotUrl, source, resolved.now);
+  let current = new URL(requested.url);
+  let response = null;
+  const deadline = monotonicTime(resolved) + resolved.timeoutMs;
+  try {
+    await resolved.assertNetworkUrl(source, false, resolved.timeoutMs);
+  } catch {
+    throw new ArchiveTodayFailure("request-failed");
+  }
+  for (let redirects = 0;redirects <= 4; redirects += 1) {
+    const remaining = remainingTimeout(deadline, resolved);
+    if (remaining <= 0)
+      throw new ArchiveTodayFailure("request-failed");
+    try {
+      response = await resolved.fetch(current, {
+        timeoutMs: remaining,
+        maxBytes: resolved.maxBytes,
+        allowPrivateNetwork: false,
+        userAgent: resolved.userAgent,
+        accept: "text/html,application/xhtml+xml;q=0.9",
+        retries: 0,
+        maxRedirects: 0,
+        redirect: "manual",
+        acceptStatuses: [403, 404, 429]
+      });
+    } catch {
+      throw new ArchiveTodayFailure("request-failed");
+    }
+    if (response.finalUrl.href !== current.href)
+      throw new ArchiveTodayFailure("invalid-snapshot");
+    if (response.status < 300 || response.status >= 400)
+      break;
+    if (redirects === 4 || typeof response.location !== "string") {
+      throw new ArchiveTodayFailure("invalid-snapshot");
+    }
+    if (response.location !== response.location.trim() || containsUnsafeLocationControl(response.location) || utf8Length(response.location) > MAX_URL_INTELLIGENCE_URL_UTF8_BYTES)
+      throw new ArchiveTodayFailure("invalid-snapshot");
+    let next;
+    try {
+      next = new URL(response.location, current);
+    } catch {
+      throw new ArchiveTodayFailure("invalid-snapshot");
+    }
+    const redirected = parseMemento(next, source, resolved.now);
+    if (redirected.timestamp !== requested.timestamp)
+      throw new ArchiveTodayFailure("invalid-snapshot");
+    current = new URL(redirected.url);
+  }
+  if (response === null)
+    throw new ArchiveTodayFailure("request-failed");
+  if (response.status === 403 || response.status === 429) {
+    throw new ArchiveTodayFailure("throttled");
+  }
+  if (response.status === 404)
+    throw new ArchiveTodayFailure("not-found");
+  if (response.status < 200 || response.status >= 300) {
+    throw new ArchiveTodayFailure("unexpected-response");
+  }
+  const finalMemento = parseMemento(current, source, resolved.now);
+  if (finalMemento.timestamp !== requested.timestamp)
+    throw new ArchiveTodayFailure("invalid-snapshot");
+  if (!isHtmlContentType(response.contentType)) {
+    throw new ArchiveTodayFailure("unsupported-content");
+  }
+  const body = decodeBytes(response.bytes, response.contentType);
+  if (body.trim() === "")
+    throw new ArchiveTodayFailure("unsupported-content");
+  return Object.freeze({
+    body,
+    contentType: response.contentType,
+    finalUrl: new URL(finalMemento.url),
+    method: "archive-is",
+    warnings: Object.freeze(["Captured from a validated Archive.today snapshot."])
+  });
+}
+
+export { ARCHIVE_TODAY_HOSTS, normalizeSourceUrlIdentity, isExactSourceTarget, parseMetadataSearchResponse, rankMetadataSearchResults, parseArchiveTodayMementoUrl, selectNewestArchiveTodayMemento, parseArchiveTodayTimeMap, ArchiveTodayFailure, discoverArchiveTodaySnapshot, acquireArchiveTodaySnapshot };