Skip to content

fix: make the first-run secret warning actionable - #284

Merged
dgenio merged 7 commits into
mainfrom
agent/first-run-secret-checklist
Aug 16, 2026
Merged

fix: make the first-run secret warning actionable#284
dgenio merged 7 commits into
mainfrom
agent/first-run-secret-checklist

Conversation

@dgenio

@dgenio dgenio commented Aug 11, 2026

Copy link
Copy Markdown
Owner

Closes #215.

What changed

  • Makes the missing-WEAVER_KERNEL_SECRET warning explain the operational consequence instead of just saying a development secret was generated:
    • process-local random signing state;
    • tokens/audit-chain signatures become invalid after restart;
    • another process does not share that signing state;
    • direct link to production guidance.
  • Adds docs/production-checklist.md covering principal authentication, signing secret/key lifecycle, capability classification, allow+deny tests, token use/revocation, mediation coverage, multi-worker consistency, audit retention, redaction limits, protocol versions, supply-chain checks, and fail-closed operational behavior.
  • Links the checklist from README.
  • Adds tests proving:
    • missing secret logs the actionable warning exactly once;
    • environment secret avoids the warning;
    • explicit constructor secret avoids the warning.

Why

The old warning created the worst combination: friction for first-time evaluators without giving production operators enough information about what the fallback actually means. This keeps the safe default loud, but makes the remediation and consequences explicit.

Deliberate design choice

I did not add a dev_mode=True / warning-suppression flag. Supplying an explicit secret is already the correct acknowledgement path; another switch would create a configuration that is easier to cargo-cult into production.

Compatibility

Warning text changes. Runtime signing semantics are unchanged.

Validation

New tests pin the warning behavior and no runtime authority/policy behavior changes.

@dgenio
dgenio marked this pull request as ready for review August 11, 2026 06:12
Copilot AI lite review requested due to automatic review settings August 11, 2026 06:12
Copilot AI reviewed Aug 11, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Improves the first-run warning when WEAVER_KERNEL_SECRET is missing by making the remediation and operational consequences explicit, and adds operator-facing production guidance.

Changes:

  • Update the dev-secret warning message to describe concrete runtime consequences and link to production guidance.
  • Add a comprehensive docs/production-checklist.md and link it from the README.
  • Add tests to pin warning emission behavior and secret precedence.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

File Description
src/weaver_kernel/_secrets.py Makes the missing-secret warning actionable and links to production checklist.
tests/test_secrets.py Adds tests for one-time warning behavior and env/explicit secret precedence.
docs/production-checklist.md Adds operator checklist for production readiness and security posture.
README.md Links the new production checklist from the docs index section.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Comment thread docs/production-checklist.md
Comment thread src/weaver_kernel/_secrets.py Outdated
Comment thread tests/test_secrets.py
@dgenio
dgenio merged commit 34ad81d into main Aug 16, 2026
11 checks passed
dgenio pushed a commit that referenced this pull request Aug 17, 2026
@claude
fix: close remaining arg-constraint type gaps; rebase onto main
64d6627 
Red-team follow-up (PR #259 review by dgenio):

- enforce_arg_constraints now validates inner rule values, not just the outer
  containers: a non-string `prefix` value (e.g. {"prefix":{"path":123}}) and a
  non-string / unhashable `allowed_keys` element (e.g. a nested list) previously
  reached value.startswith()/set(allowed) and raised an untyped TypeError that
  escaped the audited denial path. Both now fail closed with
  TokenScopeError(arg_constraint_violation). Regression cases added.

Rebase integration onto current main (was 6 commits behind):
- Reconciled with the #286 shared policy rule-chain refactor: DefaultPolicyEngine
  keeps max_ttl_s (#203) on top of the new DefaultPolicyRuleChain structure.
- Merged #284 (actionable secret warning) with the #185 rotation keyring in
  _secrets.py; merged docs/security.md and CHANGELOG.
- coding_agent_demo.py (#253) now imports HMACTokenProvider from _hmac_provider,
  since tokens.py no longer re-exports it (cycle fix).
- CHANGELOG lifecycle entries moved under [Unreleased]; dropped the stale
  "removed rate-limit aliases" note (main keeps them) and the stale re-export
  claim.

make ci green: 912 passed, 1 skipped.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019WRxQL8t2Uusa6845jWtVV
@dgenio dgenio mentioned this pull request Aug 17, 2026
Merged
dgenio added a commit that referenced this pull request Aug 19, 2026
@dgenio @claude
feat: harden capability-token lifecycle (#259)
ab594b4 
* feat: harden the capability-token lifecycle — rotation, TTL, invoke-time enforcement

Groups six issues that share one implementation path (a CapabilityToken from
issuance through invoke-time enforcement) and one code area.

- #185 Signing-key rotation: HMACTokenProvider(secrets={key_id: secret},
  active_key_id=...) verifies previous-key tokens during an overlap window;
  key_id is signed into the payload; unknown key id fails closed. New
  WEAVER_KERNEL_SECRETS / WEAVER_KERNEL_ACTIVE_KEY env resolution.
- #200 CapabilityToken.from_dict raises typed TokenInvalid on malformed input
  instead of leaking KeyError/ValueError.
- #203 Per-grant TTL: grant_capability(ttl_s=...) with DefaultPolicyEngine(
  max_ttl_s=...); non-positive or over-max is denied (not clamped), audited.
- #183 Signed argument constraints (constraints["args"]: allowed_keys/pinned/
  prefix) enforced at invoke() and invoke_stream() before the driver runs,
  raising TokenScopeError with a failure trace; dry-run predicts the same.
- #170 Opt-in per-invocation rate limiting (Kernel(invoke_rate_limits=...)),
  default off, race-free check-then-record; dry-run never consumes.
- #224 ADR docs/adr/0001-token-signing-evolution.md (HMAC vs macaroon vs
  Biscuit, measured); recommends HMAC + re-issuance now. No code/deps change.

To stay within the AGENTS.md 300-line module budget, HMACTokenProvider moved to
_hmac_provider.py (re-exported; logger name unchanged) and helpers were split
into _token_signing.py, policy_ttl.py, kernel/_grant.py, kernel/_constraints.py.
Removed the private policy._DEFAULT_RATE_LIMITS/_SERVICE_RATE_MULTIPLIER aliases
(part of #196). Breaking: the signed payload now includes key_id, so
pre-upgrade tokens no longer verify (accepted pre-1.0; legacy config unchanged).

make ci: fmt-check, lint, mypy --strict (67 files), 856 passed / 1 skipped,
94% branch coverage, all 13 examples.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019WRxQL8t2Uusa6845jWtVV

* fix: break token-module import cycle (CodeQL) and harden fail-closed inputs

Addresses PR #259 review:

- CodeQL cyclic-import errors: the tokens <-> _hmac_provider re-export and the
  tokens <-> _token_signing TYPE_CHECKING import formed cycles. Made the graph
  acyclic — _token_signing no longer references tokens (build_signable_payload
  inlined into CapabilityToken._signable_payload), and tokens no longer
  re-exports HMACTokenProvider. Importers (__init__, kernel, cli/_doctor) now
  import HMACTokenProvider from _hmac_provider; the public
  `from weaver_kernel import HMACTokenProvider` is unchanged.
- Copilot: from_dict now coerces naive ISO timestamps to UTC, so a malformed
  token can't cause a naive-vs-aware TypeError at verify() time.
- Copilot: DefaultPolicyEngine(max_ttl_s=...) now rejects non-SafetyClass dict
  keys at construction (fail closed instead of silently ignoring the cap).
- Copilot: enforce_arg_constraints fails closed (TokenScopeError,
  arg_constraint_violation) on malformed args.allowed_keys/pinned/prefix types
  instead of raising an untyped TypeError or silently ignoring them.

Tests added for each. make ci green: 861 passed, 1 skipped, 94% branch coverage.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019WRxQL8t2Uusa6845jWtVV

* fix: close remaining arg-constraint type gaps; rebase onto main

Red-team follow-up (PR #259 review by dgenio):

- enforce_arg_constraints now validates inner rule values, not just the outer
  containers: a non-string `prefix` value (e.g. {"prefix":{"path":123}}) and a
  non-string / unhashable `allowed_keys` element (e.g. a nested list) previously
  reached value.startswith()/set(allowed) and raised an untyped TypeError that
  escaped the audited denial path. Both now fail closed with
  TokenScopeError(arg_constraint_violation). Regression cases added.

Rebase integration onto current main (was 6 commits behind):
- Reconciled with the #286 shared policy rule-chain refactor: DefaultPolicyEngine
  keeps max_ttl_s (#203) on top of the new DefaultPolicyRuleChain structure.
- Merged #284 (actionable secret warning) with the #185 rotation keyring in
  _secrets.py; merged docs/security.md and CHANGELOG.
- coding_agent_demo.py (#253) now imports HMACTokenProvider from _hmac_provider,
  since tokens.py no longer re-exports it (cycle fix).
- CHANGELOG lifecycle entries moved under [Unreleased]; dropped the stale
  "removed rate-limit aliases" note (main keeps them) and the stale re-export
  claim.

make ci green: 912 passed, 1 skipped.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019WRxQL8t2Uusa6845jWtVV

---------

Co-authored-by: Claude <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot
Copilot review effort
Applies to this pull request for everyone.Learn more about Copilot code review.
Copilot left review comments

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Improve the first-run secret experience: explicit dev mode and a production checklist

2 participants

@dgenio