aeat.core.redaction package

Redaction-rule registry and the redact() helper family.

The core.classification.RedactionRule shape lives in core.classification so the SensitivityClass policy table can reference rule names without a circular import. This module ships:

• a small in-memory registry of default core.classification.RedactionRule instances keyed by name (NIF, URL, OAuth bearer token, opaque bearer token);

• redact(), the flat-string helper that applies a tuple of rules in declared order;

• redact_structured(), the recursive variant that walks dict / list / tuple containers and redacts every string leaf in place;

• redact_for_log(), the convenience wrapper for log lines and exception messages;

• redact_for_cli_output() and redact_structured_for_cli_output(), the public CLI success-output profile for rendered text and JSON-shaped payloads;

• default_rules_for() and default_rules_for_class(), the resolvers that turn rule names stored on a core.classification.ClassificationPolicy into the underlying core.classification.RedactionRule instances.

The redaction strategies, defined in core.classification.RedactionStrategy, are:

SHA256_PREFIX

Replace the matched span with sha256:<first-8-hex> of its SHA-256 digest. Used for stable identifiers (NIF / NIE / CIF).

HOST_ONLY

For URL-shaped values, retain only <scheme>://<host>; everything else (path, query, fragment) is dropped.

FINGERPRINT

Bearer- / token-shaped values rewrite to token:sha256:<first-8-hex>.

ELLIPSIS

Replace the matched span with three ASCII full stops.

default_rules()

Return the immutable default-rule registry keyed by rule name.

Return type:

Mapping[str, RedactionRule]

Returns:

A read-only Mapping from rule name to core.classification.RedactionRule.

default_rules_for(policy)

Resolve the rule references on a policy to concrete rule instances.

Parameters:

policy (ClassificationPolicy) – A core.classification.ClassificationPolicy whose redaction_rules field carries rule names.

Return type:

tuple[RedactionRule, ...]

Returns:

A tuple of core.classification.RedactionRule instances in the order they were declared on the policy. Names that are not in the default registry are silently skipped: this is deliberate so per-domain policies can reference custom rules registered by other modules.

default_rules_for_class(sensitivity)

Resolve the default rule set for a sensitivity class.

Convenience wrapper that goes through aeat.core.classification._default_policy_for and then default_rules_for() so callers do not need to know about the policy table.

Parameters:

sensitivity (SensitivityClass) – The core.classification.SensitivityClass whose default rules should apply.

Return type:

tuple[RedactionRule, ...]

Returns:

Ordered tuple of rules for that class.

redact(value, *, rules)

Apply rules to a flat string in declared order.

Parameters:

• value (str) – The candidate string. Non-string inputs raise TypeError; consumers must stringify upstream.

• rules (tuple[RedactionRule, ...]) – Ordered tuple of core.classification.RedactionRule instances. Each rule’s pattern is compiled with re.MULTILINE and its strategy is applied to every match.

Return type:

str

Returns:

The redacted string.

Raises:

RedactionError – When value is not a str.

redact_structured(value, *, rules)

Recursively apply rules to every string leaf inside a structure.

Walks dicts, lists, and tuples; redacts every string at the leaves. Non-string non-container values pass through unchanged. The container shape is preserved (dict stays dict, list stays list, tuple stays tuple). The resulting object is a fresh copy at every container level — the input is never mutated.

This is the load-bearing primitive for nested audit payloads: submission audit events and run-trace records are nested dicts, and a flat redact() call would not reach the NIF nested under e.g. event["payload"]["taxpayer"]["nif"].

Parameters:

• value (object) – Any JSON-shaped value: str, int, float, bool, None, dict, list, tuple, or a typed model that has been dumped via model_dump() upstream.

• rules (tuple[RedactionRule, ...]) – Ordered tuple of rules.

Return type:

object

Returns:

A redacted copy of value with the same nested shape.

redact_for_log(text)

Redact a string against the AUDIT-class rule set for log/error use.

Convenience wrapper for call sites that construct exception messages or log lines containing operator-controlled PII (NIF / NIE / CIF, OAuth tokens, session URLs). Raised exceptions interpolate user-controlled identifiers into exc.args[0]; the standard logging filter covers the logging path but not str(exc) flowing through Typer’s default error renderer, JSON envelopes, or observability sinks that capture exception text without going through the filter. Redact at the construction site so the secret is never in the exception’s message field to begin with.

The AUDIT rule set is the right default for exception text: it redacts NIF (sha256-prefix), URL host-only, and bearer-token fingerprints. The core.classification.SensitivityClass identity and diagnostic classes are named for at-rest identity data and observability sinks respectively; AUDIT is the canonical class for the log/error path.

Parameters:

text (str) – The log-shaped string to redact.

Return type:

str

Returns:

The redacted string.

redact_for_cli_output(text, *, reveal_identifiers=False)

Redact a rendered operator-facing CLI output line.

The CLI public-output profile composes the AUDIT rule set used by logs/errors with additional profile, bucket, and secure-object key handling. It deliberately keeps display labels untouched and targets machine identifiers, storage lookup values, URL paths, bearer tokens, and tax identities that should not be emitted as success output.

Parameters:

• text (str) – Rendered CLI text.

• reveal_identifiers (bool) – When True, opaque profile and bucket identifier surfaces are emitted raw (the operator opt-out for multi-client disambiguation). Tax identities, tokens, URLs, and secure-object keys stay redacted regardless.

Return type:

str

Returns:

Redacted CLI-safe text.

Raises:

RedactionError – When text is not a str.

redact_structured_for_cli_output(value, *, reveal_identifiers=False)

Recursively redact a JSON-shaped value for public CLI output.

Unlike redact_structured(), this helper is key-aware so values under canonical profile, bucket, and secure-object key fields become stable placeholders before JSON serialization. Container shape is preserved and the input object is never mutated.

Parameters:

• value (object) – JSON-shaped payload to prepare for CLI success output.

• reveal_identifiers (bool) – When True, opaque profile and bucket identifier surfaces are emitted raw (the operator opt-out for multi-client disambiguation). Tax identities, tokens, URLs, and secure-object keys stay redacted regardless.

Return type:

object

Returns:

A redacted copy with the same nested shape.