feat: add versioned client and provider IPC

[domenkozar]

Summary

This introduces SecretSpec IPC v1 for 0.20+: two application protocols over one canonical framed JSON-RPC wire/session layer.

Boundary	Protocol	Purpose
Application or SDK → SecretSpec broker	secretspec.client/1	Resolve one exact declared name as a value or leased file
SecretSpec → external provider endpoint	secretspec.provider/1	Provider naming, reads, presence, writes, expiry, deletion, clearing, preflight, and reflection

The two method sets cannot be mixed in one session. They share framing, initialization, capability negotiation, request IDs, deadlines, cancellation, structured errors, limits, and shutdown.

The PR includes:

• canonical JSON Schema, OpenRPC, fixtures, and protocol documentation;
• an independent Rust client/server crate and a pure-C11 client;
• secretspec broker --stdio, exact-name resolution, and broker-owned file leases;
• trusted external-provider discovery, a Rust endpoint-author API, and the core Provider adapter;
• C/Rust client differential tests plus executable broker/provider conformance cases;
• independently negotiable provider capabilities, including get_many without get, set_expiring without set, and write-only providers with exists but no plaintext read;
• the embedded ABI rename from secretspec-ffi to libsecretspec, retaining legacy runtime loader compatibility in every existing SDK.

Which library is which?

• libsecretspec is the embedded in-process resolver ABI used by the current language SDKs.
• libsecretspec-ipc is the pure-C client for launching and talking to either IPC endpoint. New non-Rust broker-mode integrations should bind this library instead of reimplementing framing and lifecycle.
• secretspec-ipc is the independent Rust wire/client/server/handler implementation.

One IPC client implementation is sufficient because initialization selects the application protocol. The client and provider protocols remain separate contracts with disjoint methods and trust boundaries.

Client IPC usage

The client library directly launches the broker as a private child—there is no global socket or daemon:

secretspec broker --stdio

Initialization fixes the manifest and resolver context for the session:

{
  "manifest": {
    "kind": "path",
    "path": "/absolute/project/secretspec.toml"
  },
  "provider": null,
  "profile": "production",
  "scope": "deploy",
  "reason": "build api container"
}

The consumer then resolves exactly the declaration it needs:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "client.resolve",
  "params": {
    "deadline_unix_ms": 1786766405000,
    "name": "FORGE_TOKEN",
    "representation": "value",
    "purpose": {
      "consumer": "nix",
      "operation": "fetch",
      "host": "github.com",
      "path": "/acme/project"
    }
  }
}

representation: "value" prevents a path from being mistaken for a token. representation: "file" returns an opaque lease that must be released with client.release; disconnect also cleans it up. The broker never resolves unrelated required secrets.

Rust consumers use secretspec-ipc's lifecycle and typed ResolutionClient. C and non-Rust consumers use libsecretspec-ipc and free every returned buffer with secretspec_ipc_buffer_free.

Provider IPC usage

An endpoint author implements ProviderHandler, advertises only the operations it actually supports, wraps it in ProviderApplication, and serves it on stdin/stdout:

let application = Arc::new(ProviderApplication::new(Arc::new(MyProvider::new())));
serve(
    tokio::io::stdin(),
    tokio::io::stdout(),
    application,
    ServerConfig::default(),
).await?;

Install a trusted registration for the provider scheme:

{
  "schema_version": 1,
  "scheme": "factorseal",
  "executable": "/absolute/path/to/secretspec-provider-factorseal",
  "arguments": [],
  "credential_names": []
}

Then use the scheme like an in-tree provider:

[providers]
deploy = "factorseal://default"

[profiles.production]
DEPLOY_TOKEN = { providers = ["deploy"] }

The provider receives its configured URI, base directory, resolved semantic credentials, and immutable access reason during initialization. It does not receive config_file, reread the manifest, receive a caller-supplied identity, or choose SecretSpec routing.

Write-only and narrow providers

A write-only endpoint can advertise:

[
  "provider.resolve_address",
  "provider.exists",
  "provider.set",
  "provider.delete",
  "provider.reflect"
]

That supports set, delete, value-free check --json / check --explain, SDK no-values resolution, and ordinary imports into missing destinations. Existing destination entries are preserved without reading them. Plaintext resolution returns capability_required; a write-only provider cannot be an import source, and import --delete-source requires a readable destination for exact-value verification.

Capabilities are otherwise independent except for real dependencies:

• addressed operations require provider.resolve_address;
• writable preflight/description requires set or set_expiring;
• deletion preflight requires delete.

The adapter can serve one get through a one-item get_many, but it never weakens set_expiring into an ordinary write when the endpoint did not advertise set.

Why a child endpoint, not a proxy configuration?

The endpoint is the unavoidable language/process adapter between SecretSpec's in-process Rust Provider trait and an out-of-tree provider implementation. It is not a network proxy and not a shared daemon: SecretSpec launches one private child for one provider URI and one reason, owns its lifecycle, and communicates over inherited pipes.

This keeps routing and policy in SecretSpec while allowing Factorseal (and future providers) to keep their database, encryption, agents, grants, and remote API logic in their own implementation. Provider-specific settings stay in the provider URI or endpoint-owned configuration; arbitrary proxy-shaped fields and manifest forwarding are deliberately excluded.

PR #98 feedback incorporated

This replaces the unmerged direction in #98 with explicit boundaries and a canonical wire contract:

• client-to-broker and broker-to-provider are separate application protocols;
• the provider does not parse SecretSpec configuration or receive config_file;
• no protocol field pretends caller metadata is authenticated identity;
• capability negotiation and structured errors replace guessed optional behavior;
• credentials and secret values stay off argv and are bounded/redacted on the private transport;
• subprocess ownership, cancellation, non-replay, crash recovery, and shutdown are specified and executable in conformance tests.

Documentation

Rendered branch docs, in contract order:

1. IPC architecture
2. Shared IPC wire protocol
3. Secret Resolution / client protocol
4. Secret Provider protocol
5. Repository implementation and conformance guide

Canonical source contracts are under docs/src/content/docs, with machine-readable schemas and fixtures under schema/ipc/v1.

Testing

Executed locally and passing:

cargo test --all
cargo check -p secretspec --no-default-features
cargo check -p secretspec --all-features
cargo clippy -p secretspec-ipc -p secretspec-ipc-conformance --all-targets --no-deps -- -D warnings
cargo fmt --all -- --check
git diff --check
npm --prefix docs run build

Focused executable gates:

cargo test -p secretspec-ipc-conformance --test client_cases
cargo test -p secretspec-ipc-conformance --test client_differential
cargo test -p secretspec-ipc-conformance --test provider_cases
cargo test -p secretspec --test ipc_broker

The provider matrix runs the same checked-in cases directly against the Rust endpoint and through SecretSpec's external-provider adapter, including write-only and narrow-capability modes.

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	secretspec	a393a27	Commit Preview URL Branch Preview URL	Aug 18 2026, 02:03 AM

[djbclark]

Following up from #345 (closed into #64) — secretspec.provider/1 is the out-of-tree provider mechanism that proposal asked for, so: thank you, and we intend to be an early adopter. sudo-secretspec plans to ship a System-scope registration whose endpoint is a thin unprivileged shim crossing a sudo-mediated privilege boundary into a root-owned broker — the "privileged integrations construct an allowlisted environment" case the architecture doc already nods at. As far as we can tell from the PR, that needs no upstream patching: ProviderHandler/ProviderApplication are public API and registration is data.

One piece of review feedback from operating that kind of boundary, aimed at the unix registration trust checks in external.rs (as of 337950c). Offered as hardening plus conformance cases, not an objection to the design:

1. macOS ACLs are invisible to the mode-bit check. check_file_security/check_parent_security gate on metadata.mode() & 0o022, but on macOS an extended ACL can grant add_file/write to a group while the POSIX bits read 0755 — third-party installers add such ACLs routinely. The Windows path already validates ACLs (path_acl_is_trusted); the unix path currently has no ACL story. sudo-secretspec's drift checker refuses any extended ACL on a protected path or its ancestors for this reason.

2. Both checks follow symlinks. std::fs::metadata resolves, so what gets validated is the resolved target, not the literal registered path. A symlinked component anywhere in the chain silently redirects discovery to wherever a root-owned, mode-clean target happens to be. symlink_metadata plus an explicit no-symlinked-components rule is cheap at discovery time.

3. Trust stops at the immediate parent. Everything above the registration directory's parent is implicitly trusted. On stock macOS 26 the default System chain (/Library/Application Support, root:admin 0755, no ACL — verified) is sound as shipped, but that soundness is assumed rather than checked, and one loosened ancestor — by mode or by ACL, see (1) — defeats both checks below it. Walking the resolved chain to / once per discovery is what sudo-secretspec does (check_ancestor_chain in its drift checker): refuse non-root-owned, group/world-writable, ACL-bearing, or symlinked ancestors.

Happy to turn this into (a) a small hardening PR against feat/ipc-v1 and (b) conformance-suite cases — ancestor-writable-by-mode, ancestor-writable-by-ACL, symlinked-component, symlinked-registration-file — if that would be useful. And once the privileged endpoint ships against this we'll write the deployment up so the reference case is documented.