Documentation
¶
Overview ¶
Package mask provides emission-time masking of secret values in Rune's output streams, so credentials never reach a terminal transcript or an agent's chat history (spec 013-secret-masking).
A Set is derived once per run from the task environment's variable NAMES (built-in sensitive patterns plus `set secrets` declarations, minus `set unmasked` exemptions) and is immutable afterwards. A Writer wraps an output stream and replaces every verbatim occurrence of a Set entry with the fixed Placeholder before bytes reach the underlying writer.
Invariants:
- Values (or lines of multi-line values) shorter than MinLen bytes are never tracked; multi-line values are tracked per line only, keeping the Writer's carry bound small.
- The Writer is safe for concurrent use and holds back at most maxEntryLen−1 bytes (a stream tail that is a proper prefix of an entry).
- Flush emits the carry after masking any completed entries in it; callers may only flush when no producer can still be writing (the engine flushes after the scheduler has joined every task).
- An empty Set means callers skip wrapping entirely, so secret-free runs stay byte-identical.
Index ¶
Constants ¶
const ( // Placeholder replaces every occurrence of a tracked secret value on every // output surface (contract §2.2). Placeholder = "***" // MinLen is the minimum tracked value (or value-line) length in bytes; // shorter values are never value-masked to avoid corrupting unrelated // output (FR-007). MinLen = 4 )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Set ¶
type Set struct {
// contains filtered or unexported fields
}
Set is an immutable collection of secret values to mask. It is safe for concurrent readers.
func NewSet ¶
NewSet derives the secret-value set from KEY=value environment pairs. A variable is tracked when its name matches a built-in pattern and is not exempted, or when it is explicitly declared. Values are split per line; lines shorter than MinLen are dropped (data-model derivation steps 1–4).
func (*Set) Empty ¶
Empty reports whether the set tracks no values; callers skip wrapping writers entirely for an empty set (FR-008). A nil Set is empty.
func (*Set) MaskString ¶
MaskString replaces every occurrence of every entry in one shot (no carry).
type Writer ¶
type Writer struct {
// contains filtered or unexported fields
}
Writer wraps an output stream and masks every occurrence of the Set's entries at emission time, including occurrences split across Write calls (FR-003/FR-004). It is safe for concurrent use: parallel tasks share the engine's streams.
func NewWriter ¶
NewWriter wraps dst. Callers should not wrap at all when set.Empty() — that keeps secret-free runs byte-identical (FR-008).
func (*Writer) Close ¶
Close flushes the writer. It never closes the underlying stream (the wrapped writer is typically os.Stdout/os.Stderr or a caller-owned buffer).
func (*Writer) Flush ¶
Flush emits the withheld tail. Completed entries inside it are masked; a genuinely incomplete prefix is emitted verbatim (it is not the secret). Callers may only flush when no producer can still be writing — the engine flushes after the scheduler has joined every task (research.md D4).
Source Files