feat: adapt Keystone for Axon 0.5.0

[shark0F0497]

Pull Request Checklist

Please ensure your PR meets the following requirements:

• Code follows the style guidelines
• Tests pass locally
• Code is formatted
• Documentation updated if needed
• Commit messages follow conventional commits
• PR description is complete and clear

---

Summary

This PR adapts Keystone for the Axon 0.5.0 workflow by adding recorder WebSocket client authentication, token rotation support, callback public URL handling, and recorder diagnostic metadata persistence.

---

Motivation

• Axon recorder and transfer clients need authenticated WebSocket access with rotatable credentials.
• Task callback URLs need to be generated from a Keystone-public base URL so machine-side clients can call back reliably.
• Operators and admins need recorder writer health and version diagnostics persisted with episode metadata.

---

Changes

Modified Files

• internal/api/handlers/device_registration.go - Adds recorder WebSocket credential handling and token rotation flow.
• internal/api/handlers/axon_rpc.go - Updates Axon RPC handling for the authenticated recorder/transfer workflow.
• internal/api/handlers/task.go - Uses callback public URL configuration when creating task callback payloads.
• internal/api/handlers/transfer.go - Persists transfer/recorder diagnostic metadata, including writer health and recorder version.
• internal/api/handlers/episode.go - Exposes recorder diagnostics in episode metadata responses.
• internal/config/config.go - Adds callback URL and WebSocket client auth configuration.
• internal/server/server.go - Registers the new callback URL endpoint and WebSocket auth wiring.
• docker/.env.example - Documents new runtime configuration.
• docker/docker-compose.dev.yml - Adds new development environment configuration.
• docker/docker-compose.test.yml - Adds new test environment configuration.

Added Files

• internal/api/handlers/ws_client_auth.go - Implements WebSocket client credential authentication helpers.
• internal/api/handlers/callback_urls.go - Adds callback public URL response handling.
• internal/storage/database/migrations/000007_ws_client_auth_tokens.up.sql - Adds WebSocket client auth token storage.
• internal/storage/database/migrations/000007_ws_client_auth_tokens.down.sql - Rolls back WebSocket client auth token storage.
• docs/designs/callback-public-base-url.zh.md - Documents callback public base URL behavior.
• docs/designs/episode-recorder-writer-health.md - Documents recorder writer health metadata.
• internal/api/handlers/episode_metadata_test.go - Covers episode metadata diagnostics.
• internal/api/handlers/task_callback_config_test.go - Covers task callback URL configuration.
• internal/api/handlers/transfer_asset_id_snapshot_test.go - Covers transfer metadata snapshot behavior.

Deleted Files

• None

---

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 change)
• Documentation update (documentation changes only)
• Refactoring (code improvement without functional changes)
• Performance improvement (code changes that improve performance)
• Test changes (adding, modifying, or removing tests)

---

Impact Analysis

Breaking Changes

None

Backward Compatibility

Fully backward compatible. Existing device registration, task, episode, and transfer flows continue to work while new Axon 0.5.0 metadata and credential fields are supported.

---

Testing

Test Environment

• Local development environment
• Go 1.24 toolchain
• GOCACHE=/tmp/archebase-go-build-cache

Test Cases

• Unit tests pass locally
• Integration tests pass locally
• E2E tests pass (if applicable)
• Manual testing completed

Manual Testing Steps

• Not performed.

Test Coverage

• New tests added
• Existing tests updated
• Coverage maintained or improved

Commands run:

GOCACHE=/tmp/archebase-go-build-cache go test ./...

---

Screenshots / Recordings

Not applicable.

---

Performance Impact

• Memory usage: No change expected
• CPU usage: No change expected
• Throughput: No change expected
• Lock contention: No change expected

---

Documentation

• README.md updated
• ARCHITECTURE.md updated
• CONTRIBUTING.md updated
• API documentation updated
• Design docs updated in docs/designs/
• No documentation changes needed

---

Related Issues

• None

---

Additional Notes

• The first go test ./... attempt failed because the default Go build cache under /home/shark/.cache/go-build is read-only in the local sandbox. Re-running with GOCACHE=/tmp/archebase-go-build-cache passed.

---

Reviewers

---

Notes for Reviewers

• Please review the WebSocket client token storage and rotation path.
• Please verify callback public URL behavior matches deployment expectations.
• Please review recorder writer health and version metadata compatibility with Axon 0.5.0 clients.

---

Checklist for Reviewers

• Code changes are correct and well-implemented
• Tests are adequate and pass
• Documentation is updated and accurate
• No unintended side effects
• Performance impact is acceptable
• Backward compatibility maintained (if applicable)