Security: what leaves your machine · Synchrobuilder

Every outbound field passes one redaction module before it is written to your state ref. The patterns are PEM blocks (private keys), the token formats used by GitHub, Anthropic, OpenAI, AWS, Slack and Stripe, and generic high-entropy strings; each match becomes [redacted]. The same module runs again on the receiving side, where URLs also lose their scheme and any embedded username or password. Because one module serves both directions, the "what leaves" list and the "what we accept" list stay aligned.

Identity is your git email mapped to a handle through a committed .synchrobuilder/team.json. The team file lists only names, handles and emails that are already in the repository's git history. Your email is resolved once per session by the background worker and stored in a local identity file under ~/.synchrobuilder/; the email itself is never pushed. State commits are authored as <handle>@synchrobuilder.invalid unless you opt in to your real email for hosts that require it.

State travels through a hidden bare repository under ~/.synchrobuilder/, never through your project's .git, and lands in the ref namespace refs/synchrobuilder/v1/<handle>/<device> on the remote you already push to. The full data flow is on the How it works page.

There are no accounts, passwords or tokens in v1. Anyone with push access to your remote can write any state ref, including one named after another teammate. Identity is therefore a claim, not authentication. Readers treat every field from every ref as untrusted data, and the status output always shows the namespace the data came from, never a display name alone.

Two checks narrow the gap without closing it. A ref whose embedded manifest does not match its own name, or whose handle is not in team.json, is kept in an "unverified" bucket that never reaches Claude. A ref whose committer email does not match the handle's entry in team.json is labelled verified=email-mismatch, which excludes it from "ask" prompts and from your inbox and lets it appear in the digest only with that label. Both checks are forgeable by anyone who can push. Signed state commits are listed as a possible v2 hardening, not a v1 feature.

The state namespace is hidden from branch UIs and from CI. It is not hidden from git. Presence and messages are readable by anyone who can fetch the repository, and for a public repository that means the world. ADR-001 requires the setup consent screen to state this, and doctor uses git ls-remote to warn about it.

Fields split into two classes. Identifiers (handle, device, branch, path, task id, symbol, timestamp, enums) are validated against a strict rule and rejected outright on failure; a rejected value is withheld, never "cleaned", so it can never be rendered in a form that still misleads. Free text (task summary, message body, handoff items, board titles) goes through a sanitizer on the reader side at sync time, because a compromised writer bypasses any writer-side step. Hooks only concatenate strings that were already sanitized.

The sanitizer, in order: cap sizes before any regex runs; normalize to NFC; strip terminal escapes (CSI, OSC, DCS, APC, PM, SOS, bare ESC and all C1 controls); delete control characters except newline; delete invisible and format characters (zero-width, bidi embeddings and isolates, BOM, soft hyphen, tag characters); collapse whitespace; neutralize markup that imitates structure (runs of three or more backticks or tildes become [fence removed], leading headings and quotes are stripped, role labels such as Human: or System: at the start of a line are prefixed with ~ ); defang URLs (an http or https URL loses its scheme and userinfo and gets its first dot bracketed, every other scheme becomes [url removed]); redact secrets; cap each field by code points; HTML-escape &, < and >. Message bodies keep at most 6 lines of 200 code points.

Sanitized text is delivered to Claude inside one wrapper. The preamble is factual rather than imperative, because the Claude Code docs say text framed as out-of-band system commands can trip Claude's own injection defenses. Every teammate line starts with | , every plugin-generated label starts with @, and the two marker lines carry a 16-hex nonce generated in the hook process per injection and never stored.

Before printing, the hook asserts that exactly one begin and one end marker exist with the same nonce, that no inner line starts at column 0, and that the total is under the 10,000-character limit at which Claude Code spills hook output to a file. If any assertion fails, the hook prints nothing and logs locally. Human-visible surfaces (systemMessage, permission reasons, the status line, monitor lines) render validated identifiers, counts and times in fixed templates only, never free text; a task summary may appear in the status line only as at most 40 printable ASCII characters.

The threat model in docs/research/evidence/teammate-message-threat-model.json covers 13 surfaces and holds a corpus of 48 injection payloads. That corpus is the test suite in tests/injection/, one assertion per surface per payload, and it passes. The exact system-reminder text Claude Code wraps hook context in is still an open question in ADR-005.

Every hook runs inside one try/catch. On any internal error it writes one line to ~/.synchrobuilder/logs/hooks.log (rotated at 1 MB), prints nothing and exits 0. It never exits 2, which is the code that would block a tool call. A watchdog ends the process with exit 0 and no output if work overruns its budget: 400 ms for session start, the prompt hook and the pre-edit hook, 1.5 s for post-edit, 2 s for stop and 1 s for session end. Fast hooks read only files under ~/.synchrobuilder/ and the plugin directory; they never run git, never open sockets and never wait on the network.

One neighbouring fact was checked, with a small test plugin rather than Synchrobuilder. Experiment E3 in docs/research/experiments.md (macOS, Claude Code 2.1.218, 2026-09-18) ran a headless session with exec-form node hooks and no node on PATH: the session exited 0, the file Claude was asked to create was still created, and each hook reported an error notice instead of blocking. Both are now in hooks/run.mjs and covered by tests/hooks/replay.test.mjs: all six hooks exit 0 on recorded inputs, on malformed stdin, on an unknown verb and outside a git repository, and write nothing outside the state directory.

Collision warnings are advisory by default. The default mode returns context to Claude and a one-line notice to you, and nothing is blocked. A team can opt into "ask" in .synchrobuilder/config.json, which asks for permission before the edit. The downgrade rules are tested; the prompt as a terminal renders it has not been checked yet (docs/VERIFICATION.md). Even then, "ask" is downgraded to "warn" in dontAsk, bypassPermissions and headless runs, where a prompt would mean a denial. Warnings fire at most once per file per 30 minutes, or every two minutes for another agent on your own machine.

There is one mode that does refuse an edit, and it is the only exception to the rule that a hook never blocks you. Setting collision.mode to "block" denies an edit to a file that another agent on this same machine is holding right now. It is deliberately narrow: a teammate on another machine can never trigger it, because nobody can confirm they are still at their desk, and neither can an agent here whose session has ended, so a crashed run cannot wedge the repository. Every internal error path stays fail-open regardless of the mode. The refusal names the command that lifts it. This exists because a warning is something an agent can read and reason past, which is fine for a person and not enough for two agents editing in the same second.

setup compares the manifest to what is installed, shows a step-by-step plan for your OS, and asks before each install. It uses the OS's native package manager (winget, Homebrew, apt), pins exact versions, and never elevates silently: no hidden sudo and no hidden admin prompt. The CLI form only applies without asking under an explicit --yes.

A plugin cannot ship a status line; only your own settings can hold one. The statusline command shows the exact settings change, warns that it replaces any status line you already have, and applies it only when you say yes. Its content is snapshot-tested; the line as Claude Code renders it has not been checked yet. fix shows a diff and applies it only on approval. init never writes extraKnownMarketplaces or enabledPlugins into your project settings by default; it offers to, shows the JSON, and explains what teammates would see. If doctor finds that node is not on Claude Code's PATH, the fix it offers is a user-level PATH setting or a symlink into a standard location, again with consent.

Plugin state is never written inside your repository or its .git. Commands that do write into the repository (init writing the manifest and team.json, ci writing a workflow, fix applying an approved diff) write ordinary files you can review and commit. The plugin's own state lives in one directory, ~/.synchrobuilder/, and npx synchrobuilder clean removes it. See the Commands page for each command's exact behaviour.

A malicious collaborator with push access. They can impersonate any handle, overwrite your state ref, or push a poisoned ref. The per-writer design means they cannot stop you publishing, an overwritten ref self-heals on the next tick, and readers cap and validate everything they ingest. But the impersonation itself is not detectable in v1 beyond the email-mismatch label, which is also forgeable.

A compromised teammate machine. If a teammate's plugin or Claude is compromised, it can send well-formed but misleading data: a false claim, a wrong branch, a message that lies. Synchrobuilder delivers it labelled as data from that namespace. Claude is told not to follow it as an instruction. It is not told whether it is true.

Anything the git host can see. State refs are ordinary git objects on your remote. Whoever administers that host, and whoever can fetch the repository, can read them.

Use GitHub's private vulnerability reporting at github.com/RyanNorouzi/synchrobuilder/security. Include the plugin version (npx synchrobuilder --version), your operating system and steps to reproduce. No response time is promised, because none has been decided.

The plugin is plain JavaScript in ESM. No TypeScript, no transpiler, no bundler, no runtime dependencies and none at dev time either; tests use node:test. The only imports are Node built-ins: node:fs, node:path, node:os, node:child_process, node:crypto, node:http for health checks, and node:test. The floor is Node 20. CI runs the suite on Node 20 and Node 24. Adding any dependency, even dev-only, needs the owner's approval.

package.json has no dependencies and the plugin ships no lockfile. The Claude Code docs say a package.json with no lockfile is skipped silently, so Claude Code's automatic npm ci on install never runs for this plugin. Every hook is declared in exec form ("command": "node" with an args array), which the docs describe as spawning the executable with no shell involved. The plugin ships no bash, PowerShell or cmd anywhere, and does not use the skills feature that runs inline shell commands.

Git is spawned by the background worker as an argv array, never through a shell, with an explicit --git-dir, credentials taken from your global git configuration only, terminal prompts disabled, and per-call timeouts. Repo-local credential keys are never copied into a second file. The source is at github.com/RyanNorouzi/synchrobuilder, so you can read all of it before you install.