@summerscar/dsh-mnemon-sync 0.0.0-stage → 0.1.0

package/targets.js

@@ -0,0 +1,533 @@
+/**
+ * Mnemon Sync — upload targets.
+ *
+ * Two target kinds ship here, both implemented against the platform's own
+ * `fetch` and `node:crypto` rather than an SDK:
+ *
+ * - `webdav`: a plain authenticated `PUT`, which is all a WebDAV collection
+ *   needs to accept an archive. `MKCOL` is tried for the parent so a fresh
+ *   target directory does not fail the first upload.
+ * - `s3`: AWS Signature Version 4 against any S3-compatible endpoint
+ *   (Cloudflare R2, MinIO, Backblaze B2, Alibaba OSS...). Signing by hand
+ *   keeps the plugin dependency-free; a wrong signature fails loudly with
+ *   `SignatureDoesNotMatch`, never silently.
+ *
+ * Nothing here stores credentials. The caller reads them from the 0600
+ * settings file and passes them in, so this module stays a pure function of
+ * (config, bytes) and can be exercised against a throwaway bucket.
+ */
+
+import { createHash, createHmac } from 'node:crypto'
+
+const EMPTY_SHA256 = createHash('sha256').update('').digest('hex')
+
+/**
+ * Normalise whatever the settings page saved into the shape the uploaders take.
+ * Kept permissive about the key spelling so a hand-edited file still works:
+ * `endpoint`/`url`, `accessKey`/`accessKeyId`, `secretKey`/`secretAccessKey`.
+ */
+export function normalizeTarget(raw) {
+  const kind = String(raw?.kind ?? '').trim()
+  if (kind !== 's3' && kind !== 'webdav') {
+    throw new Error(`unsupported backup target kind: ${kind === '' ? '(empty)' : kind}`)
+  }
+  if (kind === 'webdav') {
+    const url = required(raw.url, 'WebDAV URL')
+    return {
+      kind,
+      url: url.replace(/\/+$/u, ''),
+      username: String(raw.username ?? ''),
+      password: String(raw.password ?? ''),
+      remotePath: trimSlashes(raw.remotePath ?? 'mnemon-sync'),
+      timeoutMs: positiveInteger(raw.timeoutMs, 30000),
+    }
+  }
+  const endpoint = required(raw.endpoint, 'S3 endpoint').replace(/\/+$/u, '')
+  return {
+    kind,
+    endpoint,
+    bucket: required(raw.bucket, 'S3 bucket'),
+    region: String(raw.region ?? '').trim() || 'auto',
+    accessKeyId: required(raw.accessKeyId ?? raw.accessKey, 'S3 access key id'),
+    secretAccessKey: required(raw.secretAccessKey ?? raw.secretKey, 'S3 secret access key'),
+    sessionToken: String(raw.sessionToken ?? '').trim(),
+    remotePath: trimSlashes(raw.remotePath ?? 'mnemon-sync'),
+    forcePathStyle: raw.forcePathStyle === true,
+    timeoutMs: positiveInteger(raw.timeoutMs, 30000),
+  }
+}
+
+function required(value, label) {
+  const text = String(value ?? '').trim()
+  if (text === '') throw new Error(`${label} is required`)
+  return text
+}
+
+function trimSlashes(value) {
+  return String(value ?? '').trim().replace(/^\/+/u, '').replace(/\/+$/u, '')
+}
+
+function positiveInteger(value, fallback) {
+  const number = Number(value)
+  return Number.isFinite(number) && number > 0 ? Math.floor(number) : fallback
+}
+
+/**
+ * Upload one archive and return where it landed.
+ * The return value is what the UI shows and what the retention step deletes,
+ * so both kinds answer with the same `{ location, key }` shape.
+ */
+export async function uploadArchive(target, key, bytes, options = {}) {
+  if (target.kind === 'webdav') return putWebDav(target, key, bytes, options.signal)
+  if (target.kind === 's3') return putS3Object(target, key, bytes, options.signal)
+  throw new Error(`unsupported backup target kind: ${String(target.kind)}`)
+}
+
+/** Delete one archive; missing objects count as success so retention is idempotent. */
+export async function deleteArchive(target, key, options = {}) {
+  if (target.kind === 'webdav') return deleteWebDav(target, key, options.signal)
+  if (target.kind === 's3') return deleteS3Object(target, key, options.signal)
+  throw new Error(`unsupported backup target kind: ${String(target.kind)}`)
+}
+
+/**
+ * List the archives the target currently holds.
+ *
+ * Both kinds answer the same `{ key, bytes, modifiedAt }` shape, sorted newest
+ * first, so the page can show one list. Listing is read-only and never assumes
+ * this machine made the archive: a bucket may hold backups from another Host,
+ * which is exactly what a person wants to see after reinstalling.
+ */
+export async function listArchives(target, options = {}) {
+  if (target.kind === 'webdav') return listWebDav(target, options.signal)
+  if (target.kind === 's3') return listS3(target, options.signal)
+  throw new Error(`unsupported backup target kind: ${String(target.kind)}`)
+}
+
+/**
+ * Fetch one archive back.
+ *
+ * Restore reads first and writes later: downloading the whole archive lets the
+ * caller verify every checksum before deciding where anything lands, which is
+ * the only safe order when the target may hold an incomplete upload.
+ */
+export async function downloadArchive(target, key, options = {}) {
+  if (target.kind === 'webdav') {
+    const url = webDavUrl(target, key)
+    const response = await fetch(url, {
+      method: 'GET',
+      headers: authHeaders(target),
+      signal: options.signal ?? AbortSignal.timeout(target.timeoutMs),
+    })
+    if (!response.ok) {
+      throw new Error(`WebDAV GET ${url} failed: ${response.status} ${await safeText(response)}`)
+    }
+    return Buffer.from(await response.arrayBuffer())
+  }
+  if (target.kind === 's3') {
+    const url = new URL(s3Url(target, key))
+    const response = await fetch(url, {
+      method: 'GET',
+      headers: signedHeadersForGet(target, url),
+      signal: options.signal ?? AbortSignal.timeout(target.timeoutMs),
+    })
+    if (!response.ok) {
+      throw new Error(`S3 GET ${url.pathname} failed: ${response.status} ${await safeText(response)}`)
+    }
+    return Buffer.from(await response.arrayBuffer())
+  }
+  throw new Error(`unsupported backup target kind: ${String(target.kind)}`)
+}
+
+// ---------------------------------------------------------------------------
+// WebDAV
+// ---------------------------------------------------------------------------
+
+function webDavUrl(target, key) {
+  const segments = [target.remotePath, key].filter((part) => part !== '').join('/')
+  return `${target.url}/${segments.split('/').map(encodeURIComponent).join('/')}`
+}
+
+function authHeaders(target) {
+  if (target.username === '' && target.password === '') return {}
+  const token = Buffer.from(`${target.username}:${target.password}`).toString('base64')
+  return { authorization: `Basic ${token}` }
+}
+
+async function putWebDav(target, key, bytes, signal) {
+  const url = webDavUrl(target, key)
+  // A missing collection is the common first-run failure; create it and retry
+  // once. A 405 means it already exists, which is equally fine.
+  await ensureWebDavDirectory(target, url, signal)
+  const response = await fetch(url, {
+    method: 'PUT',
+    headers: { ...authHeaders(target), 'content-type': 'application/zip' },
+    body: bytes,
+    signal: signal ?? AbortSignal.timeout(target.timeoutMs),
+  })
+  if (!response.ok) {
+    throw new Error(`WebDAV PUT ${url} failed: ${response.status} ${await safeText(response)}`)
+  }
+  return { location: url, key }
+}
+
+async function ensureWebDavDirectory(target, url, signal) {
+  const directoryUrl = url.slice(0, url.lastIndexOf('/'))
+  if (directoryUrl === '') return
+  const segments = directoryUrl.split('/')
+  // Walk down from the collection root so a multi-segment remote path works.
+  const rootIndex = segments.indexOf(target.url.split('/').filter(Boolean).pop()?.toString() ?? '')
+  const start = rootIndex >= 0 ? rootIndex + 1 : 3
+  for (let index = start; index <= segments.length; index += 1) {
+    const current = segments.slice(0, index).join('/')
+    if (current === '' || !current.startsWith('http')) continue
+    try {
+      await fetch(current, {
+        method: 'MKCOL',
+        headers: authHeaders(target),
+        signal: signal ?? AbortSignal.timeout(target.timeoutMs),
+      })
+    } catch {
+      // Best effort: a PUT below reports the real problem with the real status.
+    }
+  }
+}
+
+async function deleteWebDav(target, key, signal) {
+  const url = webDavUrl(target, key)
+  const response = await fetch(url, {
+    method: 'DELETE',
+    headers: authHeaders(target),
+    signal: signal ?? AbortSignal.timeout(target.timeoutMs),
+  })
+  if (!response.ok && response.status !== 404) {
+    throw new Error(`WebDAV DELETE ${url} failed: ${response.status} ${await safeText(response)}`)
+  }
+  return { location: url, key, deleted: response.ok }
+}
+
+/**
+ * List the sync folder with `PROPFIND depth: 1`.
+ *
+ * Only entries directly under the remote path are read, which is what the page
+ * shows. A missing collection answers 404 and is reported as an empty list: a
+ * target that has never been written to is not an error.
+ */
+async function listWebDav(target, signal) {
+  const directory = `${target.url}/${target.remotePath.split('/').map(encodeURIComponent).join('/')}`
+  const response = await fetch(directory, {
+    method: 'PROPFIND',
+    headers: {
+      ...authHeaders(target),
+      depth: '1',
+      'content-type': 'application/xml; charset=utf-8',
+    },
+    body: XML_LIST_BODY,
+    signal: signal ?? AbortSignal.timeout(target.timeoutMs),
+  })
+  if (response.status === 404) return []
+  if (!response.ok) {
+    throw new Error(`WebDAV PROPFIND ${directory} failed: ${response.status} ${await safeText(response)}`)
+  }
+  return parseWebDavListing(await response.text(), target.remotePath)
+}
+
+const XML_LIST_BODY = '<?xml version="1.0" encoding="utf-8"?>'
+  + '<d:propfind xmlns:d="DAV:"><d:prop>'
+  + '<d:getcontentlength/><d:getlastmodified/><d:resourcetype/>'
+  + '</d:prop></d:propfind>'
+
+/**
+ * Turn a PROPFIND multistatus document into archive rows.
+ *
+ * Parsing is deliberately forgiving: tag prefixes vary between servers (`d:`,
+ * `D:`, none), and a listing that omits a property must not drop the file. Only
+ * the pieces this page needs are read.
+ */
+function parseWebDavListing(xml, remotePath) {
+  const entries = []
+  const blocks = xml.split(/<\/[^:>]*:?response>/iu)
+  for (const block of blocks) {
+    const href = /<[^:>]*:?href[^>]*>([^<]+)<\/[^:>]*:?href>/iu.exec(block)
+    if (href === null) continue
+    // A collection is the parent itself; it is not an archive.
+    if (/<[^:>]*:?collection\s*\/?>/iu.test(block)) continue
+    let path
+    try {
+      path = decodeURIComponent(href[1].trim())
+    } catch {
+      path = href[1].trim()
+    }
+    const name = path.split('/').filter(Boolean).pop() ?? ''
+    if (!name.toLowerCase().endsWith('.zip')) continue
+    entries.push({
+      key: name,
+      bytes: integerOf(/<[^:>]*:?getcontentlength[^>]*>(\d+)</iu.exec(block)),
+      modifiedAt: textOf(/<[^:>]*:?getlastmodified[^>]*>([^<]+)</iu.exec(block)),
+    })
+  }
+  return entries.sort((left, right) => String(right.modifiedAt ?? '').localeCompare(String(left.modifiedAt ?? '')))
+}
+
+function integerOf(match) {
+  if (match === null) return undefined
+  const value = Number(match[1])
+  return Number.isFinite(value) ? value : undefined
+}
+
+function textOf(match) {
+  return match === null ? undefined : match[1].trim()
+}
+
+// ---------------------------------------------------------------------------
+// S3 (Signature Version 4)
+// ---------------------------------------------------------------------------
+
+function s3Endpoint(target) {
+  // Path style keeps the bucket in the path, which R2 and MinIO both accept
+  // and which avoids wildcard-TLS surprises on custom domains.
+  if (target.forcePathStyle) return `${target.endpoint}/${target.bucket}`
+  const url = new URL(target.endpoint)
+  return `${url.protocol}//${target.bucket}.${url.host}`
+}
+
+function s3Url(target, key) {
+  const base = s3Endpoint(target)
+  const segments = [target.remotePath, key].filter((part) => part !== '').join('/')
+  return `${base}/${segments.split('/').map(encodeURIComponent).join('/')}`
+}
+
+/** One signed request against the S3 REST API. */
+async function signedS3Request(target, method, key, bytes, signal) {
+  const url = new URL(s3Url(target, key))
+  const now = new Date()
+  const amzDate = now.toISOString().replace(/[:-]|\.\d{3}/gu, '')
+  const dateStamp = amzDate.slice(0, 8)
+  const payloadHash = bytes === undefined ? EMPTY_SHA256 : sha256Hex(bytes)
+
+  const headers = {
+    host: url.host,
+    'x-amz-content-sha256': payloadHash,
+    'x-amz-date': amzDate,
+  }
+  if (target.sessionToken !== '') headers['x-amz-security-token'] = target.sessionToken
+  if (bytes !== undefined) headers['content-length'] = String(bytes.length)
+
+  const headerNames = Object.keys(headers).sort()
+  const canonicalHeaders = headerNames.map((name) => `${name}:${String(headers[name]).trim()}\n`).join('')
+  const signedHeaders = headerNames.join(';')
+
+  // The canonical URI must be the encoded path exactly as it goes on the wire,
+  // and any query string must be signed in its sorted, encoded form.
+  const canonicalRequest = [
+    method,
+    url.pathname,
+    canonicalQuery(url.searchParams),
+    canonicalHeaders,
+    signedHeaders,
+    payloadHash,
+  ].join('\n')
+
+  const scope = `${dateStamp}/${target.region}/s3/aws4_request`
+  const stringToSign = [
+    'AWS4-HMAC-SHA256',
+    amzDate,
+    scope,
+    sha256Hex(canonicalRequest),
+  ].join('\n')
+
+  const signingKey = signatureKey(target.secretAccessKey, dateStamp, target.region)
+  const signature = createHmac('sha256', signingKey).update(stringToSign).digest('hex')
+
+  headers.authorization = `AWS4-HMAC-SHA256 Credential=${target.accessKeyId}/${scope}, `
+    + `SignedHeaders=${signedHeaders}, Signature=${signature}`
+
+  const response = await fetch(url, {
+    method,
+    headers,
+    body: bytes,
+    signal: signal ?? AbortSignal.timeout(target.timeoutMs),
+  })
+  if (!response.ok) {
+    throw new Error(
+      `S3 ${method} ${url.pathname} failed: ${response.status} ${await safeText(response)}`,
+    )
+  }
+  return { response, location: url.toString() }
+}
+
+async function putS3Object(target, key, bytes, signal) {
+  const { location } = await signedS3Request(target, 'PUT', key, bytes, signal)
+  return { location, key }
+}
+
+async function deleteS3Object(target, key, signal) {
+  const url = new URL(s3Url(target, key))
+  const response = await fetch(url, {
+    method: 'DELETE',
+    headers: signedHeadersForDelete(target, url),
+    signal: signal ?? AbortSignal.timeout(target.timeoutMs),
+  })
+  // S3 answers 204 for a deleted object and 404 for one that never existed.
+  if (!response.ok && response.status !== 404) {
+    throw new Error(`S3 DELETE ${url.pathname} failed: ${response.status} ${await safeText(response)}`)
+  }
+  return { location: url.toString(), key, deleted: response.status === 204 }
+}
+
+/** DELETE carries no body, so it signs the empty-payload hash. */
+function signedHeadersForDelete(target, url) {
+  return signEmptyPayloadRequest(target, url, 'DELETE')
+}
+
+/** GET carries no body either; S3 requires it to be signed the same way. */
+function signedHeadersForGet(target, url) {
+  return signEmptyPayloadRequest(target, url, 'GET')
+}
+
+/**
+ * Sign one body-less request (GET or DELETE) against the S3 REST API.
+ *
+ * The canonical request is identical between the two methods apart from the
+ * verb, so one function keeps them from drifting: a GET signed like a PUT would
+ * fail with `SignatureDoesNotMatch` and would be tedious to spot.
+ */
+function signEmptyPayloadRequest(target, url, method) {
+  const now = new Date()
+  const amzDate = now.toISOString().replace(/[:-]|\.\d{3}/gu, '')
+  const dateStamp = amzDate.slice(0, 8)
+  const headers = {
+    host: url.host,
+    'x-amz-content-sha256': EMPTY_SHA256,
+    'x-amz-date': amzDate,
+  }
+  if (target.sessionToken !== '') headers['x-amz-security-token'] = target.sessionToken
+  const headerNames = Object.keys(headers).sort()
+  const canonicalHeaders = headerNames.map((name) => `${name}:${String(headers[name]).trim()}\n`).join('')
+  const signedHeaders = headerNames.join(';')
+  const canonicalRequest = [method, url.pathname, '', canonicalHeaders, signedHeaders, EMPTY_SHA256].join('\n')
+  const scope = `${dateStamp}/${target.region}/s3/aws4_request`
+  const stringToSign = ['AWS4-HMAC-SHA256', amzDate, scope, sha256Hex(canonicalRequest)].join('\n')
+  const signingKey = signatureKey(target.secretAccessKey, dateStamp, target.region)
+  const signature = createHmac('sha256', signingKey).update(stringToSign).digest('hex')
+  return {
+    ...headers,
+    authorization: `AWS4-HMAC-SHA256 Credential=${target.accessKeyId}/${scope}, `
+      + `SignedHeaders=${signedHeaders}, Signature=${signature}`,
+  }
+}
+
+/**
+ * Encode a query string the way Signature Version 4 expects: parameter names
+ * and values percent-encoded with unreserved characters untouched, sorted by
+ * name, joined with `&`. An empty query is the empty string, not `""`.
+ */
+function canonicalQuery(searchParams) {
+  const pairs = []
+  for (const [name, value] of searchParams.entries()) {
+    pairs.push([encodeRfc3986(name), encodeRfc3986(value)])
+  }
+  pairs.sort((left, right) => (left[0] === right[0]
+    ? left[1].localeCompare(right[1])
+    : left[0].localeCompare(right[0])))
+  return pairs.map(([name, value]) => `${name}=${value}`).join('&')
+}
+
+function encodeRfc3986(value) {
+  return encodeURIComponent(value).replace(/[!'()*]/gu, (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`)
+}
+
+/**
+ * List archives with the ListObjectsV2 API.
+ *
+ * Only keys directly under the remote path are kept, and the listing is a single
+ * page: a sync folder holding more than a thousand archives means retention is
+ * misconfigured, and paging the whole bucket would cost more than it explains.
+ */
+async function listS3(target, signal) {
+  const url = new URL(s3Url(target, ''))
+  url.searchParams.set('list-type', '2')
+  url.searchParams.set('prefix', `${target.remotePath}/`)
+  const { response } = await signedS3UrlRequest(target, 'GET', url, signal)
+  const xml = await response.text()
+  const entries = []
+  const blocks = xml.split(/<\/Contents>/u)
+  for (const block of blocks) {
+    const key = /<Key>([^<]+)<\/Key>/u.exec(block)
+    if (key === null) continue
+    const raw = key[1]
+    const name = raw.split('/').filter(Boolean).pop() ?? ''
+    if (!name.toLowerCase().endsWith('.zip')) continue
+    entries.push({
+      key: name,
+      fullKey: raw,
+      bytes: integerOf(/<Size>(\d+)<\/Size>/u.exec(block)),
+      modifiedAt: textOf(/<LastModified>([^<]+)<\/LastModified>/u.exec(block)),
+    })
+  }
+  return entries.sort((left, right) => String(right.modifiedAt ?? '').localeCompare(String(left.modifiedAt ?? '')))
+}
+
+/**
+ * Sign and send one request to an already-built URL, including its query.
+ * Kept beside the object calls so LIST reuses the same signing code.
+ */
+async function signedS3UrlRequest(target, method, url, signal) {
+  const now = new Date()
+  const amzDate = now.toISOString().replace(/[:-]|\.\d{3}/gu, '')
+  const dateStamp = amzDate.slice(0, 8)
+  const headers = {
+    host: url.host,
+    'x-amz-content-sha256': EMPTY_SHA256,
+    'x-amz-date': amzDate,
+  }
+  if (target.sessionToken !== '') headers['x-amz-security-token'] = target.sessionToken
+  const headerNames = Object.keys(headers).sort()
+  const canonicalHeaders = headerNames.map((name) => `${name}:${String(headers[name]).trim()}\n`).join('')
+  const signedHeaders = headerNames.join(';')
+  const canonicalRequest = [
+    method,
+    url.pathname,
+    canonicalQuery(url.searchParams),
+    canonicalHeaders,
+    signedHeaders,
+    EMPTY_SHA256,
+  ].join('\n')
+  const scope = `${dateStamp}/${target.region}/s3/aws4_request`
+  const stringToSign = ['AWS4-HMAC-SHA256', amzDate, scope, sha256Hex(canonicalRequest)].join('\n')
+  const signingKey = signatureKey(target.secretAccessKey, dateStamp, target.region)
+  const signature = createHmac('sha256', signingKey).update(stringToSign).digest('hex')
+  const response = await fetch(url, {
+    method,
+    headers: {
+      ...headers,
+      authorization: `AWS4-HMAC-SHA256 Credential=${target.accessKeyId}/${scope}, `
+        + `SignedHeaders=${signedHeaders}, Signature=${signature}`,
+    },
+    signal: signal ?? AbortSignal.timeout(target.timeoutMs),
+  })
+  if (!response.ok) {
+    throw new Error(`S3 ${method} ${url.pathname} failed: ${response.status} ${await safeText(response)}`)
+  }
+  return { response }
+}
+
+function signatureKey(secret, dateStamp, region) {
+  const kDate = createHmac('sha256', `AWS4${secret}`).update(dateStamp).digest()
+  const kRegion = createHmac('sha256', kDate).update(region).digest()
+  const kService = createHmac('sha256', kRegion).update('s3').digest()
+  return createHmac('sha256', kService).update('aws4_request').digest()
+}
+
+function sha256Hex(value) {
+  return createHash('sha256').update(value).digest('hex')
+}
+
+async function safeText(response) {
+  try {
+    const text = await response.text()
+    return text.slice(0, 400)
+  } catch {
+    return ''
+  }
+}

package/zip.js

@@ -0,0 +1,168 @@
+/**
+ * Mnemon Sync — a minimal, dependency-free ZIP writer.
+ *
+ * Why hand-rolled: the plugin runs from a workspace directory that does not
+ * carry dsh-mnemon's transitive dependencies, so importing `fflate` from there
+ * would only work by coincidence of hoisting. Writing stored-or-deflated
+ * entries with `node:zlib` keeps the plugin dependency-free, and a ZIP is the
+ * one archive format every OS and NAS UI can open without extra tooling.
+ *
+ * Scope is deliberately narrow: one archive, no encryption, no ZIP64. A backup
+ * of a memory store is a handful of megabytes; crossing the 4 GiB ZIP64 line
+ * would mean something is very wrong, so that limit is reported rather than
+ * silently producing a corrupt file.
+ */
+
+import { deflateRawSync, inflateRawSync } from 'node:zlib'
+
+const LOCAL_HEADER = 0x04034b50
+const CENTRAL_HEADER = 0x02014b50
+const END_OF_CENTRAL = 0x06054b50
+const ZIP64_LIMIT = 0xffffffff
+
+let crcTable
+
+function crc32(buffer) {
+  if (crcTable === undefined) {
+    crcTable = new Int32Array(256)
+    for (let index = 0; index < 256; index += 1) {
+      let value = index
+      for (let bit = 0; bit < 8; bit += 1) {
+        value = (value & 1) === 1 ? 0xedb88320 ^ (value >>> 1) : value >>> 1
+      }
+      crcTable[index] = value
+    }
+  }
+  let crc = 0 ^ -1
+  for (let index = 0; index < buffer.length; index += 1) {
+    crc = (crc >>> 8) ^ crcTable[(crc ^ buffer[index]) & 0xff]
+  }
+  return (crc ^ -1) >>> 0
+}
+
+/** DOS timestamp: ZIP carries a local-time date no earlier than 1980. */
+function dosStamp(at) {
+  const year = Math.max(1980, at.getFullYear())
+  const time = (at.getHours() << 11) | (at.getMinutes() << 5) | Math.floor(at.getSeconds() / 2)
+  const date = ((year - 1980) << 9) | ((at.getMonth() + 1) << 5) | at.getDate()
+  return { time, date }
+}
+
+/**
+ * Build a ZIP archive.
+ *
+ * @param {Array<{path: string, bytes: Uint8Array, compress?: boolean}>} entries
+ * @param {{ at?: Date, level?: number }} [options]
+ * @returns {Buffer}
+ */
+export function createZip(entries, options = {}) {
+  const at = options.at ?? new Date()
+  const level = options.level ?? 6
+  const { time, date } = dosStamp(at)
+  const parts = []
+  const central = []
+  let offset = 0
+
+  for (const entry of entries) {
+    const name = Buffer.from(entry.path, 'utf8')
+    const raw = Buffer.isBuffer(entry.bytes) ? entry.bytes : Buffer.from(entry.bytes)
+    if (raw.length >= ZIP64_LIMIT) {
+      throw new Error(`archive entry too large without ZIP64: ${entry.path}`)
+    }
+    // Small or already-compressed payloads are stored rather than deflated:
+    // deflating 4096-byte SQLite pages gains little and costs time.
+    const compress = entry.compress ?? true
+    const body = compress ? deflateRawSync(raw, { level }) : raw
+    const method = compress ? 8 : 0
+    const checksum = crc32(raw)
+
+    const local = Buffer.alloc(30)
+    local.writeUInt32LE(LOCAL_HEADER, 0)
+    local.writeUInt16LE(20, 4)
+    local.writeUInt16LE(0x0800, 6) // UTF-8 names
+    local.writeUInt16LE(method, 8)
+    local.writeUInt16LE(time, 10)
+    local.writeUInt16LE(date, 12)
+    local.writeUInt32LE(checksum, 14)
+    local.writeUInt32LE(body.length, 18)
+    local.writeUInt32LE(raw.length, 22)
+    local.writeUInt16LE(name.length, 26)
+    local.writeUInt16LE(0, 28)
+
+    parts.push(local, name, body)
+    central.push({
+      name,
+      checksum,
+      compressed: body.length,
+      uncompressed: raw.length,
+      method,
+      offset,
+    })
+    offset += local.length + name.length + body.length
+  }
+
+  const centralStart = offset
+  for (const entry of central) {
+    const header = Buffer.alloc(46)
+    header.writeUInt32LE(CENTRAL_HEADER, 0)
+    header.writeUInt16LE(20, 4)
+    header.writeUInt16LE(20, 6)
+    header.writeUInt16LE(0x0800, 8)
+    header.writeUInt16LE(entry.method, 10)
+    header.writeUInt16LE(time, 12)
+    header.writeUInt16LE(date, 14)
+    header.writeUInt32LE(entry.checksum, 16)
+    header.writeUInt32LE(entry.compressed, 20)
+    header.writeUInt32LE(entry.uncompressed, 24)
+    header.writeUInt16LE(entry.name.length, 28)
+    header.writeUInt32LE(entry.offset, 42)
+    parts.push(header, entry.name)
+    offset += header.length + entry.name.length
+  }
+
+  const end = Buffer.alloc(22)
+  end.writeUInt32LE(END_OF_CENTRAL, 0)
+  end.writeUInt16LE(central.length, 8)
+  end.writeUInt16LE(central.length, 10)
+  end.writeUInt32LE(offset - centralStart, 12)
+  end.writeUInt32LE(centralStart, 16)
+  parts.push(end)
+
+  return Buffer.concat(parts)
+}
+
+/**
+ * Read back a ZIP produced by `createZip`, used by the restore preview to
+ * prove the archive is intact before an operator acts on it.
+ *
+ * @param {Buffer} buffer
+ * @returns {Map<string, Buffer>}
+ */
+export function readZip(buffer) {
+  const eocd = buffer.lastIndexOf(Buffer.from([0x50, 0x4b, 0x05, 0x06]))
+  if (eocd < 0) throw new Error('not a ZIP archive: end of central directory not found')
+  const count = buffer.readUInt16LE(eocd + 10)
+  const centralStart = buffer.readUInt32LE(eocd + 16)
+  const files = new Map()
+  let cursor = centralStart
+  for (let index = 0; index < count; index += 1) {
+    if (buffer.readUInt32LE(cursor) !== CENTRAL_HEADER) {
+      throw new Error('corrupt ZIP: central directory header signature mismatch')
+    }
+    const method = buffer.readUInt16LE(cursor + 10)
+    const compressed = buffer.readUInt32LE(cursor + 20)
+    const nameLength = buffer.readUInt16LE(cursor + 28)
+    const extraLength = buffer.readUInt16LE(cursor + 30)
+    const commentLength = buffer.readUInt16LE(cursor + 32)
+    const localOffset = buffer.readUInt32LE(cursor + 42)
+    const name = buffer.subarray(cursor + 46, cursor + 46 + nameLength).toString('utf8')
+
+    const localNameLength = buffer.readUInt16LE(localOffset + 26)
+    const localExtraLength = buffer.readUInt16LE(localOffset + 28)
+    const dataStart = localOffset + 30 + localNameLength + localExtraLength
+    const body = buffer.subarray(dataStart, dataStart + compressed)
+    files.set(name, method === 8 ? inflateRawSync(body) : Buffer.from(body))
+    cursor += 46 + nameLength + extraLength + commentLength
+  }
+  return files
+}