Repository navigation
v0.3.0
Pre-release-
The gateway-service sandbox supervisor rejects a dispatch request when any
string value inaction.parameters, at any depth, contains NUL, starts at
a root (/or\), has a drive or UNC prefix, or has a..segment
(T-013 fix A, lexical only;/and\are both checked on every OS).
Symlinks are not resolved yet (fix B, stage 2). -
crates/praetore-mcp/GUIDE.md: a guide for external developers with a
first-run walkthrough, the limits (only MCPtools/callthrough a wrapped
server is governed; LOCAL/DEV keys; no approval flow for REQUIRE_APPROVAL;
lexical path rules; TOCTOU) and a troubleshooting table. -
praetore-mcp install/uninstallprocess a config file once when two
default paths name it (Cursor's~/.cursor/mcp.jsonand
./.cursor/mcp.jsonwhen run from~, or a symlink). Before, it was
listed twice; the second pass was skipped as already wrapped. The
praetore-mcp README records the real-app check on macOS (Claude Desktop
and Cursor). -
The praetore-mcp README documents installing without a clone:
cargo install --git https://github.com/Mavericksantander/praetore praetore-mcp --locked(checked on macOS arm64 against9735974). -
praetore-mcp <command> --help/-hprints that command's usage and
exits 0 (it used to fail withunexpected argument "--help").--help
afterwrap ... --is still passed to the MCP server.praetore-mcp versionis an alias of--version. Exit codes (0, 1, 2, andwrap's
server code / 127) are documented in--helpand the praetore-mcp README. -
praetore-mcp wrap --mode observeno longer forwardstools/callwithout
receipts when the home cannot be loaded at startup (not initialized, or
invalid keys, pins, authority or policy). Both modes now refuse every
tools/callin that case and printevery tools/call will be REFUSED;
other MCP traffic is still relayed. Per-call evaluation errors after a
successful start keep the documented observe behavior. -
New receipts always record what decided them in
decision.decided_by, as
part of the hashed and Ed25519-signed evidence payload, in the new
evidence schema v4:DecidedBy::Rule { rule_id }(a rule's declared effect applied; a
RECOVER rule'srule_idequals its recovery obligation's),
UnboundRule { rule_id }(a REQUIRE_APPROVAL/RECOVER rule matched
without its required capability or target and denied instead),
DefaultDenyandEngineGuard { guard }. Combining decisions keeps the
decider of the higher severity (Recover > Deny > RequireApproval > Allow), the earlier one on a tie.- Versioning: every new evidence is v4 (with or without HighAssurance
metadata and recovery). v1-v3 must not carrydecided_by, so existing
receipts, golden vectors and fixtures keep verifying byte-for-byte; v4
must carry it.decided_bymust be consistent with the outcome,
recovery obligation and contributions; unknown kinds, unknown fields and
an explicitnullare rejected. - Upgrade order: binaries without v4 support reject v4 evidence (fail
closed). Upgrade every verifier, Python binding and gateway node before
any node starts producing v4; during a mixed-version rollout or after a
rollback, journal rows and pending approvals written by new nodes are
unreadable (InvalidRecord) on old ones. - Breaking:
Decisionhas a requireddecided_by: DecidedBy(JSON without
it does not deserialize);Decision::allow/deny/require_approvaltake it
as a second argument (Decision::recoverderives it from the
obligation).Evidence.decisionis now aRecordedDecision(the read
path) whosedecided_byis optional, crate-private and read via
decided_by();Decisionconverts with.into().Evidence::newand
attestreject a decision that violates these invariants. Consumers that
comparedevidence_schema_versionto 2/3 should use
is_high_assurance_shape()anddecision.recovery. - Dispatch revalidation compares a legacy (pre-v4) record on every field
exceptdecided_by, so approvals pending across the upgrade can still be
dispatched; v4 records must matchdecided_bytoo. - Test fixtures in
packages/praetore-python/tests/fixtureswere
regenerated as v4; the previous v1/v2 bytes are kept in
fixtures/legacy-evidence/and still verify.
-
New crate
praetore-mcp(binarypraetore-mcp): a local stdio MCP proxy
for Claude Desktop, Cursor and VS Code that needs no PostgreSQL and no Rust.
initcreates LOCAL/DEV issuer, agent and attester keys (0600), a signed
authority,praetore-verify-compatible trust pins and a default v2 policy.
wrapevaluates every client→servertools/callin HighAssurance mode and
appends attested evidence to an fsynced JSONL journal. Inobservemode
(the default) calls are always forwarded and only recorded. Inenforce
mode DENY and REQUIRE_APPROVAL are blocked with an MCPisErrorresult,
and errors fail closed. The mode is bound into the signed evidence as
context["praetore.mode"].install/uninstallrewrite and restore
client configs, writing a backup and asking for confirmation first.
receiptsandverifyread and check the journal.policy list|check|deny|require-approval|allow|removemanage rules without
hand-written JSON. Each change is validated, written atomically with a
backup, and refused when it would create an unscoped argument rule unless
--any-toolis given. Limitations: stdio
only, REQUIRE_APPROVAL is not supported, LOCAL/DEV keys only, and receipts
attest the proxy's view of a call, not the upstream agent's intent. See
crates/praetore-mcp/README.md.praetore-coreis unchanged. -
praetore-verify evidenceaccepts--policy PATH: the receipt must record
that policy's digest (Evidence::verify_policy); receipts without a digest
fail withPOLICY_MISMATCH. -
The hash-linked journal export (
praetore-verify journal) is a proposal
only (docs/proposals/journal-chain-jsonl.md). It is not shipped: the
verifier is kept on branchfeat/journal-chain-verifieruntil a Postgres
exporter lands with it in one PR. As specified (unkeyed links, no signed
or published head) it does not let a third party detect deletion,
truncation, reordering or a recomputed chain; the proposal lists what is
missing. -
scripts/regen-legacy-evidence-fixture.shregenerates the legacy receipt
fixture (nopolicy_digest) from commit 3db7b5e. -
Breaking (core):
Evidence::signnow refuses to sign a receipt that does
not record the full lowercase SHA-256 digest of the active policy
(policy_digest, fromPolicy::digest()over the canonical JSON). The
engine already bound it in every mode; this makes it a hard requirement of the write path, so the
Ed25519 attester signature always covers which policy decided. Receipts
signed before this change (nopolicy_digest) still deserialize and verify.
Callers that sign evidence directly (not throughPolicyEngine) must call
Evidence::bind_policy_digestfirst. -
New
Evidence::verify_policy(&Policy)checks that a receipt was decided
under a given policy (digest present and equal). Legacy receipts without a
digest return an error. -
Known limitation (accepted): legacy receipts whose
policy_digestwas
recorded in uppercase hex still deserialize and verify, but cannot be
re-signed, becauseEvidence::signonly accepts the lowercase SHA-256 hex
produced byPolicy::digest();verify_policyalso rejects them. -
Security (gateway HTTP API): caller authentication.
http_api::routerand
serve_localnow take anApiAuth.ApiAuth::Required(ApiCredentials)
requiresAuthorization: Beareron every endpoint except/healthz, with
tenant-scoped credentials (SHA-256 digests, constant-time comparison) whose
tenant must match the{tenant_id}path segment or, for/v1/execute, the
submitted authority's tenant. Roles are disjoint:agentmay execute and
read status; onlyapprovermay read challenges, decide and dispatch.
Unauthenticated: 401authentication_required; wrong role or tenant: 403
caller_not_authorized.- Breaking (gateway service):
PRAETORE_GATEWAY_API_CREDENTIALS_FILEis
required with thehttpandsandboxadapters and for any non-loopback
PRAETORE_GATEWAY_LISTEN_ADDR. Onlylocal-demoon loopback may run
unauthenticated, andlocal-demonever listens beyond loopback. - The freshness snapshot is read with a bounded read (not only a
metadatasize check), and a snapshot whoseissued_atis older than
one already loaded is refused (fail closed), so a stale sync or restored
backup cannot undo a revocation. - Breaking (CLI):
praetore initcreatesagent-api.tokenand
approver-api.token;run,demo,approve,rejectanddispatch
use them. Older demo directories need a freshinit.
- Breaking (gateway service):
-
Security (gateway): approver keys can be bound to a tenant
(HumanApprovalVerifier::for_tenant); the gateway accepts several
verifiers and a key never verifies another tenant's decision. Service:
newPRAETORE_GATEWAY_APPROVER_BINDINGS_FILE; breaking: the single
PRAETORE_GATEWAY_APPROVER_KEY_ID/_PUBLIC_KEY_HEXpair is rejected with
http/sandboxunless exactly one tenant is issuer-bound (it is then bound
to that tenant). The CLI demo approver is bound to the demo tenant. -
Security (gateway service): breaking:
httpandsandboxadapters require
PRAETORE_GATEWAY_FRESHNESS_FILE, a file-based revocation snapshot
(revoked authority IDs, agent key fingerprints, authority digests) with
bounded staleness that fails closed when missing, invalid or stale
(PRAETORE_GATEWAY_FRESHNESS_RELOAD_INTERVAL_MS,_LEASE_MS,
_MAX_SNAPSHOT_VALIDITY_MS). The demo provider, which never checks
revocation, is limited tolocal-demo. -
Security (gateway):
claim_dispatchindependently re-verifies the
recorded approval (approve outcome, challenge bound to the persisted
evidence and action digest, tenant-pinned approver signature, no
self-approval) before dispatch, sincevalidate_evidence_for_dispatch
acceptsRequireApprovalevidence. -
Gateway: transient revalidation failures at dispatch claim (trusted clock,
freshness source or replay storage unavailable) leave the execution
approved_pending_dispatchinstead of closing it asdispatch_failed. -
Gateway: new
ApprovalResolution::NotDispatched(breaking for exhaustive
matches) andGateway::approval_state. The status endpoint reports
not_dispatchedplusexecutionandnot_dispatched_reasonfor approved
executions closed without dispatch, instead ofapproved. -
Breaking (gateway HTTP API):
GET /v1/approvals/{tenant}/{agent}/{request}
returns{"challenge": ..., "action": ...}(ApprovalChallengeView)
instead of the bare challenge.praetore approve/rejectshow the action,
verify its digest and policy digest, and require confirmation (--yesfor
scripts). -
Security (sandbox supervisor): worker callbacks are authenticated against
the in-memory pending execution (constant time) before any Kubernetes API
call;serve_tlstakesConnectionLimits(non-blocking accept, per-peer
connection cap, header read timeout, 20 s worker connection lifetime). -
Dependencies:
praetore-gatewaynow depends onsha20.11 andsubtle
2.6 (both already in the lockfile). -
Docs: HighAssurance replay claims are documented as keyed by
(tenant_id, agent_id, request_id)(tenant from the signed authority, nil
UUID when absent), matching the code; an action without a capability is
documented as rejected (Strict/HighAssurance) or denied (Development), with
noaction_typefallback; canonical JSON key order is documented as UTF-8
byte order, a deliberate deviation from RFC 8785's UTF-16 order (codec v1
bytes unchanged). -
AuthorizationEngine::validate_evidence_for_dispatchis now documented as
accepting ALLOW and REQUIRE_APPROVAL evidence (behavior unchanged; the
gateway's post-approval path relies on it), and its error message says so.
Newvalidate_allow_evidence_for_dispatchadditionally requires an ALLOW
decision, for dispatch paths without a verified human approval. -
Security (breaking API):
Evidence::verify_key_rotationnow takes the
trusted attester key (&VerifiedPublicKey) and requires a valid attester
signature. It previously accepted an ALLOW decision protected only by the
unkeyedcontext_hash, so anyone could forge an authorized rotation by
rewriting the decision and recomputing the hash. Unsigned evidence (e.g.
Development/Strict without an attester) no longer verifies as a rotation. -
Security (breaking for non-canonical input): uppercase or mixed-case hex is
now rejected for authority signatures,subject_key_hashand
issuer_key_id(Authority::validate), request intent signatures,
evidence attester signatures,Evidence::bind_policy_digestand issuer pin
public keys.hex::decodeaccepted both cases, so one signed document had
several valid encodings. Everything this crate emits is lowercase. -
Fix: a gateway receipt for an executed or confirmed action whose adapter
output was JSONnullnow verifies."output": nulldeserializes to
None, which verification rejected for those statuses although the
attestation signs the digest ofnull. Forexecuted/confirmed, an
absent ornulloutput is now verified as the JSON valuenull; other
statuses still require no output. Serialization is unchanged, so existing
receipts and fixtures are byte-identical. -
Security (behavior change, more restrictive, all semantics versions):
DENY/REQUIRE_APPROVAL/RECOVER rules no longer stop applying because of
theirrequired_capabilityortarget. An authority that lacks the rule's
required_capabilityis still subject to the rule (previously
RequireApproval{transfer, payments:large, amount > 1000}plus
Allow{transfer, payments:write}let an authority without
payments:largemake large transfers without approval), and an action
without a target matches a targeted restrictive rule (previously omitting
the target bypassedDeny target=prod-db). ALLOW rules are unchanged.
Targets stay exact, case-sensitive identifiers; this is now documented.
Policies that usedrequired_capabilityon a DENY rule to deny only the
holders of that capability now deny everyone for that rule's scope.
Such an unbound match (authority lacks the capability, or the action
has no target) always contributes DENY, also for REQUIRE_APPROVAL and
RECOVER rules: it never turns a default deny into an approvable request,
and never emits a recovery obligation, for an authority the rule was not
scoped to. -
Security (behavior change, more restrictive): an integer compared with a
floating-point number no longer fails open in v1 policies. Previously a v1
Deny if amount > 10000was bypassed with"amount": 50000.0, because
every mixed integer/float comparison was "no match". Numeric operators now
compare integer and float exactly (no lossyf64cast);Exact/In
treat a numerically equal float as equal. In every semantics version the
exact result applies to DENY/REQUIRE_APPROVAL/RECOVER rules, and an ALLOW
rule never matches a mixed representation (unchanged). In v2 a mixed value
that is definitively on the safe side of a restrictive rule (5.0against
> 10000) no longer counts as unknown. -
T-013:
praetore_gateway::sandbox::SandboxDispatcher(Unix), an
ActionDispatcherexecuted by the gateway with a closed allowlist
(fs:write_file,fs:delete_file) confined to a root directory.- Root: absolute, canonical, not
/, owned by the gateway user, not
group/other-writable and (macOS) without extended ACL entries; held open
as a descriptor, refused (sandbox_root_replaced) if the path stops
naming that directory and (sandbox_root_insecure) if owner, mode or
ACL change later. Leftover temporary files are swept at open. - Paths: relative only; no
./.., empty components, NUL/control
characters,\, Unicode bidi/zero-width format characters or the
reserved.praetore-tmp-prefix (ASCII case-insensitive); bounded length and depth. Every
component is opened withopenat(O_NOFOLLOW|O_DIRECTORY); symlinks at
any level and mount points are refused. Targets must be absent or
regular single-link files (no hard links, directories, FIFOs, sockets,
devices). - Writes are atomic (
O_EXCLtemp file,fsync,renameat, directory
fsync), mode0600, at most 16 KiB by default. Deletes use
unlinkat(…, 0): never a directory, never a symlink target. - Failures known to have happened before any effect reconcile as
not_applied. praetore init --sandbox-root <dir>/sandbox_rootinconfig.json
enables it inpraetore run(fail closed if the root is invalid or
contains/is inside the gateway directory);praetore demo <dir> write <path> <content>/delete <path>submit the two actions.
demo:set_valueis kept unchanged. Noexec.
- Root: absolute, canonical, not
-
New
ActionDispatcher::preflight(default: admit) returning
DispatchRefused::terminal/::transient. The gateway runs it at
submission, on the approval challenge and decision, and in
claim_dispatchafter the approval is re-verified and the evidence
revalidated, before the journal claim. Status never runs it (it reports
journal state only).- A refusal at submission closes the execution (allowed or held for
approval) asnot_dispatchedwith the new signed reason
dispatch_refused; a held approval closed this way is final and can
never be approved, rejected or dispatched. HTTP 403
action_not_dispatchablecarriesreasonand the signedreceipt. - At the claim, a terminal refusal closes
approved_pending_dispatchas
not_dispatched/dispatch_refused; a transient one leaves it
approved_pending_dispatch(HTTP 503dispatch_temporarily_refused). - A refused challenge or decision changes nothing and consumes nothing.
- A refusal at submission closes the execution (allowed or held for
-
New
NotDispatchedReason::DispatchRefused(dispatch_refused, receipt
schema v3), the only reason also valid forallowedexecutions
(breaking for exhaustive matches; older verifiers reject it as unknown).
Migration0013_dispatch_refusedaccepts it in the journal and
attestation CHECKs, replaces the transition trigger with
validate_execution_journal_transition_v3(the reason is write-once; an
undecided requires_approval row may be closed with it), and refuses any
human decision for an execution closed with a reason. -
Breaking: new
GatewayError::DispatchRefused { key, reason, transient, receipt }variant. -
HTTP:
router_with_options/serve_local_with_options(taking the same
ApiAuth) withHttpOptions::gateway_executes_effects. Then
POST /v1/execute, the approval challenge, decision, dispatch and
/statusrequire exactly onepraetore-exec-mode: gatewayheader (exact
value, at most 16 bytes), checked after caller authentication; otherwise
409exec_mode_gateway_requiredbefore the gateway is called./status
of an approved action answers 409cooperative_exec_rejectedwith
resolutionandexecution(also whileapproved_pending_dispatch), so
an agent is never told to run it. Responses for effects performed by the
gateway carrypraetore-executed-by: gateway. The header is an
unverifiable client declaration: it grants nothing and never changes who
executes or what is journaled. ThepraetoreCLI always sends it. -
Policy size and complexity limits are now public, documented constants in
praetore_core::policy, and exceeding any of them rejects the whole policy
with the typedPraetoreError::PolicyLimitExceeded { limit: PolicyLimit, max }
(error code unchanged:POLICY_EVALUATION_FAIL). Nothing is ignored or
partially applied.- Existing, now public:
MAX_CONDITIONS_PER_RULE= 128 (per scope),
MAX_POLICY_TEXT_BYTES= 1024 (ids, action type, target, condition key),
canonical policy sizeMAX_JSON_VALUE_BYTES= 65 536. MAX_POLICY_RULES= 512 (was 1024, unreachable). It sits above what
fits in 64 KiB of canonical JSON (468 minimal rules with ids
r0..r467; with minimal ids the canonical size limits it to fewer than 480 rules, below 512), so
the canonical size remains the binding limit and no previously valid
policy is rejected by the rule count.- Breaking: new
PraetoreErrorvariant; limit violations no longer surface
asPolicyEvaluationFailed(String). - Breaking: new limits that reject policies valid before this release:
- capability longer than 1024 bytes (
MAX_POLICY_TEXT_BYTES); - condition string (string or object key inside an expected value)
longer than 1024 bytes (MAX_CONDITION_STRING_BYTES); In(array value) with more than 256 values
(MAX_CONDITION_SET_VALUES);- expected value nested deeper than 8 (
MAX_CONDITION_VALUE_DEPTH).
- capability longer than 1024 bytes (
- The policy engine has no regular expressions, so there is no pattern limit.
- Existing, now public:
-
Policy validation now rejects contradictory
PathPrefixconditions on the
same key using segment semantics: two unrelated path prefixes (/aand
/b), or anExactsafe path outside aPathPrefix(/b/xwith/a).
PathPrefixagainstPrefixis rejected only when the two are lexically
unrelated (conservative). -
Documented over-restriction (fail closed): an unsafe value (
%,.., and
forPathPrefixanything not absolute and normalized) matchesDenyand
RequireApprovalrules onPrefix/PathPrefixeven if it lies outside the
rule's prefix; for example a deny on/srv/secretalso denies
/home/50%.txt. Pinned by tests. -
Security:
MatchOperator::Prefixtreats a value with a..segment
(split on/or\), any%, or a NUL as unsafe. Previously an allow
rule with prefix/srv/agent/matched/srv/agent/../../etc/passwd. -
New
MatchOperator::PathPrefix(PolicyCondition::path_prefix): purely
lexical, whole-segment path prefix. Rule prefix and value must be absolute
and normalized (no.,.., empty segments,\, NUL or%; the engine
does not percent-decode). Invalid rule prefixes are rejected when the policy
loads. -
Unsafe values for
PrefixandPathPrefixalways matchDenyand
RequireApprovalrules and never matchAllowrules, in both semantics
v1 and v2 (fail closed; keeps v1 deny rules effective). -
Lexical limits, documented and pinned by tests: no filesystem access
(symlinks out of scope), no Unicode folding (fullwidth.., U+2215),
spaces are significant,...is an ordinary name. No downstream layer may
NFKC-normalize or percent-decode an authorized value. -
Behaviour change: allow rules using
Prefixon values that contain%
(for example percent-encoded URLs) no longer match. -
Breaking:
MatchOperatoris now#[non_exhaustive]; exhaustivematches
outsidepraetore-coreneed a wildcard arm. -
Storage security (PostgreSQL journal and deployment templates):
- Migrations: each migration and its
schema_migrationsrow now commit in
one transaction. 0007-0009 contain their ownBEGIN;/COMMIT;, which
used to end the runner's transaction early (a crash in between left the
migration applied but unrecorded); the runner strips one enclosing
top-level pair and refuses any other transaction control. Migration files
and checksums are unchanged. - New migration 0011 creates the NOLOGIN group role
praetore_runtime
(needsCREATEROLE, or pre-create it) with least-privilege grants. New
migration 0012 makes SQL refuseapproved_pending_dispatch -> dispatched
without an approve decision, with an expiration receipt, or with
expires_atat or before the gateway observation time
(praetore.dispatch_observed_at, set byclaim_dispatch). - TLS: all PostgreSQL connections go through
DatabaseConnector
(rustls). Non-loopback hosts requiresslmode=verify-fulland
sslrootcert;prefer/require/verify-caare refused. The URL is
checked before any socket is opened. - Breaking (gateway service): new
PRAETORE_GATEWAY_MIGRATION_DATABASE_URL
andpraetore-gateway-demo migrate. WithPRAETORE_GATEWAY_ADAPTER=http
orsandboxthe runtime URL no longer runs migrations, and startup
refuses a runtime role that is superuser,BYPASSRLS, ownspraetore
objects or can create in the schema, or a schema that is not current.
The loopback-only database check is replaced by the TLS rule above, so
remote databases (for example inpraetore-data) work with
verify-full. The local demo and the CLI still migrate with the runtime
URL when no migration URL is set and only warn (development only). - Breaking (public API):
MigrationErrorhas new variants
ExplicitTransactionControlandPending; newDatabaseConnector,
verify_runtime_role,verify_schema_current. - Kubernetes templates (not cluster-tested): the execution-claim
admission policy is scoped to claim ConfigMaps and the supervisor CA,
handles DELETE viaoldObject, no longer blockskube-root-ca.crtor
operator ConfigMaps, and lets a dedicatedclaim-retentionidentity (new
Role) and namespace deletion remove claims. The Job policy exempts
finalizer-only updates by the garbage collector / TTL / Job controllers
on Jobs being deleted, so Foreground deletion can finish. Tool runners
no longer share the gateway's proxy: the gateway uses
gateway-egress-proxy(the only source protected tools accept) and
runners keepegress-proxy, which may reach only allowed external
destinations. Breaking: deploy the second proxy and update the gateway's
egress_proxyroute setting.
- Migrations: each migration and its