@ngockhoale/ukit 3.0.5 → 3.0.7

package/src/core/observability/support/import.js

@@ -0,0 +1,402 @@
+/**
+ * import.js (TASK-011, SPEC §5 DF-FR11, §8, §10) — untrusted support-bundle
+ * import with bounded validation.
+ *
+ *   validateSupportBundle({ path } | { buffer })
+ *     → Promise<{ ok: true, bundle } | { ok: false, reason, details? }>
+ *
+ * Input is either a bundle directory (a `UKit Support` folder), a zip
+ * file path, or a zip Buffer. Zip parsing uses Node built-ins only —
+ * STORED and DEFLATE entries via zlib; no new dependency (PLAN §7).
+ *
+ * Validation order (fail-fast, first reason wins):
+ *   input shape → container parse (zip EOCD/CD/local headers, or dir
+ *   listing) → per-entry name safety (flat namespace, no traversal,
+ *   no absolute/drive/backslash) → compression method allowlist →
+ *   entry/total size caps → zip-bomb ratio → CRC32 + declared-size
+ *   integrity → manifest presence → manifest format/checksum/member
+ *   verification → file-type allowlist (.md/.json/.jsonl) →
+ *   records.jsonl line parsing.
+ *
+ * Defense invariants:
+ *   - Nothing is ever executed, sourced, or written outside the input
+ *     location. Entries are data; extraction is in-memory only.
+ *   - Prose is untrusted: injection-looking strings are imported
+ *     verbatim and flagged (`untrusted_prose_present`, per-file
+ *     `injection_signals`), never parsed as instructions.
+ *   - Format versioning is explicit: only `format: ukit-support/1` is
+ *     accepted; any other value (or none) is `unsupported_format_version`,
+ *     never a silent skip. The interchange format is independent of
+ *     schema_version / metric_version / redaction_version / UKit version.
+ *   - Project refs stay bundle-local pseudonyms; imported records get a
+ *     fresh research-local `import_id` plus per-line provenance — raw
+ *     source identifiers are never re-derived or trusted.
+ *
+ * Research import store: this module is pure validation — it writes
+ * NOTHING. Callers persisting an accepted bundle MUST use a research
+ * store separate from the canonical segment root (e.g.
+ * `<observability-root>/imports/<import_id>/`); retention/deletion of an
+ * import is owned by that store and never touches canonical telemetry —
+ * deleting an import drops only the imported copy.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import zlib from 'node:zlib';
+import crypto from 'node:crypto';
+
+import { ioReason } from '../segments/internal.js';
+import { verifyManifest, isSafeEntryName, MANIFEST_NAME } from './manifest.js';
+
+/** Hard bounds — a support bundle is small by design (projector cap ≈ 2 MB). */
+export const IMPORT_LIMITS = Object.freeze({
+  MAX_ENTRIES: 512,
+  MAX_ENTRY_BYTES: 16 * 1024 * 1024,
+  MAX_TOTAL_BYTES: 32 * 1024 * 1024,
+  /** Reject when declared uncompressed total exceeds archive size × this. */
+  MAX_RATIO: 100,
+  /** …but only above this floor, so tiny archives can't false-positive. */
+  RATIO_FLOOR_BYTES: 256 * 1024,
+  ALLOWED_EXTENSIONS: new Set(['.md', '.json', '.jsonl']),
+});
+
+const EOCD_SIG = 0x06054b50;
+const CD_SIG = 0x02014b50;
+const LOCAL_SIG = 0x04034b50;
+const EOCD_MIN = 22;
+const EOCD_SEARCH = 22 + 0xffff; // EOCD + max comment length
+
+const CRC_TABLE = (() => {
+  const table = new Uint32Array(256);
+  for (let n = 0; n < 256; n += 1) {
+    let c = n;
+    for (let k = 0; k < 8; k += 1) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    table[n] = c >>> 0;
+  }
+  return table;
+})();
+
+function crc32(buf) {
+  let c = 0xffffffff;
+  for (let i = 0; i < buf.length; i += 1) c = CRC_TABLE[(c ^ buf[i]) & 0xff] ^ (c >>> 8);
+  return (c ^ 0xffffffff) >>> 0;
+}
+
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function fail(reason, details) {
+  return details === undefined ? { ok: false, reason } : { ok: false, reason, details };
+}
+
+// ---------------------------------------------------------------------------
+// Zip container parsing (STORED + DEFLATE, central-directory driven)
+// ---------------------------------------------------------------------------
+
+function findEocd(buf) {
+  const start = Math.max(0, buf.length - EOCD_SEARCH);
+  for (let i = buf.length - EOCD_MIN; i >= start; i -= 1) {
+    if (buf.readUInt32LE(i) === EOCD_SIG) return i;
+  }
+  return -1;
+}
+
+/**
+ * Parse + extract a zip buffer into Map<name, Buffer>. All bounds are
+ * checked against DECLARED central-directory sizes before any byte is
+ * inflated, so bombs are rejected on metadata alone.
+ */
+function unzip(buf) {
+  const entries = new Map();
+  if (buf.length < EOCD_MIN) return fail('not_a_zip');
+  const eocd = findEocd(buf);
+  if (eocd < 0) return fail('not_a_zip');
+
+  const count = buf.readUInt16LE(eocd + 10);
+  const cdSize = buf.readUInt32LE(eocd + 12);
+  const cdOffset = buf.readUInt32LE(eocd + 16);
+  if (count > IMPORT_LIMITS.MAX_ENTRIES) return fail('too_many_entries');
+  if (cdOffset + cdSize > eocd || cdOffset + cdSize > buf.length) {
+    return fail('corrupt_central_directory');
+  }
+
+  const central = [];
+  let p = cdOffset;
+  for (let i = 0; i < count; i += 1) {
+    if (p + 46 > buf.length || buf.readUInt32LE(p) !== CD_SIG) {
+      return fail('corrupt_central_directory');
+    }
+    const method = buf.readUInt16LE(p + 10);
+    const crc = buf.readUInt32LE(p + 16);
+    const compressedSize = buf.readUInt32LE(p + 20);
+    const uncompressedSize = buf.readUInt32LE(p + 24);
+    const nameLen = buf.readUInt16LE(p + 28);
+    const extraLen = buf.readUInt16LE(p + 30);
+    const commentLen = buf.readUInt16LE(p + 32);
+    const localOffset = buf.readUInt32LE(p + 42);
+    const name = buf.subarray(p + 46, p + 46 + nameLen).toString('utf8');
+    central.push({ name, method, crc, compressedSize, uncompressedSize, localOffset });
+    p += 46 + nameLen + extraLen + commentLen;
+  }
+
+  // Metadata-level bounds before touching payloads.
+  let totalUncompressed = 0;
+  for (const e of central) {
+    if (!isSafeEntryName(e.name)) {
+      return fail('unsafe_entry_name', { name: e.name });
+    }
+    if (entries.has(e.name)) return fail('duplicate_entry', { name: e.name });
+    if (e.method !== 0 && e.method !== 8) {
+      return fail('unsupported_compression', { name: e.name, method: e.method });
+    }
+    if (e.uncompressedSize > IMPORT_LIMITS.MAX_ENTRY_BYTES) {
+      return fail('entry_too_large', { name: e.name, bytes: e.uncompressedSize });
+    }
+    totalUncompressed += e.uncompressedSize;
+    if (totalUncompressed > IMPORT_LIMITS.MAX_TOTAL_BYTES) {
+      return fail('bundle_too_large', { bytes: totalUncompressed });
+    }
+    entries.set(e.name, null);
+  }
+  if (
+    totalUncompressed > IMPORT_LIMITS.RATIO_FLOOR_BYTES &&
+    totalUncompressed > buf.length * IMPORT_LIMITS.MAX_RATIO
+  ) {
+    return fail('zip_bomb_suspected', {
+      uncompressed: totalUncompressed,
+      archive_bytes: buf.length,
+    });
+  }
+
+  // Extraction: local header → data slice → inflate → CRC + size check.
+  for (const e of central) {
+    const off = e.localOffset;
+    if (off + 30 > buf.length || buf.readUInt32LE(off) !== LOCAL_SIG) {
+      return fail('corrupt_local_header', { name: e.name });
+    }
+    const nameLen = buf.readUInt16LE(off + 26);
+    const extraLen = buf.readUInt16LE(off + 28);
+    const dataStart = off + 30 + nameLen + extraLen;
+    if (dataStart + e.compressedSize > buf.length) {
+      return fail('corrupt_local_header', { name: e.name });
+    }
+    const raw = buf.subarray(dataStart, dataStart + e.compressedSize);
+    let data;
+    if (e.method === 8) {
+      try {
+        data = zlib.inflateRawSync(raw, { maxOutputLength: e.uncompressedSize });
+      } catch {
+        return fail('inflate_failed', { name: e.name });
+      }
+    } else {
+      data = Buffer.from(raw);
+    }
+    if (data.length !== e.uncompressedSize || crc32(data) !== e.crc) {
+      return fail('entry_integrity', { name: e.name });
+    }
+    entries.set(e.name, data);
+  }
+  return { ok: true, entries };
+}
+
+// ---------------------------------------------------------------------------
+// Directory input
+// ---------------------------------------------------------------------------
+
+async function readBundleDir(dir) {
+  const entries = new Map();
+  let listing;
+  try {
+    listing = await fs.promises.readdir(dir, { withFileTypes: true });
+  } catch (err) {
+    return fail(ioReason(err));
+  }
+  let total = 0;
+  for (const dent of listing) {
+    // Foreign/unsafe names and non-regular files (symlinks, dirs) are
+    // ignored — a support dir may hold user files; only manifest-listed
+    // members are verified below.
+    if (!dent.isFile() || !isSafeEntryName(dent.name)) continue;
+    let buf;
+    try {
+      buf = await fs.promises.readFile(path.join(dir, dent.name));
+    } catch (err) {
+      return fail(ioReason(err));
+    }
+    if (buf.length > IMPORT_LIMITS.MAX_ENTRY_BYTES) {
+      return fail('entry_too_large', { name: dent.name, bytes: buf.length });
+    }
+    total += buf.length;
+    if (total > IMPORT_LIMITS.MAX_TOTAL_BYTES) {
+      return fail('bundle_too_large', { bytes: total });
+    }
+    entries.set(dent.name, buf);
+  }
+  return { ok: true, entries };
+}
+
+// ---------------------------------------------------------------------------
+// Content checks
+// ---------------------------------------------------------------------------
+
+const INJECTION_PATTERNS = [
+  /ignore\s+(all\s+)?(previous|prior)\s+instructions/i,
+  /<\s*tool_call\s*>/i,
+  /<\/?(system|assistant|user)\s*>/i,
+  /```\s*(json|tool|shell|bash)/i,
+  /\bSYSTEM\s*:/,
+];
+
+function scanInjectionSignals(contents) {
+  const signals = [];
+  for (const [name, text] of Object.entries(contents)) {
+    for (const re of INJECTION_PATTERNS) {
+      if (re.test(text)) {
+        signals.push({ file: name, pattern: re.source });
+      }
+    }
+  }
+  return signals;
+}
+
+function parseRecordsJsonl(text, importId) {
+  const records = [];
+  const bad = [];
+  const lines = text.split('\n');
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    if (line.trim() === '') continue;
+    try {
+      const record = JSON.parse(line);
+      if (!isPlainObject(record)) throw new Error('not an object');
+      record.import_id = importId;
+      record.provenance = { file: 'records.jsonl', line: i + 1 };
+      records.push(record);
+    } catch {
+      bad.push(i + 1);
+    }
+  }
+  if (bad.length > 0) {
+    return fail('invalid_records_jsonl', { lines: bad });
+  }
+  return { ok: true, records };
+}
+
+/**
+ * @param {{ path?: string, buffer?: Buffer }} input
+ * @returns {Promise<{ ok: true, bundle: object } | { ok: false, reason: string, details?: object }>}
+ */
+export async function validateSupportBundle(input = {}) {
+  const hasPath = typeof input.path === 'string' && input.path.length > 0;
+  const hasBuffer = Buffer.isBuffer(input.buffer);
+  if (hasPath === hasBuffer) {
+    return fail('invalid_input', { need: 'exactly one of { path } or { buffer }' });
+  }
+
+  let entries;
+  let provenance;
+  let isDir = false;
+  if (hasBuffer) {
+    const parsed = unzip(input.buffer);
+    if (!parsed.ok) return parsed;
+    entries = parsed.entries;
+    provenance = { source: 'buffer' };
+  } else {
+    let st;
+    try {
+      st = await fs.promises.lstat(input.path);
+    } catch (err) {
+      return fail(ioReason(err));
+    }
+    if (st.isSymbolicLink()) return fail('input_symlink');
+    if (st.isDirectory()) {
+      isDir = true;
+      const read = await readBundleDir(input.path);
+      if (!read.ok) return read;
+      entries = read.entries;
+    } else if (st.isFile()) {
+      let buf;
+      try {
+        buf = await fs.promises.readFile(input.path);
+      } catch (err) {
+        return fail(ioReason(err));
+      }
+      const parsed = unzip(buf);
+      if (!parsed.ok) return parsed;
+      entries = parsed.entries;
+    } else {
+      return fail('invalid_input');
+    }
+    provenance = { source: 'path', path: input.path };
+  }
+
+  // --- manifest: presence → parse → format/checksum/member verification ---
+  const manifestBuf = entries.get(MANIFEST_NAME);
+  if (!manifestBuf) return fail('missing_manifest');
+  let manifest;
+  try {
+    manifest = JSON.parse(manifestBuf.toString('utf8'));
+  } catch {
+    return fail('invalid_manifest');
+  }
+  // strict member↔manifest parity for archives; directories may hold
+  // foreign files (projector ownership rule), so verify listed-only.
+  const verified = verifyManifest(manifest, entries, { strict: !isDir });
+  if (!verified.ok) return verified;
+
+  // --- file-type allowlist + UTF-8 decode (prose stays inert data) ---
+  const contents = {};
+  for (const [name, buf] of entries) {
+    if (name === MANIFEST_NAME) continue;
+    const ext = path.extname(name).toLowerCase();
+    if (!IMPORT_LIMITS.ALLOWED_EXTENSIONS.has(ext)) {
+      return fail('unsupported_file_type', { name });
+    }
+    contents[name] = buf.toString('utf8');
+  }
+
+  // --- evidence: records.jsonl → research-local IDs + provenance ---
+  const importId = `imp-${crypto.randomBytes(8).toString('hex')}`;
+  let records = [];
+  if (typeof contents['records.jsonl'] === 'string') {
+    const parsed = parseRecordsJsonl(contents['records.jsonl'], importId);
+    if (!parsed.ok) return parsed;
+    records = parsed.records;
+  }
+
+  const digests = Object.keys(contents)
+    .filter((name) => /^digest-.+\.md$/.test(name))
+    .sort()
+    .map((name) => ({
+      name,
+      failed: /failed=[1-9]/.test(contents[name]) || /failed=true/i.test(contents[name]),
+    }));
+
+  const proseFiles = Object.keys(contents).filter((name) => name.endsWith('.md'));
+  const injectionSignals = scanInjectionSignals(contents);
+  const untrustedProse = proseFiles.length > 0;
+
+  const bundle = {
+    import_id: importId,
+    format: manifest.format,
+    manifest,
+    coverage: isPlainObject(manifest.coverage) ? manifest.coverage : {},
+    caps: isPlainObject(manifest.caps) ? manifest.caps : {},
+    records,
+    digests,
+    contents,
+    checksums_verified: true,
+    untrusted_prose_present: untrustedProse,
+    provenance,
+    report: {
+      import_id: importId,
+      files: Object.keys(contents).length,
+      records: records.length,
+      untrusted_prose_present: untrustedProse,
+      injection_signals: injectionSignals,
+      coverage_gaps: Array.isArray(manifest.coverage?.gaps) ? manifest.coverage.gaps : [],
+    },
+  };
+  return { ok: true, bundle };
+}

package/src/core/observability/support/manifest.js

@@ -0,0 +1,135 @@
+/**
+ * manifest.js (TASK-011, SPEC §5 DF-FR11, §8) — support-bundle manifest
+ * build/verify: sha256 checksums, byte sizes, coverage + privacy
+ * (redaction_version) declarations.
+ *
+ *   buildManifest({ files, generated_at?, coverage?, caps?,
+ *                   project_ref_pseudonym?, ...extra }) → manifest object
+ *   verifyManifest(manifest, entries, { strict? })
+ *     → { ok: true, manifest } | { ok: false, reason, details? }
+ *
+ * `entries` is a Map<string, Buffer> of archive/dir members. With
+ * `strict: true` (archive inputs) every member must be listed in the
+ * manifest — unlisted entries are rejected as smuggled content. With
+ * `strict: false` (directory inputs) foreign files are ignored, matching
+ * the projector's ownership rule: a support dir may contain user files.
+ *
+ * Format versioning (SPEC §12 / test 5): the interchange contract is the
+ * `format` marker `ukit-support/<N>` — independent of schema_version,
+ * metric_version, redaction_version, and the UKit release version. A
+ * reader accepts only the major it implements; anything else is an
+ * explicit `unsupported_format_version` rejection, never a silent skip.
+ */
+
+import crypto from 'node:crypto';
+
+import { SUPPORT_FORMAT } from './projector.js';
+import { REDACTION_VERSION } from '../privacy/allowlist.js';
+import { METRIC_VERSION } from '../analytics/summary.js';
+
+export { SUPPORT_FORMAT };
+
+export const MANIFEST_NAME = 'manifest.json';
+
+/** Flat bundle namespace: no directories, no separators, no dotfiles. */
+export const ENTRY_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function sha256Hex(buf) {
+  return crypto.createHash('sha256').update(buf).digest('hex');
+}
+
+/**
+ * A member name is safe only when it is a flat, relative, portable file
+ * name — no separators, no traversal, no drive letters, no dotfiles.
+ */
+export function isSafeEntryName(name) {
+  return typeof name === 'string' && ENTRY_NAME_RE.test(name);
+}
+
+/**
+ * @param {object} opts
+ * @param {Object<string, string|Buffer>} opts.files — file set; the
+ *   manifest itself is excluded from its own checksum map.
+ * @returns {object} manifest
+ */
+export function buildManifest(opts = {}) {
+  const files = isPlainObject(opts.files) ? opts.files : {};
+  const fileEntries = {};
+  for (const [name, content] of Object.entries(files)) {
+    if (name === MANIFEST_NAME) continue;
+    const buf = Buffer.isBuffer(content) ? content : Buffer.from(String(content), 'utf8');
+    fileEntries[name] = { sha256: `sha256:${sha256Hex(buf)}`, bytes: buf.length };
+  }
+  const { files: _omit, ...rest } = opts;
+  return {
+    format: SUPPORT_FORMAT,
+    generated_at: typeof opts.generated_at === 'string' ? opts.generated_at : new Date().toISOString(),
+    redaction_version: REDACTION_VERSION,
+    metric_version: METRIC_VERSION,
+    ...rest,
+    files: fileEntries,
+  };
+}
+
+/**
+ * Verify a parsed manifest against archive/dir members.
+ *
+ * @param {object} manifest parsed manifest.json
+ * @param {Map<string, Buffer>} entries member name → raw bytes
+ * @param {{ strict?: boolean }} [opts] strict = reject unlisted members
+ * @returns {{ ok: true, manifest: object } | { ok: false, reason: string, details?: object }}
+ */
+export function verifyManifest(manifest, entries, opts = {}) {
+  const strict = opts.strict !== false;
+  if (!isPlainObject(manifest)) {
+    return { ok: false, reason: 'invalid_manifest' };
+  }
+  if (manifest.format !== SUPPORT_FORMAT) {
+    return {
+      ok: false,
+      reason: 'unsupported_format_version',
+      details: { format: manifest.format ?? null, supported: [SUPPORT_FORMAT] },
+    };
+  }
+  if (!isPlainObject(manifest.files)) {
+    return { ok: false, reason: 'invalid_manifest' };
+  }
+
+  const listed = Object.keys(manifest.files);
+  for (const name of listed) {
+    if (!isSafeEntryName(name)) {
+      return { ok: false, reason: 'unsafe_entry_name', details: { name } };
+    }
+  }
+
+  const missing = listed.filter((name) => !entries.has(name));
+  if (missing.length > 0) {
+    return { ok: false, reason: 'missing_files', details: { missing } };
+  }
+
+  if (strict) {
+    const unlisted = [...entries.keys()].filter(
+      (name) => name !== MANIFEST_NAME && !manifest.files[name],
+    );
+    if (unlisted.length > 0) {
+      return { ok: false, reason: 'unlisted_entries', details: { unlisted } };
+    }
+  }
+
+  const mismatched = [];
+  for (const [name, entry] of Object.entries(manifest.files)) {
+    const buf = entries.get(name);
+    const expected = typeof entry === 'object' && entry !== null ? entry.sha256 : null;
+    const actual = `sha256:${sha256Hex(buf)}`;
+    if (expected !== actual) mismatched.push(name);
+  }
+  if (mismatched.length > 0) {
+    return { ok: false, reason: 'checksum_mismatch', details: { mismatched } };
+  }
+
+  return { ok: true, manifest };
+}

package/src/core/observability/support/paths.js

@@ -0,0 +1,94 @@
+/**
+ * paths.js (TASK-009, SPEC §5 DF-FR10 / §8) — OS-native Documents resolver.
+ *
+ *   resolveSupportDir({ homeDir?, env?, platform? })
+ *     → { ok: true, dir } | { ok: false, reason }
+ *
+ * Resolves the user-facing `UKit Support` directory under the OS-native
+ * Documents folder:
+ *   - linux/other: $XDG_DOCUMENTS_DIR, else ~/Documents
+ *   - darwin:      ~/Documents
+ *   - win32:       %USERPROFILE%\Documents, else <homeDir>\Documents
+ *
+ * The resolver NEVER assumes `~/Documents` exists: a candidate that is
+ * absent, not a directory, or not writable produces an explicit typed
+ * reason (`documents_not_found` | `documents_not_directory` |
+ * `documents_not_writable` | `no_home` | `io_*`). There is no fallback to
+ * a leakier location — unresolved stays unresolved and the projector
+ * degrades instead of relocating.
+ *
+ * `dir` is the support directory path itself (Documents/UKit Support);
+ * the directory is NOT created here — creation and symlink/foreign-file
+ * safety are the projector's job.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { ioReason } from '../segments/internal.js';
+
+export const SUPPORT_DIR_NAME = 'UKit Support';
+
+function candidates({ homeDir, env, platform }) {
+  const list = [];
+  if (platform === 'win32') {
+    const profile = env.USERPROFILE || homeDir;
+    if (typeof profile === 'string' && profile.length > 0) {
+      list.push(path.join(profile, 'Documents'));
+    }
+    return list;
+  }
+  if (platform !== 'darwin') {
+    const xdg = env.XDG_DOCUMENTS_DIR;
+    if (typeof xdg === 'string' && xdg.length > 0) list.push(xdg);
+  }
+  if (typeof homeDir === 'string' && homeDir.length > 0) {
+    list.push(path.join(homeDir, 'Documents'));
+  }
+  return list;
+}
+
+/**
+ * @param {{ homeDir?: string|null, env?: object, platform?: string }} [opts]
+ * @returns {Promise<{ ok: true, dir: string } | { ok: false, reason: string }>}
+ */
+export async function resolveSupportDir(opts = {}) {
+  const env = opts.env && typeof opts.env === 'object' ? opts.env : process.env;
+  const platform = typeof opts.platform === 'string' ? opts.platform : process.platform;
+  const homeDir = opts.homeDir === undefined ? os.homedir() : opts.homeDir;
+
+  const list = candidates({ homeDir, env, platform });
+  if (list.length === 0) return { ok: false, reason: 'no_home' };
+
+  let reason = 'documents_not_found';
+  for (const documents of list) {
+    let stat;
+    try {
+      // stat (not lstat): a redirected/symlinked Documents folder is a
+      // legitimate OS configuration — only the final support path component
+      // is held to the no-symlink rule by the projector.
+      stat = await fs.promises.stat(documents);
+    } catch (err) {
+      if (err && err.code === 'ENOENT') continue;
+      if (err && (err.code === 'ENOTDIR' || err.code === 'ELOOP')) {
+        reason = 'documents_not_directory';
+        continue;
+      }
+      reason = ioReason(err);
+      continue;
+    }
+    if (!stat.isDirectory()) {
+      reason = 'documents_not_directory';
+      continue;
+    }
+    try {
+      await fs.promises.access(documents, fs.constants.W_OK);
+    } catch (err) {
+      reason = err && err.code === 'EACCES' ? 'documents_not_writable' : ioReason(err);
+      continue;
+    }
+    return { ok: true, dir: path.join(documents, SUPPORT_DIR_NAME) };
+  }
+  return { ok: false, reason };
+}