dodo-mcp 1.2.1 → 1.3.1

package/docs/adr/053-content-drift-and-private-git-recovery.md

@@ -0,0 +1,29 @@
+# ADR 053: content drift and independent Git recovery copies
+
+Status: implemented in the unreleased Recovery candidate (R03); platform evidence is recorded separately.
+
+The expected source state is a durable, per-workspace manifest plus committed journal updates. It is **not** the most recently captured checkpoint. Restart, owner checkpoint creation, periodic observations and emergency snapshots never silently adopt external bytes. Only a successfully verified journal transaction or an authenticated owner acknowledgement advances this state. Baseline snapshots remain retention-protected.
+
+Mutation targets are checked by content/type/mode/identity, irrespective of mtime or a freshly supplied expectedHash. Non-target changes do not block an unrelated simple edit. Before commands, Git commit hooks and verification recipes, a source scan blocks significant drift. Default significance is at least 20 changed source files **and more than 20%** of baseline file count, or at least 10 deleted source files. These are owner policy thresholds, not a malware classifier. Existing ACL, trust, approvals, sandbox and secret/path restrictions remain authoritative.
+
+A 60-second timer skips busy workspaces. Scans have a 15-second default wall budget (owner range 100–60000 ms), entry/file budgets, guarded reads and two content inventories. Watchers are not an authority or prerequisite. Missed events and equal size/mtime edits remain detectable; edits changed back between scans cannot be proven. Interrupted or over-budget scans never acknowledge the state. Jobs retain the project mutation ticket through their bounded post-exit observation. Shell results are attributed as **unknown**, because external programs may write concurrently.
+
+Emergency observations preserve the newly observed bytes separately from the original baseline. They are not known-good or verification results, and cannot recover pre-overwrite bytes that were never captured. Ordinary ignored files become tracked after a named journaled mutation; generated/data/secret exclusions still apply. Reviewed R02 restore plans have a private exemption from the drift-baseline comparison only; immutable plan/hash, caller, epoch, source scope, new before-image capture, expected hashes and journal verification still apply. This lets an owner restore externally changed files without first accepting them as normal work.
+
+## Git storage decision
+
+Git checkpoint refs live in **independent private bare repositories**, not in the working repository. Each source checkpoint at activation/session boundary, before exec, explicit owner checkpoint and successful fresh verification creates a parentless commit and create-only `refs/dodo/snapshots/<snapshot-id>`. Target-only file edits and emergency observations do not run Git. Verification-triggered copies are deduplicated by the owned verification receipt and must still match the verifier at publication; this is not a deployment approval or known-good promotion.
+
+The builder uses captured, hash-verified CAS bytes, an empty private index and plumbing commands. It never copies the working object database/history, user index, remotes, alternates, hooks, filters or configuration. Sanitized HEAD/branch/index fingerprint is evidence only. No checkout, reset, add, remote operation or credential helper runs. Missing Git/non-Git projects retain mandatory content backup; optional Git reports its limitation. Git-required projects fail closed when a required full copy cannot be created.
+
+Unborn and detached HEAD, parent repositories and worktree gitfiles use source-root scope. Submodule files already materialized in that scope are ordinary captured source; submodule Git history is not copied. LFS pointer bytes remain pointers; no LFS network fetch occurs. Git alone preserves executable bits, not all POSIX modes or empty directories; the separately stored source manifest remains the complete recovery contract.
+
+An owner can choose an existing, canonical, private, dedicated empty directory outside registered projects, DODO state and recognized credential namespaces. Subsequent contents must be registered recovery copies. Its filesystem identity is pinned. Missing/replaced volumes fail closed with **no fallback**, even if optional Git was otherwise selected. This is a bare storage backend, not a mirror of all repository history. Default copies use private installation recovery storage.
+
+Copy reservations and physical bytes count against the existing project/installation quotas. Contents/refs are checked before READY, then files and directories are synced; source-retention pruning also removes matching owned Git copies. Crash-interrupted copies remain non-READY and counted until safe retention cleanup. They are never automatically executed or treated as valid.
+
+## Owner review and limits
+
+Web/CLI scan results are bounded and paginated. Acknowledgement requires the exact observation digest, workspace/epoch, confirmation and live owner authority; it rechecks the content again under the mutation queue. MCP can inspect via `restore_status(scan:true)` but cannot acknowledge/configure. Full/Compact/Hybrid tool counts do not increase in R03.
+
+Deleting source files and `.git` inside the original registered root does not remove independent copies. The source restore restores approved files only and does not recreate Git metadata. Replacing/deleting the root directory itself still fails the root-identity contract: recover to a new directory manually from the independent copy, review it, then register that directory. Storage on the same device/account is not protection from device failure or a compromised owner account. Database/volume/destructive command side effects remain outside source recovery.

package/docs/adr/054-verified-source-checkpoints.md

@@ -0,0 +1,58 @@
+# ADR 054: Source verification evidence and owner checkpoint labels
+
+Status: implemented in the unreleased Recovery candidate; deployment/database recovery are separate work.
+
+`verify_changes` remains the only verification executor. Its existing scope,
+trust, approval, sandbox, job budget and idempotency gates remain authoritative.
+When Recovery is enabled for a registered project it captures a complete source
+checkpoint BEFORE launching the selected recipes, binds its manifest digest to
+the private verification record, and rechecks source before launch and at report.
+The independent before-exec copies are retained as well.
+
+The binding references workspace, caller and immutable snapshot. Evidence records
+contain selected recipe digests, actual job IDs/exits and recognized count scalars,
+parser version, timestamps and an allowlisted Node/platform/epoch description.
+They contain neither log contents nor raw environment variables. Jobs and their
+output are read through existing services; no endpoint accepts a caller-supplied
+pass result. The selected checks are the required set for that run, not every
+possible repository check. Missing recommended checks remain explicitly listed.
+
+Recovery compares its full included-source manifest (including previously tracked
+ignored targets) as well as the narrower assistance snapshot. Recipe, runtime,
+parser or observed source drift invalidates freshness, including an observed edit
+subsequently reverted. Truncated output, unknown/zero test counts, inconsistent
+counts and skipped tests cannot establish VERIFIED. Build/lint command success is
+only evidence for that selected command, not proof of unrun tests. Generated source
+requires a new snapshot and verification. Changes reverted BETWEEN observations,
+unmeasured dependencies/environment and deceptive repository test scripts remain
+outside the guarantee. This is not an OS sandbox or proof of program correctness.
+
+SAVED means independent bytes passed integrity checks at capture. VERIFIED,
+FAILED, INCONCLUSIVE and STALE describe bounded verification evidence. Lists are
+historical observations marked refresh-required; explicit inspection rechecks
+current source, recipes and jobs. Overview exposes only a historical timestamp,
+never a cross-caller verification ID. Recovery metadata does not display logs or
+private filesystem locations.
+
+Owner checkpoint names are a separate revisioned table. Updates use an exact
+expected revision under the project mutation queue and a SQLite transaction,
+rechecking owner authority after asynchronous integrity reads. Removing a name
+leaves a revision tombstone, preventing ABA overwrites. A durable event records
+both old and new targets with the audit entry. Names never alter manifest bytes,
+certify tests, grant permission or set PRODUCTION_KNOWN_GOOD. Production names are
+reserved; production evidence is NOT_CONFIGURED and database recovery NOT_SUPPORTED.
+
+Named targets and explicit pins retain their snapshots and associated session
+references. Retention preview and automatic pruning share one selection function;
+preview has no delete side effects. Byte estimates are logical, not a promise of
+immediate physical reclamation because objects can be shared and have a GC grace
+period. Reviewed plans, active/unresolved history and the latest baselines remain
+protected. No public purge/mark/pin tools are introduced.
+
+The owner web panel lives in a separate bundled module. It uses authenticated
+fetch, current project/epoch and the existing confirmation UI/CSP. Text-only DOM
+construction escapes names, paths, errors and diffs. Durable journal receipts are
+queried after reconnect; an uncertain restore is never repeated with a new key.
+Full catalog stays 148 and Compact 20; existing Recovery operations expose only
+caller-owned records under current ACLs. Private owner web and CLI share IPC
+validation for evidence, names, pins and retention preview.

package/docs/adr/055-reviewed-docker-deployments.md

@@ -0,0 +1,42 @@
+# ADR 055 — Reviewed Docker deployments and image recovery
+
+Status: accepted in unreleased working source; native platform release gates pending.
+
+A source checkpoint does not prove which image is running or that a database can
+be undone. Deployment is an opt-in owner-registered adapter, separate from
+source recovery, which remains enabled by default.
+
+The first adapter controls one explicitly named Docker Compose service/context.
+It builds a bounded tar stream from verified, policy-filtered CAS bytes and uses
+an immutable image ID. It never consumes repository Compose hooks. Source labels
+are metadata, not proof: declared source mappings are compared against actual
+image/container bytes, with archive traversal/link/mount exclusions. A stopped,
+network-disabled probe records its identity before creation and is never started.
+
+Every effect uses the shared invocation authority, project mutation queue,
+JobManager, sandbox and exec policy. A plan binds workspace/epoch, target revision,
+source manifest and required test evidence. Health checks have separately declared
+network permission, DNS pinning, redirect rejection and private/admin endpoint
+restrictions. Stabilization and a final container identity check precede a
+revisioned known-good pointer update. Image rollback uses a new reviewed plan,
+exact old image and fresh health; it never runs database migrations.
+
+Durable state precedes external effects. Restart converts in-flight records to
+UNKNOWN. Retries inspect the receipt rather than repeat commands. Owner-only
+maintenance previews re-observe exact state before acknowledgement or cleanup;
+acknowledging UNKNOWN is not a success/health assertion. The original unknown
+receipt remains available. Private owner review IDs/hashes and expiry protect
+maintenance; these controls are not MCP tools.
+
+Retention groups immutable IDs, protects current/previous known-good, active
+containers, unexpired plans, unresolved outcomes, owner pins and other target
+references. Cleanup is explicit, uses exact managed tags/IDs without force, and
+never prunes volumes. Interrupted cleanup is resolved by observation before a new
+review. Source manifests stay protected by deployment provenance independently
+of image retention. Each target admits at most 500 records; owner maintenance
+reviews are bounded at 2,000 per project.
+
+Limits: Docker access can affect resources beyond the workspace. Generic shell,
+external CI and owner terminal commands remain outside this adapter's deployment
+guards. Missing/compiled source is not reconstructed, unavailable manifests are
+not fabricated, and source recovery does not include database or secret data.

package/docs/adr/056-owner-data-recovery.md

@@ -0,0 +1,47 @@
+# ADR 056 — Owner-controlled database awareness and private config recovery
+
+Status: implemented in unreleased working source; platform/release gates remain independent.
+
+Source snapshots cannot reverse database transactions or safely include secrets.
+We keep both data classes outside source CAS/Git and outside MCP restore authority.
+
+`RecoveryDatabases` is a bounded read-only SQLite migration-table adapter. Owner
+registration pins the canonical file identity and policy. Explicit compatibility
+rules bind manifest hash and target revision. Only ordinary tables, bounded string
+IDs and strict identifiers are accepted; read connections use query-only and
+trusted-schema-off. No SQL, remote DB, mutation or generic rollback API exists.
+Source preview/apply checks the rule and rechecks after the pre-restore checkpoint;
+post-apply drift is reported without auto-undo. This is not a cross-process database
+lock or a proof of semantic compatibility. Missing information is UNKNOWN.
+
+`RecoveryConfigVault` registers existing private, source-denied project files.
+AES-256-GCM uses a fresh nonce and associated data binding version, project/root,
+backup, target/revision and key reference. Ciphertext goes into dedicated private
+SQLite tables; a random 256-bit key stays in the OS credential store. `OSRecoveryKeys`
+uses fixed helper protocols with stdin for secret input, bounded output, no shell,
+minimal environment and no plaintext fallback. Owner UI/CLI see redacted metadata,
+not decrypted bytes. No new public MCP tools, credential-export endpoint or
+permission bypass is introduced.
+
+Owner actions use shared per-project mutation queues, live owner leases and context.
+Restore previews bind expiry, epoch, target revision, authenticated ciphertext,
+original file identity and a keyed content digest. An encrypted pre-restore backup
+and UNKNOWN receipt commit before any write. A single existing file is rewritten in
+place to preserve its private metadata and avoid temporary plaintext copies. This
+is explicitly not crash-atomic; read-back certifies only completed writes. UNKNOWN
+never auto-replays; a separate owner review may restore the encrypted before-copy.
+The owner must stop/restart dependent services. Same-user external writers are not
+confined by DODO's mutation queue.
+
+Keys rotate by creating a new OS reference; old backups retain old keys. Key loss
+is unrecoverable through DODO. Retention is separate from source, bounded, and
+protects restore-referenced copies. Full metadata/receipt history is intentionally
+bounded instead of evicting uncertain recovery evidence. SQLite row deletion is
+logical retention, not guaranteed physical secure erasure of storage pages.
+
+Tests use real SQLite/files and authenticated private HTTP for permissions,
+compatibility drift, ciphertext tampering, missing/wrong keys, rotation, stale
+context, file conflicts and crash receipts. Protocol fixtures separately exercise
+all three OS-helper boundaries; actual credential-store tests opt in with
+`DODO_TEST_OS_RECOVERY_KEYS=1` and create/delete only a random fixture item.
+Fixtures do not substitute for live manual production recovery.

package/docs/adr/README.md

@@ -66,3 +66,10 @@ decisions; ADR-011+ resolve implementation ambiguities without reducing security
 - [048 — Persistent exclusive Local/Tunnel connection mode](048-persistent-connection-mode.md)
 - [049 — Owner-approved Android control through ADB](049-android-adb-control.md)
 - [050 — Cloudflare Local mode and visible per-project access](050-cloudflare-local-and-project-access.md)
+
+- [051 — Source Recovery foundation](051-source-recovery-foundation.md)
+- [052 — Reviewed source restore](052-reviewed-source-restore.md)
+- [053 — Content drift and private Git recovery](053-content-drift-and-private-git-recovery.md)
+- [054 — Verified source checkpoints](054-verified-source-checkpoints.md)
+- [055 — Reviewed Docker deployments](055-reviewed-docker-deployments.md)
+- [056 — Owner-controlled database awareness and private config recovery](056-owner-data-recovery.md)

package/native/private-state-windows.cs

@@ -0,0 +1,105 @@
+// Same admission policy as privateFs.ts, using inbox .NET ACL APIs directly.
+// Target and mode are environment DATA. No shell, arbitrary SID, elevation or
+// permission-result cache. Every invocation rereads owner, DACL and attributes.
+using System;
+using System.IO;
+using System.Security.AccessControl;
+using System.Security.Principal;
+
+class DodoPrivateState {
+  static readonly AccessControlSections Sections = AccessControlSections.Owner | AccessControlSections.Access;
+  static string stage = "input";
+  static void Require(bool ok) { if (!ok) throw new InvalidOperationException(); }
+  static FileSystemSecurity Read(string path, bool directory) {
+    return directory ? (FileSystemSecurity)Directory.GetAccessControl(path, Sections) : File.GetAccessControl(path, Sections);
+  }
+  static void Write(string path, bool directory, FileSystemSecurity acl) {
+    if (directory) Directory.SetAccessControl(path, (DirectorySecurity)acl);
+    else File.SetAccessControl(path, (FileSecurity)acl);
+  }
+  static void PrivateDacl(FileSystemSecurity acl, string sid) {
+    bool ownerAllowed = false;
+    foreach (FileSystemAccessRule rule in acl.GetAccessRules(true, true, typeof(SecurityIdentifier))) {
+      if (rule.AccessControlType != AccessControlType.Allow) continue;
+      string id = rule.IdentityReference.Value;
+      Require(id == sid || id == "S-1-5-18" || id == "S-1-5-32-544");
+      if (id == sid) ownerAllowed = true;
+    }
+    Require(ownerAllowed);
+  }
+  static bool CanonicalPrivateDirectory(FileSystemSecurity acl, string sid) {
+    if (!acl.AreAccessRulesProtected || acl.GetOwner(typeof(SecurityIdentifier)).Value != sid) return false;
+    var remaining = new System.Collections.Generic.HashSet<string>(new string[] { sid, "S-1-5-18", "S-1-5-32-544" });
+    foreach (FileSystemAccessRule rule in acl.GetAccessRules(true, true, typeof(SecurityIdentifier))) {
+      if (rule.AccessControlType != AccessControlType.Allow || rule.IsInherited
+        || rule.FileSystemRights != FileSystemRights.FullControl
+        || rule.InheritanceFlags != (InheritanceFlags.ContainerInherit | InheritanceFlags.ObjectInherit)
+        || rule.PropagationFlags != PropagationFlags.None || !remaining.Remove(rule.IdentityReference.Value)) return false;
+    }
+    return remaining.Count == 0;
+  }
+  static FileAttributes Attributes(string path) {
+    FileAttributes value = File.GetAttributes(path);
+    Require((value & FileAttributes.ReparsePoint) == 0);
+    return value;
+  }
+  static void Verify(string path, string mode) {
+    Require(!String.IsNullOrEmpty(path) && Path.IsPathRooted(path));
+    stage = "attributes";
+    bool directory = (Attributes(path) & FileAttributes.Directory) != 0;
+    using (WindowsIdentity current = WindowsIdentity.GetCurrent()) {
+      SecurityIdentifier sid = current.User;
+      SecurityIdentifier admin = new SecurityIdentifier("S-1-5-32-544");
+      WindowsPrincipal principal = new WindowsPrincipal(current);
+      stage = "read";
+      FileSystemSecurity acl = Read(path, directory);
+      string owner = acl.GetOwner(typeof(SecurityIdentifier)).Value;
+      bool repairAdminOwner = owner == admin.Value && principal.IsInRole(admin);
+      stage = "owner";
+      Require(owner == sid.Value || repairAdminOwner);
+      if (mode == "protect") {
+        Require(directory);
+        DirectorySecurity next = new DirectorySecurity();
+        next.SetOwner(sid);next.SetAccessRuleProtection(true, false);
+        foreach (string id in new string[] { sid.Value, "S-1-5-18", admin.Value })
+          next.AddAccessRule(new FileSystemAccessRule(new SecurityIdentifier(id), FileSystemRights.FullControl,
+            InheritanceFlags.ContainerInherit | InheritanceFlags.ObjectInherit, PropagationFlags.None, AccessControlType.Allow));
+        // Reapplying an identical inheritable DACL propagates security to live
+        // descendants while another owner CLI may be protecting those paths.
+        // Skip only an EXACT policy match from this fresh read, never a cache.
+        if (!CanonicalPrivateDirectory(acl, sid.Value)) {
+          stage = "protect-write";
+          Write(path, true, next);
+        }
+      } else if (mode == "verify") {
+        stage = "verify-dacl";
+        PrivateDacl(acl, sid.Value);
+        if (repairAdminOwner) {
+          string before = acl.GetSecurityDescriptorSddlForm(AccessControlSections.Access);
+          stage = "repair-owner";
+          acl.SetOwner(sid);Write(path, directory, acl);
+          Require(Read(path, directory).GetSecurityDescriptorSddlForm(AccessControlSections.Access) == before);
+        }
+      } else throw new InvalidOperationException();
+      stage = "final-attributes";
+      Require(((Attributes(path) & FileAttributes.Directory) != 0) == directory);
+      stage = "final-read";
+      FileSystemSecurity final = Read(path, directory);
+      stage = "final-owner";
+      Require(final.GetOwner(typeof(SecurityIdentifier)).Value == sid.Value);
+      stage = "final-dacl";
+      PrivateDacl(final, sid.Value);
+    }
+  }
+  static int Main() {
+    try {
+      Verify(Environment.GetEnvironmentVariable("DODO_PRIVATE_PATH"), Environment.GetEnvironmentVariable("DODO_PRIVATE_MODE"));
+      Console.Write("private");return 0;
+    } catch (Exception error) {
+      // Fixed labels and a numeric OS error only; never emit paths, identities,
+      // ACL contents or exception text. Callers still fail closed.
+      Console.Error.Write("private ACL verification failed; stage=" + stage + "; hresult=" + error.HResult);
+      return 1;
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dodo-mcp",
-  "version": "1.2.1",
+  "version": "1.3.1",
   "author": "Arthittakun",
   "description": "DODO — local-first MCP server with multi-project coding, AI providers, sub-agents, context, memory, media and workflow tools; embedded OAuth and workspace permissions.",
   "type": "module",
@@ -26,6 +26,7 @@
     "docs/ANDROID.md",
     "docs/AUTH.md",
     "docs/BRAIN.md",
+    "docs/CI.md",
     "docs/COMPATIBILITY.md",
     "docs/CONTEXT.md",
     "docs/CONFIRMATION.md",
@@ -37,6 +38,7 @@
     "docs/MEMORY.md",
     "docs/MULTIMODAL.md",
     "docs/PROJECTS.md",
+    "docs/RECOVERY.md",
     "docs/RESOURCES.md",
     "docs/RUNTIME.md",
     "docs/RELEASE_1.0.0.md",
@@ -49,11 +51,14 @@
     "docs/RELEASE_1.1.0.md",
     "docs/RELEASE_1.2.0.md",
     "docs/RELEASE_1.2.1.md",
+    "docs/RELEASE_1.3.0.md",
+    "docs/RELEASE_1.3.1.md",
     "docs/RELEASE_NOTES.md",
     "docs/SCHEDULES.md",
     "docs/SECURITY.md",
     "docs/TEST_REPORT.md",
     "docs/TUNNEL.md",
+    "docs/MCP_CONNECTIONS.md",
     "docs/WEB_CLIENTS.md",
     "docs/WINDOWS.md",
     "docs/WINDOWS_SETUP.md",
@@ -80,6 +85,7 @@
     "test:all": "npm run typecheck && npm run lint && vitest run tests/unit tests/integration tests/security tests/compatibility && npm run test:pack",
     "release:gate": "node scripts/release-gate.mjs --allow-dirty",
     "release:gate:ci": "node scripts/release-gate.mjs",
+    "ci:windows:focus": "node scripts/windows-focus.mjs",
     "release:gate:strict": "node scripts/release-gate.mjs --release",
     "prepublishOnly": "node scripts/guard-publish.mjs",
     "desktop:setup": "node dist/cli/main.js desktop setup",
@@ -101,6 +107,7 @@
     "picomatch": "^4.0.7",
     "playwright": "1.63.0",
     "sharp": "0.35.4",
+    "tar-stream": "3.2.1",
     "typescript": "5.9.3",
     "zod": "^4.2.0"
   },

package/schemas/global-config.schema.json

@@ -7,6 +7,39 @@
       "type": "number",
       "const": 1
     },
+    "recovery": {
+      "default": {
+        "version": 1,
+        "storageBytes": 21474836480,
+        "freeFloorBytes": 524288000
+      },
+      "type": "object",
+      "properties": {
+        "version": {
+          "default": 1,
+          "type": "number",
+          "const": 1
+        },
+        "storageBytes": {
+          "default": 21474836480,
+          "type": "integer",
+          "minimum": 1048576,
+          "maximum": 1099511627776
+        },
+        "freeFloorBytes": {
+          "default": 524288000,
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 107374182400
+        }
+      },
+      "required": [
+        "version",
+        "storageBytes",
+        "freeFloorBytes"
+      ],
+      "additionalProperties": false
+    },
     "publicUrl": {
       "type": "string",
       "format": "uri"
@@ -478,6 +511,7 @@
   },
   "required": [
     "version",
+    "recovery",
     "port",
     "configPort",
     "allowedHosts",