Documentation
¶
Overview ¶
Package txcguard is the single source of truth for which `_txc.*` envelope paths an author-controlled producer may write or delete.
The `_txc.*` namespace is the chassis control plane carried inside every envelope: identity and routing (`_txc.tenant`, `_txc.src`, `_txc.rid`, `_txc.route.*`), budget (`_txc.fuel_used`, `_txc.ttl`, `_txc._seen`), inbound request facts (`_txc.web.req.*`, `_txc.lmtp.*`, `_txc.client.*`), computed auth results (`_txc.computed.*`), and billing telemetry (`_txc.chat.*`).
Most of it must NOT be settable by a tenant author. But a few `_txc.*` paths are legitimately produced by author-controlled code (the rendered response, flow control). AuthorMayWrite draws that line for every place an author can name a destination: the Tier-2 output sanitizer, the EMIT overlay, SET POST, LOOP SET, the `_txc.delete` target guard (all in chassis/processor), and the author-chosen output target of a trusted `txco://` op (`WITH into`, `to`, `output_path` — see AuthorTarget / ComputedTarget).
It is a leaf package so both the processor and the op handlers (chassis/ops, chassis/server) can share one policy without an import cycle.
The policy is default-CLOSED: only the paths listed here are author-writable under `_txc.`; everything else (including any field added later) is reserved. A false reject is a degraded feature; a missing reservation is a control-plane bypass — so the allowlist is deliberately small and grows only with a test that proves a shipped resonator needs the path.
Index ¶
- Constants
- Variables
- func AuthorMayDelete(path string) bool
- func AuthorMayWrite(path string) bool
- func AuthorTarget(raw string) (path string, ok bool)
- func AuthorWritablePaths() []string
- func BoundedSet(doc, path string, value any) (string, error)
- func BoundedSetBytes(doc []byte, path string, value any) ([]byte, error)
- func BoundedSetRaw(doc, path, raw string) (string, error)
- func ComputedTarget(raw string) (path string, ok bool)
- func NormalizePath(p string) string
- func PadsArray(doc, path string) bool
- func SystemMayWrite(path string) bool
Constants ¶
const MaxArrayPad = 65535
MaxArrayPad is the most `null` elements one author-directed write may make sjson add. 65,535 × `null,` is ~320 KB — far past any real sparse array, far short of hurting the node.
Variables ¶
var ErrArrayPad = errors.New("path would pad an array past the limit: a key in digits is an array index — write it `:123` to make it an object key (quoted in a txcl path: `.\":123\"`)")
ErrArrayPad is returned by BoundedSet* for a write PadsArray refuses.
Functions ¶
func AuthorMayDelete ¶
AuthorMayDelete is the `_txc.delete` target guard: everything an author may write, plus the delete-only facts in authorDeletable. Same normalized-path contract as AuthorMayWrite.
func AuthorMayWrite ¶
AuthorMayWrite reports whether an author-controlled producer (a Tier-2 executor's output, an EMIT overlay, a SET POST, an op's `into`) may write the given envelope path. `path` must already be normalized (no leading "."/"@" — see NormalizePath). Non-`_txc` paths are always writable; under `_txc.` only the allowlisted subtrees are.
`_txc.ttl` is intentionally NOT here: it is writable only via EMIT, and only lowered (the IP-TTL idiom), which the processor's OverlayResponse handles as a special case. A remote/compute/mock producer has no legitimate need to touch the chassis budget, so it cannot.
func AuthorTarget ¶
AuthorTarget resolves the author-chosen output target of a trusted op — a `WITH into = …` or txco://copy's `to`. The op's output merges into the envelope unsanitized (trusted transport), so the target itself is the only place to stop `into = "@tenant"` from forging a control field.
It returns the normalized sjson path and whether the author may write there. raw == "" returns ("", true): no target given, the caller applies its default.
func AuthorWritablePaths ¶
func AuthorWritablePaths() []string
AuthorWritablePaths returns a copy of the author-writable `_txc.` subtrees, for the processor's output projection (which rebuilds `_txc` from exactly these).
func BoundedSet ¶
BoundedSet is sjson.Set for an author-supplied path: it returns doc unchanged and ErrArrayPad instead of padding an array past MaxArrayPad.
func BoundedSetBytes ¶
BoundedSetBytes is sjson.SetBytes with the same bound.
func BoundedSetRaw ¶
BoundedSetRaw is sjson.SetRaw with the same bound.
func ComputedTarget ¶
ComputedTarget is AuthorTarget for the trusted auth helpers' verdict paths (`output_path`, `configured_path`), which additionally may sit under `_txc.computed.*` — their documented home. The value written there is the op's own verdict, never author data, so letting the author pick the leaf under `computed` forges nothing. txco://copy and `into` do NOT get this allowance: they write author data.
func NormalizePath ¶
NormalizePath turns a txcl-authored envelope path (a `WITH into=…` value, a `_txc.delete` entry) into an sjson path: a leading `@` (txcl sugar for `._txc.`) expands, and a leading `.` is dropped. "" stays "" (no path).
func PadsArray ¶
PadsArray reports whether writing path into doc would make sjson pad arrays by more than MaxArrayPad elements in total.
It looks at doc, not just the path, because a numeric key is only an index where sjson would build or extend an array: under a missing parent, a scalar, or an array shorter than the index. Under an existing OBJECT the same key is a plain object key (`by_id.1690000000` into `{"by_id":{}}`), and so is a `:`-forced one anywhere — those are never refused.
func SystemMayWrite ¶
SystemMayWrite reports whether path is in the EXTRA set a system-authored rule may EMIT (`_txc.route.*`). It does not include the author-writable set; callers check that separately. Unlike the author checks it is false outside `_txc`.
Types ¶
This section is empty.
Source Files