Signet

Signet is a provider-neutral MCP human approval gateway. A configured write call returns an honest pending_approval result only after the exact executable payload, expiry, origin namespace, and byte-identical acknowledgement are durable. That acknowledgement never claims the external action succeeded. The downstream mutation remains unsent until a fresh human confirmation authorizes the frozen request version.

The first reviewed adapters cover Fastmail email and an owned wacli WhatsApp wrapper. The core is generic: exact MCP schemas are mirrored behind four policy modes, immutable payloads are encrypted, approval transitions are persisted in SQLite, dispatch is fenced, ambiguous delivery enters bounded reconciliation, and the authenticated web app presents the private review queue.

Public beta

Signet 0.1.0b1 ships a complete packaged setup path and guided provider setup. signet setup creates the private installation, services, Hermes entries, and owner ceremony. Providers start disabled. A separate signet provider setup command then stores the credential, discovers schemas, sends one test message, writes the generated configuration and policy, and enables the rollout.

Fastmail is supported on Linux x86_64 and macOS arm64. WhatsApp is supported on Linux x86_64 through the pinned wacli 0.12.0 release; it is not available on macOS. This is a public beta, so take a backup before upgrading and verify the test message before relying on a provider. Read the packaged setup guide for the full flow.

The files under deploy/ remain inert review templates. Their placeholders prevent installation without review. The older installed signet deployment commands provide a runnable downstream-disabled staging assembly: it has no provider transport, credential resolver, dispatch worker, or downstream MCP alias. Its authenticated approvals tools all return deployment_disabled. Use signet setup, not those staging helpers, for the resumable packaged owner setup path.

The generic plugin surface is staged-only as well. Local, hash-pinned manifests can describe MCP connectors and propose effects, but installation, discovery, and authenticated effect review never enable tools/call or provider dispatch. Read the plugin integration guide and the explicit plugin readiness boundary before handling a manifest or connector configuration.

Guarantees

• Unknown tools resolve to deny. A tool is exposed only after exact schema capture, policy configuration, and digest review.
• approval tools make zero downstream calls before approval and return the normative pending shape in spec/fixtures/gateway-pending-result.json.
• A fresh TOTP proof or WebAuthn assertion is bound to one action, request, immutable version, and payload hash, then consumed transactionally.
• The MCP TOTP path can approve a normal caller-owned request, but cannot deny, edit, retry, manage credentials, or approve a policy change.
• Dispatch crosses a durable fenced boundary before network I/O. A possible post-dispatch crash becomes outcome_unknown, never a blind retry.
• Production retains exhausted unknown content indefinitely. The demo-only redaction drill is marker-guarded fake functionality, preserves "may have sent", and is not production human authorization.
• Push messages contain category and count information only. The authenticated queue remains authoritative if push delivery fails.
• Provider credentials are references such as keychain://Signet/fastmail, not values accepted by normal configuration models.
• The MCP listener is loopback-only. The separately bound web app supplies its own login, sessions, CSRF validation, action confirmation, and security headers.

These controls protect managed MCP routes. They do not prevent a malicious process running as the same operating-system user from reading that user's files, memory, or Keychain items, and they cannot govern direct provider scripts, native adapters, browser sessions, webhooks, or other paths that bypass Signet. See docs/security-model.md.

Packaged setup

With Python 3.12 selected for pipx, install the beta and run the one-command setup:

pipx install signet-gateway
signet setup

Setup prints the automatic safe steps, human ceremonies, deferred provider proofs, and destructive-action set before confirmation. signet setup --plan exits after that read-only review and emits the exact signet setup --apply PLAN_ID command. signet --version reports the installed distribution version. Configure only the provider you use after setup completes:

signet provider setup fastmail --from you@example.com --to you@example.com
signet provider status

Fastmail prompts for its API token without echoing it. On Linux x86_64, use signet provider setup whatsapp --to PHONE_OR_JID instead; Signet downloads the verified binary, opens the pairing flow, and sends one test message. The provider rollout gate is shared, so provider enable and provider disable report every configured alias they affect.

The default private origin is the current Tailscale node on HTTPS 8443. Review the generated Hermes entries, enable approvals and the providers you configured, then run /reload-mcp; Signet never restarts Hermes itself. Use signet authenticators open to print the exact private URL before opening named passkey/TOTP management. See docs/setup.md for prerequisites, browser setup, backup/restore, reviewed Hermes testing, crash recovery, plan/apply lifecycle commands, stable exit codes, upgrade, uninstall, and rollback.

Development

The Python distribution is named signet-gateway; the import package and command remain signet. The complete supported-platform runtime dependency closure and build backend closure are pinned to the reviewed versions. The supported platforms are Linux and macOS; the CLI fails closed elsewhere.

Version tags matching the project version wait for successful main-branch CI on the exact tagged commit, then trigger native Linux x86_64 and macOS arm64 wheel builds plus a source distribution. The release workflow emits a reproducible CycloneDX runtime SBOM and checksums, signs the artifacts with Sigstore OIDC, records GitHub provenance and SBOM attestations, and publishes only after those steps succeed. Release actions and release tooling are commit- or lock-pinned.

Signet requires Python 3.12 and exact uv version 0.11.28. Install that version with pipx install 'uv==0.11.28' or the official versioned uv installer; inspect a downloaded installer before executing it and do not substitute the unversioned installer. The repository pins uv-managed Python 3.12.13 because its bundled SQLite satisfies Signet's 3.51.3 safety floor.

Developers extending the provider-neutral onboarding path should start with the manifest, connector, discovery, review, and worker contracts. The companion readiness report lists the capabilities that remain intentionally absent and the prerequisites for any future live work.

(
  set -e
  UV_VERSION="$(uv --version)"
  case "$UV_VERSION" in
    "uv 0.11.28"|"uv 0.11.28 "*) ;;
    *) printf 'expected uv 0.11.28, received %s\n' "$UV_VERSION" >&2; exit 1 ;;
  esac
  uv python install 3.12.13
  uv sync --frozen
  uv lock --check --project deploy/hermes/runtime
  uv run playwright install --with-deps chromium
  uv run pytest -q
  uv run ruff check .
  uv run mypy
)

The reviewed local stdio boundary requires Linux with /proc/self/fd. Guided WhatsApp setup therefore supports Linux x86_64 and installs the pinned wacli 0.12.0 Linux artifact. macOS arm64 supports the packaged service and Fastmail, but local WhatsApp activation remains unsupported. On Linux, Signet also uses the kernel-owned /proc/self/fd view to change the mode of an already-held mode-000 directory without reopening an attacker-controlled path. It fails closed if procfs is unavailable. macOS instead uses a verified parent descriptor and a one-component, no-follow fchmodat operation, then opens and revalidates the expected directory. It never retries an unanchored path.

The generic package entry point serves only an explicitly supplied application factory. After creating the disabled state below, run its two shipped factories in separate terminals. In terminal A:

SIGNET_HOME="$(cd "$HOME" && pwd -P)" || exit 1
export SIGNET_HOME
export SIGNET_SERVICE_ROOT="$SIGNET_HOME/.hermes/services/signet"
export SIGNET_DISABLED_CONFIG="$SIGNET_SERVICE_ROOT/config/disabled.json"
uv run signet serve-mcp --factory signet.deployment:create_mcp_app \
  --host 127.0.0.1 --port 8789

In terminal B:

SIGNET_HOME="$(cd "$HOME" && pwd -P)" || exit 1
export SIGNET_HOME
export SIGNET_SERVICE_ROOT="$SIGNET_HOME/.hermes/services/signet"
export SIGNET_DISABLED_CONFIG="$SIGNET_SERVICE_ROOT/config/disabled.json"
uv run signet serve-web --factory signet.deployment:create_web_app \
  --host 127.0.0.1 --port 8790

SIGNET_DISABLED_CONFIG is the absolute non-secret config path, not configuration JSON or a credential. The dedicated signet deployment serve-* commands below are preferred because they use the verified listener settings from that file. The MCP command rejects a non-loopback numeric host. Do not point an ad hoc factory at live credentials.

Downstream-disabled deployment staging

Create private, persistent staging state without enrolling a human credential or creating a downstream client:

(
  set -e
  SIGNET_HOME="$(cd "$HOME" && pwd -P)"
  export SIGNET_HOME
  export SIGNET_SERVICE_ROOT="$SIGNET_HOME/.hermes/services/signet"
  export SIGNET_DISABLED_PROFILE=signet-disabled
  uv run signet deployment init \
    --config "$SIGNET_SERVICE_ROOT/config/disabled.json" \
    --data-dir "$SIGNET_SERVICE_ROOT/data" \
    --namespace "profile:$SIGNET_DISABLED_PROFILE"
  uv run signet deployment validate \
    --config "$SIGNET_SERVICE_ROOT/config/disabled.json"
  uv run signet deployment serve-mcp \
    --config "$SIGNET_SERVICE_ROOT/config/disabled.json"
)

One initialized disabled state supports exactly that one dedicated Hermes profile; the CLI does not add principals to an existing config. Follow the tested deploy/hermes/README.md sequence to create the blank profile and stream token issue directly into the checked-in atomic configurator. The raw token is accepted only on stdin and is never written to YAML or output by the helper. Do not paste it into an argument, shell history, log, chat, or documentation. token list returns metadata only. token revoke --token-id=TOKEN_ID takes effect on the next authentication check. token rotate --token-id=TOKEN_ID stages and prints a linked replacement while deliberately leaving the old token valid; install, reload, and test the replacement before explicitly revoking the old token.

The optional init human-auth context flags validate only the exact HTTPS origin, RP ID, and user ID. deployment auth-status reads counts, not credential material. Neither command enrolls anything. A passkey requires a real browser/authenticator ceremony at the final HTTPS origin and cannot be created by an offline CLI. See docs/deployment.md.

Fake-only operator path

docs/operator-runbook.md is the start-to-finish path for a disposable local demo, Hermes profile wiring, verification, troubleshooting, backup/restore drills, and rollback. The demo uses explicit fake identities and network-disabled providers; it is not evidence of passkey/TOTP enrollment, live schema review, provider readiness, or cutover authorization.

From the repository root, the minimal fake-only path is:

(
  set -e
  SIGNET_HOME="$(cd "$HOME" && pwd -P)"
  export SIGNET_HOME
  export SIGNET_DEMO_DIR="$SIGNET_HOME/.signet-fake-demo"
  test ! -e "$SIGNET_DEMO_DIR" && test ! -L "$SIGNET_DEMO_DIR" || exit 1
  uv run signet demo init --data-dir "$SIGNET_DEMO_DIR"
  uv run signet demo smoke --data-dir "$SIGNET_DEMO_DIR"
  uv run signet demo seed-request --data-dir "$SIGNET_DEMO_DIR"
  uv run signet demo serve --data-dir "$SIGNET_DEMO_DIR"
)

The physical home path is required because private demo paths reject symlinked ancestors. demo init refuses every existing destination and never creates parent directories. smoke is offline unless --live is explicit, and serve binds both demo apps to numeric loopback. The generic serve-* factory interface remains deployment-owned. Hermes templates stay inert; the runbook uses a new blank profile and a validated structured merge instead of editing an existing profile. Agents other than Hermes should follow the provider-neutral MCP client guide; that guide does not turn the fake or downstream-disabled assembly into a live deployment. seed-request must run while the server is stopped. It admits a realistic fake email through the real gateway pipeline, returns only safe request metadata, and makes the complete context immediately reviewable without an LLM, Hermes profile, provider credential, or network call.

Offline onboarding

Operational helpers are available without adding another console entry point:

uv run python -m signet.operations --help

They normalize a previously captured local tools/list fixture, add advisory read/write hints, generate an all-deny policy, create and verify fake-adapter test inputs, evaluate a caller-supplied names-and-locations-only bypass inventory, and produce a fail-closed cutover readiness report. Output files are created once with mode 0600; existing files are never overwritten. The readiness report is advisory: it always keeps ready and authorizes_live_changes false, even when its supplied evidence packet is complete.

Repository map

• spec/ contains executable policy, provider-input, pending-result, and gateway tool schema fixtures.
• src/signet/ contains canonicalization, encryption, persistence, authentication, MCP mirroring, gateway, adapters, web UI, notifications, backup, and operations.
• tests/ contains contract, adversarial, durability, authentication, adapter, runtime, web, backup, and offline operations coverage.
• docs/ contains the MCP tool reference, security model, deployment guide, and policy/onboarding guide.
• deploy/ contains secret-free launchd, Homepage, Tailscale, Hermes, and readiness staging material. It changes nothing by itself.

Documentation

• MCP approval tools
• Provider-neutral MCP agent integration
• Security model
• Policy and adapter onboarding
• Staged plugin integrations
• Plugin readiness boundary
• Deployment, backup, restore, and rollback
• Production runtime and lifecycle architecture
• Productionisation plan and acceptance matrix
• No-live operator and Hermes runbook

The current productionisation plan and acceptance matrix are recorded in docs/plans/2026-07-17-signet-productionization-plan.md. The earlier generic approval-gateway plan remains in 2026-07-14-signet-approval-gateway-plan.md.