@ouro.bot/cli 0.1.0-alpha.83 → 0.1.0-alpha.830

package/deploy/unraid/docker-man-template-xml.cjs

@@ -0,0 +1,105 @@
+"use strict"
+
+const { TextDecoder } = require("node:util")
+
+const DECLARATION = "<?xml version=\"1.0\"?>"
+const ROOT_OPEN = "<Container version=\"2\">"
+const ROOT_CLOSE = "</Container>"
+const NAME_START = /^[A-Za-z_]$/u
+const NAME_CHARACTER = /^[A-Za-z0-9_.:-]$/u
+const XML_WHITESPACE = /^[\t\n\r ]$/u
+const UTF8_DECODER = new TextDecoder("utf-8", { fatal: true })
+
+function decodeUtf8(value) {
+  if (typeof value === "string") return value
+  if (!(value instanceof Uint8Array)) throw new TypeError("DockerMan template bytes are invalid")
+  return UTF8_DECODER.decode(value)
+}
+
+function skipWhitespace(value, start) {
+  let index = start
+  while (XML_WHITESPACE.test(value[index] ?? "")) index += 1
+  return index
+}
+
+function readName(value, start) {
+  if (!NAME_START.test(value[start] ?? "")) return null
+  let index = start + 1
+  while (NAME_CHARACTER.test(value[index] ?? "")) index += 1
+  return { name: value.slice(start, index), index }
+}
+
+function readOpenTag(xml, start) {
+  if (xml[start] !== "<") return null
+  const parsedName = readName(xml, start + 1)
+  if (!parsedName) return null
+  const attributes = new Map()
+  let index = parsedName.index
+  while (index < xml.length) {
+    if (xml[index] === ">") return { name: parsedName.name, attributes: Object.fromEntries(attributes), form: "text", index: index + 1 }
+    if (xml.startsWith("/>", index)) return { name: parsedName.name, attributes: Object.fromEntries(attributes), form: "empty", index: index + 2 }
+    const whitespaceEnd = skipWhitespace(xml, index)
+    if (whitespaceEnd === index) return null
+    index = whitespaceEnd
+    if (xml[index] === ">" || xml.startsWith("/>", index)) continue
+    const attribute = readName(xml, index)
+    if (!attribute || attributes.has(attribute.name)) return null
+    index = skipWhitespace(xml, attribute.index)
+    if (xml[index] !== "=") return null
+    index = skipWhitespace(xml, index + 1)
+    if (xml[index] !== "\"") return null
+    const end = xml.indexOf("\"", index + 1)
+    if (end === -1) return null
+    const value = xml.slice(index + 1, end)
+    if (!/^[\x20-\x7E]*$/u.test(value) || value.includes("<") || value.includes("&")) return null
+    attributes.set(attribute.name, value)
+    index = end + 1
+  }
+  return null
+}
+
+function hasValidXmlCharacters(value) {
+  for (const character of value) {
+    const codePoint = character.codePointAt(0)
+    if (!(codePoint === 0x9 || codePoint === 0xA || codePoint === 0xD
+      || (codePoint >= 0x20 && codePoint <= 0xD7FF)
+      || (codePoint >= 0xE000 && codePoint <= 0xFFFD)
+      || (codePoint >= 0x10000 && codePoint <= 0x10FFFF))) return false
+  }
+  return true
+}
+
+// Canonical DockerMan dialect: exact declaration and Container root, flat leaf children, double-quoted ASCII attributes, and literal text without entities or auxiliary XML constructs.
+function parseDockerManTemplateXml(input) {
+  let xml
+  try { xml = decodeUtf8(input) } catch { return null }
+  if (!hasValidXmlCharacters(xml) || !xml.startsWith(DECLARATION)) return null
+  let index = skipWhitespace(xml, DECLARATION.length)
+  if (!xml.startsWith(ROOT_OPEN, index)) return null
+  index += ROOT_OPEN.length
+  const children = []
+  while (index < xml.length) {
+    index = skipWhitespace(xml, index)
+    if (xml.startsWith(ROOT_CLOSE, index)) {
+      index = skipWhitespace(xml, index + ROOT_CLOSE.length)
+      return index === xml.length ? { root: { name: "Container", attributes: { version: "2" } }, children } : null
+    }
+    const child = readOpenTag(xml, index)
+    if (!child) return null
+    index = child.index
+    if (child.form === "empty") {
+      children.push({ name: child.name, attributes: child.attributes, form: child.form, text: "" })
+      continue
+    }
+    const close = `</${child.name}>`
+    const end = xml.indexOf("<", index)
+    if (end === -1 || !xml.startsWith(close, end)) return null
+    const text = xml.slice(index, end)
+    if (text.includes("&") || text.includes("]]>")) return null
+    children.push({ name: child.name, attributes: child.attributes, form: child.form, text })
+    index = end + close.length
+  }
+  return null
+}
+
+module.exports = { decodeUtf8, parseDockerManTemplateXml }

package/deploy/unraid/migrate-sanctuary-bundle.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+import * as path from "node:path"
+import { pathToFileURL } from "node:url"
+
+const USAGE = "Usage: migrate-sanctuary-bundle.mjs --package-root <path> --agent-root <path> --operation <migrate|rollback|finalize-rollback|commit|status|inspect> [--rollback-image-id <sha256:id> --target-image-id <sha256:id>]"
+const BASE_KEYS = ["--package-root", "--agent-root", "--operation"]
+const MIGRATE_KEYS = [...BASE_KEYS, "--rollback-image-id", "--target-image-id"]
+
+function parseArguments(args) {
+  if (args.length % 2 !== 0) throw new Error(USAGE)
+  const values = new Map()
+  for (let index = 0; index < args.length; index += 2) {
+    const key = args[index]
+    const value = args[index + 1]
+    if (values.has(key) || typeof value !== "string" || value.length === 0) throw new Error(USAGE)
+    values.set(key, value)
+  }
+  const operation = values.get("--operation")
+  if (!["migrate", "rollback", "finalize-rollback", "commit", "status", "inspect"].includes(operation)) throw new Error(USAGE)
+  const expectedKeys = operation === "migrate" ? MIGRATE_KEYS : BASE_KEYS
+  if (values.size !== expectedKeys.length || expectedKeys.some((key) => !values.has(key)) || [...values.keys()].some((key) => !expectedKeys.includes(key))) throw new Error(USAGE)
+  return values
+}
+
+export function runSanctuaryBundleOperation(args, dependencies) {
+  const values = parseArguments(args)
+  const packageRoot = values.get("--package-root")
+  const agentRoot = values.get("--agent-root")
+  const operation = values.get("--operation")
+  const result = operation === "migrate"
+    ? dependencies.migrate({ packageRoot, agentRoot, retainRollback: true, rollbackImageId: values.get("--rollback-image-id"), targetImageId: values.get("--target-image-id") })
+    : operation === "rollback"
+      ? { rolledBack: dependencies.rollback(agentRoot, { retainRecord: true }) }
+      // `rollback` keeps crash-retry evidence; the host uses `finalize-rollback` only after old production is audited, ready, and restored to autostart.
+      : operation === "finalize-rollback"
+        ? { rolledBack: dependencies.rollback(agentRoot, { retainRecord: false }) }
+        : operation === "commit"
+          ? { committed: dependencies.commit(agentRoot) }
+          : operation === "status"
+            ? dependencies.status(agentRoot)
+            : dependencies.inspect({ packageRoot, agentRoot, runtimePackageVersion: dependencies.getPackageVersion() })
+  if (result === null || ("rolledBack" in result && !result.rolledBack) || ("committed" in result && !result.committed)) throw new Error(`${operation} found no pending Sanctuary bundle transaction`)
+  return result
+}
+
+export async function runSanctuaryBundleCli(args = process.argv.slice(2), output = process.stdout) {
+  const migration = await import("../../dist/heart/daemon/sanctuary-bundle-migration.js")
+  const manifest = await import("../../dist/mind/bundle-manifest.js")
+  const result = runSanctuaryBundleOperation(args, {
+    commit: migration.commitSanctuaryPackageManagedBundle,
+    getPackageVersion: manifest.getPackageVersion,
+    inspect: migration.inspectSanctuaryPackageManagedBundle,
+    migrate: migration.migrateSanctuaryPackageManagedBundle,
+    rollback: migration.rollbackSanctuaryPackageManagedBundle,
+    status: migration.inspectSanctuaryPackageManagedBundleRollback,
+  })
+  output.write(`${JSON.stringify(result)}\n`)
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) await runSanctuaryBundleCli()

package/deploy/unraid/ouro-events/bootstrap-spool.sh

@@ -0,0 +1,92 @@
+#!/bin/bash
+set -euo pipefail
+
+SPOOL_ROOT="/boot/config/custom/ouro-events/spool"
+INSTALL_PATH="/boot/config/custom/ouro-events/bootstrap-spool.sh"
+GO_FILE="/boot/config/go"
+TMPFS_OPTIONS="size=4m,mode=0755,uid=0,gid=0,nodev,nosuid,noexec"
+BOOT_HOOK="/bin/bash /boot/config/custom/ouro-events/bootstrap-spool.sh --mount"
+ACTION="mount"
+
+while (($# > 0)); do
+  case "$1" in
+    --mount|--install-only|--self-test) ACTION="${1#--}"; shift ;;
+    --go-file) GO_FILE="${2:?missing --go-file value}"; shift 2 ;;
+    --install-path) INSTALL_PATH="${2:?missing --install-path value}"; shift 2 ;;
+    *) echo "ouro event spool bootstrap: invalid argument: $1" >&2; exit 2 ;;
+  esac
+done
+
+mount_spool() {
+  local target="$1"
+  /bin/mkdir -p "$target"
+  /bin/chown 0:0 "$target"
+  /bin/chmod 0755 "$target"
+  if /bin/mountpoint -q "$target"; then
+    [[ "$(/bin/findmnt -n -o FSTYPE --target "$target")" == "tmpfs" ]] || { echo "ouro event spool bootstrap: canonical path is already a non-tmpfs mount" >&2; return 1; }
+  else
+    /bin/mount -t tmpfs -o "$TMPFS_OPTIONS" ouro-events-spool "$target"
+  fi
+  [[ "$(/bin/stat -c '%u:%g:%a' "$target")" == "0:0:755" ]] || { echo "ouro event spool bootstrap: tmpfs identity or mode is unsafe" >&2; return 1; }
+  local options
+  options="$(/bin/findmnt -n -o OPTIONS --target "$target")"
+  for required in nodev nosuid noexec; do
+    [[ ",$options," == *",$required,"* ]] || { echo "ouro event spool bootstrap: tmpfs is missing $required" >&2; return 1; }
+  done
+  local size_bytes
+  size_bytes="$(/bin/findmnt -bn -o SIZE --target "$target")"
+  [[ "$size_bytes" =~ ^[0-9]+$ && "$size_bytes" -le 4194304 ]] || { echo "ouro event spool bootstrap: tmpfs exceeds its 4 MiB bound" >&2; return 1; }
+}
+
+install_boot_hook() {
+  local install_dir resolved_source resolved_install
+  install_dir="$(dirname "$INSTALL_PATH")"
+  /bin/mkdir -p "$install_dir"
+  resolved_source="$(cd "$(dirname "$0")" && pwd -P)/$(basename "$0")"
+  resolved_install="$(cd "$install_dir" && pwd -P)/$(basename "$INSTALL_PATH")"
+  if [[ "$resolved_source" != "$resolved_install" ]]; then
+    install -m 0700 "$0" "$INSTALL_PATH"
+  else
+    /bin/chmod 0700 "$INSTALL_PATH"
+  fi
+  [[ -f "$GO_FILE" ]] || printf '#!/bin/bash\n' > "$GO_FILE"
+  if ! grep -Fqx "$BOOT_HOOK" "$GO_FILE"; then
+    local temporary="${GO_FILE}.ouro-events.$$"
+    awk -v hook="$BOOT_HOOK" 'NR == 1 && /^#!/ { print; print hook; next } NR == 1 { print hook } { print }' "$GO_FILE" > "$temporary"
+    /bin/chmod 0700 "$temporary"
+    /bin/mv "$temporary" "$GO_FILE"
+  fi
+}
+
+self_test() {
+  [[ "$(/usr/bin/id -u)" == "0" ]] || { echo "ouro event spool bootstrap self-test requires root" >&2; return 1; }
+  local test_root target readonly_view
+  test_root="$(/usr/bin/mktemp -d /tmp/ouro-event-spool.XXXXXX)"
+  target="$test_root/spool"
+  readonly_view="$test_root/readonly"
+  /bin/chmod 0755 "$test_root"
+  /bin/mkdir "$target" "$readonly_view"
+  cleanup() {
+    /bin/umount "$readonly_view" 2>/dev/null || true
+    /bin/umount "$target" 2>/dev/null || true
+    /bin/rmdir "$readonly_view" "$target" "$test_root" 2>/dev/null || true
+  }
+  trap cleanup EXIT
+  mount_spool "$target"
+  /usr/bin/printf 'probe\n' > "$target/probe"
+  /bin/chown 0:0 "$target/probe"
+  /bin/chmod 0444 "$target/probe"
+  /bin/mount --bind "$target" "$readonly_view"
+  /bin/mount -o remount,bind,ro,nodev,nosuid,noexec "$readonly_view"
+  /usr/bin/setpriv --reuid=10001 --regid=10001 --clear-groups /usr/bin/test -r "$readonly_view/probe"
+  [[ ",$(/bin/findmnt -n -o OPTIONS --target "$readonly_view")," == *",ro,"* ]] || { echo "ouro event spool bootstrap: test bind is not read-only" >&2; return 1; }
+  echo "uid10001-ro-bind: pass"
+  cleanup
+  trap - EXIT
+}
+
+case "$ACTION" in
+  mount) mount_spool "$SPOOL_ROOT" ;;
+  install-only) install_boot_hook ;;
+  self-test) self_test ;;
+esac

package/deploy/unraid/ouro-events/emit-event.mjs

@@ -0,0 +1,310 @@
+#!/usr/bin/env node
+
+import { createHash, randomBytes } from "node:crypto"
+import * as fs from "node:fs"
+import * as path from "node:path"
+import { fileURLToPath } from "node:url"
+
+const SPOOL_ROOT = "/boot/config/custom/ouro-events/spool"
+const MAX_BYTES = 32 * 1024
+const MAX_SPOOL_FILES = 4_096
+const DEFAULT_EXPIRY_GRACE_MS = 24 * 60 * 60_000
+const ENVELOPE_KEYS = ["action", "actionReceipt", "agent", "createdAt", "critical", "eventType", "evidence", "expiresAt", "incidentKey", "nonce", "observationRevision", "protectiveStateDigest", "protectiveStateObservedAt", "protectiveStateVerified", "schemaVersion", "source", "summary", "transitionId"]
+
+function id(value, name) {
+  if (typeof value !== "string" || !/^[a-zA-Z0-9._:-]{1,160}$/u.test(value)) throw new Error(`${name} is invalid`)
+  return value
+}
+
+function bounded(value, name, max) {
+  if (typeof value !== "string" || !value || Buffer.byteLength(value) > max) throw new Error(`${name} must be bounded`)
+  return value
+}
+
+function stableInput(envelope) {
+  const { createdAt: _createdAt, expiresAt: _expiresAt, nonce: _nonce, protectiveStateObservedAt: _protectiveStateObservedAt, ...stable } = envelope
+  return stable
+}
+
+function canonicalIso(value) {
+  return typeof value === "string" && Number.isFinite(Date.parse(value)) && new Date(value).toISOString() === value
+}
+
+function validateEnvelope(envelope) {
+  const eventShapeIsAllowed = envelope && typeof envelope === "object" && !Array.isArray(envelope) && ((envelope.eventType === "usenet.protective_action" && envelope.action === "sabnzbd.pause")
+    || (envelope.eventType === "usenet.health_observation" && envelope.action === "usenet.observe"))
+  const observationTransitionIsAllowed = envelope?.eventType !== "usenet.health_observation" || /^(?:auth-failed|stalled|recovered|indeterminate):\d{8}T\d{6}Z$/u.test(String(envelope.transitionId))
+  if (!envelope || typeof envelope !== "object" || Array.isArray(envelope) || Object.keys(envelope).sort().join("\0") !== [...ENVELOPE_KEYS].sort().join("\0")
+    || envelope.schemaVersion !== 1 || envelope.agent !== "sanctuary" || envelope.source !== "sanctuary-usenet"
+    || !eventShapeIsAllowed || !observationTransitionIsAllowed
+    || envelope.critical !== true || !/^[a-zA-Z0-9._:-]{1,160}$/u.test(String(envelope.incidentKey)) || !/^[a-zA-Z0-9._:-]{1,160}$/u.test(String(envelope.transitionId))
+    || !/^[a-f0-9]{64}$/u.test(String(envelope.observationRevision)) || !/^[a-f0-9]{64}$/u.test(String(envelope.nonce))
+    || typeof envelope.protectiveStateVerified !== "boolean" || !/^[a-f0-9]{64}$/u.test(String(envelope.protectiveStateDigest))
+    || !canonicalIso(envelope.protectiveStateObservedAt)
+    || typeof envelope.actionReceipt !== "string" || !envelope.actionReceipt || Buffer.byteLength(envelope.actionReceipt) > 512
+    || typeof envelope.summary !== "string" || !envelope.summary || Buffer.byteLength(envelope.summary) > 4_096
+    || !Array.isArray(envelope.evidence) || envelope.evidence.length > 16 || envelope.evidence.some((entry) => typeof entry !== "string" || !entry || Buffer.byteLength(entry) > 2_048)
+    || !canonicalIso(envelope.createdAt) || !canonicalIso(envelope.expiresAt)
+    || Date.parse(envelope.expiresAt) <= Date.parse(envelope.createdAt)
+    || Date.parse(envelope.expiresAt) - Date.parse(envelope.createdAt) > 60 * 60_000) {
+    throw new Error("event envelope is invalid")
+  }
+  const serialized = `${JSON.stringify(envelope)}\n`
+  if (Buffer.byteLength(serialized) > MAX_BYTES) throw new Error("event envelope must be bounded")
+  return serialized
+}
+
+function buildEnvelope(input, now, nonce) {
+  const createdAt = new Date(now()).toISOString()
+  const expiresAt = new Date(Date.parse(createdAt) + 15 * 60_000).toISOString()
+  const evidence = input.evidence ?? []
+  if (!Array.isArray(evidence) || evidence.length > 16) throw new Error("evidence must be bounded")
+  const envelope = {
+    schemaVersion: input.schemaVersion,
+    agent: input.agent,
+    source: input.source,
+    eventType: input.eventType,
+    incidentKey: id(input.incidentKey, "incident key"),
+    transitionId: id(input.transitionId, "transition id"),
+    observationRevision: input.observationRevision,
+    action: input.action,
+    actionReceipt: bounded(input.actionReceipt, "action receipt", 512),
+    protectiveStateVerified: input.protectiveStateVerified,
+    protectiveStateDigest: input.protectiveStateDigest,
+    protectiveStateObservedAt: input.protectiveStateObservedAt,
+    critical: input.critical,
+    summary: bounded(input.summary, "summary", 4_096),
+    evidence: evidence.map((entry) => bounded(entry, "evidence", 2_048)),
+    createdAt,
+    expiresAt,
+    nonce: nonce(),
+  }
+  return { envelope, serialized: validateEnvelope(envelope) }
+}
+
+function linuxProcessStart(pid) {
+  try {
+    const raw = fs.readFileSync(`/proc/${pid}/stat`, "utf8")
+    return raw.slice(raw.lastIndexOf(")") + 2).trim().split(/\s+/u)[19] ?? null
+  } catch { return null }
+}
+
+const currentProcessStart = linuxProcessStart(process.pid) ?? `fallback-${Math.floor(Date.now() - process.uptime() * 1_000)}`
+
+function ownerIsLive(owner) {
+  if (!owner || typeof owner.token !== "string" || !Number.isSafeInteger(owner.pid) || typeof owner.processStart !== "string") return false
+  try { process.kill(owner.pid, 0) } catch (error) { return error?.code !== "ESRCH" }
+  const observedStart = owner.pid === process.pid ? currentProcessStart : linuxProcessStart(owner.pid)
+  return observedStart === null || observedStart === owner.processStart
+}
+
+function openSpool(options) {
+  const effectiveUid = options.effectiveUid ?? process.getuid?.()
+  if (effectiveUid !== 0) throw new Error("ouro event producer must run as root")
+  const spoolRoot = options.spoolRoot ?? SPOOL_ROOT
+  const expectedOwnerUid = options.expectedSpoolOwnerUid ?? 0
+  const directory = fs.openSync(spoolRoot, fs.constants.O_RDONLY | fs.constants.O_DIRECTORY | fs.constants.O_NOFOLLOW)
+  const openedRoot = fs.fstatSync(directory)
+  const assertRootIdentity = () => {
+    const namedRoot = fs.lstatSync(spoolRoot)
+    if (!openedRoot.isDirectory() || openedRoot.uid !== expectedOwnerUid || (openedRoot.mode & 0o777) !== 0o755
+      || !namedRoot.isDirectory() || namedRoot.isSymbolicLink() || namedRoot.uid !== expectedOwnerUid || (namedRoot.mode & 0o777) !== 0o755
+      || namedRoot.dev !== openedRoot.dev || namedRoot.ino !== openedRoot.ino) {
+      throw new Error(expectedOwnerUid === 0 ? "event spool root must be root-owned and mode 0755" : "event spool root is unsafe")
+    }
+  }
+  try {
+    assertRootIdentity()
+    return { spoolRoot, expectedOwnerUid, directory, anchoredRoot: process.platform === "linux" ? `/proc/self/fd/${directory}` : spoolRoot, assertRootIdentity }
+  } catch (error) {
+    fs.closeSync(directory)
+    throw error
+  }
+}
+
+function writeOwner(ownerPath, owner) {
+  fs.writeFileSync(ownerPath, `${JSON.stringify(owner)}\n`, { mode: 0o600, flag: "wx" })
+  const file = fs.openSync(ownerPath, "r")
+  try { fs.fsyncSync(file) } finally { fs.closeSync(file) }
+}
+
+function withProducerLock(context, operation) {
+  const lockPath = path.join(context.anchoredRoot, ".producer.lock")
+  const ownerPath = path.join(lockPath, "owner.json")
+  const token = randomBytes(32).toString("hex")
+  const cleanup = (target, verifyToken) => {
+    if (verifyToken) {
+      let owner
+      try { owner = JSON.parse(fs.readFileSync(path.join(target, "owner.json"), "utf8")) } catch { return }
+      if (owner.token !== token) return
+    }
+    for (const name of ["event.tmp", "owner.json"]) {
+      try { fs.unlinkSync(path.join(target, name)) } catch (error) { if (error?.code !== "ENOENT") throw error }
+    }
+    fs.rmdirSync(target)
+  }
+  const deadline = Date.now() + 30_000
+  while (true) {
+    try {
+      fs.mkdirSync(lockPath, { mode: 0o700 })
+      writeOwner(ownerPath, { token, pid: process.pid, processStart: currentProcessStart, leaseUntil: new Date(Date.now() + 30_000).toISOString() })
+      break
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error
+      let owner = null
+      try { owner = JSON.parse(fs.readFileSync(ownerPath, "utf8")) } catch { /* incomplete owner */ }
+      if (ownerIsLive(owner)) {
+        if (Date.now() >= deadline) throw new Error("event transition publication is busy")
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10)
+        continue
+      }
+      let leaseActive
+      if (owner && canonicalIso(owner.leaseUntil)) {
+        leaseActive = Date.parse(owner.leaseUntil) > Date.now()
+      } else {
+        try {
+          leaseActive = Date.now() - fs.statSync(lockPath).mtimeMs <= 30_000
+        } catch (statError) {
+          if (statError?.code === "ENOENT") {
+            try {
+              fs.lstatSync(lockPath)
+            } catch (lstatError) {
+              if (lstatError?.code === "ENOENT") continue
+              throw lstatError
+            }
+            throw new Error("event transition publication lock is unsafe")
+          }
+          throw statError
+        }
+      }
+      if (leaseActive) {
+        if (Date.now() >= deadline) throw new Error("event transition publication is busy")
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10)
+        continue
+      }
+      const stalePath = `${lockPath}.stale-${token}`
+      try { fs.renameSync(lockPath, stalePath) } catch { continue }
+      cleanup(stalePath, false)
+    }
+  }
+  try { return operation(lockPath) } finally { cleanup(lockPath, true) }
+}
+
+function parseStoredEnvelope(raw, fileName) {
+  if (Buffer.byteLength(raw) > MAX_BYTES) throw new Error("event envelope must be bounded")
+  const envelope = JSON.parse(raw)
+  validateEnvelope(envelope)
+  const expectedName = `${createHash("sha256").update(`${envelope.source}\0${envelope.incidentKey}\0${envelope.transitionId}`).digest("hex")}.json`
+  if (fileName !== expectedName) throw new Error("event envelope filename is invalid")
+  return envelope
+}
+
+function readSafeEnvelope(context, fileName, directoryEntry) {
+  const filePath = path.join(context.anchoredRoot, fileName)
+  const before = fs.lstatSync(filePath)
+  if ((directoryEntry && !directoryEntry.isFile()) || before.isSymbolicLink() || !before.isFile() || before.uid !== context.expectedOwnerUid
+    || before.nlink !== 1 || (before.mode & 0o777) !== 0o444 || before.size < 2 || before.size > MAX_BYTES) throw new Error("existing event spool file is unsafe")
+  const file = fs.openSync(filePath, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW)
+  try {
+    const opened = fs.fstatSync(file)
+    if (!opened.isFile() || opened.dev !== before.dev || opened.ino !== before.ino || opened.size !== before.size || opened.uid !== context.expectedOwnerUid
+      || opened.nlink !== 1 || (opened.mode & 0o777) !== 0o444) throw new Error("existing event spool file changed")
+    return parseStoredEnvelope(fs.readFileSync(file, "utf8"), fileName)
+  } finally { fs.closeSync(file) }
+}
+
+function maintainUnderLock(context, options) {
+  const now = new Date(options.now?.() ?? new Date()).getTime()
+  const graceMs = options.graceMs ?? DEFAULT_EXPIRY_GRACE_MS
+  if (!Number.isSafeInteger(graceMs) || graceMs < 0) throw new Error("event spool expiry grace is invalid")
+  let pruned = 0
+  let preserved = 0
+  for (const entry of fs.readdirSync(context.anchoredRoot, { withFileTypes: true })) {
+    if (!entry.name.endsWith(".json")) continue
+    const filePath = path.join(context.anchoredRoot, entry.name)
+    try {
+      const envelope = readSafeEnvelope(context, entry.name, entry)
+      if (Date.parse(envelope.expiresAt) + graceMs >= now) { preserved += 1; continue }
+      fs.unlinkSync(filePath)
+      pruned += 1
+    } catch {
+      preserved += 1
+    }
+  }
+  if (pruned > 0) fs.fsyncSync(context.directory)
+  return { pruned, preserved }
+}
+
+export function maintainSpool(options = {}) {
+  const context = openSpool(options)
+  try { return withProducerLock(context, () => maintainUnderLock(context, options)) } finally { fs.closeSync(context.directory) }
+}
+
+export function emitEvent(input, options = {}) {
+  const context = openSpool(options)
+  try {
+    const { envelope, serialized } = buildEnvelope(input, options.now ?? (() => new Date()), options.nonce ?? (() => randomBytes(32).toString("hex")))
+    const digest = createHash("sha256").update(`${envelope.source}\0${envelope.incidentKey}\0${envelope.transitionId}`).digest("hex")
+    const fileName = `${digest}.json`
+    const filePath = path.join(context.spoolRoot, fileName)
+    return withProducerLock(context, (lockPath) => {
+      maintainUnderLock(context, options)
+      let existing = null
+      try {
+        existing = readSafeEnvelope(context, fileName)
+      } catch (error) { if (error?.code !== "ENOENT") throw error }
+      if (existing) {
+        if (JSON.stringify(stableInput(existing)) !== JSON.stringify(stableInput(envelope))) throw new Error("transition already exists with different content")
+        return { filePath, created: false }
+      }
+      const maxSpoolFiles = options.maxSpoolFiles ?? MAX_SPOOL_FILES
+      if (!Number.isSafeInteger(maxSpoolFiles) || maxSpoolFiles < 1) throw new Error("event spool capacity is invalid")
+      const currentFiles = fs.readdirSync(context.anchoredRoot, { withFileTypes: true }).filter((entry) => entry.isFile() && entry.name.endsWith(".json")).length
+      if (currentFiles >= maxSpoolFiles) throw new Error("event spool capacity is exhausted; unexpired and unsafe artifacts were preserved")
+      const temporary = path.join(lockPath, "event.tmp")
+      fs.writeFileSync(temporary, serialized, { encoding: "utf8", mode: 0o600, flag: "wx" })
+      const file = fs.openSync(temporary, "r")
+      try { fs.fsyncSync(file) } finally { fs.closeSync(file) }
+      fs.chmodSync(temporary, 0o444)
+      context.assertRootIdentity()
+      fs.renameSync(temporary, path.join(context.anchoredRoot, fileName))
+      fs.fsyncSync(context.directory)
+      context.assertRootIdentity()
+      return { filePath, created: true }
+    })
+  } finally { fs.closeSync(context.directory) }
+}
+
+function parseArgs(argv) {
+  const input = { schemaVersion: 1, critical: true, evidence: [] }
+  const names = new Map([
+    ["--agent", "agent"], ["--source", "source"], ["--event-type", "eventType"], ["--incident-key", "incidentKey"],
+    ["--transition-id", "transitionId"], ["--revision", "observationRevision"], ["--action", "action"],
+    ["--action-receipt", "actionReceipt"], ["--summary", "summary"],
+    ["--protective-state-digest", "protectiveStateDigest"], ["--protective-state-observed-at", "protectiveStateObservedAt"],
+  ])
+  for (let index = 0; index < argv.length; index += 2) {
+    const flag = argv[index]
+    const value = argv[index + 1]
+    if (flag === "--evidence" && value !== undefined) input.evidence.push(value)
+    else if (flag === "--protective-state-verified" && (value === "true" || value === "false")) input.protectiveStateVerified = value === "true"
+    else if (names.has(flag) && value !== undefined) input[names.get(flag)] = value
+    else throw new Error("event producer arguments are invalid")
+  }
+  return input
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    if (process.argv.length === 3 && process.argv[2] === "--maintain") {
+      const result = maintainSpool()
+      process.stdout.write(`maintained pruned=${result.pruned} preserved=${result.preserved}\n`)
+    } else {
+      const result = emitEvent(parseArgs(process.argv.slice(2)))
+      process.stdout.write(`${result.created ? "created" : "existing"} ${path.basename(result.filePath)}\n`)
+    }
+  } catch (error) {
+    process.stderr.write(`ouro event producer failed: ${error instanceof Error ? error.message : "unknown error"}\n`)
+    process.exitCode = 1
+  }
+}

package/deploy/unraid/ouro-events/emit-usenet-event.sh

@@ -0,0 +1,54 @@
+#!/bin/bash
+set -euo pipefail
+
+PRODUCER="/boot/config/custom/ouro-events/emit-event.mjs"
+
+if [ "$#" -eq 2 ] && [ "$1" = "--self-test" ]; then
+  exec "$(command -v node)" "$2" --maintain
+fi
+
+if [ "$#" -ne 9 ]; then
+  echo "usage: emit-usenet-event.sh <action> <incident> <transition> <receipt> <summary> <evidence> <verified> <verification-digest> <observed-at>" >&2
+  exit 2
+fi
+
+ACTION="$1"
+INCIDENT="$2"
+TRANSITION="$3"
+RECEIPT="$4"
+SUMMARY="$5"
+EVIDENCE="$6"
+VERIFIED="$7"
+VERIFICATION_DIGEST="$8"
+VERIFIED_AT="$9"
+EVENT_TYPE="usenet.protective_action"
+
+case "$ACTION" in
+  sabnzbd.pause) ;;
+  usenet.observe) EVENT_TYPE="usenet.health_observation" ;;
+  *) echo "usenet event adapter: action is not allowlisted" >&2; exit 2 ;;
+esac
+case "$VERIFIED" in true|false) ;; *) echo "usenet event adapter: verification state is invalid" >&2; exit 2 ;; esac
+[[ "$VERIFICATION_DIGEST" =~ ^[a-f0-9]{64}$ ]] || { echo "usenet event adapter: verification digest is invalid" >&2; exit 2; }
+
+if [ "$ACTION" = "usenet.observe" ]; then
+  OBSERVED_STATE="${TRANSITION%%:*}"
+  REVISION="$(printf '%s\0%s\0%s' "$ACTION" "$INCIDENT" "$OBSERVED_STATE" | sha256sum | cut -d' ' -f1)"
+else
+  REVISION="$(printf '%s\0%s\0%s\0%s' "$ACTION" "$INCIDENT" "$TRANSITION" "$RECEIPT" | sha256sum | cut -d' ' -f1)"
+fi
+
+exec /usr/local/bin/node "$PRODUCER" \
+  "--agent" "sanctuary" \
+  "--source" "sanctuary-usenet" \
+  "--event-type" "$EVENT_TYPE" \
+  "--incident-key" "$INCIDENT" \
+  "--transition-id" "$TRANSITION" \
+  "--revision" "$REVISION" \
+  "--action" "$ACTION" \
+  "--action-receipt" "$RECEIPT" \
+  "--summary" "$SUMMARY" \
+  "--evidence" "$EVIDENCE" \
+  "--protective-state-verified" "$VERIFIED" \
+  "--protective-state-digest" "$VERIFICATION_DIGEST" \
+  "--protective-state-observed-at" "$VERIFIED_AT"