logutil

package
v0.0.0-...-85648f4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 29, 2026 License: AGPL-3.0 Imports: 8 Imported by: 0

Documentation

Overview

Package logutil entity helpers.

These helpers exist to enforce CLAUDE.md convention 18: internal `id INT UNSIGNED` is for FK / JOIN only. Only `public_id BINARY(16)` (UUID v7) may be exposed externally — including in structured logs.

The previous pattern of `slog.Int64("workspace_id", int64(ws.ID))` is forbidden by the forbidigo lint rule; use LogEntity instead.

The lint rule is a nudge, not the boundary. It can only match on the callee name, so it never sees `slog.Any("workspace_id", ws.ID)` nor the loose `logger.Warn(msg, "workspace_id", id)` key/value form. The boundary that actually holds is RedactHandler, which inspects the resolved record: see IsInternalIDKey.

Package logutil provides structured-logging helpers shared across all nodate-flow Go services. The centrepiece is RedactHandler, an slog.Handler wrapper that scrubs secret-looking values before they reach the underlying writer.

Index

Constants

View Source
const InternalIDPlaceholder = "[REDACTED:internal-id]"

InternalIDPlaceholder replaces the value of any numeric attr whose key names a row id. It is deliberately loud: an operator who sees it knows the call site still has to be moved onto LogEntity.

Variables

View Source
var SecretPrefixes = []string{
	"sk-ant-",
	"sk-",
	"sk_live_",
	"mcp_",
	"pat_",
	"rfr_",
	"ghp_",
	"gho_",
	"github_pat_",
	"glpat-",
	"xoxb-",
	"xoxp-",
	"AKIA",
	"AIza",
	"SG.",
	"rk_live_",
}

SecretPrefixes is the fixed list of literal prefixes scanned for in strings passed to Redact. The project rule forbids regex, so this list is the single source of truth for prefix-based secret detection.

Add new prefixes via RegisterPrefix at process startup. Order does not matter; the scanner walks every prefix per input.

Functions

func IsInternalIDKey

func IsInternalIDKey(key string) bool

IsInternalIDKey reports whether an attr key names an internal row id and therefore must not carry a numeric value into a log line.

The predicate is on the key, not the value, because the key is the only thing available at every point the rule has to hold: the call site, the slog.Any escape hatch, the loose key/value form, and the handler. A "_public_id" key is exempt — that is the sanctioned spelling and its value is a UUID string, never a sequence.

The rule is intentionally blunt. A numeric attr under an id-shaped key is either an internal sequence (a leak) or a badly named counter (a naming bug); redacting both is the safe direction, and callers with a genuine number can rename or use LogNumber under a non-id key.

func LogEntity

func LogEntity(name string, publicID uuid.UUID) slog.Attr

LogEntity returns a slog.Attr for a domain entity, keyed "<name>_public_id" with the canonical UUID string form as value.

Use this in place of slog.Int64("<name>_id", ...) for any user-facing entity (workspace, task, user, project, page, label, comment, event, calendar, share, invite, ...). Internal numeric ids must never appear in logs.

Example:

slog.ErrorContext(ctx, "eventbus.Append failed",
    slog.Any("err", err),
    logutil.LogEntity("workspace", ws.PublicID),
    logutil.LogEntity("task", task.PublicID),
)

func LogEntityPID

func LogEntityPID(name string, publicID dbtype.PublicID) slog.Attr

LogEntityPID is the dbtype.PublicID twin of LogEntity for callers that already hold the project's PublicID wrapper (typically code that has just round-tripped through sqlc).

func LogNumber

func LogNumber[T numeric](name string, v T) slog.Attr

LogNumber returns a slog.Attr for a numeric value that is not an entity identifier — a count, a byte size, a duration in milliseconds, an HTTP status code.

It exists because slog.Int / slog.Int64 / slog.Uint64 are forbidden in service code. A callee-name-only lint rule cannot tell slog.Int64("row_count", n) from slog.Int64("task_id", id), so the raw constructors are banned outright and the two legitimate shapes get named helpers: LogEntity for identity, LogNumber for everything else.

Passing an id-shaped key redacts the value rather than logging it, so routing an internal id through LogNumber cannot recreate the leak the ban exists to prevent.

func Redact

func Redact(s string) string

Redact scans s for any registered secret prefix and replaces every match with "[REDACTED:<prefix>]". The scanner is greedy on the secret token: a match runs until the first non-token character (whitespace, quote, comma, brace, bracket, semicolon, or newline).

A prefix only counts where a word starts (see startsWord). Short prefixes otherwise match inside ordinary English — "sk-" sits inside task-filter, risk-adjusted and disk-usage, "pat_" inside compat_mode, "SG." inside MSG. — and the marker is an assertion that a credential was found at that spot. One planted in prose costs twice: the words it swallows are gone from the stored string, and an operator who reads it investigates a leak that never happened.

The rule belongs here rather than in SecretPrefixes: dropping or lengthening a colliding prefix narrows what the scanner catches, while the boundary rule keeps every prefix and only rejects the positions where a secret cannot begin.

func RedactJSONFields

func RedactJSONFields(s string) string

RedactJSONFields walks raw JSON-ish text and replaces the value of any object field whose key matches redactedSensitiveJSONKeys. The scan is a hand-rolled string walk (no regex, no full json.Decode) so it tolerates non-strict JSON such as logs that interleave structured fragments.

The output is also passed through Redact so prefix matches in non-target fields are still scrubbed.

func RegisterPrefix

func RegisterPrefix(p string)

RegisterPrefix adds a literal secret prefix to the redaction scanner. Safe to call from init functions; it is a no-op if the prefix is already registered or shorter than 4 characters (too short to be specific).

Types

type RedactHandler

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

RedactHandler wraps another slog.Handler and scrubs secret-looking values from record attrs before forwarding.

func NewRedactHandler

func NewRedactHandler(inner slog.Handler) *RedactHandler

NewRedactHandler returns a RedactHandler wrapping inner.

func (*RedactHandler) Enabled

func (h *RedactHandler) Enabled(ctx context.Context, lvl slog.Level) bool

Enabled reports whether the inner handler handles records at lvl.

func (*RedactHandler) Handle

func (h *RedactHandler) Handle(ctx context.Context, r slog.Record) error

Handle redacts attrs in-place on a copied record, then forwards.

func (*RedactHandler) WithAttrs

func (h *RedactHandler) WithAttrs(attrs []slog.Attr) slog.Handler

WithAttrs returns a new handler whose inner has the supplied attrs attached (also redacted).

func (*RedactHandler) WithGroup

func (h *RedactHandler) WithGroup(name string) slog.Handler

WithGroup returns a new handler with the supplied group name pushed on the inner handler.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL