app/lib/webmention/urls.mjs

Functions

Imports

It imports app/lib/content/slug.mjs. Imported by app/components/post-mentions.tsx, app/lib/webmention/verify.server.ts, app/routes/webmention.ts.

Source

1import { SLUG_PATTERN } from "../content/slug.mjs";
2
3// Pure so node:test can reach it (the route imports `~/lib/context`). Allowed origins are passed in, never
4// a constant: the site answers on two hosts across the cutover. The slug uses the imported `SLUG_PATTERN`;
5// a local regex would fail silently in the permissive direction.
6
7const BLOG_PREFIX = "/writing/";
8
9/**
10 * Null for every rejection: distinct refusals would let a caller map this site's URL space.
11 *
12 * @param {string} target the `target` field, verbatim
13 * @param {readonly string[]} allowedOrigins origins this site answers on
14 * @returns {string | null} the post slug, or null
15 */
16export function targetSlug(target, allowedOrigins) {
17  let url;
18  try {
19    url = new URL(target);
20  } catch {
21    return null;
22  }
23  if (url.protocol !== "https:" && url.protocol !== "http:") return null;
24  if (!allowedOrigins.includes(url.origin)) return null;
25
26  // `new URL` has already resolved dot segments and decoded the path, so only prefix and shape remain.
27  if (!url.pathname.startsWith(BLOG_PREFIX)) return null;
28  const rest = url.pathname.slice(BLOG_PREFIX.length);
29  // A trailing slash is the same post; anything with a further segment is not.
30  const slug = rest.endsWith("/") ? rest.slice(0, -1) : rest;
31  if (!SLUG_PATTERN.test(slug)) return null;
32  return slug;
33}
34
35/**
36 * IPv6 reaches `hostname` bracketed. `http://2130706433/` stays all digits, so the digits arm catches it.
37 *
38 * @param {string} hostname
39 */
40function isIpLiteral(hostname) {
41  if (hostname.startsWith("[")) return true;
42  if (/^[0-9]+$/.test(hostname)) return true;
43  return /^[0-9]{1,3}(?:\.[0-9]{1,3}){3}$/.test(hostname);
44}
45
46/**
47 * RFC 6761 reserves the whole `.localhost` tree, and some resolvers honor it.
48 *
49 * @param {string} hostname
50 */
51function isLoopbackName(hostname) {
52  const host = hostname.toLowerCase();
53  return host === "localhost" || host.endsWith(".localhost");
54}
55
56const SOURCE_REFUSALS = {
57  unparseable: "source is not an absolute URL",
58  protocol: "source must be http or https",
59  selfOrigin: "source must be another site",
60  ipLiteral: "source must name a host, not an IP address",
61  loopback: "source must not be a loopback address",
62  sameAsTarget: "source and target must differ",
63};
64
65/**
66 * The verifier fetches the source, so these refusals bound SSRF. NOT a complete defence: public DNS can
67 * resolve to a private address. The runtime bounds the rest: a Worker's `fetch` has no private network
68 * or metadata endpoint, and the verifier reads at most 1 MB and stores no markup.
69 *
70 * @param {string} source the `source` field, verbatim
71 * @param {string} target the `target` field, verbatim
72 * @param {readonly string[]} allowedOrigins origins this site answers on
73 * @returns {{ ok: true } | { ok: false, reason: string }}
74 */
75export function sourceVerdict(source, target, allowedOrigins) {
76  let url;
77  try {
78    url = new URL(source);
79  } catch {
80    return { ok: false, reason: SOURCE_REFUSALS.unparseable };
81  }
82  if (url.protocol !== "https:" && url.protocol !== "http:") {
83    return { ok: false, reason: SOURCE_REFUSALS.protocol };
84  }
85  if (allowedOrigins.includes(url.origin)) {
86    return { ok: false, reason: SOURCE_REFUSALS.selfOrigin };
87  }
88  if (isLoopbackName(url.hostname)) {
89    return { ok: false, reason: SOURCE_REFUSALS.loopback };
90  }
91  if (isIpLiteral(url.hostname)) {
92    return { ok: false, reason: SOURCE_REFUSALS.ipLiteral };
93  }
94  if (source === target) {
95    return { ok: false, reason: SOURCE_REFUSALS.sameAsTarget };
96  }
97  return { ok: true };
98}
99
100/**
101 * A trailing slash and the fragment are ignored; the QUERY is not, because a query can name a different
102 * document (the `/writing` index filters with one).
103 *
104 * @param {string} href an absolute URL, already resolved against the source
105 * @param {string} target the target URL
106 */
107export function sameDocument(href, target) {
108  let a;
109  let b;
110  try {
111    a = new URL(href);
112    b = new URL(target);
113  } catch {
114    return false;
115  }
116  const strip = (/** @type {URL} */ u) =>
117    `${u.origin}${u.pathname.endsWith("/") ? u.pathname.slice(0, -1) : u.pathname}${u.search}`;
118  return strip(a) === strip(b);
119}
120
121// One owner; the schema comment points here.
122const EXCERPT_MAX_CHARS = 280;
123
124/**
125 * Plain text by construction: the caller passes `textContent`. This is not a sanitizer.
126 *
127 * @param {string} text
128 */
129export function collapseExcerpt(text) {
130  const flat = text.replace(/\s+/g, " ").trim();
131  return flat.length > EXCERPT_MAX_CHARS ? flat.slice(0, EXCERPT_MAX_CHARS) : flat;
132}
133
134/**
135 * Checked again at RENDER: a row can outlive the code that wrote it or be hand-written, and a wrong `href`
136 * is executable. Null means render the name without a link. Returns the parser's output, not the input.
137 *
138 * @param {string | null | undefined} value
139 * @returns {string | null}
140 */
141export function safeHttpHref(value) {
142  if (!value) return null;
143  let url;
144  try {
145    url = new URL(value);
146  } catch {
147    return null;
148  }
149  if (url.protocol !== "https:" && url.protocol !== "http:") return null;
150  return url.href;
151}