Skip to content

docs: architecture decision records and Marten backed key bindings - #2

Merged
rian-be merged 7 commits into
mainfrom
docs/adr-fixed-KeyBinding-repo
Aug 26, 2026
Merged

rian-be merged 7 commits into
mainfrom
docs/adr-fixed-KeyBinding-repo

Conversation

@rian-be

@rian-be rian-be commented Aug 26, 2026 •

Copy link
Copy Markdown
Contributor

docs: architecture decision records and Marten backed key bindings

Summary

This PR introduces a curated Architecture Decision Record (ADR) collection and makes token key bindings durable.

  • introduces the Docs/ADR collection with globally numbered decisions (001-016) and collection README explaining how to read and extend it
  • documents the Core, Plugins, and Host architecture areas using Context / Problem / Decision / Rejected / Consequences with cross linked Related sections
  • persists token key bindings in Marten, replacing the in-memory repository (implements ADR-012)
  • links the ADR collection from the root README.md

Architecture Decision Records

  • adds Docs/ADR/README.md as the collection index with How To Read, Category Map, Relationships, and When To Add guidance
  • each ADR carries Tag, Date, Scope, and stable navigation (Previous / Next)
  • each ADR links related decisions in Related section to make dependencies between areas explicit

Core ADRs (001-008)

  • adds ADR-001 centralizing signing key management behind the IJwtKeyStore abstraction
  • adds ADR-002 encrypting persisted keystore bytes at rest via the pluggable IKeyEncryptor (AES-256-CBC)
  • adds ADR-003 modeling the signing key lifecycle as immutable with based transitions on SigningKey
  • adds ADR-004 treating developer token to signing key bindings as core domain (TokenKeyBinding)
  • adds ADR-005 publishing public keys through JWKS, exposing only non revoked keys with cached invalidation
  • adds ADR-006 deriving the JWT kid as generated GUID used across memory, persistence, and JWKS
  • adds ADR-007 defaulting the signing algorithm to RSA-4096 with RS256
  • adds ADR-008 standardizing API errors through the Core ErrorResponse contract and DomainException base

Plugin ADRs (009-010)

  • adds ADR-009 discovering and loading plugins dynamically through the IAuthKitPlugin contract
  • adds ADR-010 loading plugins from configurable PluginsPath at startup into the default load context

Host ADRs (011-016)

  • adds ADR-011 persisting the encrypted keystore as singleton Marten document
  • adds ADR-012 persisting token key bindings in Marten (implemented by this PR)
  • adds ADR-013 exposing both REST and gRPC transport surfaces from one host
  • adds ADR-014 rendering HTTP errors as RFC 7807 ProblemDetails via middleware
  • adds ADR-015 using Keycloak as the external JWT authority
  • adds ADR-016 using Marten and Wolverine as the host infrastructure

Key Binding Persistence

  • replaces InMemoryKeyBindingRepository with KeyBindingRepository backed by Marten
  • stores each binding as document identified by {tokenId:N}:{signingKeyId} using lightweight sessions
  • updates DI registration (IKeyBindingRepository -> KeyBindingRepository) and excludes the repository from automatic DI discovery
  • bindings now survive restarts alongside the encrypted keystore

Documentation

  • adds link to the ADR collection in the root README.md Documentation table

Result

  • architectural decisions across Core, Host, and Plugins are documented, stable, and cross linked
  • token key bindings are durable and consistent with the rest of the Marten backed host
  • new contributors can read or extend decisions following the collection's stated conventions

@rian-be rian-be self-assigned this Aug 26, 2026
@rian-be rian-be added the documentation Improvements or additions to documentation label Aug 26, 2026
@rian-be rian-be changed the title docs: architecture decision records and Marten-backed key bindings docs: architecture decision records and Marten backed key bindings Aug 26, 2026
@rian-be
rian-be merged commit 3e848cb into main Aug 26, 2026
4 checks passed
@rian-be
rian-be deleted the docs/adr-fixed-KeyBinding-repo branch August 26, 2026 22:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant