artifacty 0.11.1 → 0.13.0

package/src/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { readFile } from "node:fs/promises";
 import path from "node:path";
+import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { generateToken } from "./lib/token.js";
 import { parseSseFrames } from "./lib/sse.js";
@@ -32,6 +33,27 @@ async function main() {
     return;
   }
 
+  // Recovery must work before loading storage or triggering a schema migration.
+  if (command === "backups") {
+    const { listUpgradeBackups, verifyUpgradeBackup, restoreUpgradeBackup } = await import("./lib/upgrade-backup.js");
+    const store = { home: path.resolve(options.home || process.env.ARTIFACTY_HOME || path.join(homedir(), ".artifacty")) };
+    const [action, id, ...extra] = options._;
+    if (extra.length || !["list", "verify", "restore"].includes(action) || (action === "list" ? Boolean(id) : !id)) {
+      throw new Error("Usage: artifacty backups list | verify <id> | restore <id> --confirm restore-store");
+    }
+    if (action === "list") {
+      printJson({ backups: listUpgradeBackups(store) });
+    } else if (action === "verify") {
+      printJson(verifyUpgradeBackup(store, id));
+    } else {
+      if (options.confirm !== "restore-store") {
+        throw new Error("Store recovery requires --confirm restore-store. Stop all server and MCP processes before restoring.");
+      }
+      printJson(restoreUpgradeBackup(store, id, { confirm: options.confirm }));
+    }
+    return;
+  }
+
   const {
     addComment,
     addRelation,
@@ -71,6 +93,16 @@ async function main() {
   const { startServer } = await import("./server.js");
   const store = createStore({ home: options.home });
 
+  if (command === "samples") {
+    const { installSamples, removeSamples } = await import("./lib/samples.js");
+    const action = options._[0];
+    if (action !== "install" && action !== "remove") {
+      throw new Error("Usage: artifacty samples install|remove");
+    }
+    printJson(await (action === "install" ? installSamples : removeSamples)(store, { audit: cliAuditContext() }));
+    return;
+  }
+
   if (command === "serve") {
     if (options.detach && options.foreground) {
       throw new Error("Use either --foreground or --detach, not both");
@@ -699,7 +731,12 @@ async function runWatchCommand(store, options) {
   for (;;) {
     const matched = await watchOnce({ baseUrl, token, filter, lastEventId, options });
     if (matched.stop) {
-      return;
+      // --once has delivered its event and run any --exec command, so the
+      // command is complete. Flush and exit rather than waiting for every
+      // handle to close on its own: a socket the runtime keeps pooled would
+      // otherwise leave the process running with nothing left to do.
+      await flushStdio();
+      process.exit(0);
     }
     if (matched.lastEventId) {
       lastEventId = matched.lastEventId;
@@ -721,9 +758,13 @@ async function watchOnce({ baseUrl, token, filter, lastEventId, options }) {
     headers["last-event-id"] = String(lastEventId);
   }
 
+  // An SSE response is a long-lived socket. Cancelling the reader alone left
+  // it in the connection pool on some platforms, so `watch --once` could
+  // finish its work and still not exit; abort the request instead.
+  const controller = new AbortController();
   let response;
   try {
-    response = await fetch(url, { headers });
+    response = await fetch(url, { headers, signal: controller.signal });
   } catch (error) {
     process.stderr.write(`artifacty watch: connection failed: ${error.message}\n`);
     return {};
@@ -766,7 +807,12 @@ async function watchOnce({ baseUrl, token, filter, lastEventId, options }) {
         const event = JSON.parse(parsed.data);
         await emitWatchEvent(event, options);
         if (options.once) {
-          await reader.cancel().catch(() => {});
+          // Abort first and do not await the cancel: cancelling a live SSE
+          // body can sit unresolved while the server is still writing, which
+          // left `watch --once` hanging after it had already printed its
+          // event. Aborting the request tears the socket down directly.
+          controller.abort();
+          reader.cancel().catch(() => {});
           return { stop: true };
         }
       }
@@ -777,6 +823,22 @@ async function watchOnce({ baseUrl, token, filter, lastEventId, options }) {
   return { lastEventId: seenLastEventId };
 }
 
+// Resolves once buffered stdout/stderr have drained, so an explicit exit
+// cannot truncate output that a caller is reading from a pipe. Bounded so a
+// stuck pipe delays the exit rather than preventing it.
+function flushStdio(timeoutMs = 1000) {
+  return Promise.race([
+    Promise.all([
+      new Promise((resolve) => process.stdout.write("", resolve)),
+      new Promise((resolve) => process.stderr.write("", resolve))
+    ]),
+    new Promise((resolve) => {
+      const timer = setTimeout(resolve, timeoutMs);
+      timer.unref?.();
+    })
+  ]);
+}
+
 function printWatchReady(options) {
   if (options.json) {
     process.stderr.write(`${JSON.stringify({ ready: true })}\n`);
@@ -930,6 +992,7 @@ Usage:
   artifacty install claude|codex|gemini|copilot|cursor|all [--dry-run] [--config <path>] [--server-path <path>] [--url http://127.0.0.1:8787] [--mcp-url http://127.0.0.1:8787/mcp] [--api-token token] [--transport local|bridge] [--timeout 30000]
   artifacty check [--server-path <path>] [--timeout 5000]
   artifacty update <id> (--file <path> | --content <text>) [--title <title>] [--format html|markdown|text|json|code|svg|mermaid|react|notebook] [--expected-version N] [--visibility private|team]
+  artifacty samples install|remove
   artifacty archive <id>
   artifacty restore <id>
   artifacty visibility <id> private|team
@@ -941,6 +1004,9 @@ Usage:
   artifacty retention run [--dry-run] [--allow-purge]
   artifacty export --file <path> [--full]
   artifacty backup [--file <path>] [--full]
+  artifacty backups list [--home <path>]
+  artifacty backups verify <id> [--home <path>]
+  artifacty backups restore <id> --confirm restore-store [--home <path>]
   artifacty import-store --file <path> [--confirm replace-all] [--force-users]
   artifacty users import --file <path.csv> [--no-password-reset]
   artifacty service plist|unit|task|install|uninstall [--platform macos|linux|windows] [--dry-run] [--path <path>] [--mcp-http]
@@ -959,8 +1025,17 @@ Usage:
   artifacty diff <id> [--from N] [--to M] [--structured] [--json]
   artifacty watch [--tag tag] [--artifact <id>] [--type artifact.updated] [--json] [--once] [--exec "<cmd>"]
 
+Upgrade recovery:
+  Existing stores receive a mandatory snapshot before a schema migration.
+  Set ARTIFACTY_BACKUP_ON_UPDATE=true to also snapshot before app-version changes.
+  backups list and verify do not migrate the store.
+  Stop all server and MCP processes before backups restore. Restore preserves a recovery snapshot.
+  artifacty restore <id> restores an archived artifact, not a store backup.
+
 Environment:
   ARTIFACTY_HOME           Storage directory. Defaults to ~/.artifacty
+  ARTIFACTY_BACKUP_ON_UPDATE  Set true for optional app-version snapshots; schema backups are mandatory
+  ARTIFACTY_UPGRADE_BACKUP_KEEP  Automatic snapshots to retain after a successful upgrade (default: 3)
   ARTIFACTY_URL            Public URL override. Otherwise CLI/MCP read the last running server URL
   ARTIFACTY_HOST           Bind host for the HTTP server. Defaults to 127.0.0.1
   ARTIFACTY_PORT           Bind port for the HTTP server. Defaults to 8787

package/src/lib/backup.js

@@ -172,21 +172,21 @@ export async function importStoreBundle(store = createStore(), bundle, { confirm
     // artifact's comments/relations/embeddings (foreign keys, ON DELETE
     // CASCADE) — but an artifacts-scope bundle never carries or restores
     // those tables. Silently wiping a target store's comment/relation
-    // history because someone ran an artifacts-only restore would be a
+    // history or sharing grants because someone ran an artifacts-only restore would be a
     // surprising, unrecoverable data loss, so refuse unless the caller
     // explicitly opts in the same way a full-scope restore does.
     const dependents = countArtifactDependents(store);
-    if (dependents.comments > 0 || dependents.relations > 0) {
+    if (dependents.comments > 0 || dependents.relations > 0 || dependents.shares > 0) {
       if (confirm !== "replace-all") {
         throw Object.assign(
           new Error(
-            'Target store has comments and/or relations that this artifacts-scope restore would delete without restoring equivalents. Pass confirm: "replace-all" to proceed anyway, or use a full-scope backup.'
+            'Target store has comments, relations, and/or sharing grants that this artifacts-scope restore would delete without restoring equivalents. Pass confirm: "replace-all" to proceed anyway, or use a full-scope backup.'
           ),
           { statusCode: 409, code: "dependents_exist" }
         );
       }
       warnings.push(
-        `Target store's ${dependents.comments} comment(s) and ${dependents.relations} relation(s) were deleted by this artifacts-scope restore and are not restored (only a full-scope backup carries them).`
+        `Target store's ${dependents.comments} comment(s) and ${dependents.relations} relation(s), and ${dependents.shares} sharing grant(s) were deleted by this artifacts-scope restore and are not restored (only a full-scope backup carries them).`
       );
     }
   }
@@ -238,7 +238,8 @@ function countArtifactDependents(store) {
   try {
     return {
       comments: db.prepare("SELECT COUNT(*) AS count FROM artifact_comments").get().count,
-      relations: db.prepare("SELECT COUNT(*) AS count FROM artifact_relations").get().count
+      relations: db.prepare("SELECT COUNT(*) AS count FROM artifact_relations").get().count,
+      shares: db.prepare("SELECT COUNT(*) AS count FROM artifact_shares").get().count
     };
   } finally {
     db.close();
@@ -254,7 +255,11 @@ const FULL_BACKUP_TABLE_ARRAY_KEYS = [
   "comments",
   "savedViews",
   "embeddings",
-  "meta"
+  "meta",
+  "teams",
+  "teamMembers",
+  "artifactShares",
+  "notifications"
 ];
 
 // Partial, fail-fast validation of a full-scope backup's `full` object,
@@ -289,6 +294,14 @@ function assertValidFullBackupTables(full) {
       });
     }
   }
+  for (const row of full.artifactShares || []) {
+    if (row?.permission !== undefined && !["read", "comment", "edit"].includes(row.permission)) {
+      throw Object.assign(new Error("Invalid Artifacty backup: sharing permission must be read, comment, or edit"), {
+        statusCode: 400,
+        code: "INVALID_BACKUP"
+      });
+    }
+  }
   for (const row of full.apiTokens || []) {
     if (!row || typeof row !== "object" || !String(row.id || "").trim() || !String(row.userId || "").trim()) {
       throw Object.assign(new Error("Invalid Artifacty backup: each `full.apiTokens` entry needs an id and userId"), {

package/src/lib/doctor.js

@@ -9,7 +9,7 @@ import { securityConfig, validateServerExposure, exposureWarning } from "./secur
 import { serviceCommand } from "./service.js";
 import { checkStoreIntegrity, createStore } from "./storage.js";
 
-const MIN_NODE_VERSION = "22.5.0";
+const MIN_NODE_VERSION = "22.12.0";
 
 export async function runDoctor(options = {}) {
   const packageRoot = path.resolve(options.packageRoot || process.cwd());

package/src/lib/i18n.js

@@ -3,6 +3,77 @@ export const SUPPORTED_LOCALES = ["en", "ko"];
 
 const TRANSLATIONS = {
   en: {
+    "sharing.staticPreview": "Static preview; scripts and external resources are disabled.",
+    "sharing.safeSource": "Source preview: active content is disabled for public share links.",
+    "sharing.networkCondition": "All permissions also require an allowed connection IP",
+    "sharing.unrestricted": "Any IP",
+    "access.preview": "Preview mode change",
+    "access.previewCount": "Mode: {mode}. {count} artifacts will be readable without signing in.",
+    "access.pendingNetwork": "Confirm network access",
+    "access.pendingHelp": "This network change is temporary. Confirm by {expiresAt}, or the previous policy will be restored automatically.",
+    "access.confirm": "Confirm access works",
+    "access.rollback": "Restore previous policy",
+    "access.samples": "Sample manuals",
+    "access.samplesHelp": "Install or remove the bundled sample artifacts.",
+    "access.samples.install": "Install samples",
+    "access.samples.remove": "Remove samples",
+    "sharing.links": "Share links",
+    "sharing.enablePrivate": "Allow share links in private mode",
+    "sharing.effective": "Effective access",
+    "sharing.anonymous": "Anonymous access",
+    "sharing.allowed": "Allowed",
+    "sharing.denied": "Denied",
+    "sharing.permission": "Permission",
+    "sharing.reason": "Reason",
+    "sharing.permission.none": "No access",
+    "sharing.permission.read": "Read",
+    "sharing.permission.comment": "Comment",
+    "sharing.permission.edit": "Edit",
+    "sharing.permission.owner": "Owner",
+    "sharing.permission.admin": "Administrator",
+    "sharing.linksHelp": "Anyone with a valid link can read its artifact until the link expires or is revoked.",
+    "sharing.copyNow": "Copy this link now; its token will not be shown again.",
+    "sharing.version": "Version",
+    "sharing.latest": "Latest version",
+    "sharing.days": "Expires in days",
+    "sharing.createLink": "Create share link",
+    "sharing.expires": "Expires",
+    "sharing.revoked": "Revoked",
+    "sharing.revoke": "Revoke link",
+    "sharing.readOnly": "Shared artifact · Read only",
+    "inbox.title": "Inbox",
+    "inbox.unread": "{count} unread notifications",
+    "inbox.readAll": "Mark all as read",
+    "inbox.read": "Read",
+    "inbox.markRead": "Mark as read",
+    "inbox.empty": "No notifications.",
+
+    "access.network": "Network access",
+    "access.networkHelp": "Applies in both modes. Enter one IPv4 or IPv6 address or CIDR per line. Leave blank to allow all addresses. Uses the direct connection IP, not forwarded headers. The list must include your current address.",
+    "access.currentIp": "Your connection IP",
+    "access.allowedCidrs": "Allowed addresses and CIDRs",
+    "access.saveNetwork": "Save network access",
+
+    "access.title": "Access",
+    "access.mode": "Dashboard access",
+    "access.public": "Public",
+    "access.private": "Private",
+    "access.publicHelp": "Public mode lets anyone view team-visible artifacts without signing in. Private artifacts remain restricted.",
+    "access.privateHelp": "Private mode requires sign-in. Only the owner, administrators, and explicitly allowed users or team members can read an artifact.",
+    "access.save": "Save access settings",
+    "access.teams": "Teams",
+    "access.teamName": "Team name",
+    "access.createTeam": "Create team",
+    "access.members": "Members",
+    "access.saveMembers": "Save members",
+    "access.noUsers": "No users available.",
+    "access.noTeams": "No teams yet.",
+    "sharing.title": "Sharing",
+    "sharing.help": "Choose read, comment, or edit access for each user and team. The strongest user or team grant applies. The owner and administrators always retain access and control sharing. Grants restrict private mode; public team visibility may provide broader access.",
+    "sharing.users": "Allowed users",
+    "sharing.teams": "Allowed teams",
+    "sharing.save": "Save sharing",
+
     "nav.new": "New",
     "nav.import": "Import",
     "nav.api": "API",
@@ -207,6 +278,77 @@ const TRANSLATIONS = {
     "views.namePlaceholder": "View name"
   },
   ko: {
+    "sharing.staticPreview": "정적 미리보기: 스크립트와 외부 리소스는 비활성화됩니다.",
+    "sharing.safeSource": "소스 미리보기: 공개 공유 링크에서는 실행 가능한 콘텐츠를 비활성화합니다.",
+    "sharing.networkCondition": "모든 권한은 허용된 IP에서 접속해야 사용할 수 있습니다",
+    "sharing.unrestricted": "모든 IP",
+    "access.preview": "모드 변경 미리보기",
+    "access.previewCount": "모드: {mode}. 로그인 없이 볼 수 있는 아티팩트는 {count}개입니다.",
+    "access.pendingNetwork": "네트워크 접근 확인",
+    "access.pendingHelp": "임시로 적용된 네트워크 설정입니다. {expiresAt}까지 확인하지 않으면 이전 설정으로 자동 복구됩니다.",
+    "access.confirm": "접속 확인 및 확정",
+    "access.rollback": "이전 설정 복구",
+    "access.samples": "샘플 매뉴얼",
+    "access.samplesHelp": "번들로 제공되는 샘플 아티팩트를 설치하거나 제거합니다.",
+    "access.samples.install": "샘플 설치",
+    "access.samples.remove": "샘플 제거",
+    "sharing.links": "공유 링크",
+    "sharing.enablePrivate": "프라이빗 모드에서 공유 링크 허용",
+    "sharing.effective": "실제 접근 권한",
+    "sharing.anonymous": "익명 접근",
+    "sharing.allowed": "허용",
+    "sharing.denied": "차단",
+    "sharing.permission": "권한",
+    "sharing.reason": "이유",
+    "sharing.permission.none": "접근 불가",
+    "sharing.permission.read": "읽기",
+    "sharing.permission.comment": "댓글",
+    "sharing.permission.edit": "편집",
+    "sharing.permission.owner": "소유자",
+    "sharing.permission.admin": "관리자",
+    "sharing.linksHelp": "유효한 링크를 가진 사람은 만료되거나 폐기될 때까지 아티팩트를 읽을 수 있습니다.",
+    "sharing.copyNow": "지금 링크를 복사하세요. 토큰은 다시 표시되지 않습니다.",
+    "sharing.version": "버전",
+    "sharing.latest": "최신 버전",
+    "sharing.days": "만료까지 일수",
+    "sharing.createLink": "공유 링크 만들기",
+    "sharing.expires": "만료",
+    "sharing.revoked": "폐기됨",
+    "sharing.revoke": "링크 폐기",
+    "sharing.readOnly": "공유 아티팩트 · 읽기 전용",
+    "inbox.title": "알림함",
+    "inbox.unread": "읽지 않은 알림 {count}개",
+    "inbox.readAll": "모두 읽음 처리",
+    "inbox.read": "읽음",
+    "inbox.markRead": "읽음 처리",
+    "inbox.empty": "알림이 없습니다.",
+
+    "access.network": "네트워크 접근",
+    "access.networkHelp": "두 모드 모두에 적용됩니다. IPv4 또는 IPv6 주소나 CIDR을 한 줄에 하나씩 입력하세요. 비워두면 모든 주소를 허용합니다. 전달 헤더 대신 직접 연결된 IP를 사용합니다. 현재 접속 주소를 반드시 포함해야 합니다.",
+    "access.currentIp": "현재 접속 IP",
+    "access.allowedCidrs": "허용할 주소 및 CIDR",
+    "access.saveNetwork": "네트워크 접근 저장",
+
+    "access.title": "접근 관리",
+    "access.mode": "대시보드 접근 모드",
+    "access.public": "퍼블릭",
+    "access.private": "프라이빗",
+    "access.publicHelp": "퍼블릭 모드에서는 로그인 없이 팀 공개 아티팩트를 볼 수 있습니다. 비공개 아티팩트는 계속 제한됩니다.",
+    "access.privateHelp": "프라이빗 모드에서는 로그인이 필요합니다. 소유자, 관리자, 명시적으로 허용된 사용자 또는 팀 구성원만 아티팩트를 읽을 수 있습니다.",
+    "access.save": "접근 설정 저장",
+    "access.teams": "팀",
+    "access.teamName": "팀 이름",
+    "access.createTeam": "팀 만들기",
+    "access.members": "구성원",
+    "access.saveMembers": "구성원 저장",
+    "access.noUsers": "사용자가 없습니다.",
+    "access.noTeams": "아직 팀이 없습니다.",
+    "sharing.title": "공유 관리",
+    "sharing.help": "사용자와 팀마다 읽기, 댓글 또는 편집 권한을 선택하세요. 사용자와 소속 팀의 권한 중 가장 높은 권한이 적용됩니다. 소유자와 관리자는 항상 접근할 수 있으며 공유 설정을 관리합니다. 권한 제한은 프라이빗 모드에 적용되며 퍼블릭 팀 공개 설정은 더 넓은 접근을 허용할 수 있습니다.",
+    "sharing.users": "허용된 사용자",
+    "sharing.teams": "허용된 팀",
+    "sharing.save": "공유 설정 저장",
+
     "nav.new": "새로 만들기",
     "nav.import": "가져오기",
     "nav.api": "API",

package/src/lib/network-policy.js

@@ -0,0 +1,234 @@
+import { randomUUID } from "node:crypto";
+import { isIP } from "node:net";
+import { createStore, insertAuditRow, openDatabase, transaction } from "./storage.js";
+
+function policyError(message, code = "INVALID_NETWORK_POLICY", statusCode = 400) {
+  return Object.assign(new Error(message), { code, statusCode });
+}
+
+function parseAddress(address) {
+  if (typeof address !== "string" || address.includes("%")) return null;
+  const family = isIP(address);
+  if (!family) return null;
+  if (family === 4) {
+    return { bits: 32, value: address.split(".").reduce((value, byte) => (value << 8n) | BigInt(byte), 0n) };
+  }
+  let text = address.toLowerCase();
+  if (text.includes(".")) {
+    const separator = text.lastIndexOf(":");
+    const ipv4 = parseAddress(text.slice(separator + 1));
+    text = `${text.slice(0, separator)}:${(ipv4.value >> 16n).toString(16)}:${(ipv4.value & 65535n).toString(16)}`;
+  }
+  const halves = text.split("::");
+  const left = halves[0] ? halves[0].split(":") : [];
+  const right = halves[1] ? halves[1].split(":") : [];
+  const words = halves.length === 2 ? [...left, ...Array(8 - left.length - right.length).fill("0"), ...right] : left;
+  return { bits: 128, value: words.reduce((value, word) => (value << 16n) | BigInt(`0x${word}`), 0n) };
+}
+
+function formatAddress(value, bits) {
+  if (bits === 32) return [24n, 16n, 8n, 0n].map((shift) => Number((value >> shift) & 255n)).join(".");
+  const words = Array.from({ length: 8 }, (_, index) => ((value >> BigInt((7 - index) * 16)) & 65535n).toString(16));
+  let bestStart = -1;
+  let bestLength = 1;
+  for (let index = 0; index < words.length;) {
+    if (words[index] !== "0") { index++; continue; }
+    const start = index;
+    while (index < words.length && words[index] === "0") index++;
+    if (index - start > bestLength) { bestStart = start; bestLength = index - start; }
+  }
+  if (bestStart < 0) return words.join(":");
+  return `${words.slice(0, bestStart).join(":")}::${words.slice(bestStart + bestLength).join(":")}`;
+}
+
+function parseNetwork(entry) {
+  const parts = entry.split("/");
+  const address = parseAddress(parts[0]);
+  if (!address || parts.length > 2 || (parts.length === 2 && !/^\d+$/.test(parts[1]))) {
+    throw policyError(`Invalid IP address or CIDR: ${entry}`);
+  }
+  let { value, bits } = address;
+  let prefix = parts.length === 2 ? Number(parts[1]) : bits;
+  if (prefix > bits) throw policyError(`Invalid CIDR prefix: ${entry}`);
+  // Socket peers commonly use IPv4-mapped IPv6 addresses. Treat their
+  // IPv4-sized networks identically to ordinary IPv4 entries.
+  if (bits === 128 && value >> 32n === 65535n && prefix >= 96) {
+    bits = 32;
+    prefix -= 96;
+    value &= 0xffffffffn;
+  }
+  const shift = BigInt(bits - prefix);
+  value = (value >> shift) << shift;
+  return { value, bits, prefix, text: `${formatAddress(value, bits)}${parts.length === 2 ? `/${prefix}` : ""}` };
+}
+
+export function normalizeAllowedNetworks(input = []) {
+  if (typeof input !== "string" && !Array.isArray(input)) throw policyError("Allowed networks must be a list or text.");
+  const entries = typeof input === "string" ? input.split(/[,\r\n]+/) : input;
+  return [...new Set(entries.map((entry) => {
+    if (typeof entry !== "string") throw policyError("Each allowed network must be text.");
+    return entry.trim();
+  }).filter(Boolean).map((entry) => parseNetwork(entry).text))];
+}
+
+export function isAddressAllowed(address, allowedCidrs = []) {
+  const networks = normalizeAllowedNetworks(allowedCidrs);
+  if (!networks.length) return true;
+  const parsed = parseAddress(address);
+  if (!parsed) return false;
+  const candidates = [parsed];
+  if (parsed.bits === 128 && parsed.value >> 32n === 65535n) candidates.push({ bits: 32, value: parsed.value & 0xffffffffn });
+  return networks.some((entry) => {
+    const network = parseNetwork(entry);
+    const shift = BigInt(network.bits - network.prefix);
+    return candidates.some((candidate) => candidate.bits === network.bits && (candidate.value >> shift) === (network.value >> shift));
+  });
+}
+
+function readPolicy(db) {
+  const row = db.prepare("SELECT value FROM meta WHERE key = 'network_policy'").get();
+  if (!row) return { allowedCidrs: [] };
+  const policy = JSON.parse(row.value);
+  if (!policy || !Object.hasOwn(policy, "allowedCidrs")) throw policyError("Stored network policy is invalid.");
+  return { allowedCidrs: normalizeAllowedNetworks(policy.allowedCidrs) };
+}
+
+function readPending(db) {
+  const row = db.prepare("SELECT value FROM meta WHERE key = 'network_policy_pending'").get();
+  return row ? JSON.parse(row.value) : null;
+}
+
+function publicPending(pending) {
+  return pending ? { id: pending.id, expiresAt: pending.expiresAt, allowedCidrs: pending.allowedCidrs } : null;
+}
+
+function writePolicy(db, policy, action, audit, metadata = {}) {
+  db.prepare("INSERT OR REPLACE INTO meta (key, value) VALUES ('network_policy', ?)").run(JSON.stringify(policy));
+  insertAuditRow(db, { action, artifactId: "", audit, metadata: { ...metadata, policy } });
+}
+
+function recoverExpired(db, now = Date.now()) {
+  const pending = readPending(db);
+  if (!pending || Date.parse(pending.expiresAt) > Number(now)) return false;
+  writePolicy(db, pending.previousPolicy, "network-policy-auto-rollback", { actor: "system:network-policy", surface: "network-policy" }, { pendingId: pending.id });
+  db.prepare("DELETE FROM meta WHERE key = 'network_policy_pending'").run();
+  return true;
+}
+
+function requireAdmin(db, access) {
+  const user = access?.userId && db.prepare("SELECT role, active FROM users WHERE id = ?").get(access.userId);
+  if (access?.role !== "admin" || !user || user.role !== "admin" || !user.active) {
+    throw policyError("An active administrator account is required.", "FORBIDDEN", 403);
+  }
+}
+
+function validatePolicy(policy, remoteAddress) {
+  if (!policy || !Object.hasOwn(policy, "allowedCidrs")) throw policyError("Allowed networks are required.");
+  const normalized = { allowedCidrs: normalizeAllowedNetworks(policy.allowedCidrs) };
+  if (remoteAddress !== undefined && !isAddressAllowed(remoteAddress, normalized.allowedCidrs)) {
+    throw policyError("Allowed networks must include your current IP address.", "NETWORK_POLICY_LOCKOUT");
+  }
+  return normalized;
+}
+
+function requireNoPending(db) {
+  if (readPending(db)) throw policyError("Confirm or roll back the pending network change first.", "NETWORK_POLICY_PENDING", 409);
+}
+
+export function recoverExpiredNetworkPolicy(store = createStore(), { now = Date.now() } = {}) {
+  const db = openDatabase(store);
+  try { return transaction(db, () => recoverExpired(db, now)); }
+  finally { db.close(); }
+}
+
+export function getNetworkPolicy(store = createStore()) {
+  const db = openDatabase(store);
+  try {
+    return transaction(db, () => {
+      recoverExpired(db);
+      return readPolicy(db);
+    });
+  } finally { db.close(); }
+}
+
+export function getPendingNetworkPolicy(store = createStore()) {
+  const db = openDatabase(store);
+  try {
+    return transaction(db, () => {
+      recoverExpired(db);
+      return publicPending(readPending(db));
+    });
+  } finally { db.close(); }
+}
+
+export function setNetworkPolicy(store = createStore(), policy = {}, { access, audit = {}, remoteAddress } = {}) {
+  recoverExpiredNetworkPolicy(store);
+  const db = openDatabase(store);
+  try {
+    return transaction(db, () => {
+      requireAdmin(db, access);
+      requireNoPending(db);
+      const normalized = validatePolicy(policy, remoteAddress);
+      writePolicy(db, normalized, "network-policy-update", { ...audit, actor: audit.actor || access.userId });
+      return normalized;
+    });
+  } finally { db.close(); }
+}
+
+export function stageNetworkPolicy(store = createStore(), policy = {}, { access, audit = {}, remoteAddress, timeoutMs = 120000 } = {}) {
+  recoverExpiredNetworkPolicy(store);
+  const db = openDatabase(store);
+  try {
+    return transaction(db, () => {
+      requireAdmin(db, access);
+      requireNoPending(db);
+      if (!Number.isInteger(timeoutMs) || timeoutMs < 10000 || timeoutMs > 600000) {
+        throw policyError("Network confirmation timeout must be between 10 seconds and 10 minutes.");
+      }
+      if (!parseAddress(remoteAddress)) throw policyError("Your current IP address is required.");
+      const normalized = validatePolicy(policy, remoteAddress);
+      const pending = {
+        id: randomUUID(), expiresAt: new Date(Date.now() + timeoutMs).toISOString(),
+        allowedCidrs: normalized.allowedCidrs, previousPolicy: readPolicy(db)
+      };
+      db.prepare("INSERT INTO meta (key, value) VALUES ('network_policy_pending', ?)").run(JSON.stringify(pending));
+      writePolicy(db, normalized, "network-policy-stage", { ...audit, actor: audit.actor || access.userId }, { pendingId: pending.id, expiresAt: pending.expiresAt });
+      return publicPending(pending);
+    });
+  } finally { db.close(); }
+}
+
+function finishPending(store, id, { access, audit = {}, remoteAddress } = {}, confirm) {
+  // Commit expiry recovery independently so a subsequent stale-ID error cannot
+  // roll it back and leave a user locked out after the deadline.
+  recoverExpiredNetworkPolicy(store);
+  const db = openDatabase(store);
+  try {
+    return transaction(db, () => {
+      requireAdmin(db, access);
+      const pending = readPending(db);
+      if (!pending || pending.id !== id) throw policyError("Pending network change not found or expired.", "NETWORK_POLICY_NOT_PENDING", 409);
+      if (confirm && (!parseAddress(remoteAddress) || !isAddressAllowed(remoteAddress, pending.allowedCidrs))) {
+        throw policyError("Confirmation requires access from an allowed IP address.", "IP_NOT_ALLOWED", 403);
+      }
+      const policy = confirm ? { allowedCidrs: pending.allowedCidrs } : pending.previousPolicy;
+      writePolicy(db, policy, confirm ? "network-policy-confirm" : "network-policy-rollback", { ...audit, actor: audit.actor || access.userId }, { pendingId: pending.id });
+      db.prepare("DELETE FROM meta WHERE key = 'network_policy_pending'").run();
+      return policy;
+    });
+  } finally { db.close(); }
+}
+
+export function confirmNetworkPolicy(store = createStore(), id, options = {}) {
+  return finishPending(store, id, options, true);
+}
+
+export function rollbackNetworkPolicy(store = createStore(), id, options = {}) {
+  return finishPending(store, id, options, false);
+}
+
+export function assertNetworkAccess(store, remoteAddress) {
+  if (!isAddressAllowed(remoteAddress, getNetworkPolicy(store).allowedCidrs)) {
+    throw policyError("Access from this IP address is not allowed.", "IP_NOT_ALLOWED", 403);
+  }
+}