@jonathanleelx/meddle 0.5.0-beta.9 → 0.5.1

package/bin/lib/proxy-or-file.js

@@ -0,0 +1,93 @@
+/**
+ * Decide whether a proxy API failure may fall back to a direct file write.
+ *
+ * Fall back only when the proxy is not running, or the request fails before
+ * any HTTP response (connection refused, timeout, DNS). A 4xx/5xx is the
+ * proxy's answer: callers print that body and must not touch the file.
+ * Treating a 409 (corrupt mocks.json) as "proxy down" rewrote the file and
+ * dropped every existing rule.
+ */
+
+const output = require('./output')
+const { isProxyRunning } = require('./proxy-detect')
+
+const UNREACHABLE_CODES = new Set([
+  'ECONNREFUSED',
+  'ECONNRESET',
+  'ENOTFOUND',
+  'EAI_AGAIN',
+  'EHOSTUNREACH',
+  'ENETUNREACH',
+  'EPIPE',
+  'ETIMEDOUT',
+  'ECONNABORTED',
+  'UND_ERR_CONNECT_TIMEOUT',
+  'UND_ERR_SOCKET',
+  'UND_ERR_HEADERS_TIMEOUT',
+])
+
+function causeCode(err) {
+  if (!err || typeof err !== 'object') return undefined
+  if (err.code && err.code !== 'MOCKS_FILE_INVALID') return err.code
+  if (err.cause) return causeCode(err.cause)
+  return undefined
+}
+
+/** True when the proxy answered with an HTTP 4xx/5xx (api-client sets err.status). */
+function isApiHttpError(err) {
+  const status = err && err.status
+  return Number.isInteger(status) && status >= 400 && status <= 599
+}
+
+/**
+ * True when we never got an HTTP response: connection refused, DNS, reset,
+ * timeout, or undici's `TypeError: fetch failed`.
+ */
+function isProxyUnreachableError(err) {
+  if (!err || isApiHttpError(err)) return false
+  if (err.name === 'AbortError' || err.name === 'TimeoutError') return true
+  const code = causeCode(err)
+  if (code && UNREACHABLE_CODES.has(code)) return true
+  if (err.name === 'TypeError' && err.message === 'fetch failed') return true
+  return false
+}
+
+/**
+ * Call the proxy when it is up. `file` runs only when it is down or the
+ * request never received an HTTP response. HTTP errors reject.
+ *
+ * @param {{ api: () => Promise<any>, file: () => any }} opts
+ * @returns {Promise<{ fileOnly: boolean, value: any }>}
+ */
+async function withProxyOrFile({ api, file }) {
+  const running = await isProxyRunning()
+  if (!running) return { fileOnly: true, value: file() }
+  try {
+    return { fileOnly: false, value: await api() }
+  } catch (err) {
+    if (!isProxyUnreachableError(err)) throw err
+    return { fileOnly: true, value: file() }
+  }
+}
+
+/**
+ * Exit 1. An HTTP error's message is the response body and is printed as-is.
+ * `err.rawStderr` prints `err.message` with no `✗` prefix (mock list).
+ * Other human-mode failures use the CLI `✗` style.
+ */
+function failCommand(err) {
+  const message = err && err.message ? String(err.message) : String(err)
+  // HTTP / raw-stderr failures print the body as-is (no JSON wrapper, no `✗`).
+  // Other failures go through output.error, which emits `{success:false}` on
+  // stdout when --json is set.
+  if (isApiHttpError(err) || (err && err.rawStderr)) console.error(message)
+  else output.error(message)
+  process.exit(1)
+}
+
+module.exports = {
+  isApiHttpError,
+  isProxyUnreachableError,
+  withProxyOrFile,
+  failCommand,
+}

package/bin/lib/route-write-args.js

@@ -0,0 +1,150 @@
+/**
+ * Argument parsing for `meddle route add|update|delete` (issue #149).
+ *
+ * `--exclusions=` clears a rule's exclusions. `--exclusions=/a,/b` replaces
+ * them. A bare `--exclusions`, an unknown flag, or an empty `!` token used to
+ * be ignored and the command still exited 0 without changing exclusions.
+ */
+
+const { splitPatternArg } = require('./rule-file-edit')
+
+class RouteArgError extends Error {
+  constructor(message) {
+    super(message)
+    this.name = 'RouteArgError'
+  }
+}
+
+const CLEAR_HINT = 'To clear exclusions, pass --exclusions= (empty). To replace them, pass --exclusions=/a,/b.'
+
+/**
+ * @param {string} raw value after `=`
+ * @returns {string[]}
+ */
+function parseExclusionList(raw) {
+  const value = String(raw).trim()
+  if (value === '') return []
+  const pieces = value.includes(',') ? value.split(',') : value.split(/\s+/)
+  const out = []
+  for (const piece of pieces) {
+    const token = piece.trim()
+    if (!token) {
+      throw new RouteArgError(`Invalid --exclusions: empty entry. ${CLEAR_HINT}`)
+    }
+    const body = token.startsWith('!') ? token.slice(1).trim() : token
+    if (!body) {
+      throw new RouteArgError(`Invalid --exclusions: "!" needs a path, for example --exclusions=/health. ${CLEAR_HINT}`)
+    }
+    out.push(body)
+  }
+  return out
+}
+
+/**
+ * @param {string[]} args argv after the subcommand
+ * @param {{ allowExclusions?: boolean }} [options]
+ * @returns {{ help: boolean, json: boolean, positional: string[], exclusions: string[] | undefined }}
+ * `exclusions` is undefined when the flag was not passed. `[]` means clear.
+ */
+function parseRouteWriteArgs(args, { allowExclusions = true } = {}) {
+  let help = false
+  let json = false
+  /** @type {string[] | undefined} */
+  let exclusions
+  let sawExclusions = false
+  const positional = []
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+    if (arg === '--help' || arg === '-h') {
+      help = true
+      continue
+    }
+    if (arg === '--json') {
+      json = true
+      continue
+    }
+    if (arg === '--exclusions' || arg.startsWith('--exclusions=')) {
+      if (!allowExclusions) {
+        throw new RouteArgError(`Unsupported option: ${arg === '--exclusions' ? '--exclusions' : '--exclusions='}. route delete does not change exclusions.`)
+      }
+      if (arg === '--exclusions') {
+        throw new RouteArgError(`Unsupported option: --exclusions. ${CLEAR_HINT}`)
+      }
+      if (sawExclusions) throw new RouteArgError('--exclusions was given more than once.')
+      sawExclusions = true
+      exclusions = parseExclusionList(arg.slice('--exclusions='.length))
+      continue
+    }
+    if (arg.startsWith('-')) {
+      throw new RouteArgError(`Unsupported option: ${arg}.`)
+    }
+    positional.push(arg)
+  }
+
+  return { help, json, positional, exclusions: sawExclusions ? exclusions : undefined }
+}
+
+/**
+ * Split a pattern argument the way the CLI always has (`"host !/api"`), but
+ * refuse a bare `!` — that used to be dropped and looked like a successful clear.
+ * @returns {{ patterns: string[], exclusions: string[] }}
+ */
+function parsePatternArg(raw) {
+  const parts = String(raw).trim().split(/\s+/).filter(Boolean)
+  for (const part of parts) {
+    if (part.startsWith('!') && part.slice(1).trim() === '') {
+      throw new RouteArgError('Invalid exclusion "!": a "!" token needs a path such as "!/api". To clear exclusions, pass --exclusions=.')
+    }
+  }
+  return splitPatternArg(raw)
+}
+
+/**
+ * @param {string[]} patternExclusions exclusions parsed from !path tokens
+ * @param {string[] | undefined} flagExclusions undefined when --exclusions was omitted
+ * @returns {{ explicit: boolean, exclusions: string[] | undefined }}
+ */
+function resolveExclusions(patternExclusions, flagExclusions) {
+  if (flagExclusions !== undefined && patternExclusions.length > 0) {
+    throw new RouteArgError('Pass exclusions either as !path tokens in the pattern or with --exclusions, not both.')
+  }
+  if (flagExclusions !== undefined) return { explicit: true, exclusions: flagExclusions }
+  if (patternExclusions.length > 0) return { explicit: true, exclusions: patternExclusions }
+  return { explicit: false, exclusions: undefined }
+}
+
+const UPDATE_HELP = `
+meddle route update <file> <pattern> [<target>] [--exclusions=<list>] [--json]
+
+Update a rule. Edits only the line(s) that hold the pattern; every other line
+stays byte-for-byte, including comments, blank lines and other rules' !path.
+
+  --exclusions=            Clear this rule's exclusions (the line loses !path).
+  --exclusions=/a,/b       Replace exclusions. Spaces work inside quotes
+                           (--exclusions="/a /b"). A leading ! is optional.
+  "pattern !/a !/b"        Replace exclusions (same as before). Omit both
+                           --exclusions and !path to keep existing exclusions.
+
+The <target> may be omitted when --exclusions is set; the current target stays.
+A bare --exclusions, an empty "!" token, an unknown flag, or both exclusion
+forms at once exits 1 and does not change the file.
+
+A "#" comments out a whole line only when it is the first non-space character.
+A "#" later on a rule line is a pattern token, not a trailing comment.
+
+Examples:
+  meddle route update dev "api.example.com" "localhost:4000"
+  meddle route update dev "api.example.com" --exclusions=
+  meddle route update dev "api.example.com" "localhost:4000" --exclusions=/health
+`
+
+module.exports = {
+  CLEAR_HINT,
+  RouteArgError,
+  UPDATE_HELP,
+  parseExclusionList,
+  parsePatternArg,
+  parseRouteWriteArgs,
+  resolveExclusions,
+}

package/bin/lib/rule-file-edit.js

@@ -0,0 +1,263 @@
+/**
+ * Line-preserving edits of route rule files (issue #145).
+ *
+ * The old write path parsed a rule file into a ruleMap and rebuilt the whole
+ * text, which dropped comments, blank lines, disabled (`//`) rules and — in the
+ * CLI — every other rule's exclusions (`!path`). These helpers edit only the
+ * lines that hold the target pattern; every other line keeps its exact bytes
+ * (including its line ending).
+ *
+ * Kept in sync with core/rule-file-edit.ts (same convention as
+ * bin/lib/meddle-home.js ↔ core/meddle-home.ts).
+ */
+
+const MARKER = /\[([^\]]+)\]/
+const BOM = '\uFEFF'
+const SPLIT_UNSAFE_MESSAGE = '该行剩余的 pattern 以 // 或 # 开头，拆开后会被当成注释，请用文本编辑器手动修改'
+
+/**
+ * Thrown when splitting a line or removing a pattern would put a pattern that
+ * starts with `//` or `#` at the start of a line, turning it into a disabled
+ * rule or a comment. The rule file is left untouched.
+ */
+class RuleLineSplitError extends Error {
+  constructor() {
+    super(SPLIT_UNSAFE_MESSAGE)
+    this.name = 'RuleLineSplitError'
+    this.code = 'RULE_LINE_SPLIT_UNSAFE'
+  }
+}
+
+const NEW_RULE_COMMENT_MESSAGE = '规则不能以 // 或 # 开头，否则会被当成禁用行或注释。要写注释或禁用规则，请用文本编辑器。'
+
+/**
+ * Thrown when a NEW rule's pattern starts with `//` or `#`: appended as a line it
+ * would read back as a disabled rule or a comment. Same code as RuleLineSplitError.
+ */
+class RuleNewRuleCommentError extends Error {
+  constructor() {
+    super(NEW_RULE_COMMENT_MESSAGE)
+    this.name = 'RuleNewRuleCommentError'
+    this.code = 'RULE_LINE_SPLIT_UNSAFE'
+  }
+}
+
+function startsAsComment(pattern) {
+  return pattern.startsWith('//') || pattern.startsWith('#')
+}
+
+/**
+ * A leading UTF-8 BOM is not part of the first line: strip it before editing
+ * and put it back afterwards, so it stays byte-identical even when the first
+ * line is split or deleted (JS `trim()` / `\s` treat U+FEFF as whitespace).
+ */
+function withBom(content, edit) {
+  if (!content.startsWith(BOM)) return edit(content)
+  const result = edit(content.slice(BOM.length))
+  return { ...result, content: BOM + result.content }
+}
+
+/** Internal key of a pattern token: `[marker]` brackets removed (same as the parser). */
+function patternKey(token) {
+  const bm = token.match(MARKER)
+  return bm ? token.replace(bm[0], bm[1]) : token
+}
+
+/** Split into [line, eol, line, eol, ..., line]; the parser splits on /\r?\n/ too. */
+function splitLines(content) {
+  return content.split(/(\r?\n)/)
+}
+
+/**
+ * Parse one line the way parseEprcWithExclusions does. Returns null for blank
+ * lines, `#` comments, `//` disabled rules and lines that are not rules.
+ */
+function parseRuleLine(line) {
+  const trimmed = line.trim()
+  if (!trimmed || trimmed.startsWith('#') || trimmed.startsWith('//')) return null
+  const parts = trimmed.split(/\s+/).filter(Boolean)
+  const exclusionTokens = parts.filter((p) => p.startsWith('!'))
+  const regular = parts.filter((p) => !p.startsWith('!'))
+  if (regular.length < 2) return null
+  return {
+    leading: line.match(/^\s*/)[0],
+    patterns: regular.slice(0, -1),
+    target: regular[regular.length - 1],
+    exclusions: exclusionTokens.map((t) => t.slice(1)),
+  }
+}
+
+function formatLine(leading, patterns, exclusions, target) {
+  const parts = patterns.slice()
+  for (const e of exclusions) parts.push(`!${e}`)
+  parts.push(target)
+  return `${leading}${parts.join(' ')}`
+}
+
+function sameList(a, b) {
+  return a.length === b.length && a.every((v, i) => v === b[i])
+}
+
+/** Replace the last regular (target) token in place, keeping all spacing. */
+function replaceTargetInPlace(line, target) {
+  const tokens = line.match(/\s+|\S+/g) || []
+  for (let i = tokens.length - 1; i >= 0; i--) {
+    if (/\S/.test(tokens[i]) && !tokens[i].startsWith('!')) {
+      tokens[i] = target
+      return tokens.join('')
+    }
+  }
+  return line
+}
+
+/** Remove the given non-space token indexes (and one adjacent separator each). */
+function removePatternTokens(line, keys) {
+  const tokens = line.match(/\s+|\S+/g) || []
+  const nonSpace = []
+  tokens.forEach((t, i) => { if (/\S/.test(t)) nonSpace.push(i) })
+  const regularIdx = nonSpace.filter((i) => !tokens[i].startsWith('!'))
+  const patternIdx = regularIdx.slice(0, -1)
+  const drop = new Set()
+  for (const i of patternIdx) {
+    if (!keys.has(patternKey(tokens[i]))) continue
+    drop.add(i)
+    // Prefer the separator after the token (a pattern is never the last token).
+    if (i + 1 < tokens.length && !/\S/.test(tokens[i + 1]) && !drop.has(i + 1)) drop.add(i + 1)
+    else if (i - 1 > 0 && !/\S/.test(tokens[i - 1])) drop.add(i - 1)
+  }
+  return tokens.filter((_, i) => !drop.has(i)).join('')
+}
+
+/**
+ * Normalise a user-supplied pattern argument. The CLI accepts exclusions inside
+ * the pattern argument (`"app.example.com !/api"`), so split those out.
+ */
+function splitPatternArg(raw) {
+  const parts = String(raw).trim().split(/\s+/).filter(Boolean)
+  const patterns = parts.filter((p) => !p.startsWith('!'))
+  const exclusions = parts.filter((p) => p.startsWith('!')).map((p) => p.slice(1)).filter(Boolean)
+  return { patterns, exclusions }
+}
+
+/**
+ * Point every enabled occurrence of `pattern` at `target` (if given) and/or set
+ * its exclusions (if given; `undefined` keeps each line's own exclusions).
+ * Lines that do not contain the pattern are left untouched.
+ * @returns {{ content: string, found: boolean }}
+ */
+function updateRouteRule(content, { pattern, target, exclusions }) {
+  return withBom(content, (text) => updateLines(text, { pattern, target, exclusions }))
+}
+
+function updateLines(content, { pattern, target, exclusions }) {
+  const key = patternKey(pattern)
+  const userHasMarker = MARKER.test(pattern)
+  const segments = splitLines(content)
+  let found = false
+
+  for (let s = 0; s < segments.length; s += 2) {
+    const line = segments[s]
+    const parsed = parseRuleLine(line)
+    if (!parsed || !parsed.patterns.some((p) => patternKey(p) === key)) continue
+    found = true
+
+    const nextTarget = target !== undefined ? target : parsed.target
+    const nextExclusions = exclusions !== undefined ? exclusions : parsed.exclusions
+    const exclusionsChanged = !sameList(nextExclusions, parsed.exclusions)
+    const markerChanged = userHasMarker && parsed.patterns.some((p) => patternKey(p) === key && p !== pattern)
+    if (nextTarget === parsed.target && !exclusionsChanged && !markerChanged) continue
+
+    const allMatch = parsed.patterns.every((p) => patternKey(p) === key)
+    if (allMatch && !exclusionsChanged && !markerChanged) {
+      segments[s] = replaceTargetInPlace(line, nextTarget)
+      continue
+    }
+
+    // Split the line into consecutive groups so other patterns on the same line
+    // keep their target / exclusions and the original order is preserved.
+    const groups = []
+    for (const p of parsed.patterns) {
+      const match = patternKey(p) === key
+      const last = groups[groups.length - 1]
+      if (last && last.match === match) last.patterns.push(p)
+      else groups.push({ match, patterns: [p] })
+    }
+    if (groups.some((g) => startsAsComment(g.match && userHasMarker ? pattern : g.patterns[0]))) throw new RuleLineSplitError()
+    const lines = groups.map((g) => g.match
+      ? formatLine(parsed.leading, g.patterns.map((p) => (userHasMarker ? pattern : p)), nextExclusions, nextTarget)
+      : formatLine(parsed.leading, g.patterns, parsed.exclusions, parsed.target))
+    const eol = segments[s + 1] !== undefined ? segments[s + 1] : (content.includes('\r\n') ? '\r\n' : '\n')
+    segments[s] = lines.join(eol)
+  }
+
+  return { content: segments.join(''), found }
+}
+
+/**
+ * Add a rule. An existing pattern is updated in place (its exclusions are kept
+ * unless `exclusions` is given); otherwise a new line is appended at the end.
+ * @returns {{ content: string, existed: boolean }}
+ */
+function addRouteRule(content, { pattern, target, exclusions }) {
+  const updated = updateRouteRule(content, { pattern, target, exclusions })
+  if (updated.found) return { content: updated.content, existed: true }
+  if (startsAsComment(pattern)) throw new RuleNewRuleCommentError()
+
+  const line = formatLine('', [pattern], exclusions || [], target)
+  if (content === '' || content === BOM) return { content: content + line, existed: false }
+  const eol = content.includes('\r\n') ? '\r\n' : '\n'
+  if (/\r?\n$/.test(content)) return { content: `${content}${line}${eol}`, existed: false }
+  return { content: `${content}${eol}${line}`, existed: false }
+}
+
+/**
+ * Remove every enabled occurrence of `pattern`. Other patterns on the same line
+ * stay; a line left without patterns is removed with its line ending.
+ * @returns {{ content: string, found: boolean }}
+ */
+function deleteRouteRule(content, { pattern }) {
+  return withBom(content, (text) => deleteLines(text, { pattern }))
+}
+
+function deleteLines(content, { pattern }) {
+  const key = patternKey(pattern)
+  const segments = splitLines(content)
+  const out = []
+  let found = false
+
+  for (let s = 0; s < segments.length; s += 2) {
+    const line = segments[s]
+    const eol = segments[s + 1]
+    const parsed = parseRuleLine(line)
+    if (!parsed || !parsed.patterns.some((p) => patternKey(p) === key)) {
+      out.push(line)
+      if (eol !== undefined) out.push(eol)
+      continue
+    }
+    found = true
+    if (parsed.patterns.every((p) => patternKey(p) === key)) {
+      // Drop the whole line. For a last line without a line ending, drop the
+      // previous line's ending instead so no dangling empty line is left behind.
+      if (eol === undefined && out.length > 0) out.pop()
+      continue
+    }
+    if (startsAsComment(parsed.patterns.find((p) => patternKey(p) !== key))) throw new RuleLineSplitError()
+    out.push(removePatternTokens(line, new Set([key])))
+    if (eol !== undefined) out.push(eol)
+  }
+
+  return { content: out.join(''), found }
+}
+
+module.exports = {
+  SPLIT_UNSAFE_MESSAGE,
+  RuleLineSplitError,
+  NEW_RULE_COMMENT_MESSAGE,
+  RuleNewRuleCommentError,
+  patternKey,
+  parseRuleLine,
+  splitPatternArg,
+  addRouteRule,
+  updateRouteRule,
+  deleteRouteRule,
+}

package/bin/lib/ruleset-readonly.js

@@ -0,0 +1,61 @@
+/**
+ * Issue #137: read-only rulesets (rule files).
+ *
+ * The lock lives in settings.json (`readonlyRuleFiles`) and can only be set or
+ * cleared from the Meddle web UI. The CLI has no lock / unlock command; it only
+ * reports the state (`readonly` in --json output) and refuses writes.
+ */
+
+const chalk = require('chalk')
+
+const RULESET_READONLY = 'RULESET_READONLY'
+const RULESET_READONLY_MESSAGE = '该规则集已设为只读，只能在 Meddle 界面中解锁'
+/** Dedicated CLI exit code for a write rejected because the ruleset is read-only. */
+const EXIT_RULESET_READONLY = 3
+
+class RulesetReadonlyError extends Error {
+  constructor(ruleFile) {
+    super(RULESET_READONLY_MESSAGE)
+    this.name = 'RulesetReadonlyError'
+    this.code = RULESET_READONLY
+    this.ruleFile = ruleFile
+  }
+}
+
+function isRulesetReadonlyError(err) {
+  return Boolean(err) && err.code === RULESET_READONLY
+}
+
+/**
+ * Print the rejection and exit with EXIT_RULESET_READONLY.
+ * --json: one JSON line on stdout; the human message always goes to stderr.
+ */
+function exitRulesetReadonly(err, { json = false, ruleFile } = {}) {
+  const file = (err && err.ruleFile) || ruleFile || null
+  if (json) {
+    console.log(JSON.stringify({
+      success: false,
+      error: { code: RULESET_READONLY, message: RULESET_READONLY_MESSAGE, ruleFile: file },
+    }))
+  }
+  console.error(chalk.red('  ✗'), `${RULESET_READONLY_MESSAGE} (${RULESET_READONLY}${file ? `: ${file}` : ''})`)
+  process.exit(EXIT_RULESET_READONLY)
+}
+
+/** Throw if any of `names` is in the given rule-file list with readonly: true. */
+function assertListedFilesWritable(files, names) {
+  const locked = new Set((Array.isArray(files) ? files : []).filter((f) => f && f.readonly).map((f) => f.name))
+  for (const name of names) {
+    if (locked.has(name)) throw new RulesetReadonlyError(name)
+  }
+}
+
+module.exports = {
+  RULESET_READONLY,
+  RULESET_READONLY_MESSAGE,
+  EXIT_RULESET_READONLY,
+  RulesetReadonlyError,
+  isRulesetReadonlyError,
+  exitRulesetReadonly,
+  assertListedFilesWritable,
+}

package/bin/lib/update-check.js

@@ -27,6 +27,58 @@ const DEFAULT_CACHE_TTL_MS = 24 * 60 * 60 * 1000
 const DEFAULT_TIMEOUT_MS = 5000
 const DEFAULT_DOWNLOAD_TIMEOUT_MS = 120 * 1000
 
+/**
+ * Resolve a GitHub token for private release downloads / latest redirects.
+ * Precedence: explicit argument → GH_TOKEN → GITHUB_TOKEN.
+ * @param {string} [explicit]
+ * @returns {string}
+ */
+function resolveGithubToken(explicit) {
+    if (typeof explicit === 'string' && explicit.trim()) return explicit.trim()
+    const gh = process.env.GH_TOKEN
+    if (typeof gh === 'string' && gh.trim()) return gh.trim()
+    const github = process.env.GITHUB_TOKEN
+    if (typeof github === 'string' && github.trim()) return github.trim()
+    return ''
+}
+
+/**
+ * @param {string} token
+ * @returns {Record<string, string>}
+ */
+function githubAuthHeaders(token) {
+    if (!token) return {}
+    // GitHub accepts Bearer for PATs / fine-grained tokens on release asset URLs.
+    return { Authorization: `Bearer ${token}` }
+}
+
+function privateReleaseAuthHint() {
+    return (
+        'Private GitHub releases require GH_TOKEN or GITHUB_TOKEN '
+        + '(scope: repo, or fine-grained contents:read). '
+        + `Or: gh release download -R ${REPO} -p 'meddle-*'`
+    )
+}
+
+/**
+ * @param {'checksum' | 'download'} kind
+ * @param {number} status
+ * @param {boolean} hadToken
+ * @returns {string}
+ */
+function formatDownloadStatusError(kind, status, hadToken) {
+    const base = kind === 'checksum'
+        ? `checksum sidecar missing (${status})`
+        : `download failed (${status})`
+    if ((status === 404 || status === 401 || status === 403) && !hadToken) {
+        return `${base}. ${privateReleaseAuthHint()}`
+    }
+    if ((status === 401 || status === 403) && hadToken) {
+        return `${base}. Token may lack repo/contents:read access to ${REPO}`
+    }
+    return base
+}
+
 const VERSION_RE = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/
 
 /**
@@ -120,12 +172,14 @@ async function getLatestVersionNpm({ fetchImpl, registryUrl, timeoutMs, distTag
  * @param {{ fetchImpl?: Function, latestUrl?: string, timeoutMs?: number }} opts
  * @returns {Promise<string>}
  */
-async function getLatestVersionGithub({ fetchImpl, latestUrl, timeoutMs } = {}) {
+async function getLatestVersionGithub({ fetchImpl, latestUrl, timeoutMs, githubToken } = {}) {
     const doFetch = fetchImpl || fetch
     const url = latestUrl || process.env.MEDDLE_GITHUB_LATEST_URL || DEFAULT_GITHUB_LATEST_URL
+    const token = resolveGithubToken(githubToken)
     const response = await doFetch(url, {
         redirect: 'manual',
         signal: AbortSignal.timeout(timeoutMs || DEFAULT_TIMEOUT_MS),
+        headers: githubAuthHeaders(token),
     })
     if (response.status < 300 || response.status >= 400) {
         throw new Error(`GitHub latest release did not redirect (${response.status})`)
@@ -287,7 +341,7 @@ function sha256Hex(buffer) {
  *           baseUrl?: string, fetchImpl?: Function, timeoutMs?: number,
  *           retries?: number, retryDelayMs?: number,
  *           onProgress?: Function, onAttempt?: Function,
- *           fsImpl?: object }} opts
+ *           githubToken?: string, fsImpl?: object }} opts
  * @returns {Promise<{ installed: string, backup: string, version: string }>}
  */
 async function downloadBinaryAsset(opts) {
@@ -300,6 +354,8 @@ async function downloadBinaryAsset(opts) {
     const retryDelayMs = opts.retryDelayMs === undefined ? 1000 : opts.retryDelayMs
     const onProgress = typeof opts.onProgress === 'function' ? opts.onProgress : () => {}
     const onAttempt = typeof opts.onAttempt === 'function' ? opts.onAttempt : () => {}
+    const token = resolveGithubToken(opts.githubToken)
+    const authHeaders = githubAuthHeaders(token)
 
     const asset = getAssetName({ platform, arch })
     const assetUrl = `${baseUrl}/v${version}/${asset}`
@@ -327,8 +383,8 @@ async function downloadBinaryAsset(opts) {
             }
             resetIdle()
             try {
-                const response = await doFetch(assetUrl, { signal: controller.signal })
-                if (!response.ok) throw new Error(`download failed (${response.status})`)
+                const response = await doFetch(assetUrl, { signal: controller.signal, headers: authHeaders })
+                if (!response.ok) throw new Error(formatDownloadStatusError('download', response.status, Boolean(token)))
                 const total = Number(response.headers.get('content-length')) || 0
                 const chunks = []
                 let received = 0
@@ -365,8 +421,11 @@ async function downloadBinaryAsset(opts) {
     // download — otherwise the sidecar body stream aborts before it is read
     // and the whole install fails with "operation aborted" right after the
     // payload reached 100%.
-    const shaResponse = await doFetch(shaUrl, { signal: AbortSignal.timeout(DEFAULT_TIMEOUT_MS) })
-    if (!shaResponse.ok) throw new Error(`checksum sidecar missing (${shaResponse.status})`)
+    const shaResponse = await doFetch(shaUrl, {
+        signal: AbortSignal.timeout(DEFAULT_TIMEOUT_MS),
+        headers: authHeaders,
+    })
+    if (!shaResponse.ok) throw new Error(formatDownloadStatusError('checksum', shaResponse.status, Boolean(token)))
     const shaText = await shaResponse.text()
 
     const payload = await fetchPayload()
@@ -559,5 +618,7 @@ module.exports = {
     setAutoUpdate,
     resolveUpdateBinDir,
     runAsyncUpdateCheck,
+    resolveGithubToken,
+    githubAuthHeaders,
     DEFAULT_DOWNLOAD_TIMEOUT_MS,
 }