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
test(it): integration tests of the native image with Keycloak - #4
Keycloak 26.8.1, pinned by digest. Realm trailhand with groups assessors/approvers/catalog-admins/readers and one user each. Confidential client trailhand-web with exact redirect and post-logout URIs and PKCE S256. Client trailhand-mcp-agent registered for the MCP server, unused so far.
The native image trailhand:it: read-only root, cap_drop: ALL, no-new-privileges, tmpfs /tmp, named data volume. The health check comes from the image (the binary's --health-probe).
Split horizon as in API Sheriff: the issuer is https://localhost:1443, and the container dials keycloak:8443 (SHERIFF_CLIENT_BACK_CHANNEL_ORIGIN, TRAILHAND_OIDC_JWKS_URL).
Scripts:
TLS material and bare file: remotes are generated into target/, so no key is committed.
The native build runs only when sources changed.
Start waits for readiness; stop dumps the logs.
Gitea is not started yet; it comes with the Git round trip (NativeGitRoundTripIT, TRH-NFR-5).
ITs (27, failsafe)
Class
Checks
HealthIT
live/ready UP after the clone, git-remote group, metrics on 9000 only, status not degraded
WebAppServingIT
every address answers index.html with CSP (sha256- hash, frame-ancestors 'none', no unsafe-inline), nosniff, no-referrer; own fonts/files; catalogue en/de
WebLoginIT
full login against Keycloak (code + PKCE S256, response_mode=query), cookie attributes, no JWT in any browser-facing answer, rights per group, deny by default, callback without transaction refused
ReturnAddressIT
canonical return kept; //evil, absolute URL and unknown paths become /
CsrfIT
401 without session; 403 without token, with wrong token, with foreign Origin
LogoutIT
logout ends the session, revokes the tokens, leads to Keycloak's end-session address with id_token_hint, Keycloak redirects back
After the ITs, verify-invalid-config-fails.sh checks that the native image refuses to boot with an invalid trailhand.yaml (one TRAILHAND-200 per violation) and that --validate-config exits 1 (the second half of TRH-NFR-5).
Verification
./mvnw clean verify -Pintegration-tests -pl integration-tests -am locally: stack from scratch, native build, 27/27 ITs, invalid configuration refused, teardown. The profile is not part of the CI build, which has no Docker stack step; wiring it into CI is a decision for .github/ I have not touched.
Summary by CodeRabbit
Tests
Added an integration-test suite covering sign-in and sign-out, session and CSRF protections, access rights, health and status endpoints, web pages, and invalid configuration handling.
The suite runs against a Docker-based environment with Keycloak and local Git remotes; integration tests are skipped by default and are not currently run in CI.
Documentation
Updated build and testing guides with instructions for running integration tests, including the Docker requirement and stack setup.
…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>
- 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>
Adds the module integration-tests (profile integration-tests):
- compose stack: Keycloak 26.8.1 (digest-pinned, realm trailhand with
one user per group, confidential client trailhand-web, registered
client trailhand-mcp-agent) and the native image, hardened
(read-only, no capabilities, no-new-privileges); split horizon with
SHERIFF_CLIENT_BACK_CHANNEL_ORIGIN and trailhand.oidc.jwks-url
- scripts: TLS material and bare file: remotes generated into target/
(no key committed), native build only when the sources changed,
start with readiness waits, stop with logs
- 27 failsafe ITs: health and metrics on the management port, web app
serving with CSP, the full login against Keycloak (code + PKCE,
response_mode=query, cookie attributes, no token in the browser),
rights from groups, return check, CSRF and Origin, RP-initiated
logout; afterwards a boot with an invalid configuration must fail
(TRH-NFR-5, second half)
Co-Authored-By: plan-marshall <noreply@cuioss.de>
The PR adds a Maven integration-test module and profile. The profile provisions a local Keycloak and TrailHand stack, then runs integration tests for authentication, health endpoints, and web content.
Changes: Native integration-test profile
Layer / File(s)
Summary
Module and profile wiring pom.xml, integration-tests/pom.xml, README.adoc, doc/specification/*.adoc, integration-tests/README.adoc
The Maven reactor includes the integration-test module. Its profile configures stack setup, Failsafe tests, invalid-configuration checks, and cleanup. The documentation describes the module, profile, and local repository setup.
Stack and test fixtures integration-tests/src/main/docker/*
The Compose stack configures Keycloak and TrailHand. Realm, user, client, application, secret, and invalid-configuration fixtures provide test data.
Stack setup and lifecycle integration-tests/scripts/*
Scripts generate certificates, seed local repositories, build the native image when needed, start services with readiness checks, verify invalid configuration, and stop the stack.
Login and session tests integration-tests/src/test/java/de/cuioss/trailhand/integration/Stack.java, *IT.java
The login helper follows the Keycloak flow and checks session creation. Tests cover session rights, return addresses, CSRF rejection, logout, and callbacks without a login transaction.
Health and web-serving tests integration-tests/src/test/java/de/cuioss/trailhand/integration/HealthIT.java, WebAppServingIT.java
Tests check health endpoints, repository status, metrics, application pages, static files, security headers, and English and German message catalogues.
cuioss/TrailHand#3: Provides the application endpoints, authentication flow, and configuration validation exercised by this PR’s integration tests.
Merge Risk: Low · previous review d5334
This adds an opt-in integration-test profile that does not affect the shipped application. Before relying on it, fix the native-image cache check so tests do not run against a stale binary. Also make setup failures clean up the stack and tighten a few weak assertions and readiness checks. Merge risk is low.
Pre-merge checks: 2
Check name
Status
Explanation
Description Check
Check skipped - CodeRabbit’s high-level summary is enabled.
Title check
The title "test(it): integration tests of the native image with Keycloak" matches the main change. The PR adds the integration-tests Maven module, a Docker Compose stack with Keycloak, and 27 integrat…
Full details: Title check
Explanation
The title "test(it): integration tests of the native image with Keycloak" matches the main change. The PR adds the integration-tests Maven module, a Docker Compose stack with Keycloak, and 27 integration tests that run against the native image. The title is short, specific, and follows the conventional commit style. It does not describe every detail, such as the TLS scripts or the invalid-config check, and that is acceptable.
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.
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>
docs(it): README of the integration tests
The integration-tests README describes what the profile runs, how to run the
tests against a stack that is already up, the stack with its ports and
addresses, the realm users and what each IT checks. The module table names
the module as a jar, not a pom, and the root README links its README.
Co-Authored-By: plan-marshall <noreply@cuioss.de>
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>
The application now pushes the authorization request when the provider
offers PAR, as Keycloak does: the browser address carries only client_id
and request_uri, and Keycloak answers it with a redirect to its login
action. The login helper checks that no authorization parameter appears
in the browser address and follows Keycloak's own redirects with its
cookies, as a browser does.
Co-Authored-By: plan-marshall <noreply@cuioss.de>
- 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 native build of the stack no longer skips the tests: the profile
native runs NativeRegistrationTest before packaging.
Co-Authored-By: plan-marshall <noreply@cuioss.de>
- 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>
Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.
The reason will be displayed to describe this comment to others. Learn more.
Actionable comments posted: 10
Caution
Some comments are outside the diff and can’t be posted inline due to GitHub limitations.
⚠️ Outside diff range comments (1)
Major · Invalidate the runner when its build inputs change. · build-native-if-needed.sh:23
integration-tests/scripts/build-native-if-needed.sh:23 Major · Functional Correctness · Quick win
Invalidate the runner when its build inputs change.
After one native build, change only version.token-sheriff in the root pom.xml. This predicate does not inspect that file, so the suite tests the old dependency inside the cached runner. Docker only copies that runner. Source deletions also escape the timestamp check. Use a build-input fingerprint that includes dependency configuration and file membership, or rebuild unconditionally. (raw.githubusercontent.com)
As per path instructions, “Check a guard's predicate against the scenario the guard exists for.”
cara-catalog belongs to catalog-admins, which explicitly grants rights on directory. This test verifies isolation between repositories, not denial for an unmapped group. No supplied realm group lacks a rights mapping. (raw.githubusercontent.com)
Keep this assertion as an isolation test. Add a user with an unmapped group and assert that its session has no rights. This will detect a permissive fallback that the current fixtures cannot exercise.
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: e0440ddd-f277-40f1-b7df-e7edc06dc2ad
Commits
Reviewing files that changed from the base of the PR and between f240f78 and d5334a1.
Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.
- Certificates are reused only as a complete set, the key included.
- The bare remotes are derived from the stack's trailhand.yaml, built in a
temporary directory and moved into place only after their main branch is
pushed; a remote without main is rebuilt.
- The start waits until TrailHand is ready and the image's health check
reports healthy, bounds every request, and stops the stack again when it
fails; the stack stops before the invalid-config check, so that check
cannot leave it running.
- The invalid-config check requires one TRAILHAND-200 record per violation
of the fixture.
- The native runner is rebuilt when a fingerprint of its inputs (build
files with dependency versions, sources, package lock) changes, not by
file times.
- All ports are published on loopback only.
- LogoutIT builds its expectations from the configured origins;
WebAppServingIT checks media type and content of the static files, so
the start-page fallback fails; a realm user in an unmapped group shows
that such a group grants nothing.
Co-Authored-By: plan-marshall <noreply@cuioss.de>
Replies to the two review findings that had no inline thread:
Outside the diff: invalidate the runner when its build inputs change (build-native-if-needed.sh). Fixed in 9f34154. File times are replaced by a fingerprint by path and content of the native build's inputs: the root and module POMs (dependency versions), .mvn, trailhand/src/main, and web-app's sources, static files, build configuration and package-lock.json. It is stored in trailhand/target/native-inputs.sha256, so a changed version or a deleted file rebuilds the runner. A second run with unchanged inputs reuses it.
Nitpick: an unmapped group in denyByDefault (WebLoginIT.java:73). Done in 9f34154. The realm has a user otto-outsider in the group auditors, which trailhand.yaml does not map; the test asserts that this session has no rights. The cara-catalog assertion stays as the isolation check.
All 27 integration tests and the invalid-config check pass against the native image.
…e expected violations
The 0.1.0-SNAPSHOT of git-document-repository added the prune flag to
RepositoryOperations.FetchInput, which broke the build of main as well.
The fetch passes false, so references the remote no longer advertises stay
in the local copy as before.
The invalid-config check now compares the TRAILHAND-200 records of the
boot with the ones --validate-config reports for the same fixture, as a
multiset, instead of a hand-kept list; the list of rule groups stays as a
check that the fixture still covers them.
Co-Authored-By: plan-marshall <noreply@cuioss.de>
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.
Third of three staged bootstrap PRs. Stacked on #2 and #3: only commit
7d588a2is new here. Draft until those are merged and the branch is rebased.integration-tests (profile
integration-tests)src/main/docker/docker-compose.yml):trailhandwith groups assessors/approvers/catalog-admins/readers and one user each. Confidential clienttrailhand-webwith exact redirect and post-logout URIs and PKCE S256. Clienttrailhand-mcp-agentregistered for the MCP server, unused so far.trailhand:it: read-only root,cap_drop: ALL,no-new-privileges, tmpfs/tmp, named data volume. The health check comes from the image (the binary's--health-probe).https://localhost:1443, and the container dialskeycloak:8443(SHERIFF_CLIENT_BACK_CHANNEL_ORIGIN,TRAILHAND_OIDC_JWKS_URL).file:remotes are generated intotarget/, so no key is committed.NativeGitRoundTripIT, TRH-NFR-5).ITs (27, failsafe)
HealthITgit-remotegroup, metrics on 9000 only, status not degradedWebAppServingITindex.htmlwith CSP (sha256-hash,frame-ancestors 'none', nounsafe-inline),nosniff,no-referrer; own fonts/files; catalogue en/deWebLoginITresponse_mode=query), cookie attributes, no JWT in any browser-facing answer, rights per group, deny by default, callback without transaction refusedReturnAddressITreturnkept;//evil, absolute URL and unknown paths become/CsrfITOriginLogoutITid_token_hint, Keycloak redirects backAfter the ITs,
verify-invalid-config-fails.shchecks that the native image refuses to boot with an invalidtrailhand.yaml(oneTRAILHAND-200per violation) and that--validate-configexits 1 (the second half of TRH-NFR-5).Verification
./mvnw clean verify -Pintegration-tests -pl integration-tests -amlocally: stack from scratch, native build, 27/27 ITs, invalid configuration refused, teardown. The profile is not part of the CI build, which has no Docker stack step; wiring it into CI is a decision for.github/I have not touched.Summary by CodeRabbit