jackherd 1.8.1 → 1.10.0

package/src/preview/embed.ts

@@ -0,0 +1,209 @@
+import { lookup } from 'node:dns/promises'
+import { isIPv4, isIPv6 } from 'node:net'
+import { decodedAttribute } from './images'
+
+/** An image as fetched: its media type and bytes; null when it cannot be had. */
+type FetchedImage = { type: string; bytes: Uint8Array }
+
+/** The seam the page's external images are fetched through; a test replaces it. */
+export type ImageFetch = (url: string) => Promise<FetchedImage | null>
+
+/** What fetching an image needs from the network: the addresses of a host, and one request. Tests pass their own. */
+export type ImageSeams = {
+  resolve: (host: string) => Promise<string[]>
+  request: (url: string, init: RequestInit) => Promise<Response>
+}
+
+const MAX_BYTES = 5 * 1024 * 1024
+const TIMEOUT_MS = 10_000
+const MAX_REDIRECTS = 3
+const EXTERNAL_IMAGE = /<img\b[^>]*?\ssrc="(https:\/\/[^"]+)"/g
+const REDIRECT = new Set([301, 302, 303, 307, 308])
+/** A plain image media type; anything else would be written into the page's `src` attribute unchecked. */
+const IMAGE_TYPE = /^image\/[a-z0-9.+-]+$/i
+
+/**
+ * IPv4 ranges no public image lives in: this network, private, shared (carrier NAT), loopback, link-local (cloud
+ * metadata), IETF protocol assignments, benchmarking, multicast and reserved. As [first octets, prefix length].
+ */
+const NON_PUBLIC_V4: [number, number, number][] = [
+  [0, 0, 8],
+  [10, 0, 8],
+  [100, 64, 10],
+  [127, 0, 8],
+  [169, 254, 16],
+  [172, 16, 12],
+  [192, 0, 24],
+  [192, 168, 16],
+  [198, 18, 15],
+  [224, 0, 3],
+]
+
+const v4Number = (address: string): number => address.split('.').reduce((value, part) => value * 256 + Number(part), 0)
+
+const isPublicV4 = (address: string): boolean => {
+  const value = v4Number(address)
+  return NON_PUBLIC_V4.every(([first, second, prefix]) => {
+    const network = (first * 256 + second) * 65_536
+    const size = 2 ** (32 - prefix)
+    return value < network || value >= network + size
+  })
+}
+
+/** An IPv4 address as the last two groups of an IPv6 address: `127.0.0.1` → `7f00:1`. */
+const v4AsGroups = (address: string): string => {
+  const value = v4Number(address)
+  return `${(value >>> 16).toString(16)}:${(value & 0xffff).toString(16)}`
+}
+
+const groupsOf = (part: string | undefined): number[] =>
+  part ? part.split(':').map((group) => Number.parseInt(group, 16)) : []
+
+/** The eight 16-bit groups of an IPv6 address, an embedded IPv4 tail included. */
+const v6Groups = (address: string): number[] => {
+  const tail = /\d+\.\d+\.\d+\.\d+$/.exec(address)?.[0]
+  const text = tail ? `${address.slice(0, -tail.length)}${v4AsGroups(tail)}` : address
+  const [head, rest] = text.split('::')
+  const left = groupsOf(head)
+  const right = groupsOf(rest)
+  return rest === undefined ? left : [...left, ...Array(8 - left.length - right.length).fill(0), ...right]
+}
+
+const v4Of = (high: number, low: number): string => [high >>> 8, high & 0xff, low >>> 8, low & 0xff].join('.')
+
+const isPublicV6 = (address: string): boolean => {
+  const groups = v6Groups(address)
+  const [first] = groups
+  const zeroPrefix = groups.slice(0, 5).every((group) => group === 0)
+  if (zeroPrefix && (groups[5] === 0xffff || groups[5] === 0)) {
+    return groups[5] === 0xffff || groups[6] !== 0 ? isPublicV4(v4Of(groups[6], groups[7])) : false
+  }
+  // Unique local fc00::/7, link-local fe80::/10, site-local fec0::/10, multicast ff00::/8.
+  return (first & 0xfe00) !== 0xfc00 && (first & 0xffc0) !== 0xfe80 && (first & 0xffc0) !== 0xfec0 && first < 0xff00
+}
+
+/** Whether an IP address is one a public host answers on; loopback, private, link-local and the like are not. */
+export const isPublicAddress = (address: string): boolean => {
+  if (isIPv4(address)) return isPublicV4(address)
+  if (isIPv6(address)) return isPublicV6(address)
+  return false
+}
+
+/** Whether the address is https and every address its host resolves to is public; none resolved is no. */
+const isFetchable = async (url: URL, resolve: ImageSeams['resolve']): Promise<boolean> => {
+  if (url.protocol !== 'https:') return false
+  const host = url.hostname.replace(/^\[(.*)\]$/, '$1')
+  const addresses = isIPv4(host) || isIPv6(host) ? [host] : await resolve(host)
+  return addresses.length > 0 && addresses.every(isPublicAddress)
+}
+
+/** The body up to `limit` bytes, read as a stream; null once it grows past it. */
+const readCapped = async (body: ReadableStream<Uint8Array> | null, limit: number): Promise<Uint8Array | null> => {
+  if (!body) return new Uint8Array()
+  const reader = body.getReader()
+  const chunks: Uint8Array[] = []
+  let size = 0
+  for (let read = await reader.read(); !read.done; read = await reader.read()) {
+    size += read.value.length
+    if (size > limit) {
+      await reader.cancel()
+      return null
+    }
+    chunks.push(read.value)
+  }
+  const bytes = new Uint8Array(size)
+  let offset = 0
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset)
+    offset += chunk.length
+  }
+  return bytes
+}
+
+/**
+ * The image an answer carries: a successful answer with a plain `image/<subtype>` type within the size limit, refused by its
+ * announced length before anything is read, else while it streams; null otherwise.
+ */
+export const imageFromResponse = async (response: Response): Promise<FetchedImage | null> => {
+  const type = response.headers.get('content-type')?.split(';')[0].trim().toLowerCase()
+  if (!response.ok || type === undefined || !IMAGE_TYPE.test(type)) return null
+  if (Number(response.headers.get('content-length') ?? 0) > MAX_BYTES) return null
+  const bytes = await readCapped(response.body, MAX_BYTES)
+  return bytes ? { type, bytes } : null
+}
+
+/**
+ * Fetches an image from a public https host: the host is resolved first and refused when any of its addresses is
+ * loopback, private or link-local, redirects are followed by hand (at most three), each target checked the same way.
+ * Null for any refusal or failure. Resolving and requesting are two lookups, so a host that changes its answer between
+ * them (DNS rebinding) is not caught; the page is a local preview, which bounds what such a host could read.
+ */
+export const fetchImageWith = async (
+  address: string,
+  { resolve, request }: ImageSeams,
+): Promise<FetchedImage | null> => {
+  let url = new URL(address)
+  for (let hop = 0; hop <= MAX_REDIRECTS; hop += 1) {
+    if (!(await isFetchable(url, resolve))) return null
+    const response = await request(url.href, { redirect: 'manual', signal: AbortSignal.timeout(TIMEOUT_MS) })
+    const location = response.headers.get('location')
+    if (!REDIRECT.has(response.status)) return imageFromResponse(response)
+    if (!location) return null
+    url = new URL(location, url)
+  }
+  return null
+}
+
+const systemSeams: ImageSeams = {
+  resolve: async (host) => (await lookup(host, { all: true, verbatim: true })).map(({ address }) => address),
+  request: (url, init) => fetch(url, init),
+}
+
+/** Fetches an image over the network with a time limit; null for any failure. */
+export const fetchImage: ImageFetch = async (url) => {
+  try {
+    return await fetchImageWith(url, systemSeams)
+  } catch {
+    return null
+  }
+}
+
+const dataAddressOf = ({ type, bytes }: FetchedImage): string =>
+  `data:${type};base64,${Buffer.from(bytes).toString('base64')}`
+
+const safely = async (fetchOne: ImageFetch, url: string): Promise<FetchedImage | null> => {
+  try {
+    return await fetchOne(url)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * The page with every external image (`https://…` in an `<img src>`) shown from a data address, so it is complete where
+ * a page may load nothing from outside (an Artifact's content security policy). Each address is fetched once, as the
+ * address its attribute text stands for (`&amp;` read as `&`), and replaced by its text as written. One that
+ * cannot be fetched, or answers with no plain image type, keeps its address; `failed` counts those addresses. Plain
+ * http images are left as they are.
+ */
+export const embedExternalImages = async (
+  html: string,
+  fetchOne: ImageFetch,
+): Promise<{ html: string; failed: number }> => {
+  const addresses = [...new Set([...html.matchAll(EXTERNAL_IMAGE)].map(([, address]) => address))]
+  const fetched = await Promise.all(
+    addresses.map(async (address) => [address, await safely(fetchOne, decodedAttribute(address))] as const),
+  )
+  const embedded = new Map(
+    fetched.flatMap(([address, image]) =>
+      image && IMAGE_TYPE.test(image.type) ? [[address, dataAddressOf(image)] as const] : [],
+    ),
+  )
+  return {
+    html: html.replace(EXTERNAL_IMAGE, (tag, address: string) => {
+      const data = embedded.get(address)
+      return data ? tag.replace(`src="${address}"`, `src="${data}"`) : tag
+    }),
+    failed: addresses.length - embedded.size,
+  }
+}

package/src/preview/images.ts

@@ -0,0 +1,89 @@
+import { posix } from 'node:path'
+
+/** Reads the file at a path relative to the package root as an address the page can show; null when it cannot. */
+export type LocalImage = (relativePath: string) => string | null
+
+const CAMO = /^https:\/\/camo\.githubusercontent\.com\/[0-9a-f]+\/([0-9a-f]+)$/
+const SCHEME = /^[a-z][a-z0-9+.-]*:|^\/\//i
+
+/** The address GitHub's image proxy stands for; any other address as it is. */
+const canonicalOf = (src: string): string => {
+  const hex = CAMO.exec(src)?.[1]
+  return hex ? Buffer.from(hex, 'hex').toString('utf8') : src
+}
+
+/** The path below `<package>[@version]/` of an unpkg address of the package; null for any other address. */
+const unpkgPathOf = (address: string, packageName: string): string | null => {
+  if (!URL.canParse(address)) return null
+  const { host, pathname } = new URL(address)
+  const [, name, ...rest] = pathname.split('/')
+  if (host !== 'unpkg.com' || name?.split('@')[0] !== packageName || rest.length === 0) return null
+  return posix.normalize(rest.join('/'))
+}
+
+/**
+ * The path inside the package an image address means: a relative path, or an `unpkg.com/<package>/…` address of the
+ * package itself (any version, `?` part cut off). Null for every other address.
+ */
+export const packagePathOf = (address: string, packageName: string): string | null => {
+  const clean = address.split(/[?#]/)[0]
+  const unpkg = unpkgPathOf(clean, packageName)
+  if (unpkg !== null) return unpkg
+  if (SCHEME.test(clean) || clean.startsWith('/') || clean === '') return null
+  const normalized = posix.normalize(clean)
+  return normalized.startsWith('..') ? null : normalized
+}
+
+const ENTITIES: Record<string, string> = { '&amp;': '&', '&quot;': '"', '&lt;': '<', '&gt;': '>', '&#39;': "'" }
+
+/** An attribute's text as the address it stands for, the entities GitHub's renderer writes undone. */
+export const decodedAttribute = (text: string): string =>
+  text.replace(/&(amp|quot|lt|gt|#39);/g, (entity) => ENTITIES[entity])
+
+/** An address as attribute text: nothing in it can close the attribute or open a tag. */
+const escapedAttribute = (text: string): string =>
+  text.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+
+const attributeOf = (tag: string, name: string): string | null => {
+  const text = new RegExp(`\\s${name}="([^"]*)"`).exec(tag)?.[1]
+  return text === undefined ? null : decodedAttribute(text)
+}
+
+const withoutAttributes = (tag: string, names: readonly string[]): string =>
+  names.reduce((rest, name) => rest.replace(new RegExp(`\\s${name}="[^"]*"`, 'g'), ''), tag)
+
+/** The tag with `source` as its only address; `source` is the address itself, not attribute text, and is escaped here. */
+const withSource = (tag: string, source: string): string =>
+  withoutAttributes(tag, ['src', 'data-canonical-src']).replace(/^<img/, () => `<img src="${escapedAttribute(source)}"`)
+
+const localOrKept = (address: string, packageName: string, read: LocalImage): string => {
+  const path = packagePathOf(address, packageName)
+  return (path === null ? null : read(path)) ?? address
+}
+
+/** One `<img>` tag with its address resolved: the working tree's file for the package's own images, the original address otherwise. */
+const resolveImage = (tag: string, packageName: string, read: LocalImage): string => {
+  const address = canonicalOf(attributeOf(tag, 'data-canonical-src') ?? attributeOf(tag, 'src') ?? '')
+  return address === '' ? tag : withSource(tag, localOrKept(address, packageName, read))
+}
+
+const withClass = (tag: string, className: string): string => tag.replace(/^<img/, `<img class="${className}"`)
+
+/** `<picture>` with a dark source as two images, one shown per theme; the page switches themes itself, the browser's media query would not follow it. */
+const themedPicture = (picture: string): string => {
+  const dark = /<source[^>]*\bsrcset="([^"]+)"/.exec(picture)?.[1]
+  const image = /<img[^>]*>/.exec(picture)?.[0]
+  if (dark === undefined || image === undefined) return picture
+  const darkImage = withSource(image, decodedAttribute(dark))
+  return `${withClass(image, 'only-light')}${withClass(darkImage, 'only-dark')}`
+}
+
+/**
+ * The rendered HTML with every image shown from the working tree where it is the package's own (relative paths and
+ * `unpkg.com/<package>/…`, so an unpublished README shows its unpublished pictures) and every `<picture>` split
+ * into a light and a dark image. Other addresses stay as they are.
+ */
+export const rewriteImages = (html: string, packageName: string, read: LocalImage): string =>
+  html
+    .replace(/<picture>[\s\S]*?<\/picture>/g, themedPicture)
+    .replace(/<img\b[^>]*>/g, (tag) => resolveImage(tag, packageName, read))

package/src/preview/open.ts

@@ -0,0 +1,12 @@
+const MEDIA_TYPES: Record<string, string> = {
+  svg: 'image/svg+xml',
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  gif: 'image/gif',
+  webp: 'image/webp',
+}
+
+/** The media type of an image file by its extension; null when the preview does not inline that kind of file. */
+export const mediaTypeOf = (path: string): string | null =>
+  MEDIA_TYPES[path.split('.').pop()?.toLowerCase() ?? ''] ?? null

package/src/preview/options.ts

@@ -0,0 +1,32 @@
+import { CLI_NAME } from '../version/release'
+
+/** What `jh preview` was asked for: the Markdown file, where to write the page (null: the temporary directory) and whether to open it. */
+export type PreviewOptions = { file: string; out: string | null; open: boolean }
+
+export const PREVIEW_USAGE = `usage: ${CLI_NAME} preview <markdown-file> [--out <path>] [--open]`
+
+/** Whether the command line asks for the usage: `--help` or `-h` anywhere, as the top level of `jh` reads it. */
+export const asksForHelp = (args: readonly string[]): boolean => args.includes('--help') || args.includes('-h')
+
+const usageError = (message: string): Error => new Error(`${message}\n${PREVIEW_USAGE}`)
+
+/** Reads `<file> [--out <path>] [--open]` in any order; throws on an unknown option, a missing value or a missing or second file. */
+export const parsePreviewOptions = (args: readonly string[]): PreviewOptions => {
+  const words: string[] = []
+  let out: string | null = null
+  let open = false
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i]
+    if (arg === '--open') open = true
+    else if (arg === '--out') {
+      const value = args[i + 1]
+      if (value === undefined || value.startsWith('--')) throw usageError('--out needs a path')
+      out = value
+      i += 1
+    } else if (arg.startsWith('--')) throw usageError(`unknown option ${arg}`)
+    else words.push(arg)
+  }
+  if (words.length === 0) throw usageError('the Markdown file is required')
+  if (words.length > 1) throw usageError(`one file at most, got ${words.join(' ')}`)
+  return { file: words[0], out, open }
+}

package/src/preview/page.ts

@@ -0,0 +1,89 @@
+export type PreviewPage = { title: string; html: string }
+
+const escapeHtml = (text: string): string =>
+  text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;')
+
+const PREVIEW_STYLE = {
+  github: {
+    name: 'GitHub',
+    font: '-apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans", Helvetica, Arial, sans-serif',
+    size: '16px',
+    line: '1.5',
+  },
+  npm: { name: 'npm', font: '"Source Sans Pro", "Source Sans 3", sans-serif', size: '18px', line: '29.7px' },
+} as const
+
+const FONT_LINK = 'https://fonts.googleapis.com/css2?family=Source+Sans+3:wght@400;600;700&display=swap'
+
+const STYLE = `
+:root { color-scheme: light dark; }
+body { margin: 0; font: 14px system-ui, sans-serif; background: #6e7781; }
+header { display: flex; gap: 16px; align-items: center; padding: 8px 16px; background: #24292f; color: #fff; }
+header label { display: flex; gap: 4px; align-items: center; }
+main { display: flex; gap: 16px; align-items: flex-start; padding: 16px; }
+section.pane { flex: 1 1 0; min-width: 0; border-radius: 6px; overflow: hidden; }
+body.phone section.pane { flex: 0 0 390px; }
+.pane-bar { display: flex; justify-content: space-between; padding: 4px 12px; background: #d0d7de; color: #1f2328; }
+.pane[data-theme="dark"] .pane-bar { background: #30363d; color: #e6edf3; }
+.doc { padding: 32px; --fg: #1f2328; --bg: #fff; --muted: #656d76; --line: #d0d7de; --code: #f6f8fa; --link: #0969da; color: var(--fg); background: var(--bg); }
+.pane[data-theme="dark"] .doc { --fg: #e6edf3; --bg: #0d1117; --muted: #8d96a0; --line: #30363d; --code: #161b22; --link: #4493f8; }
+.pane[data-theme="light"] .only-dark, .pane[data-theme="dark"] .only-light { display: none; }
+.doc a { color: var(--link); }
+.doc h1, .doc h2 { padding-bottom: .3em; border-bottom: 1px solid var(--line); }
+.doc h1, .doc h2, .doc h3, .doc h4 { margin: 24px 0 16px; font-weight: 600; line-height: 1.25; }
+.doc p, .doc ul, .doc ol, .doc table, .doc pre, .doc details { margin: 0 0 16px; }
+.doc img { max-width: 100%; }
+.doc code { padding: .2em .4em; border-radius: 6px; background: var(--code); font-size: 85%; }
+.doc pre { padding: 16px; overflow: auto; border-radius: 6px; background: var(--code); }
+.doc pre code { padding: 0; background: none; }
+.doc table { border-collapse: collapse; display: block; overflow: auto; }
+.doc th, .doc td { padding: 6px 13px; border: 1px solid var(--line); }
+.doc tr:nth-child(2n) { background: var(--code); }
+.doc blockquote { margin: 0 0 16px; padding: 0 1em; color: var(--muted); border-left: .25em solid var(--line); }
+.doc hr { border: 0; height: 1px; background: var(--line); }
+.doc .anchor { display: none; }
+@media (max-width: 900px) { main { flex-direction: column; } }
+`
+
+const SCRIPT = `
+for (const button of document.querySelectorAll('[data-theme-for]')) {
+  button.addEventListener('click', () => {
+    const pane = document.getElementById(button.dataset.themeFor)
+    pane.dataset.theme = pane.dataset.theme === 'dark' ? 'light' : 'dark'
+    button.textContent = pane.dataset.theme
+  })
+}
+document.getElementById('phone').addEventListener('change', (event) => document.body.classList.toggle('phone', event.target.checked))
+`
+
+const paneOf = (id: keyof typeof PREVIEW_STYLE, html: string): string => {
+  const { name, font, size, line } = PREVIEW_STYLE[id]
+  return `<section class="pane" id="${id}" data-theme="light">
+<div class="pane-bar"><b>${name} style</b><button data-theme-for="${id}">light</button></div>
+<article class="doc" style="font: ${size}/${line} ${font}">${html}</article>
+</section>`
+}
+
+/**
+ * The preview page: the rendered README twice, in GitHub style (16 px system font) and in npm style (Source Sans
+ * 18 px, line height 29.7 px), each pane with its own light/dark switch, and a switch to phone width.
+ */
+export const previewPage = ({ title, html }: PreviewPage): string => `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(title)} (preview)</title>
+<link rel="stylesheet" href="${FONT_LINK}">
+<style>${STYLE}</style>
+</head>
+<body>
+<header><b>${escapeHtml(title)}</b><label><input type="checkbox" id="phone"> phone width</label></header>
+<main>
+${paneOf('github', html)}
+${paneOf('npm', html)}
+</main>
+<script>${SCRIPT}</script>
+</body>
+</html>
+`

package/src/preview/render.ts

@@ -0,0 +1,41 @@
+import type { GhAnswer, GhOptions } from '../watch/gh'
+
+export type GhRunner = (args: string[], cwd: string, options?: GhOptions) => Promise<GhAnswer>
+
+/** Names the `owner/repo` of a git remote address (ssh or https, `.git` optional); null for anything else. */
+export const repositorySlugOf = (remote: string): string | null =>
+  /^git@[^:]+:([^/]+\/[^/]+?)(?:\.git)?$/.exec(remote.trim())?.[1] ??
+  /^https?:\/\/[^/]+\/([^/]+\/[^/]+?)(?:\.git)?\/?$/.exec(remote.trim())?.[1] ??
+  null
+
+const MISSING_GH =
+  'the GitHub CLI `gh` is not installed: install it from https://cli.github.com, then run `gh auth login`'
+const NOT_SIGNED_IN = 'the GitHub CLI is not signed in: run `gh auth login`, then try again'
+
+/** The reason a `gh` call failed, with the step that fixes it when it is the missing CLI or the missing login. */
+export const ghFailure = (error: string): string => {
+  if (/ENOENT|not found|not installed|No such file/i.test(error)) return MISSING_GH
+  if (/gh auth login|HTTP 401|not logged|authentication/i.test(error)) return NOT_SIGNED_IN
+  return `GitHub's markdown API failed: ${error}`
+}
+
+/**
+ * The HTML GitHub renders for `markdown` (flavor `gfm`, with the repository as context when known). The request body
+ * goes in through standard input: a long document as an argument exceeds the operating system's limit (`E2BIG`).
+ * Throws with the missing step.
+ */
+export const renderMarkdown = async (
+  markdown: string,
+  repositorySlug: string | null,
+  cwd: string,
+  gh: GhRunner,
+): Promise<string> => {
+  const body = JSON.stringify({
+    text: markdown,
+    mode: 'gfm',
+    ...(repositorySlug === null ? {} : { context: repositorySlug }),
+  })
+  const answer = await gh(['api', '/markdown', '--input', '-'], cwd, { stdin: body })
+  if (!answer.ok) throw new Error(ghFailure(answer.error))
+  return answer.stdout
+}

package/src/settled/board-row.ts

@@ -1,3 +1,4 @@
+import { twoDigits } from '../plan-format/clock'
 import { sectionStart } from '../plan-format/markdown'
 import { terminalSafe } from '../plan-format/terminal-text'
 import { PLAN_LANGUAGE, type PlanLanguage } from '../vocabulary'
@@ -50,8 +51,6 @@ export const isInSettledSection = (lines: readonly string[], index: number): boo
   return above !== undefined && headings.includes(above.trim())
 }
 
-const twoDigits = (value: number): string => String(value).padStart(2, '0')
-
 /** Local time as the board writes it: `DD.MM. hh:mm` in German, `YYYY-MM-DD hh:mm` in English. */
 export const settledTime = (time: Date, language: PlanLanguage): string =>
   BOARD_TEXTS[language].time({

package/src/shared/is-record.ts

@@ -0,0 +1,2 @@
+export const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)

package/src/shared/private-location.ts

@@ -0,0 +1,89 @@
+import { lstatSync, readFileSync, type Stats } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { isAbsolute, join } from 'node:path'
+import { ensurePrivateDirectory, isOwnedBy } from '../../kit/hooks/hooks/shared/private-directory'
+
+type Entry = Pick<Stats, 'uid' | 'mode' | 'isDirectory' | 'isSymbolicLink'>
+
+/** What choosing a private location reads from the system; the default is the real one (`systemLocation`). */
+export type LocationSystem = {
+  env: Record<string, string | undefined>
+  temporaryDirectory: string
+  uid: number | undefined
+  /** What sits at the path, without following a link; null for nothing. */
+  entryAt: (path: string) => Entry | null
+}
+
+const PAGE_DIRECTORY_PREFIX = 'jackherd'
+const GROUP_OR_OTHER = 0o077
+
+const isPrivateDirectoryEntry = (entry: Entry | null, uid: number | undefined): boolean =>
+  entry !== null &&
+  !entry.isSymbolicLink() &&
+  entry.isDirectory() &&
+  isOwnedBy(entry, uid) &&
+  (entry.mode & GROUP_OR_OTHER) === 0
+
+/**
+ * Where files only the user may read are kept: `$XDG_RUNTIME_DIR` when it is an absolute path to a directory of the
+ * user, no link, that neither group nor others may enter; else the temporary directory, which may be the shared `/tmp`
+ * and so needs a private level of its own below it (`userDirectoryOf`, `ensurePrivateLevels`).
+ */
+export const runtimeBaseOf = ({ env, temporaryDirectory, uid, entryAt }: LocationSystem): string => {
+  const runtime = env.XDG_RUNTIME_DIR
+  return runtime && isAbsolute(runtime) && isPrivateDirectoryEntry(entryAt(runtime), uid) ? runtime : temporaryDirectory
+}
+
+/** The user's own level below `base`: `<base>/<prefix>-<uid>`, with `user` where the platform has no user ids. */
+export const userDirectoryOf = (base: string, prefix: string, uid: number | undefined): string =>
+  join(base, `${prefix}-${uid ?? 'user'}`)
+
+/**
+ * The user's directory for pages a browser opens: below the temporary directory, never the runtime directory, which a
+ * sandboxed browser may not reach.
+ */
+export const pageDirectoryOf = (system: LocationSystem): string =>
+  userDirectoryOf(system.temporaryDirectory, PAGE_DIRECTORY_PREFIX, system.uid)
+
+const entryAt = (path: string): Entry | null => {
+  try {
+    return lstatSync(path)
+  } catch {
+    return null
+  }
+}
+
+export const systemLocation = (): LocationSystem => ({
+  env: process.env,
+  temporaryDirectory: tmpdir(),
+  uid: process.getuid?.(),
+  entryAt,
+})
+
+/**
+ * Whether `userDirectory` and `directory` (itself or a directory right below it) both exist as directories of the user,
+ * no link, closed to group and others; creates nothing, for readers that must not read from a level someone else
+ * planted.
+ */
+export const isPrivateLevels = (userDirectory: string, directory: string, system: LocationSystem): boolean =>
+  [userDirectory, directory].every((level) => isPrivateDirectoryEntry(system.entryAt(level), system.uid))
+
+/** The text of a regular file; null for nothing, a link or anything else (a FIFO would block the read). */
+export const readPrivateText = (path: string): string | null => {
+  try {
+    return lstatSync(path).isFile() ? readFileSync(path, 'utf8') : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Creates `directory`, the user level `userDirectory` itself or a directory right below it, and verifies each level
+ * with `ensurePrivateDirectory`, the user level first: nothing is created inside a level someone else owns or planted
+ * as a link, and this throws before anything is written there.
+ */
+export const ensurePrivateLevels = (userDirectory: string, directory: string): string => {
+  ensurePrivateDirectory(userDirectory)
+  if (directory !== userDirectory) ensurePrivateDirectory(directory)
+  return directory
+}

package/src/shared/private-records.ts

@@ -0,0 +1,48 @@
+import { chmodSync, lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const RECORD_FILE = /^[0-9a-f]{12}\.json$/
+const MAX_RECORD_BYTES = 16 * 1024
+const PRIVATE_FILE = 0o600
+const PRIVATE_DIRECTORY = 0o700
+
+const recordAt = <T>(path: string, isRecordOfKind: (value: unknown) => value is T): T[] => {
+  try {
+    const entry = lstatSync(path)
+    if (!entry.isFile() || entry.size > MAX_RECORD_BYTES) return []
+    const record: unknown = JSON.parse(readFileSync(path, 'utf8'))
+    return isRecordOfKind(record) ? [record] : []
+  } catch {
+    return []
+  }
+}
+
+/**
+ * Every well-formed `<id>.json` record in `directory` (a symbolic link, an oversized file and one the guard refuses are
+ * skipped), ascending by `sortKey`; nothing when the directory is missing or unreadable.
+ */
+export const readRecords = <T>(
+  directory: string,
+  isRecordOfKind: (value: unknown) => value is T,
+  sortKey: (record: T) => number,
+): T[] => {
+  try {
+    return readdirSync(directory)
+      .filter((name) => RECORD_FILE.test(name))
+      .flatMap((name) => recordAt(join(directory, name), isRecordOfKind))
+      .sort((left, right) => sortKey(left) - sortKey(right))
+  } catch {
+    return []
+  }
+}
+
+/** Writes `<id>.json` through a temporary file, `0600` in a `0700` directory, so a reader never sees half of it. */
+export const writeRecordAtomically = <T extends { id: string }>(directory: string, record: T): void => {
+  mkdirSync(directory, { recursive: true, mode: PRIVATE_DIRECTORY })
+  chmodSync(directory, PRIVATE_DIRECTORY)
+  const path = join(directory, `${record.id}.json`)
+  const temporary = `${path}.${process.pid}.tmp`
+  writeFileSync(temporary, `${JSON.stringify(record)}\n`, { mode: PRIVATE_FILE })
+  chmodSync(temporary, PRIVATE_FILE)
+  renameSync(temporary, path)
+}