Auth & Secrets
Authentication controls who can trigger runs and access evidence. Secrets handling focuses on risk mapping and best-effort redaction—not absolute guarantees.
What this page can (and cannot) claim
✓Mechanical claims
- • Identity tracking: Producer, viewer, and subject identities are recorded in the envelope.
- • Redaction receipts: The
redactions[]array logs which rules were applied and where. - • Deny-by-default: Public exports are restricted by
public_allowlist_fields. - • Classification: Artifacts carry a classification in
redaction.class.
✗No-claims
- • No “secrets safe” guarantee: Redaction is best-effort; unknown patterns can slip through.
- • No allowlist wisdom: The system filters by your rules, not by inherent safety.
- • No isolation enforcement: Network/sandbox security is outside Quoderat's scope.
- • No perfect masking: Redaction receipts are proof of intervention, not absence of secrets.
Mental model: Three identities
Viewer Identity (Who can read)
Entities (UI users or API consumers) authorized to view runs and export evidence packs.
Producer Identity (Who can write)
The Server and Worker instances that emit receipts and register step/artifact metadata.
Subject Identity (What was executed)
The immutable anchor of the work—typically repo_url, commit_sha, and the reported runner_context.
Auth surfaces
UI → Server API
- • Authentication: The UI authenticates to the Server API via secure sessions or tokens.
- • Authorization gates: Logic gates determine which runs a viewer can see, which projects they can trigger, and which evidence packs they can export.
Worker → Server API
- • Registration: Workers must authenticate to the Server when they register and throughout run execution.
- • Attribution: The Server must be able to mechanically attribute every envelope: “This record was produced by Worker X (reported identity) at Time Y.”
External Systems → Webhooks
- • Verification: Inbound webhooks are treated as untrusted input unless signatures are verified.
- • Recording: Quoderat records the verification outcome as an observation (e.g.,
signature_verified: true) that cites the raw request artifact as its basis.
Where secrets can surface
Secrets often leak inadvertently through standard engineering outputs. High-risk areas include:
- stdout / stderr: Tool output may echo tokens, keys, or connection strings.
- Automated reports: junit.xml or coverage files containing stack traces with tokens.
- Build logs: Detailed output from docker build, npm, pip, or other package managers.
- Environment context: Environment variables accidentally captured into the runner_context.
- Webhook payloads: Inbound data containing tickets, emails, or internal URLs.
Quoderat's position on secrets
Quoderat does not make absolute “safe” guarantees. Instead, it provides auditable hygiene:
- Redaction receipts: Quoderat records redaction interventions as receipts in the
redactions[]array. - Deny-by-default: Public exports are restricted by
public_allowlist_fields. - Mechanical proof: The system provides a record of what was masked, rather than a claim that no secrets exist.
Minimum safe defaults
- Select a single token mechanism for UI/API access (sessions or bearer tokens).
- Implement per-project and per-run access controls.
- Rotate worker credentials regularly; ensure they never appear in logs.
- Configure artifact store credentials with minimum required permissions.
- Add regex patterns for common tokens (JWT, API keys) to the global policy.
When sharing externally
- Always export a “Public Pack” for external stakeholders; keep the internal envelope private.
- Validate
integrity.hash_chainbefore sharing. - Spot-check at least one artifact hash against its content.
- Verify that raw logs are excluded from the public pack (unless explicitly intended).
- Confirm observations cite basis artifacts that are also present in the public pack; if not, treat them as informational only.
Reviewer checklist
When evidence is shared, a reviewer should inspect:
Policy anchor
The policy_id or policy_hash recorded in the envelope.
Redaction log
Entries in redactions[] proving that masking rules were active.
Log presence
Whether raw logs are present in a public pack (they generally should be excluded).
Observation basis (critical)
Whether observations cite basis_artifact_ids that are also present in the shared pack. If basis artifacts are missing, treat the observation as informational only—not verifiable evidence.
Troubleshooting
Why is my public pack missing fields?
The allowlist is deny-by-default; you must explicitly permit fields to be visible.
Why do I see redactions but still worry?
Redactions are receipts of intervention, not absolute guarantees of safety. Unknown patterns can slip through.
Why does my worker fail to register?
Check for an authentication token or producer identity mismatch between the Worker and Server. Verify the server base URL is correct (see #serverBaseUrlFromConfig).
Why are observations not verifiable?
Check that the observation's basis_artifact_ids are present in the pack. If not, the observation is informational only.
Next steps
- Policies — configuring masking and allowlists
- Webhooks — handling untrusted inbound triggers
- API Reference — programmatic auth and consumption
- Concepts — the Evidence Envelope contract
- Events (SSE) — real-time monitoring vs. authoritative records