cameleer-server/.planning/phases/04-security/04-01-SUMMARY.md

---
phase: 04-security
plan: 01
subsystem: auth
tags: [jwt, ed25519, hmac-sha256, nimbus-jose-jwt, spring-security, bootstrap-token]

# Dependency graph
requires:
  - phase: 01-ingestion
    provides: "Maven multi-module structure, Spring Boot app scaffold, application.yml patterns"
  - phase: 03-agent-registry
    provides: "Agent registration flow, AgentRegistryService, SSE connection manager"
provides:
  - "JwtService interface and HMAC-SHA256 implementation for access/refresh token lifecycle"
  - "Ed25519SigningService interface and JDK 17 implementation for payload signing"
  - "BootstrapTokenValidator with constant-time comparison and dual-token rotation"
  - "SecurityProperties configuration binding with env var mapping"
  - "TestSecurityConfig permit-all for existing test compatibility"
affects: [04-02, 04-03]

# Tech tracking
tech-stack:
  added: [nimbus-jose-jwt 9.47, spring-boot-starter-security, spring-security-test]
  patterns: [ephemeral HMAC secret per server instance, ephemeral Ed25519 keypair per startup, constant-time token comparison, InitializingBean fail-fast validation]

key-files:
  created:
    - cameleer-server-core/src/main/java/com/cameleer/server/core/security/JwtService.java
    - cameleer-server-core/src/main/java/com/cameleer/server/core/security/Ed25519SigningService.java
    - cameleer-server-core/src/main/java/com/cameleer/server/core/security/InvalidTokenException.java
    - cameleer-server-app/src/main/java/com/cameleer/server/app/security/JwtServiceImpl.java
    - cameleer-server-app/src/main/java/com/cameleer/server/app/security/Ed25519SigningServiceImpl.java
    - cameleer-server-app/src/main/java/com/cameleer/server/app/security/BootstrapTokenValidator.java
    - cameleer-server-app/src/main/java/com/cameleer/server/app/security/SecurityProperties.java
    - cameleer-server-app/src/main/java/com/cameleer/server/app/security/SecurityBeanConfig.java
    - cameleer-server-app/src/test/java/com/cameleer/server/app/security/TestSecurityConfig.java
    - cameleer-server-app/src/test/java/com/cameleer/server/app/security/JwtServiceTest.java
    - cameleer-server-app/src/test/java/com/cameleer/server/app/security/Ed25519SigningServiceTest.java
    - cameleer-server-app/src/test/java/com/cameleer/server/app/security/BootstrapTokenValidatorTest.java
  modified:
    - cameleer-server-app/pom.xml
    - cameleer-server-app/src/main/resources/application.yml
    - cameleer-server-app/src/test/resources/application-test.yml

key-decisions:
  - "HMAC-SHA256 with ephemeral 256-bit secret for JWT signing (simpler than Ed25519 for tokens, Ed25519 reserved for config signing)"
  - "Nimbus JOSE+JWT chosen for JWT library (mature, well-maintained, explicit API)"
  - "JDK 17 built-in Ed25519 KeyPairGenerator (no Bouncy Castle dependency needed)"
  - "TestSecurityConfig as @Configuration in test sources for automatic component scanning by @SpringBootTest"
  - "InitializingBean pattern for fail-fast bootstrap token validation on startup"

patterns-established:
  - "Core module interfaces (JwtService, Ed25519SigningService) with app module implementations"
  - "SecurityProperties @ConfigurationProperties with env var mapping via ${ENV_VAR:default}"
  - "SecurityBeanConfig wires all security beans with explicit @Bean methods"

requirements-completed: [SECU-03, SECU-05]

# Metrics
duration: 12min
completed: 2026-03-11
---

# Phase 4 Plan 01: Security Service Foundation Summary

**HMAC-SHA256 JWT service with access/refresh token lifecycle, JDK 17 Ed25519 signing for config payloads, and constant-time bootstrap token validation with dual-token rotation**

## Performance

- **Duration:** 12 min
- **Started:** 2026-03-11T18:56:17Z
- **Completed:** 2026-03-11T19:08:55Z
- **Tasks:** 1 (TDD: RED + GREEN)
- **Files modified:** 15

## Accomplishments
- JwtService creates and validates access JWTs (1h expiry) and refresh JWTs (7d expiry) with agentId, group, and type claims
- Ed25519SigningService generates ephemeral keypair, signs payloads with verifiable signatures using JDK 17 built-in crypto
- BootstrapTokenValidator uses MessageDigest.isEqual for constant-time comparison with dual-token rotation support
- Server fails fast on startup if CAMELEER_AUTH_TOKEN env var is not set
- All 71 tests pass (18 new security + 29 existing unit + 24 existing integration) with TestSecurityConfig permit-all

## Task Commits

Each task was committed atomically (TDD flow):

1. **Task 1 RED: Failing tests for security services** - `51a0270` (test)
2. **Task 1 GREEN: Implement security service foundation** - `ac9e8ae` (feat)

_No REFACTOR commit needed -- implementations are clean and minimal._

## Files Created/Modified

- `cameleer-server-core/.../security/JwtService.java` - JWT service interface with create/validate methods
- `cameleer-server-core/.../security/Ed25519SigningService.java` - Ed25519 signing interface with sign/getPublicKeyBase64
- `cameleer-server-core/.../security/InvalidTokenException.java` - Runtime exception for invalid/expired/wrong-type tokens
- `cameleer-server-app/.../security/JwtServiceImpl.java` - Nimbus JOSE+JWT HMAC-SHA256 implementation
- `cameleer-server-app/.../security/Ed25519SigningServiceImpl.java` - JDK 17 Ed25519 KeyPairGenerator implementation
- `cameleer-server-app/.../security/BootstrapTokenValidator.java` - Constant-time bootstrap token validation
- `cameleer-server-app/.../security/SecurityProperties.java` - Config properties for token expiry and bootstrap tokens
- `cameleer-server-app/.../security/SecurityBeanConfig.java` - Bean wiring with fail-fast startup validation
- `cameleer-server-app/.../security/TestSecurityConfig.java` - Temporary permit-all for existing test compatibility
- `cameleer-server-app/pom.xml` - Added nimbus-jose-jwt, spring-boot-starter-security, spring-security-test
- `cameleer-server-app/.../application.yml` - Security config section with env var mapping
- `cameleer-server-app/.../application-test.yml` - Test bootstrap token values
- `cameleer-server-app/.../security/JwtServiceTest.java` - 7 unit tests for JWT creation/validation
- `cameleer-server-app/.../security/Ed25519SigningServiceTest.java` - 5 unit tests for signing/verification
- `cameleer-server-app/.../security/BootstrapTokenValidatorTest.java` - 6 unit tests for token matching

## Decisions Made

- **HMAC-SHA256 for JWT signing:** Simpler than using Ed25519 for tokens; ephemeral 256-bit secret generated per server instance. Ed25519 reserved for config/command payload signing where agents need the public key.
- **Nimbus JOSE+JWT:** Mature library with explicit MACSigner/MACVerifier API. Chose explicit version 9.47 since it may not be transitively available without spring-boot-starter-oauth2-resource-server.
- **JDK 17 built-in Ed25519:** No external crypto library needed -- `KeyPairGenerator.getInstance("Ed25519")` available since JDK 15.
- **@Configuration (not @TestConfiguration) for TestSecurityConfig:** Ensures automatic component scanning by @SpringBootTest without requiring @Import on every IT class.
- **InitializingBean for fail-fast:** Validates CAMELEER_AUTH_TOKEN is set before any request processing begins.

## Deviations from Plan

None - plan executed exactly as written.

## Issues Encountered

None.

## User Setup Required

None - no external service configuration required.

## Next Phase Readiness

- Security primitives are ready for Plan 02 (Spring Security filter chain, JWT auth filter, registration/refresh integration)
- JwtService, Ed25519SigningService, and BootstrapTokenValidator are all wired as Spring beans
- TestSecurityConfig will be replaced by real SecurityFilterChain in Plan 02
- Plan 03 will integrate Ed25519 signing into SSE command push

## Self-Check: PASSED

- All 12 created files verified present on disk
- Both commits (51a0270, ac9e8ae) verified in git log
- Full `mvn clean verify` passed: 71 tests, 0 failures

---
*Phase: 04-security*
*Completed: 2026-03-11*