Repository Docs & Knowledge Base

Consolidated Spensara documentation repository (722 Markdown & architecture documents in ../repository)

Built Word Documents (.docx): Spensara Overview (.docx) Capability Assessment (.docx) Brink POS Ingestion Analysis (.docx) The Borg Ingestion Architecture (.docx)

Implementation Specs (157)

Detailed engineering and feature implementation specifications.

implementation-specs/specs/CustomerCredentialCustomHeaders/TASK1.2.md 2,963 bytes · Updated Oct 23, 2026 10:44 AM EDT

Raw File

TASK 1.2: Define redaction and update-preservation rules for secret header values

Summary

Extend the current secret-handling contract so custom header values behave like existing token fields in admin read and update flows.

This task exists because custom headers may contain secrets, and the current code already has a specific redaction/preservation pattern for accessToken and locationToken.

Dependencies

TASK 1.1

Files to Modify

This task is primarily a design and implementation-alignment task.

Expected implementation touch points for later phases include:

backend/Kds.Ai.ApiService/Services/CustomerManagementService.cs
backend/Kds.Ai.ApiService/Endpoints/AdminCustomerEndpoints.cs
backend/tests/Kds.Ai.ApiService.Tests/Kds.Ai.ApiService.Tests/Endpoints/AdminCustomerEndpointsTests.cs

Required Behavior

Document and lock:

how admin GET/list responses represent custom header values,
how update requests preserve existing values for unchanged secret headers,
how partial edits behave when some headers are removed, added, or modified,
whether redaction applies to all custom header values or only selected ones,
how a caller intentionally clears one previously stored header.

Recommended contract for this slice:

admin responses return real header names but redact all stored header values,
the same redaction token used for other secrets, currently [REDACTED], is reused for custom header values,
when an update request sends a header value equal to [REDACTED] for an existing stored header with the same name, the previous secret value is preserved,
when an update request omits a previously stored header entirely, that header is removed,
when an update request sends a new header with [REDACTED] as its value and no existing stored value exists for that name, validation fails,
create flows never accept [REDACTED] as a real new secret value.

Implemented decision for this task:

redaction applies to all customHeaders values in admin responses,
preservation is keyed by header name using case-insensitive matching,
omission means deletion during full credential replacement updates,
explicit new values overwrite stored values,
[REDACTED] is valid only as a preserve-existing marker for matching stored headers during update.

Acceptance Criteria

[ ] Response redaction behavior is defined for custom header values
[ ] Update-preservation behavior is defined for unchanged header secrets
[ ] Add/update/remove semantics for individual headers are defined
[ ] Invalid [REDACTED] create or rename scenarios are explicitly rejected
[ ] The rules are consistent with existing token-field handling

Notes

The key risk in this slice is accidentally leaking secret header values through admin responses or overwriting them during innocent edits.
Prefer the same mental model that the current API already uses for token secrets.