docs: enterprise security & deployment hardening guide

[PenguinzTech]

First branch in the stacked-PR series off `v2.1.x`. Documents the enterprise-hardening controls already shipped to `v2.1.x`.

What

• docs/ENTERPRISE_SECURITY.md (new) — operator guide covering:
  • Asymmetric JWT (ES256 default, RS256 fallback): keypair generation (`scripts/gen-jwt-keys.sh`), the `squawk-jwt-keys` Secret, per-service config reference, key rotation, fail-closed tenant requirement, HS256/none rejection.
  • Tenant isolation model (required non-empty `tenant` claim).
  • Supply chain: `cosign verify` + `cosign verify-attestation` (SPDX SBOM) for release images.
  • Kubernetes runtime hardening (`seccompProfile: RuntimeDefault` + securityContext).
  • Renovate digest/vulnerability pinning.
• Wired into the mkdocs nav under a new Security & Operations section.
• Linked from the README Security Features section.

Stack

Base of the chain. Subsequent PRs stack on top:

1. docs/enterprise-hardening ← this PR (→ `v2.1.x`)
2. client-config tokens → asymmetric JWT
3. NTS wire-interop tests
4. Scope-bundle authz refactor
5. Server tokens → SPIFFE/mTLS

Docs-only; no code changes.

🤖 Generated with Claude Code

Summary by Sourcery

Document enterprise-focused security and deployment hardening features and link them into the main docs and README.

Documentation:

• Add an Enterprise Security & Deployment Hardening operator guide covering asymmetric JWT signing, tenant isolation, supply-chain verification, Kubernetes runtime hardening, and dependency pinning.
• Expose the new enterprise security guide in the MkDocs navigation under a Security & Operations section and link it from the README security features list.

[sourcery-ai]

Reviewer's Guide

Adds a new Enterprise Security & Deployment Hardening operator guide and wires it into the docs navigation and README, documenting existing asymmetric JWT, tenant isolation, supply-chain verification, Kubernetes hardening, and Renovate-based dependency pinning features in the v2.1.x line.

File-Level Changes

Change	Details	Files
Document enterprise security and deployment hardening features for operators in a new guide.	Introduce ENTERPRISE_SECURITY.md describing asymmetric JWT signing (ES256/RS256), mandatory claims, key generation and rotation, configuration env vars, and Kubernetes Secret wiring via squawk-jwt-keys. Explain tenant isolation requirements around the non-empty tenant claim and its current enforcement semantics. Describe supply-chain security using cosign keyless signatures and SBOM attestations, including verification examples. Document Kubernetes runtime hardening defaults (securityContext, seccompProfile, non-root, read-only rootfs) for first-party workloads. Outline Renovate configuration for digest pinning and vulnerability-driven updates, plus an operator checklist.	docs/ENTERPRISE_SECURITY.md
Surface the new enterprise security guide in existing top-level documentation entry points.	Extend README Security Features section with bullets on asymmetric JWT and signed images/SBOMs and link to ENTERPRISE_SECURITY.md for hardening guidance. Add a new 'Security & Operations' section to mkdocs navigation with an 'Enterprise Security & Hardening' entry pointing to ENTERPRISE_SECURITY.md.	README.md docs/mkdocs.yml

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've left some high level feedback:

• The guide states verifiers read public keys at verification time and pick up new keys without restart; consider briefly describing the reload mechanism (e.g., file read per request vs cached with TTL) so operators understand latency and failure modes during key rotation.
• The cosign verification examples hardcode the workflow identity regex; consider aligning this pattern with the actual release workflow name or referencing a shared constant/snippet to avoid the docs drifting if GitHub workflow paths change.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- The guide states verifiers read public keys at verification time and pick up new keys without restart; consider briefly describing the reload mechanism (e.g., file read per request vs cached with TTL) so operators understand latency and failure modes during key rotation.
- The cosign verification examples hardcode the workflow identity regex; consider aligning this pattern with the actual release workflow name or referencing a shared constant/snippet to avoid the docs drifting if GitHub workflow paths change.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}