ADR-001: Depend on nr-passkeys-be as Composer Dependency 

Status

Accepted

Date

2026-03-14

Decision-makers

Sebastian Mendel

Context 

nr_passkeys_fe needs WebAuthn ceremony implementation (registration/assertion), HMAC-SHA256 challenge token generation with replay protection, and per-IP rate limiting with account lockout. These are security-critical primitives already proven in netresearch/nr-passkeys-be.

Three approaches were considered:

A. nr-passkeys-be as composer dependency — Reuse services directly B. Standalone extension — Copy patterns, own code C. Shared library extraction (nr-passkeys-core) — Extract common code into third package

Decision 

Option A: nr-passkeys-be as composer dependency.

The FE extension requires netresearch/nr-passkeys-be and reuses:

  • WebAuthnService — Registration/assertion ceremonies
  • ChallengeService — HMAC-SHA256 signed challenge tokens with nonce
  • RateLimiterService — Per-IP/endpoint rate limiting and lockout
  • ExtensionConfigurationService — RP ID, origin, algorithm configuration

The FE extension does NOT reuse BE-specific classes (controllers, middleware, TCA, credential repository, auth service).

Consequences 

Positive:

  • No duplication of security-critical code ( 700 lines of WebAuthn + challenge + rate limit)
  • Security fixes in BE propagate to FE automatically
  • Single web-auth/webauthn-lib version across both extensions
  • Faster initial development

Negative:

  • BE extension installed even on FE-only sites (unused backend module, BE TCA)
  • Version lock-step: FE releases may be blocked by BE version constraints
  • BE service API changes can break FE

Mitigation:

  • Plan for future extraction to nr-passkeys-core shared library (Option C)
  • Define interface contracts for shared services to ease future refactoring
  • Accept BE overhead as minimal (no runtime cost, only disk space)

Alternatives Considered 

Option B (Standalone): Would require duplicating  700 lines of security-critical code. Any bug fix would need to be applied twice. Rejected for maintenance burden.

Option C (Shared library): Architecturally cleanest, but requires refactoring nr-passkeys-be first. Deferred to a future release when both extensions are stable.