Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
eaac480
feat(web): bootstrap the web app, its mock server and the end-to-end …
cuioss-oliver Nov 20, 2026
c1d9a7d
fix: resolve the Sonar findings of the bootstrap
cuioss-oliver Nov 20, 2026
f2c9698
feat(app): bootstrap the Quarkus application with the BFF login and t…
cuioss-oliver Nov 20, 2026
bf5b207
fix(app): query response mode, native login and the Sonar findings
cuioss-oliver Nov 20, 2026
066f56d
fix(app): state why the two producers use @Singleton (Sonar java:S9068)
cuioss-oliver Nov 20, 2026
386a964
docs: state the bootstrap and describe the end-to-end suite
cuioss-oliver Nov 21, 2026
d0ee810
Merge branch 'feature/bootstrap-ui' into feature/bootstrap-app
cuioss-oliver Nov 21, 2026
f72c231
docs(app): README of the application module and the native JGit state
cuioss-oliver Nov 21, 2026
eb103d3
docs: remove doc/ai-rules.md
cuioss-oliver Nov 21, 2026
dc9deff
Merge commit 'eb103d3' into feature/bootstrap-app
cuioss-oliver Nov 21, 2026
d32ed2c
Merge branch 'main' into feature/bootstrap-app
cuioss-oliver Nov 21, 2026
86f1cfe
fix(app): handle the review of the application module
cuioss-oliver Nov 21, 2026
d5d3ad8
test(app): check that the native build arguments keep the escaped comma
cuioss-oliver Nov 21, 2026
8da268f
fix(app): handle the second review round of the application module
cuioss-oliver Nov 21, 2026
bdeb8bd
fix(app): handle the third review round of the application module
cuioss-oliver Nov 21, 2026
bff0b1a
fix(app): split the IPv6 serialization and name the status event (Sonar)
cuioss-oliver Nov 21, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 10 additions & 4 deletions README.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,9 @@ Gate Status]]
image:https://sonarcloud.io/api/project_badges/measure?project=cuioss_TrailHand&metric=ncloc[Lines of Code,link=https://sonarcloud.io/summary/new_code?id=cuioss_TrailHand]
image:https://sonarcloud.io/api/project_badges/measure?project=cuioss_TrailHand&metric=coverage[Coverage,link=https://sonarcloud.io/summary/new_code?id=cuioss_TrailHand]

*Bootstrap.* The concepts, specifications and decisions are written; the web app, its mock server and its end-to-end
suite are built, the application follows.
*Bootstrap.* The concepts, specifications and decisions are written; the web app, its mock server, its end-to-end
suite and the application with its login, configuration and repository handling are built; the document operations
follow.

== What is it?

Expand All @@ -36,12 +37,17 @@ The target is Java 25; CI builds on Java 25 and 27.
----

The modules of link:doc/specification/architecture-and-modules.adoc[Architecture and Modules] are added as they are
built: `web-app` (the Svelte web app), `web-mock` (the mock server of its requests, development and tests only) and
`web-e2e` (Playwright and axe-core). The end-to-end suite runs with the profile `e2e`:
built, each with its own README: link:web-app/README.adoc[`web-app`] (the Svelte web app),
link:web-mock/README.adoc[`web-mock`] (the mock server of its requests, development and tests only),
link:trailhand/README.adoc[`trailhand`] (the Quarkus application) and link:web-e2e/README.adoc[`web-e2e`] (Playwright
and axe-core). The end-to-end suite runs with the profile `e2e`, the native image with the profile `native` (Mandrel
in a container):

[source,bash]
----
./mvnw verify -Pe2e -pl web-e2e -am
./mvnw package -Pnative -pl trailhand -am
docker build -f trailhand/src/main/docker/Dockerfile.native -t trailhand:dev trailhand
----

== Working on the Web App
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,9 @@ application; the identity provider is the external system.
* The application is a confidential client through `token-sheriff-client-quarkus`. It holds the tokens server-side.
* During the login the browser holds a short-lived `HttpOnly`, `Secure`, `SameSite=Lax` login-transaction cookie
that binds `state` and `nonce` across the identity provider's callback. Afterwards it holds only an `HttpOnly`,
`Secure`, `SameSite=Strict` session cookie.
`Secure`, `SameSite=Strict` session cookie. The authorization request asks for `response_mode=query`, so the
callback is a top-level `GET` navigation that carries the `Lax` cookie
(xref:../specification/authentication.adoc#TRH-AUTH-1[TRH-AUTH-1]).
* Step-up for releases uses RFC 9470 through the client.
* Agents present bearer tokens that `token-sheriff-validation-quarkus` validates.
* Rights come from identity-provider groups, mapped per repository. Directory roles grant nothing.
Expand Down Expand Up @@ -57,12 +59,15 @@ option for organisations that run API Sheriff anyway.

=== Properties of the design

* No token reaches the browser.
* No token reaches the browser, except the ID token as `id_token_hint` in the address of the RP-initiated logout,
after the held tokens are revoked (TRH-AUTH-1).
* One authentication component serves the web app and the MCP server.

=== Accepted costs

* Sessions are lost on restart. Users log in again.
* The logout address shows the browser the ID token of the ended session, so the provider can end its own session
without a confirmation page.
* The application runs as one instance; a second instance would need a shared session store.

=== When this is revisited
Expand Down
16 changes: 11 additions & 5 deletions doc/concepts/application-architecture.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -131,10 +131,15 @@ asks for it. The compare-and-swap of the library still keeps concurrent saves of
== Native Image

The native image follows API Sheriff: Mandrel builder on the JDK 25 line, distroless runtime image, a health probe
built into the binary. JGit in a native image is the open risk of this architecture: its reflection, resource and
service-loader use has to be registered, and the transport is restricted to HTTPS, which avoids the SSH stack. The
first integration test builds the native image and runs a fetch, a save and a push against a local Git server before
anything else depends on it.
built into the binary. JGit in a native image was the open risk of this architecture: its reflection, resource and
service-loader use has to be registered, and the transport is restricted to HTTPS, which avoids the SSH stack.

The bootstrap settled the first half. Clone and fetch of `file:` remotes run in the native image, with no JVM fallback,
once JGit is initialised at run time (it holds random generators in static fields) and its message bundle and enums
are registered for reflection; Token Sheriff's flow package needs the same run-time initialisation. The registrations
and their reasons are listed in the README of the `trailhand` module. HTTPS transport, in-core writing and notes
follow with the Git round trip, whose integration test (TRH-NFR-5) runs a fetch, a save, a release and a push against
a local Git server.

== Testing

Expand All @@ -145,7 +150,8 @@ specified in xref:../specification/testing.adoc[Testing].

== Open Questions

. Verify that JGit (HTTPS transport, in-core writing, notes) runs in the native image without the JVM fallback.
. Verify that the rest of JGit (HTTPS transport, in-core writing, notes) runs in the native image without the JVM
fallback; clone and fetch are verified.
. Whether the categories module ships inside the application or as an overridable directory mounted at run time.

== Related
Expand Down
3 changes: 2 additions & 1 deletion doc/specification/architecture-and-modules.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -297,7 +297,8 @@ created with the code. Metrics: `quarkus-micrometer-registry-prometheus` at `/q/
|Condition |Behaviour

|Fetch fails
|The index serves the last fetched state; the health check `git-remote` reports `DOWN` per repository; readiness
|The index serves the last fetched state; the health check `git-remote` (health group
`/q/health/group/git-remote`) reports `DOWN` with the fetch state per repository; readiness
stays `UP`

|Push fails during a save
Expand Down
39 changes: 29 additions & 10 deletions doc/specification/authentication.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,8 @@ https://github.com/cuioss/git-document-repository/blob/main/doc/specification/gi
== TRH-AUTH-1: Web Login

* The web login must use the authorization code flow with PKCE `S256` as a confidential client through Token Sheriff.
* No access, refresh or ID token may be sent to the browser.
* No access, refresh or ID token may be sent to the browser, with one exception: the ID token as `id_token_hint` in
the address of the RP-initiated logout, after the held tokens are revoked and the session is ended.
* During login the browser must hold only a short-lived login-transaction cookie, afterwards only the session cookie,
both `HttpOnly` and `Secure`; the session must end after a configurable idle time (default 30 minutes) and absolute
lifetime (default 8 hours).
Expand All @@ -37,15 +38,19 @@ https://github.com/cuioss/git-document-repository/blob/main/doc/specification/gi
|Endpoints
|`GET /api/v1/auth/login?return=<address>`, `GET /api/v1/auth/callback`, `POST /api/v1/auth/logout`

|`return`
|Starts with a single `/` (not `//`, no `\`, no scheme, no authority) and matches one of the canonical addresses of
xref:web-app.adoc#TRH-WEB-3[Web App, Navigation]; kept in the server-side login transaction, not in the browser
|Response mode
|`response_mode=query`: the provider sends the browser back to the callback with `code`, `state` and `iss` in the
query, a top-level `GET` navigation that carries the transaction cookie. Token Sheriff's request builder sets
`form_post`, whose callback is a cross-site `POST` without `SameSite=Lax` cookies
(link:https://www.ietf.org/archive/id/draft-ietf-httpbis-rfc6265bis-22.html#section-5.6.7.1[draft-ietf-httpbis-rfc6265bis-22, §5.6.7.1]);
the application replaces only that parameter, as API Sheriff does. Accepted cost: the code appears in the callback
address; PKCE, the single use of the code, the transaction with `state` and `Referrer-Policy: no-referrer` bound it

|Transaction cookie
|`__Host-trailhand-login`; `HttpOnly`, `Secure`, `SameSite=Lax`, `Path=/`, `Max-Age=600`; carries only an opaque
reference to the server-side login transaction (`state`, `nonce`, PKCE verifier); deleted by the callback. `Lax`,
because the browser does not send a `SameSite=Strict` cookie on the cross-site redirect back from the identity
provider
reference to the server-side login transaction (`state`, `nonce`, PKCE verifier); taken once and deleted by the
callback. `Lax`, because the browser does not send a `SameSite=Strict` cookie on the cross-site redirect back from the
identity provider

|Session cookie
|`__Host-trailhand-session`; `HttpOnly`, `Secure`, `SameSite=Strict`, `Path=/`; set by the callback
Expand All @@ -64,7 +69,20 @@ carries the session cookie.
|`web.session.idle-timeout` (default `PT30M`), `web.session.max-lifetime` (default `PT8H`)

|Logout
|RP-initiated at the provider's `end_session_endpoint`; held tokens revoked first
|RP-initiated at the provider's `end_session_endpoint`; held tokens revoked first. Revocation is best effort: a
provider without `revocation_endpoint` or a refused revocation (logged, `TRAILHAND-104`) does not stop the logout. The
session ends and the tokens are dropped from the application in every case, and the end-session request ends the
provider's session. The address carries the ID token as
`id_token_hint`, which OpenID Connect RP-Initiated Logout recommends
(link:https://openid.net/specs/openid-connect-rpinitiated-1_0.html#RPLogout[RP-Initiated Logout 1.0, §2]: the RP
redirects the user agent to the logout endpoint; `id_token_hint` RECOMMENDED); with it the provider ends its session
without asking again. The application accepts no token from the browser, only the session cookie

|Pending logins
|At most 10,000 login transactions at once, each for 10 minutes; a start beyond that answers `503 TOO_MANY_LOGINS`
with `Retry-After: 60` (the login is reachable without a session). Every transaction has the same lifetime, so each
start drops the expired and taken transactions in the order of their expiry, without scanning the others. A start
whose authorization request cannot be sent (PAR refused) frees its place at once

|`401` from `/api/v1`
|Response body names the login address; the web app follows it with the current canonical address as `return`
Expand All @@ -78,8 +96,9 @@ carries the session cookie.
* Every request must be checked; a request without a mapped right must be refused (deny by default).
* No right may be derived from a directory role.

Input: the `groups` claim (or the claim configured as group source) of the session or bearer token. Mapping:
`trailhand.yaml` → `rights`.
Input: the `groups` claim (or the claim configured as group source) of the session or bearer token, read from the
JSON payload of the validated token as the provider wrote it: an array yields its strings, a single string one group,
anything else none, so a group name that contains a comma stays one group. Mapping: `trailhand.yaml` → `rights`.

[cols="1,3"]
|===
Expand Down
35 changes: 30 additions & 5 deletions doc/specification/configuration.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -48,8 +48,21 @@ The application sets these values; the column shows the application's value, not
|`trailhand.config.dir`
|`config`
|Directory holding `trailhand.yaml`

|`trailhand.oidc.jwks-url`
|not set
|The address of the provider's keys, set only when the application reaches the provider under another origin than
its issuer (split horizon, as in the compose stack); otherwise the keys are found through the issuer's well-known
document
|===

Token Sheriff reads its own keys (`sheriff.client.*`, `sheriff.token.issuers.*`); the application derives them from
`trailhand.yaml` → `oidc` and `web.origin` with an ordinal above `application.properties` and below the environment.
Settings of the deployment's network stay in the environment, among them `SHERIFF_CLIENT_BACK_CHANNEL_ORIGIN` (the
origin the client dials instead of the issuer's), `SHERIFF_CLIENT_ALLOWED_EGRESS_HOSTS` and
`SHERIFF_TOKEN_ISSUERS_TRAILHAND_JWKS_HTTP_ALLOWED_EGRESS_HOSTS` (hosts on private addresses that the egress guard
admits).

=== trailhand.yaml

Validated against `schema/trailhand.schema.json` (bundled). Top-level keys:
Expand Down Expand Up @@ -125,7 +138,9 @@ https://github.com/cuioss/git-document-repository/blob/main/doc/specification/gi

|`web`
|yes
|`session.idle-timeout` (default `PT30M`), `session.max-lifetime` (default `PT8H`), `information-text-ref`
|`origin` (the application's own origin, an absolute `https` URI without path: the `Origin` check of
xref:web-app.adoc#TRH-WEB-8[TRH-WEB-8] compares with it, and the login callback is `<origin>/api/v1/auth/callback`),
`session.idle-timeout` (default `PT30M`), `session.max-lifetime` (default `PT8H`), `information-text-ref`

|`directory`
|no
Expand All @@ -152,16 +167,26 @@ Every key ending in `-ref` accepts one of three reference forms; no key accepts
`anchor.signed-key-ref`).
* `vault:<path>`: a secret of Vault's key-value engine; accepted by every key except the signing keys.

Placeholders: `${NAME}` and `${NAME:-default}` in any string value, resolved from the environment before validation;
an unresolved placeholder without default is a boot error.
Placeholders: `${NAME}` and `${NAME:-default}` in any string value, resolved from the environment before validation.
`NAME` is an environment variable name (letters, digits and underscores, not starting with a digit). An unresolved
placeholder without default is a boot error, and so is any other `${...}`, so it never passes as a literal value.

=== Boot Validation

Before the application accepts requests, every rule runs; each violation produces one `ERROR` record, and any
violation stops the boot. Besides the schema, the rules refuse what the schema cannot see: two repositories with one
alias, a `rights` entry or `directory.persons.repository` naming an unknown alias, a `-ref` value in a form its key
does not accept, an `anchor.signed-key-ref` equal to `signing.key-ref`, and an `mcp.canonical-uri` that is not an
absolute HTTPS URI without fragment. `--validate-config <dir>` runs the same rules offline.
does not accept, an `anchor.signed-key-ref` equal to `signing.key-ref`, an `mcp.canonical-uri` that is not an
absolute HTTPS URI without fragment, and a `web.origin` that is no HTTPS origin or a `web.session.idle-timeout` longer
than `web.session.max-lifetime`. `--validate-config <dir>` runs the same rules offline.
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved

The bootstrap enforces the rules of the keys it reads: `repositories`, `rights`, `oidc`, `web` and `fetch`, the
placeholders, and `web.origin` and the session lifetimes. Until the Vault adapter is built, `file:` is the only
reference form it accepts for the references it reads, `repositories[].credential-ref` and
`oidc.client-credential-ref`; `vault:` and `kms:` are refused there at boot. Other `-ref` keys, such as
`web.information-text-ref`, are not read yet and not checked. The JSON Schema and the rules of `signing`,
`anchor`, `mcp` and `directory`, with the per-key reference forms, apply once their modules are built; until then a
value under those keys is not checked.

[#TRH-CONF-2]
== TRH-CONF-2: Repositories and Refresh
Expand Down
2 changes: 1 addition & 1 deletion doc/specification/deployment.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ xref:../concepts/deployment.adoc[Deployment].
|`quay.io/quarkus/quarkus-distroless-image:2.0@sha256:<digest>`; the digest is updated by a dependency bot

|User and binary
|`nonroot`; `/app/application`
|`nonroot`, declared numerically as `65532:65532`, its id in the base image's `/etc/passwd`; `/app/application`

|Health check
|`HEALTHCHECK CMD ["/app/application","--health-probe"]`; the binary probes its own management port and exits `0`
Expand Down
10 changes: 9 additions & 1 deletion doc/specification/web-app.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -243,12 +243,20 @@ Refusals:
|`VALIDATION`
|`errors`: a list of `{"pointer", "code"}`, `pointer` a JSON Pointer into the request body

|`502`
|`IDENTITY_PROVIDER_UNAVAILABLE`
|`GET /api/v1/auth/login` cannot start the login: the provider's metadata cannot be read

|`503`
|`GIT_UNAVAILABLE`
|The Git server is unreachable (xref:architecture-and-modules.adoc#TRH-GEN-6[TRH-GEN-6])

|`503`
|`TOO_MANY_LOGINS`
|`GET /api/v1/auth/login` cannot start the login: 10,000 logins are pending (TRH-AUTH-1); with `Retry-After: 60`
|===

The login callback (xref:authentication.adoc#TRH-AUTH-1[TRH-AUTH-1]) navigates with
The login callback (xref:authentication.adoc#TRH-AUTH-1[TRH-AUTH-1]) answers a page that navigates with
`<meta http-equiv="refresh" content="0;url=<return>">`, so the page needs no script and passes the policy of
<<TRH-WEB-8>> unchanged. `POST /api/v1/auth/logout` answers `{"redirect"}`, the address the web app navigates to
(the provider's `end_session_endpoint`).
1 change: 1 addition & 0 deletions pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,7 @@
<modules>
<module>web-app</module>
<module>web-mock</module>
<module>trailhand</module>
<module>web-e2e</module>
</modules>
<dependencyManagement>
Expand Down
4 changes: 4 additions & 0 deletions trailhand/.dockerignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
# Only the native runner and the data directory placeholder enter the image (Dockerfile.native).
*
!target/*-runner
!src/main/docker/data/
Loading