secretnat

type CustomDetector ¶

type CustomDetector struct {
	Name    string `yaml:"name" json:"name"`
	Pattern string `yaml:"pattern" json:"pattern"`
	// Prefix is used for the synthetic token in semantic mode.
	Prefix string `yaml:"prefix" json:"prefix"`
}

CustomDetector is the user-facing config shape for plugging in an extra regex detector without writing code (config: snat.custom_detectors).

type Detector ¶

type Detector interface {
	// Name identifies the detector (stable, lowercase, e.g. "github").
	Name() string
	// Detect returns all secret spans in text. Spans must not overlap
	// within a single detector's result.
	Detect(text string) []Match
	// SyntheticPrefix is the default format-preserving prefix for tokens
	// minted from this detector's matches ("" when not applicable).
	SyntheticPrefix() string
	// Validate post-filters a candidate secret value (entropy / length /
	// shape checks). Candidates failing Validate are not translated.
	Validate(candidate string) bool
}

Detector is the plugin interface for secret detection. Implementations must be safe for concurrent use and should detect in linear time (RE2 regexps satisfy this).

type Generator ¶

type Generator struct {
	// contains filtered or unexported fields
}

Generator mints synthetic tokens for detected-tier secrets. Tokens embed the fixed "SNAT" marker plus a fixed-width sequence number: distinctive enough that no built-in detector re-matches its own output (idempotent sanitize) and no real-world text collides with it.

func NewGenerator(mode Mode) *Generator

func (g *Generator) Mode() Mode

func (g *Generator) Synthetic(m Match, seq int) string

type KnownSecret ¶

type KnownSecret struct {
	Name  string
	Value string
}

KnownSecret is one (name, value) pair from the host's secret store.

type KnownSet ¶

type KnownSet struct {
	// contains filtered or unexported fields
}

KnownSet is an immutable snapshot of the known-tier secrets. Rebuild (via NewKnownSet) and atomically swap on every secret-store mutation.

func NewKnownSet(secrets []KnownSecret) *KnownSet

func (ks *KnownSet) Size() int

func (ks *KnownSet) Tokens() []string

func (ks *KnownSet) ValueFor(name string) (string, bool)

type Manager ¶

type Manager struct {
	// contains filtered or unexported fields
}

Manager owns the process-wide SecretNAT state: options, detector registry, the known-secret snapshot, and one Session per conversation (pane / agent / humanoid). Safe for concurrent use.

func NewManager(opts Options) (*Manager, error)

func (m *Manager) CloseSession(convID string)

func (m *Manager) DetectorNames() []string

func (m *Manager) Enabled() bool

func (m *Manager) Mode() Mode

func (m *Manager) RestoreDisplay() bool

func (m *Manager) Session(convID string) *Session

func (m *Manager) SetEnabled(v bool)

func (m *Manager) SetMode(mode Mode)

func (m *Manager) Stats() ManagerStats

func (m *Manager) SweepExpired() int

func (m *Manager) UpdateKnownSecrets(secrets []KnownSecret)

type ManagerStats ¶

type ManagerStats struct {
	Enabled        bool
	Mode           Mode
	RestoreDisplay bool
	KnownSecrets   int
	Sessions       int
	Detected       int
	Restored       int
	PerDetector    map[string]int
}

ManagerStats is the value-free aggregate metrics view (##snat status).

type MappingEntry ¶

type MappingEntry struct {
	Token    string
	Detector string
	Hits     int
}

MappingEntry is the value-free view of one translation, safe to display (##snat list) and log: it carries the synthetic token and metadata but NEVER the real value.

type MappingTable ¶

type MappingTable struct {
	// contains filtered or unexported fields
}

MappingTable is the in-memory, per-conversation bidirectional map between real secret values and synthetic tokens.

Security invariants:

• lives only in memory; MarshalJSON fails loudly so the table can never ride along an accidentally-serialized struct into KV or logs;
• real values are reachable only via RestoreAll / lookups, never via Entries()/stats.

func NewMappingTable() *MappingTable

func (t *MappingTable) Entries() []MappingEntry

func (t *MappingTable) IsToken(s string) bool

func (t *MappingTable) LastUsed() time.Time

func (t *MappingTable) MarshalJSON() ([]byte, error)

func (t *MappingTable) MaxTokenLen() int

func (t *MappingTable) PerDetector() map[string]int

func (t *MappingTable) RestoreAll(text string) (string, int)

func (t *MappingTable) RestoredCount() int

func (t *MappingTable) RevealToken(token string) (string, bool)

func (t *MappingTable) Size() int

func (t *MappingTable) TokenFor(value, detector string, mint func(seq int) string) string

func (t *MappingTable) Tokens() []string

type Match ¶

type Match struct {
	// Start/End delimit the secret VALUE itself (not the surrounding
	// context a detector may have matched, e.g. the "PASSWORD=" key of an
	// env-style line or the "user:" part of a database URL).
	Start, End int
	// Type is the detector name that produced this match (e.g. "stripe").
	Type string
	// Confidence in [0,1]; when overlapping matches conflict, the leftmost-
	// longest span wins first, then higher confidence.
	Confidence float64
	// Prefix is the format-preserving prefix carried into the synthetic
	// token in semantic mode (e.g. "sk_live_", "ghp_"). Empty when the
	// secret has no meaningful prefix (passwords, env values).
	Prefix string
	// Synthetic optionally overrides synthetic-token generation for this
	// match (used e.g. by the JWT detector to preserve the three-segment
	// shape). When nil the Generator's default format applies.
	Synthetic func(seq int) string
}

Match is one detected secret span within a scanned text.

type Mode ¶

type Mode string

Mode selects the synthetic-token style.

const (
	// ModeSemantic preserves the credential's visible type so the LLM keeps
	// full context: "sk_live_SNAT000042", "ghp_SNAT000007".
	ModeSemantic Mode = "semantic"
	// ModePrivate hides even the provider/type: "SECRET_TOKEN_042". Better
	// privacy, less context for the LLM.
	ModePrivate Mode = "private"
)

func ParseMode(s string) Mode

type NATProvider ¶

type NATProvider struct {
	// contains filtered or unexported fields
}

NATProvider decorates an AgenticProvider with outbound sanitization: every request's conversation, tool inputs, and system prompt are deep-sanitized (on copies — the caller's conversation is never mutated) before reaching the wire. It performs NO inbound restore: synthetic tokens deliberately stay in the assistant turns so real values never enter the persisted conversation. The orchestrator restores just-in-time at tool execution and (optionally) for display.

Sanitize is idempotent, so text already sanitized at source (tool results, user turns) passes through byte-identical — safe for prompt caching.

func (n *NATProvider) Complete(ctx context.Context, prompt string) (string, error)

func (n *NATProvider) CompleteWithTools(
	ctx context.Context,
	conversation []provider.ConversationTurn,
	tools []provider.ToolSpec,
	systemPrompt string,
) (*provider.AgenticResponse, error)

func (n *NATProvider) Name() string

func (n *NATProvider) Unwrap() provider.AgenticProvider

func (n *NATProvider) WithMaxTokens(maxTokens int) provider.AgenticProvider

func (n *NATProvider) WithModelEffort(model, effort string) provider.AgenticProvider

type Options ¶

type Options struct {
	// Enabled is the session-wide default; individual sessions may override
	// (##snat on|off on a pane).
	Enabled bool
	// Mode selects semantic (type-preserving) or private tokens.
	Mode Mode
	// RestoreDisplay controls whether displayed LLM output has tokens
	// restored to real values. Default false: the pane display buffer is
	// persisted and forwarded to listeners, so restoring would re-leak.
	RestoreDisplay bool
	// MappingTTL expires idle per-conversation mappings; 0 = conversation
	// lifetime (mappings die when the session closes or the process exits).
	MappingTTL time.Duration
	// DisabledDetectors removes built-in detectors by name.
	DisabledDetectors []string
	// CustomDetectors adds user-defined regex detectors.
	CustomDetectors []CustomDetector
}

Options configures a Manager. Zero value = disabled.

type Registry ¶

type Registry struct {
	// contains filtered or unexported fields
}

Registry holds an ordered, fixed set of detectors. Order is significant: it is the deterministic tiebreak for equal-length overlapping matches, so a Registry must not be mutated after construction.

func NewDefaultRegistry(disabled []string, custom []CustomDetector) (*Registry, error)

func NewRegistry(detectors ...Detector) *Registry

func (r *Registry) DetectAll(text string) []Match

func (r *Registry) Names() []string

type Session ¶

type Session struct {
	// contains filtered or unexported fields
}

Session is one conversation's translation context: the manager's shared detector/known state plus a private mapping table. All methods are safe on a nil receiver (no-ops), for callers that thread the handle unconditionally.

func (s *Session) Enabled() bool

func (s *Session) ID() string

func (s *Session) NewStreamRestorer() *StreamRestorer

func (s *Session) Restore(text string) string

func (s *Session) RestoreDisplay() bool

func (s *Session) RestoreJSON(raw json.RawMessage) json.RawMessage

func (s *Session) Reveal(token string) (value, source string, ok bool)

func (s *Session) Sanitize(text string) string

func (s *Session) SanitizeJSON(raw json.RawMessage) json.RawMessage

func (s *Session) SetOverride(v *bool)

func (s *Session) Stats() SessionStats

type SessionHandle ¶

type SessionHandle interface {
	Enabled() bool
	Sanitize(text string) string
	SanitizeJSON(raw json.RawMessage) json.RawMessage
	Restore(text string) string
	RestoreJSON(raw json.RawMessage) json.RawMessage
	RestoreDisplay() bool
	NewStreamRestorer() *StreamRestorer
	Stats() SessionStats
}

SessionHandle is the interface the agentic layer consumes. All methods are safe on a nil *Session and cheap no-ops when disabled, so callers can thread it unconditionally.

type SessionStats ¶

type SessionStats struct {
	Detected    int            // total value→token replacements (both tiers)
	Restored    int            // total token→value replacements
	Mappings    int            // distinct detected-tier mappings alive
	PerDetector map[string]int // hit counts per detector
	Entries     []MappingEntry // token/detector/hits — never values
	Override    *bool          // per-session enable override (nil = default)
}

SessionStats is the value-free per-session metrics view.

type StreamRestorer ¶

type StreamRestorer struct {
	// contains filtered or unexported fields
}

StreamRestorer restores synthetic tokens in a streamed text where a token may straddle chunk boundaries. It emits text as soon as it provably cannot be the beginning of a restorable token, holding back at most one max-token-length tail — O(1) memory, imperceptible latency.

Usage: out := r.Feed(delta) per chunk, then out := r.Flush() at stream end (message_stop) to drain the held-back tail.

func NewStreamRestorer(restore func(string) string, candidates func() []string) *StreamRestorer

func (r *StreamRestorer) Feed(chunk string) string

func (r *StreamRestorer) Flush() string