You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
feat(app): bootstrap the Quarkus application with the BFF login and the native image - #3
Second of three staged bootstrap PRs. Stacked on #2: until #2 is merged this diff also shows its two commits; only commit f2c9698 is new here. Draft until #2 is merged and this branch is rebased.
trailhand (Quarkus application)
config: trailhand.yaml with ${NAME:-default} placeholders and the boot rules: one TRAILHAND-200 ERROR record per violation, the boot stops; --validate-config <dir> exits 0/1. Token Sheriff's sheriff.client.* and the validating issuer are derived from trailhand.yaml (TokenSheriffConfigSourceFactory), so operators keep one policy file.
service: local bare copies through git-core/git-store 0.1.0-SNAPSHOT (RepositoryRegistry, JGitRepositoryOperations): clone on boot in the background, periodic fetch, readiness repositories (TRH-OPS-2), health group git-remote (TRH-GEN-6).
security / web – the BFF of ADR-0001 inside the application, on token-sheriff-client-quarkus 0.9.9:
GET /api/v1/auth/login?return= (code + PKCE S256, state/nonce via Token Sheriff), GET /api/v1/auth/callback, POST /api/v1/auth/logout (revocation + RP-initiated logout)
in-memory sessions with idle/absolute lifetime, __Host-trailhand-session (Strict), __Host-trailhand-login
return checked against the shared canonical-addresses.json
CSP header taken from the built index.html plus frame-ancestors 'none', nosniff, no-referrer; SPA fallback for every non-file address
/api/v1/status, /messages, /session, /due (empty until the index exists), /events (SSE with status)
native: Dockerfile.native (distroless 2.0 pinned by digest, --health-probe, UID 65532 = nonroot, OCI labels, /app/data owned by nonroot), hadolint clean. Token Sheriff's DSL-JSON converters are registered for reflection and its flow package is initialised at run time (as in API Sheriff); the login works natively against Keycloak (verified by the ITs of the next PR).
Login: response_mode=query (no deviation from ADR-0001)
Token Sheriff 0.9.9 always requests response_mode=form_post, whose callback is a cross-site POST without SameSite=Lax cookies. As in API Sheriff (QueryResponseModeAuthorizationRequestBuilder), the application rewrites only that parameter to query, so the callback is a top-level GET and the Lax transaction cookie arrives, exactly as TRH-AUTH-1 specifies. Accepted cost: the code appears in the callback URL. It is bounded by PKCE, the single-use code, the transaction with state, and Referrer-Policy: no-referrer. A first draft of this PR used SameSite=None instead; that is withdrawn (commit bf5b207).
Native image / JGit (open question of application-architecture.adoc)
JGit runs natively without a JVM fallback once:
all of org.eclipse.jgit is initialised at run time (static Random/SecureRandom)
JGitText and the 100 JGit enums are registered for reflection (META-INF/native-image/de.cuioss/trailhand)
Smoke-tested in the container: clone of a file: remote, restart from the volume, unreachable remote → readiness stays UP and git-remote is DOWN. The Quarkiverse quarkus-jgit extension would cover this too, but needs a dependency approval.
Verification
./mvnw clean verify: 87 tests in trailhand (config rules, placeholders, repository service against a local remote, sessions, rights, return check, login service with EasyMock, web API incl. CSRF/Origin/CSP/SPA/SSE/health, ArchUnit)
./mvnw -Ppre-commit clean verify -DskipTests: headers added, no other changes
Summary by CodeRabbit
New Features
Added the TrailHand application with sign-in and sign-out, session and access management, repository synchronization, and status, event, message, and due-list endpoints.
Added configuration validation, repository health reporting, and native-image container packaging.
Added safeguards for pending logins, single-use login transactions, and session expiration; token revocation failures no longer prevent sign-out.
Added English and German sign-in callback messages.
Documentation
Expanded setup, configuration, deployment, authentication, and architecture guidance, including persistent storage and health checks.
Build & Tests
Added the application to the build and expanded coverage for configuration, authentication, repositories, web APIs, native registration, and runtime endpoints.
…suite
Adds the first three modules of doc/specification/architecture-and-modules.adoc:
- web-app: Svelte 5 single-page app after pm-web-app, with design
(tokens.css pinned to pm-mcp-clients 05e6c68, WCAG AA token test,
stylelint), branding (provisional mark, wordmark, mascot place) and
i18n (server catalogue en/de, cache per version, text-literal lint)
as separate layers; shell, page templates, closed component
vocabulary, canonical addresses shared as data, ApiClient with
cookie session, anti-CSRF header, login on 401 and one event stream;
Due, first-login, Settings and lens placeholder views.
- web-mock: plain-Java mock of the /api/v1 requests driven by scenario
profiles (workshop, first-login, read-only, degraded, empty); it
emulates session cookie, anti-CSRF header and Origin check and
serves the real catalogue (TRH-TEST-1, ADR-0003).
- web-e2e: Playwright and axe-core against the Vite dev server and the
mock; profile e2e.
Docs: TRH-WEB-9 shell requests, TRH-TEST-1 mock server, ADR-0003,
web-mock in the module table, trailhand_theme instead of cf_theme,
provenance of the provisional mark.
Co-Authored-By: plan-marshall <noreply@cuioss.de>
- web-app: split the stream reader out of openStream (cognitive
complexity), replaceAll for the plural marker, trailing slashes
trimmed without a backtracking regex, toHaveLength in the test
- web-mock: API paths derived from one prefix, STATUS_ROUTE and the
scenario field reused, unused parameter removed, Right.ALLOWED_ACTIONS
(no clash with the actions component), constants for repeated
literals in ScenarioLoader, an iterator instead of a moved loop
counter, the usage and readiness line through log records instead of
System.out (start.sh waits for WEB_MOCK-1)
Co-Authored-By: plan-marshall <noreply@cuioss.de>
…he native image
Adds the module trailhand of doc/specification/architecture-and-modules.adoc:
- config: trailhand.yaml with ${NAME:-default} placeholders and the
boot rules (one TRAILHAND-200 record per violation, boot stops),
--validate-config <dir>; Token Sheriff's sheriff.client.* and the
issuer configuration derived from trailhand.yaml
- service: local bare copies of the repositories through git-core and
git-store (clone, periodic fetch), readiness check repositories,
health group git-remote
- security and web (ADR-0001, BFF in the application): login with
code + PKCE through token-sheriff-client-quarkus 0.9.9, server-side
sessions, __Host- cookies, return check against the canonical
addresses, RP-initiated logout with token revocation, rights from
groups, anti-CSRF and Origin gate, CSP header from the built page,
SPA fallback, /api/v1 status, messages, session, due and events
- native: Dockerfile.native on the digest-pinned distroless base,
binary health probe, nonroot; JGit runs natively with its classes
initialised at run time and its enums and message bundle registered
- ArchUnit rules for TRH-GEN-2 and TRH-GEN-4, enforcer ban of
datasource and Hibernate (TRH-GEN-3)
Spec: the callback is a form post (Token Sheriff always requests
response_mode=form_post), so the login-transaction cookie is
SameSite=None (TRH-AUTH-1, ADR-0001); web.origin; the refusal
IDENTITY_PROVIDER_UNAVAILABLE.
Co-Authored-By: plan-marshall <noreply@cuioss.de>
Adds the TrailHand Quarkus application module with configuration loading, repository management, OIDC login and server-side sessions, health checks, REST endpoints, and native-image packaging. Adds application and deployment documentation, runtime configuration, localized callback messages, and tests for these flows.
Adds the trailhand Maven module, Quarkus entry point, health probe, native-image settings and registrations, and a nonroot Docker image. Updates build, native-image, and data-volume documentation.
Adds configuration records, YAML loading and validation, placeholder resolution, offline validation, and Token Sheriff settings derived from configuration. Adds log-record definitions, tests, and fixtures.
Repository lifecycle and health reporting doc/specification/architecture-and-modules.adoc, trailhand/src/main/java/de/cuioss/trailhand/service/*, trailhand/src/main/java/de/cuioss/trailhand/web/EventStream.java, trailhand/src/main/java/de/cuioss/trailhand/web/EventsResource.java, trailhand/src/main/java/de/cuioss/trailhand/web/StatusResource.java, trailhand/src/test/java/de/cuioss/trailhand/service/RepositoryServiceTest.java, trailhand/src/test/java/de/cuioss/trailhand/web/RuntimeEndpointsTest.java
Adds repository creation, clone and fetch tracking, scheduled refresh, readiness and remote health checks, status responses, and status event streaming. Adds repository and runtime endpoint tests.
Adds the authorization-code login and callback flow, login transaction storage, server-side session lifecycle, rights mapping, logout and token revocation, cookie handling, and API session and CSRF checks. Updates authentication specifications and callback messages.
Web content and API endpoints trailhand/src/main/java/de/cuioss/trailhand/web/DueResource.java, trailhand/src/main/java/de/cuioss/trailhand/web/MessageCatalogue.java, trailhand/src/main/java/de/cuioss/trailhand/web/MessagesResource.java, trailhand/src/main/java/de/cuioss/trailhand/web/PagePolicy.java, trailhand/src/main/java/de/cuioss/trailhand/web/RequestGate.java, trailhand/src/test/java/de/cuioss/trailhand/web/PagePolicyTest.java, trailhand/src/test/java/de/cuioss/trailhand/web/WebApiTest.java, web-app/pom.xml, web-app/src/lib/i18n/catalogue.test.ts
Adds due-list and localized-message endpoints, content-security policy handling, and page fallback routing. Moves SPA resource copying to process-classes and checks locale codes against server catalogue files.
The change adds the Quarkus application with login, sessions, and repository handling. It has no blocking defects. A few minor edge cases remain: native-image registration lists must still be edited by hand, one login-queue counter can drift under concurrent load, and several narrow validation and timing gaps. These can be followed up without blocking the merge.
Pre-merge checks: 2
Check name
Status
Explanation
Description Check
Check skipped - CodeRabbit’s high-level summary is enabled.
Title check
The title names the main change: bootstrapping the Quarkus application (the trailhand module) with the BFF login flow and the native image build. The changeset adds the trailhand Quarkus app, its web …
Full details: Title check
Explanation
The title names the main change: bootstrapping the Quarkus application (the trailhand module) with the BFF login flow and the native image build. The changeset adds the trailhand Quarkus app, its web login via Token Sheriff, and the native Docker image, so the title matches the primary change. The title is a single line with a conventional commit prefix and specific terms. It is 84 characters, which is slightly long but still readable.
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.
- Login with response_mode=query (QueryResponseModeRequestBuilder, as
in API Sheriff): the callback is a top-level GET that carries the
SameSite=Lax transaction cookie, as TRH-AUTH-1 and ADR-0001 state;
the earlier SameSite=None deviation is withdrawn
- Native image: Token Sheriff's DSL-JSON converters registered for
reflection, its flow package and SessionStore initialised at run
time; /app/data owned by nonroot in the image
- trailhand.oidc.jwks-url for a split-horizon deployment
- Sonar: thread-safe holders instead of volatile fields, nullable
fields and locals for JSpecify, UnaryOperator, constants, no clashing
names, no nested ternary, the OpenRewrite markers of the pre-commit
run resolved (suppression with its reason)
Co-Authored-By: plan-marshall <noreply@cuioss.de>
AGENTS.md and the documentation index no longer say that nothing is built;
they point to the module list and the module READMEs. The web-e2e README
lists its helpers and what each spec checks.
Co-Authored-By: plan-marshall <noreply@cuioss.de>
The trailhand README describes the packages, the request gate and the
endpoints, how the Token Sheriff settings derive from trailhand.yaml, the
health checks and every native-image registration with its reason and how
the JGit enum list is regenerated. The application architecture concept
records that clone and fetch run in the native image; HTTPS transport,
in-core writing and notes stay open. The root README links the module
READMEs.
Co-Authored-By: plan-marshall <noreply@cuioss.de>
The reason will be displayed to describe this comment to others. Learn more.
Actionable comments posted: 20
Caution
Some comments are outside the diff and can’t be posted inline due to GitHub limitations.
⚠️ Outside diff range comments (2)
Major · Reject vault: credential references at boot, or… · TokenSheriffConfigSourceFactory.java:147-148
trailhand/src/main/java/de/cuioss/trailhand/config/TokenSheriffConfigSourceFactory.java:147-148 Major · Data Integrity & Integration · Heavy lift
Reject vault: credential references at boot, or resolve them before token exchange.
ConfigurationLoader accepts client-credential-ref: vault:... as a valid reference form. TokenSheriffConfigSourceFactory.readSecret returns empty for every non-file: reference, so derive omits sheriff.client.client-secret. The factory's own Javadoc states that such a configuration has no client secret and that login fails. The inspected source contains no vault resolver that supplies the secret before token exchange. A confidential client configured this way cannot complete token exchange.
Either the loader must reject vault: references until the adapter exists, or a resolver must supply the secret before token exchange. The loader and the factory must agree on which reference forms are usable.
Major · Make session renewal atomic with session removal. · SessionStore.java:94-107
trailhand/src/main/java/de/cuioss/trailhand/security/SessionStore.java:94-107 Major · Security & Privacy · Quick win
Make session renewal atomic with session removal.
use() reads a session and later writes its touched copy with an unconditional put. If logout removes the session between those operations, use() restores it. A later request with the same cookie can authenticate after logout has completed. LoginService.logout() removes the session before clearing its tokens. (raw.githubusercontent.com)
Use computeIfPresent to check expiry and renew the session atomically. If logout removes the entry first, renewal must not recreate it.
Review info
Run configuration
Source mode: Auto
Repository: Unavailable
Branch: Unavailable
File: No configuration file from this repository applied
Commit: Unavailable
Layers: Central YAML; Path: .coderabbit.yaml
Review profile: CHILL
Plan: Advanced
Run ID: c71a9112-3ee6-4086-981f-ce625117fe5e
Commits
Reviewing files that changed from the base of the PR and between aa6629d and d32ed2c.
Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.
Login and sessions (TRH-AUTH-1):
- PAR: when discovery names a pushed-authorization-request endpoint, the
authorization parameters are pushed and the browser gets only client_id
and request_uri.
- Session renewal and removal are atomic; a session a request finds
expired is handed to the janitor, so its tokens are dropped; the janitor
removes only the session it found expired.
- Pending logins are bounded (10,000; 503 TOO_MANY_LOGINS) and swept at
most once a minute instead of on every start.
- Groups are read from the JSON payload of the validated ID token, so a
comma inside a group name no longer splits it.
- The ID token as id_token_hint of the RP-initiated logout is now an
explicit exception in TRH-AUTH-1 and ADR-0001.
Configuration: web.origin is written as the browser sends it (lower case,
no default port); a placeholder that names no environment variable is a
boot error; the secret file loses only one trailing line break; vault:
references are refused until the Vault adapter exists; the specification
states which boot rules apply now.
Runtime: refresh no longer holds the state monitor during Git transport;
status and health checks read one snapshot; the initial status of a new
event connection cannot be overtaken by a broadcast; the catalogue
languages are the catalogue files; the public requests are named by the
resources' own path constants; the comma of --enable-url-protocols is
escaped for the list converter.
Build and tests: the SPA is copied at process-classes, so a reactor run
that stops at test finds it; quarkus-jacoco records the coverage of the
@QuarkusTest classes; NativeRegistrationTest compares the reflection
registrations with the resolved Token Sheriff and JGit JARs.
Co-Authored-By: plan-marshall <noreply@cuioss.de>
Replies to the two findings CodeRabbit raised outside the diff:
vault: references accepted but never resolved (TokenSheriffConfigSourceFactory.java:147-148). Fixed in 86f1cfe. Until the Vault adapter is built, the loader accepts only file: references. A vault: reference is refused at boot with the reason, for both oidc.client-credential-ref and repositories[].credential-ref, and --validate-config exits with 1. The loader and the factory now agree. configuration.adoc states it, and ConfigurationLoaderTest has the refusal row.
Session renewal not atomic with removal (SessionStore.java:94-107). Fixed in 86f1cfe. use() checks expiry and renews in one computeIfPresent, so a session closed by logout in between is not recreated. An expired session is removed inside the same step, and its id is handed to the janitor, so its tokens are dropped. Covered by SecurityTest.SessionStore.closedStaysClosed and expiredOnUse.
- Pending logins are kept in a queue in the order of their expiry: each
start drops the expired and taken ones at its head instead of scanning
the store, also at the limit; a compaction bounds the queue when started
logins are taken at once.
- A start whose PAR request fails frees its transaction at once.
- The native profile runs NativeRegistrationTest before packaging instead
of skipping every test, so no image is built with stale registrations.
- The specification states that revocation at logout is best effort and
which reference keys the bootstrap checks.
- Sonar: renamed record() (restricted identifier) and the path constants
that clashed with the members login and callback.
Co-Authored-By: plan-marshall <noreply@cuioss.de>
The reason will be displayed to describe this comment to others. Learn more.
Actionable comments posted: 7
Caution
Some comments are outside the diff and can’t be posted inline due to GitHub limitations.
⚠️ Outside diff range comments (2)
Minor · Derive the Token Sheriff registration targets during the… · TokenClientNativeRegistration.java:39
trailhand/src/main/java/de/cuioss/trailhand/security/TokenClientNativeRegistration.java:39 Minor · Maintainability & Code Quality · Heavy lift
Derive the Token Sheriff registration targets during the build.
This annotation manually mirrors the converters and response types in the resolved token-sheriff-client JAR. A dependency update can change that set. NativeRegistrationTest detects the difference but still requires a manual annotation edit. Generate these targets from the resolved JAR before native packaging. (raw.githubusercontent.com)
As per path instructions, “Treat a hardcoded list that must mirror a set defined elsewhere … as a defect unless it is derived from that source at build or run time.”
Source: Path instructions
Minor · Generate the JGit enum registrations from the resolved JAR. · reflect-config.json:8
trailhand/src/main/resources/META-INF/native-image/de.cuioss/trailhand/reflect-config.json:8 Minor · Maintainability & Code Quality · Heavy lift
Generate the JGit enum registrations from the resolved JAR.
This file manually mirrors the enum classes in the resolved org.eclipse.jgit JAR. A dependency update can change that set and block the build until this file is edited. jgitEnums detects drift but does not derive the metadata used by native-image. Add generation in trailhand/pom.xml, while retaining the separate JGitText registration. (raw.githubusercontent.com)
As per path instructions, “Treat a hardcoded list that must mirror a set defined elsewhere … as a defect unless it is derived from that source at build or run time.”
Source: Path instructions
Review info
Run configuration
Source mode: Auto
Repository: Unavailable
Branch: Unavailable
File: No configuration file from this repository applied
Commit: Unavailable
Layers: Central YAML; Path: .coderabbit.yaml
Review profile: CHILL
Plan: Advanced
Run ID: 13ffa0f7-fff8-442a-b8c0-09744eabcd60
Commits
Reviewing files that changed from the base of the PR and between d32ed2c and 8da268f.
Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.
- Placeholders: a nested ${...} in a default is refused like an unresolved
placeholder instead of passing as a literal.
- web.origin: an IPv6 literal is written as the browser serializes it (URL
Standard, IPv6 serializer), so the Origin check matches.
- Pending logins: the expiry is taken and queued in one step, so the queue
order is the expiry order across threads; a single compaction at a time
recounts the queue.
- Sessions: the clock is read inside the atomic renewal, so an older
request cannot undo a newer renewal.
- Repositories: a copy kept on the volume is present at once but reported
fetch-UP only after its fetch succeeds.
- Event stream: a status a new connection sees changed is broadcast to
every connection and recorded, so no connection keeps a stale status.
Co-Authored-By: plan-marshall <noreply@cuioss.de>
java:S3776 and java:S127 in WebSettings: the IPv6 serialization is split
into parsing, writing and the zero-run helpers, without assignments to loop
counters. java:S1192 in EventStream: the event name is a constant.
Co-Authored-By: plan-marshall <noreply@cuioss.de>
main holds the squash of #3, whose content this branch already contains.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Second of three staged bootstrap PRs. Stacked on #2: until #2 is merged this diff also shows its two commits; only commit
f2c9698is new here. Draft until #2 is merged and this branch is rebased.trailhand (Quarkus application)
trailhand.yamlwith${NAME:-default}placeholders and the boot rules: oneTRAILHAND-200ERROR record per violation, the boot stops;--validate-config <dir>exits 0/1. Token Sheriff'ssheriff.client.*and the validating issuer are derived fromtrailhand.yaml(TokenSheriffConfigSourceFactory), so operators keep one policy file.git-core/git-store0.1.0-SNAPSHOT (RepositoryRegistry,JGitRepositoryOperations): clone on boot in the background, periodic fetch, readinessrepositories(TRH-OPS-2), health groupgit-remote(TRH-GEN-6).token-sheriff-client-quarkus0.9.9:GET /api/v1/auth/login?return=(code + PKCE S256, state/nonce via Token Sheriff),GET /api/v1/auth/callback,POST /api/v1/auth/logout(revocation + RP-initiated logout)__Host-trailhand-session(Strict),__Host-trailhand-loginreturnchecked against the sharedcanonical-addresses.jsonX-CSRF-Token+Origincheck → 403index.htmlplusframe-ancestors 'none',nosniff,no-referrer; SPA fallback for every non-file address/api/v1/status,/messages,/session,/due(empty until the index exists),/events(SSE withstatus)Dockerfile.native(distroless 2.0 pinned by digest,--health-probe, UID 65532 = nonroot, OCI labels,/app/dataowned by nonroot), hadolint clean. Token Sheriff's DSL-JSON converters are registered for reflection and its flow package is initialised at run time (as in API Sheriff); the login works natively against Keycloak (verified by the ITs of the next PR).Login:
response_mode=query(no deviation from ADR-0001)Token Sheriff 0.9.9 always requests
response_mode=form_post, whose callback is a cross-site POST withoutSameSite=Laxcookies. As in API Sheriff (QueryResponseModeAuthorizationRequestBuilder), the application rewrites only that parameter toquery, so the callback is a top-level GET and theLaxtransaction cookie arrives, exactly as TRH-AUTH-1 specifies. Accepted cost: the code appears in the callback URL. It is bounded by PKCE, the single-use code, the transaction withstate, andReferrer-Policy: no-referrer. A first draft of this PR usedSameSite=Noneinstead; that is withdrawn (commitbf5b207).Native image / JGit (open question of application-architecture.adoc)
JGit runs natively without a JVM fallback once:
org.eclipse.jgitis initialised at run time (staticRandom/SecureRandom)JGitTextand the 100 JGit enums are registered for reflection (META-INF/native-image/de.cuioss/trailhand)Smoke-tested in the container: clone of a
file:remote, restart from the volume, unreachable remote → readiness stays UP andgit-remoteis DOWN. The Quarkiversequarkus-jgitextension would cover this too, but needs a dependency approval.Verification
./mvnw clean verify: 87 tests intrailhand(config rules, placeholders, repository service against a local remote, sessions, rights, return check, login service with EasyMock, web API incl. CSRF/Origin/CSP/SPA/SSE/health, ArchUnit)./mvnw package -Pnative -pl trailhand -am+docker build: native boot 0.14 s, image healthy via--health-probe./mvnw -Ppre-commit clean verify -DskipTests: headers added, no other changesSummary by CodeRabbit