feat(rest-api-application): migrate auth_key context to contract-first architecture

[josecelano]

Description

Implements SI-3: Migrate auth_key context to contract-first architecture (sub-issue of #1938).

Changes

• rest-api-protocol: Added v1::context::auth_key/ with:
  • resources/auth_key.rs — AuthKey DTO + AuthKeyError enum (3 variants matching PeerKeyError)
  • forms/add_key_form.rs — AddKeyForm input DTO (protocol now covers both input and output types)
• rest-api-application: Defined AuthKeyPort trait and AuthKeyApiService use-case
• rest-api-runtime-adapter: Implemented TrackerAuthKeyAdapter wrapping KeysHandler + conversion function
• axum-rest-api-server: Rewired handlers to dispatch through AuthKeyApiService, removed local DTOs (resources.rs, forms.rs)

Architecture flow

Handlers → AuthKeyApiService (use-case)
         → AuthKeyPort (trait)
         → TrackerAuthKeyAdapter (adapter)
         → KeysHandler (tracker-core)

Verification

• Protocol DTOs created and exported (resources + forms)
• AuthKeyPort trait defined in rest-api-application
• AuthKeyApiService use-case implemented
• TrackerAuthKeyAdapter implemented
• Axum handlers dispatch through use-case
• Pre-commit checks pass
• Pre-push checks (CI)

[Copilot]

Pull request overview

This PR implements SI-3 of the contract-first REST API migration by moving the auth_key context to the protocol → application → runtime-adapter → axum transport layering, and rewiring the Axum handlers to dispatch via a new application use-case service instead of calling tracker-core directly.

Changes:

• Added auth_key protocol DTOs (resources + input forms) under rest-api-protocol, and moved usage away from Axum-local DTO modules.
• Introduced AuthKeyPort (application boundary) and AuthKeyApiService (use-case) in rest-api-application, plus TrackerAuthKeyAdapter in rest-api-runtime-adapter.
• Updated axum-rest-api-server routing/handlers/tests to use protocol DTOs and the new application service, removing the old auth_key local DTO module.

Reviewed changes

Copilot reviewed 22 out of 23 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
packages/rest-api-runtime-adapter/src/adapters/mod.rs	Exposes the new auth_key adapter module.
packages/rest-api-runtime-adapter/src/adapters/auth_key.rs	Implements AuthKeyPort by wrapping KeysHandler and mapping tracker-core outputs to protocol DTOs.
packages/rest-api-protocol/src/v1/context/mod.rs	Registers the new auth_key context and documents forms vs resources.
packages/rest-api-protocol/src/v1/context/auth_key/mod.rs	Adds the protocol context module for /api/v1/keys.
packages/rest-api-protocol/src/v1/context/auth_key/resources/mod.rs	Exposes AuthKey protocol resource module.
packages/rest-api-protocol/src/v1/context/auth_key/resources/auth_key.rs	Introduces AuthKey DTO + AuthKeyError protocol error type.
packages/rest-api-protocol/src/v1/context/auth_key/forms/mod.rs	Exposes AddKeyForm input DTO module.
packages/rest-api-protocol/src/v1/context/auth_key/forms/add_key_form.rs	Moves AddKeyForm into the protocol layer (requires serde_with).
packages/rest-api-protocol/Cargo.toml	Adds serde_with dependency to support the moved form DTO.
packages/rest-api-application/src/use_cases/mod.rs	Registers the new auth-key use-case service module.
packages/rest-api-application/src/use_cases/auth_key.rs	Adds AuthKeyApiService orchestrating calls to the AuthKeyPort.
packages/rest-api-application/src/ports/mod.rs	Registers the new auth-key port module.
packages/rest-api-application/src/ports/auth_key.rs	Defines AuthKeyPort trait (application boundary).
packages/axum-rest-api-server/tests/server/v1/asserts.rs	Switches AuthKey assertions to use protocol DTO type.
packages/axum-rest-api-server/src/v1/routes.rs	Wires TrackerAuthKeyAdapter + AuthKeyApiService into v1 routing.
packages/axum-rest-api-server/src/v1/context/auth_key/routes.rs	Changes handler state from KeysHandler to AuthKeyApiService.
packages/axum-rest-api-server/src/v1/context/auth_key/handlers.rs	Rewrites handlers to call AuthKeyApiService and map protocol-level errors.
packages/axum-rest-api-server/src/v1/context/auth_key/responses.rs	Switches response payload type to protocol AuthKey and adjusts invalid-key response signature.
packages/axum-rest-api-server/src/v1/context/auth_key/resources.rs	Removes Axum-local AuthKey DTO module (migrated to protocol).
packages/axum-rest-api-server/src/v1/context/auth_key/mod.rs	Removes forms/resources module exports (now provided by protocol).
packages/axum-rest-api-server/Cargo.toml	Drops serde_with dependency (moved to protocol crate).
docs/issues/open/1941-1938-si-3-migrate-auth-key-context.md	Updates the SI-3 issue spec/progress to match the implemented architecture.
Cargo.lock	Moves serde_with dependency from axum-rest-api-server to rest-api-protocol.

Comments suppressed due to low confidence (1)

packages/axum-rest-api-server/src/v1/context/auth_key/responses.rs:60

• invalid_auth_key_duration_response is triggered from POST /keys when the provided seconds_valid overflows the clock computation, but the message currently starts with "Invalid URL". This isn't a URL issue; it should describe invalid request input.

#[must_use]
pub fn invalid_auth_key_duration_response(duration: u64) -> Response {
    bad_request_response(&format!("Invalid URL: invalid auth key duration: \"{duration}\""))
}

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[josecelano]

ACK f7cbdb2