security: consolidate v3.1.0 hygiene and dependency remediation

[devin-ai-integration]

Pull Request Description

Summary

Consolidates the green v3.1.0 hygiene stack (#297-#300) with the actionable Dependabot queue (#292-#296), resolves the pydantic/pydantic-core lockstep conflict, remediates the two reviewed non-justified # nosec findings, and clarifies documentation language so current consumers are stated as Mercury Agent and FINDΩYOU™ (private repo). This preserves version 3.1.0, keeps public API signatures intact, preserves the ama_cryptography_monitor compatibility shim, and leaves C source / constant-time code / KAT vectors untouched.

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Security fix (addresses a security vulnerability)
• Performance improvement (improves performance without changing functionality)
• Documentation update (changes to documentation only)
• Code refactoring (improves code quality without changing functionality)
• Test enhancement (adds or improves tests)
• Dependency update (updates dependencies)

Related Issues

Fixes #
Relates to #292, #293, #294, #295, #296, #297, #298, #299, #300

Motivation and Context

Why is this change required?

The original hygiene stack was green, but closeout review identified two pre-existing # nosec findings that needed corrective engineering rather than documentation-only disposition: a demo hardcoded password and legacy RFC 3161 timestamp URL handling that claimed HTTPS enforcement while accepting HTTP. The Dependabot pydantic and pydantic-core PRs also could not pass independently because their lockfile pins are interdependent. Final documentation review also required exact current-consumer wording rather than downstream/later phrasing.

What problem does it solve?

This creates a single mergeable closeout branch that resolves the remaining non-justified suppressions, preserves the documentation/tooling cleanup, consolidates the dependency queue into a compatible lock state, states the current AMA consumers accurately, and keeps all reviewed AI/bot feedback resolved.

Cryptographic Impact

Security Impact Assessment

• No cryptographic security impact
• Adds new cryptographic primitive (requires extensive review)
• Modifies existing cryptographic operation (requires security analysis)
• Changes key management approach
• Affects multiple security layers
• Performance optimization only (no security changes)

This is a security-hardening hygiene change to the legacy RFC 3161 timestamp transport path only. It does not modify C cryptographic primitives, constant-time code, KAT vectors, key formats, or public function signatures.

Standards Compliance

• NIST FIPS 202 (SHA-3)
• NIST FIPS 204 (Dilithium)
• NIST SP 800-108 (Key Derivation)
• RFC 2104 (HMAC)
• RFC 5869 (HKDF)
• RFC 8032 (Ed25519)
• RFC 3161 (Timestamps)
• No standards affected

Academic References

N/A — no primitive or protocol construction changes.

Security Analysis

Classical Security: Strengthens legacy timestamp transport by rejecting non-HTTPS TSA URLs before subprocess/network work and by failing loud when create_crypto_package(..., use_rfc3161=True) cannot obtain a timestamp token. Removes a demo-only hardcoded password literal.

Quantum Security: No impact. PQC code and KAT vectors are unchanged.

Security Impact: Improves posture by reducing suppressions from 9 to 7 and making the remaining suppressions justified-only.

Implementation Details

Changes Made

1. Carries forward docs: add nosec disposition and invariant pointer #297-chore: tidy repo root monitoring and benchmarks #300 hygiene work: v3.1.0 tag workflow guardrails, invariant pointer model, docs/CVE review, auto-docs stale closure, and repo-root tidy.
2. Removes the key-management demo hardcoded password by generating an ephemeral URL-safe password at runtime.
3. Replaces the legacy RFC 3161 urllib.request.urlopen path with an HTTPS-only http.client.HTTPSConnection path, rejects HTTP TSA URLs before subprocess/network work, and fails loud when package creation requests RFC 3161 but receives no token.
4. Consolidates Dependabot updates: cryptography >=46.0.7, CodeQL action 4.35.4, tomlkit 0.15.0, pydantic 2.13.4, pydantic-core 2.46.4.
5. Refreshes the FIPS module integrity digest after Python source changes.
6. Updates README, architecture, cryptography, security, changelog, and wiki language to state current consumers as Mercury Agent and FINDΩYOU™ without downstream/future wording.

Technical Approach

The branch intentionally stacks the existing reviewed PRs first, then merges the dependency PRs and resolves only the pydantic/pydantic-core lock conflict manually. The legacy timestamp function still preserves its Optional[bytes] signature, while package creation now treats a requested-but-missing RFC 3161 token as a hard failure so security layers are not silently skipped. Documentation edits are wording-only and do not alter runtime behavior.

Breaking Changes

Breaking Changes:

• None
• Yes (describe below)

Migration Path:
N/A.

Testing

Test Coverage

• Unit tests added/updated
• Integration tests added/updated
• Test coverage maintained or improved
• All tests pass locally/CI

Testing Performed

Environment:

• Python version(s): 3.12.8 locally; CI matrix covers Python 3.9-3.13 across Ubuntu, macOS, Windows, and Ubuntu ARM jobs
• Operating System: Ubuntu Linux locally; CI covers Ubuntu/macOS/Windows
• PQC backend: [x] Native C library [ ] None

Test Cases:

1. PYTHONPATH=/home/ubuntu/ama-merge-check python -m pytest tests/test_comprehensive_system.py::TestCryptoPackageWithRFC3161::test_package_with_rfc3161_failure_raises tests/test_crypto_import_paths.py::TestRFC3161SuccessPath -q — 4 passed.
2. PYTHONPATH=/home/ubuntu/ama-merge-check python -m ruff check ama_cryptography/legacy_compat.py tests/test_comprehensive_system.py tests/test_crypto_import_paths.py — passed.
3. PYTHONPATH=/home/ubuntu/ama-merge-check python -m black --check --diff ama_cryptography/legacy_compat.py tests/test_comprehensive_system.py tests/test_crypto_import_paths.py — passed.
4. PYTHONPATH=/home/ubuntu/ama-merge-check python -m bandit -r ama_cryptography/ -l — no issues identified.
5. PYTHONPATH=/home/ubuntu/ama-merge-check python -m mypy --strict ama_cryptography/ — passed.
6. PYTHONPATH=/home/ubuntu/ama-merge-check python -m ama_cryptography.integrity --verify — OK.
7. git diff --check and grep verification for consumer wording — passed.
8. GitHub CI for PR security: consolidate v3.1.0 hygiene and dependency remediation #301 — 69 passed, 0 failed, 0 pending.

Known Test Vectors

• Tested against official NIST test vectors
• Tested against IETF RFC test vectors
• No official test vectors added in this PR

Code Quality

Code Quality Checks

• Code follows PEP 8 style guidelines
• All functions have type hints
• All functions have comprehensive docstrings
• No security warnings from linters (Bandit, etc.)
• Black formatting applied (black .)
• Ruff linting passed (ruff check .)
• Type checking passed (mypy ama_cryptography/)

Documentation Updates

• README.md updated
• SECURITY.md updated (if security affected)
• IMPLEMENTATION_GUIDE.md updated (if deployment affected)
• CHANGELOG.md updated
• Inline code comments added for complex logic
• Docstrings include academic citations (if applicable)

Backwards Compatibility

Compatibility Assessment

• Fully backwards compatible
• Backwards compatible with deprecation warnings
• Breaking changes with migration path
• Major version bump required

Deprecation Notices

Deprecated Features:

• None

Deprecation Timeline:

• N/A

Performance Impact

Performance Analysis

Benchmarks:
Not performance-related.

Impact:

• No performance impact
• Performance improvement
• Slight performance decrease
• Significant performance impact

Security Checklist

• No secrets committed
• No new # nosec annotations
• Remaining # nosec suppressions are justified in nosec_disposition.md
• No public API signatures changed
• No version bump
• No C source, constant-time function, or KAT vector changes

Link to Devin session: https://app.devin.ai/sessions/380c3bcb95034d1f83fb66062f20e8cf
Requested by: @Steel-SecAdv-LLC

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring