Proof#
This page says what each check of Drawbridge proves, in the README's words, and how to run it.
Last run#
| Check | Date | Commit | Result | Duration |
|---|---|---|---|---|
composer ci |
2026-11-10 | 5c6e564 |
pass: 577 tests, 3988 assertions, 12 skipped | 17 s |
sh rig/run.sh |
2026-11-10 | 5c6e564 |
pass: 159 tests, 1120 assertions, 5 skipped; smoke 23 passed, 7 skipped | 77 s |
sh rig/run.sh trial |
2026-11-10 | 5c6e564 |
pass: 5 tests, 33 assertions and smoke 9 of 9, before and after the rollback | 63 s |
rig\run.ps1 trial |
2026-11-10 | 1150b91 |
pass: 5 tests, 33 assertions and smoke 9 of 9, before and after the rollback | 62 s |
rig\run.ps1 keycloak |
2026-11-07 | a60990a |
pass: 4 tests, 33 assertions | 38 s |
rig\run.ps1 rotation |
2026-11-07 | a60990a |
pass: 5 of 5 phases | 68 s |
sh rig/run.sh redis-rotation |
2026-11-10 | 57bf8fa |
pass: 4 of 4 steps, 34 assertions | 65 s |
sh rig/run.sh multi |
2026-11-10 | 57bf8fa |
pass: 4 of 4 steps, 130 assertions | 57 s |
rig\run.ps1 multi |
2026-11-10 | 57bf8fa |
pass: 4 of 4 steps, 130 assertions | 54 s |
The keycloak and rotation rows ran through rig\run.ps1 on 2026-11-07, when Git Bash still rewrote the Unix config path rig/run.sh exports for Docker into a Windows path. Since 2026-11-10 rig/run.sh switches that rewrite off (MSYS_NO_PATHCONV=1), so it runs from Git Bash on Windows too; the redis-rotation and multi rows ran that way. Rerun the commands and replace the values to refresh this table; the composer ci, redis-rotation and multi rows are newer than the other rig rows, which still date from 2026-11-07. The optional SESAME integration suite did not run because no SESAME checkout was available; its eleven tests show as skipped. The twelfth skip is FileStorageTest::testAnUnwritableDirectoryThrowsAtConstruction, which cannot make a directory unwritable when the suite runs as root, as it does in the composer container.
composer ci#
composer ci # manifest, unit tests, Pint, agent-ready pages, PHPStan level 8, composer audit, docs build
The same command runs in the GitLab pipeline and in the GitHub Actions workflow kept in .github/. The PHPStan and Pint settings come from Pinstripe, the stack's coding standard: phpstan.neon includes the raw PHP cut, and pint.json uses the same per preset as Pinstripe's pint/per.json. This repository adds only its own paths, PHP version range and excludes.
In Docker, with no local PHP:
docker run --rm -v "${PWD}:/app" -w /app composer:2.11.1@sha256:8de2184c6de224f4689e8f80ed5f5edaf0030b6b8b7839a22a2bcb6722ac87d0 sh -c "composer install --no-interaction && composer ci"
The unit suite checks the assertion against a mirror of SESAME's gateway driver rules (tests/Support/SesameContract.php). To check it against the real driver instead, point SESAME_PATH at a SESAME checkout that has been installed (composer install in it) and run the integration suite; without it the suite skips, so composer ci stays green:
docker run --rm -v "${PWD}:/app" -v "C:\path\to\sesame:/sesame:ro" -e SESAME_PATH=/sesame -w /app composer:2.11.1@sha256:8de2184c6de224f4689e8f80ed5f5edaf0030b6b8b7839a22a2bcb6722ac87d0 sh -c "composer install --no-interaction && vendor/bin/phpunit --filter RealSesame"
The container rig#
The container rig runs the real gateway image with a mock OpenID Connect provider (mock-oauth2-server, pinned) standing in for Entra, and a tiny echo app. It covers sign-in, public and protected paths, header spoofing (including forged OIDC_* headers), path tricks, forged callbacks, step-up to an authentication context, signature checks against SESAME's gateway driver rules, and logout. The mock signs in anyone with whatever claims the test types into its form, which is exactly what you want from a stunt double. Nothing in the rig reaches Entra.
sh
sh rig/run.sh # Linux, macOS
PowerShell
rig\run.ps1 # Windows
The keycloak argument#
The keycloak argument swaps the mock for a pinned Keycloak started from rig/keycloak/realm.json and runs the sign-in, claims and logout tests against it. Unlike the mock, that provider checks the client secret and PKCE, signs in only the realm's two synthetic users, and refuses redirect URIs it was not given, so the run proves the round trip against a strict OpenID Connect implementation.
sh
sh rig/run.sh keycloak # Linux, macOS
PowerShell
rig\run.ps1 keycloak # Windows
The rotation argument#
The rotation argument walks a crypto passphrase change through the running gateway without recreating it. It signs in, saves the session cookie, re-renders the Apache config with the new passphrase while keeping the old one as mod_auth_openidc's documented previous value, sends Apache a graceful reload, and replays the saved cookie. The run documents what the pinned module actually does: it accepts the two values and starts, but its shared-memory session store is rebuilt empty on every reload, so the saved cookie is refused and the browser is sent to sign in again. The same refusal is then shown with the old passphrase dropped, and after the gateway container is recreated with a fresh sign-in, so the result is not an accident of the reload.
sh
sh rig/run.sh rotation # Linux, macOS
PowerShell
rig\run.ps1 rotation # Windows
The redis-rotation argument#
The redis-rotation argument walks the same kind of passphrase change with the sessions in Redis (gateway.session_store: redis), where it is graceful. It signs in under passphrase A, reloads with B current and A previous, and checks that the saved cookie is still accepted and a new sign-in works under B. It then reloads with B alone: the cookie from A is sent back to sign in (a redirect, not a 500) while the session from B keeps working. Last, it recreates the gateway container from its environment on B, and the session from B survives that too (RedisRotationTest). ```bash tab="sh"
sh rig/run.sh redis-rotation # Linux, macOS
```powershell tab="PowerShell"
rig\run.ps1 redis-rotation # Windows
The multi argument#
The multi argument raises a second gateway instance (gateway2) on the same image, config and Redis, and rolls the redis-rotation steps across the two one at a time (MultiInstanceRotationTest). The tests reach the second instance by its service name and send the app host themselves.
- Both on A: a session signed in through the first instance opens the app on the second, which hands the app the same person's assertion.
- Mid-roll, the first on B current and A previous, the second still on A alone: the session from A opens both, and a session the second issues opens the first. A session the first issues under B is sent to sign in by the second (a redirect, not an error page), because the second does not know B yet.
- Both on B current and A previous: a session either instance issues under B opens the app on the other.
- Both on B alone: both send the session from A to sign in, and both sessions from step 3 keep opening the app on both.
The run fails when the second instance does not share the first one's view. Pointing it at the shared-memory store instead of Redis fails step 1 (the cookie gets a 302 on the second instance), and leaving A as its previous value at the end fails step 4 (it still opens the session from A). Not proven here: more than two instances, a real load balancer in front of them, and a Redis outside the rig.
sh
sh rig/run.sh multi # Linux, macOS
PowerShell
rig\run.ps1 multi # Windows
The trial argument#
The trial argument runs the trial kit (trial/compose.yaml, the deployment First deployment puts on a pre-production host) as shipped, with rig/trial.yaml adding the mock provider, the keys and a tester. It proves the kit, not only the gateway:
TrialTestsigns in through the whoami app and reads what whoami verified: the signature against the key set filekeys:jwkswrote,typ, the audience and the expiry, all true, as alice. The public path carries no identity even when the visitor sends one. Sent straight to whoami, around the gateway, an assertion signed with a stranger's key (under the gateway's own kid) and a plain header are both refused.drawbridge smokeinside the gateway container, with no options: every check passes, none skipped.- The rollback drill: the gateway moves to another image tag with
up -d --no-deps gateway, the run checks that the gateway now runs that tag and that whoami was not recreated, then steps 1 and 2 run again.
TrialConfigTest (in composer ci) keeps the kit honest without Docker: the example config loads and has a path of every kind, the rig's copy has the same rules, both services keep their hardening and read-only mounts, only the gateway is published (on loopback), and every setting in .env.example is one the gateway reads.
sh
sh rig/run.sh trial # Linux, macOS
PowerShell
rig\run.ps1 trial # Windows
Where the tests live#
BEST_PRACTICES.md holds the practices Drawbridge holds itself to, each with one tag (Enforced, Checked, Documented or Not yet), and every Enforced practice names the tests that prove it. Those tests live under tests/ (for example tests/E2E/SpoofingTest.php); the Best practices page lists the rules.
What 0.1.1 added to the proof#
From the Changelog, 0.1.1 (2026-11-03):
- Rig: an opt-in
keycloakargument (rig/run.sh keycloak,rig/run.ps1 keycloak) starts a pinned Keycloak from a hand-written realm as a second identity provider. It checks the client secret and PKCE, knows only two synthetic users, and refuses unregistered redirect URIs; the Keycloak tests sign one of them in and out through the gateway. - Rig: the gateway runs with a throwaway metrics token, and the end-to-end tests check every app host answers
/metricsto the bearer token (200,text/plain,Cache-Control: no-store) and refuses it otherwise (403). - Rig: an opt-in
rotationargument (rig/run.sh rotation,rig/run.ps1 rotation) walks a crypto passphrase change through the running gateway: it signs in, re-renders the Apache config with the new passphrase while keeping the old one as mod_auth_openidc's documented previous value, sends Apache a graceful reload, and replays the saved session cookie. It documents that the pinned module accepts the two values but rebuilds its shared-memory session store empty on every reload, so the saved cookie is refused and the browser is sent to sign in again; the same refusal holds once the old passphrase is dropped and after the gateway container is recreated. - Tests: the rendered session cookie flags are pinned:
OIDCCookieSameSite LaxandOIDCCookieHTTPOnly Onhold whether secure cookies are on or off, andOIDCCookieSameSite Nonenever appears. - Tests:
GatewayTest::testTheSessionCookieIsHttpOnlyAndLaxAtCallbacksigns in through the rig and reads the session cookie the gateway actually set out of the BrowserKit cookie jar: it is HttpOnly, SameSite=Lax, scoped to path/, and carries no Domain attribute beyond the app host. - Tests:
BestPracticesTestverifies that every test method and class cited inBEST_PRACTICES.mdstill exists undertests/, so the document cannot drift from the suite. - Tests: the gateway error pages are pinned to WCAG 2.2 AA properties: text contrast of at least 4.5:1 in both the light and dark color schemes, a viewport that does not block zoom, a visible focus outline of at least 2px, and a body text size of at least 16px with headings set in rem or em.
- Tests:
KeycloakTest::testLogoutWithThirdPartyCookiesBlockedsigns alice in through the Keycloak rig profile, then strips every identity-provider cookie from the browser's cookie jar (a simulation of a browser that blocks third-party cookies, not a real-browser run) and proves the gateway logout still ends the gateway session with only the app host's cookies left. - Tests:
RealSesameTest::testAReplayedTokenFailspresents one signed assertion twice to one SESAME GatewayDriver instance (through a new optionalrepeatfield intests/Support/sesame-verify.php) and proves the first presentation passes while the second is refused as a replay. - Tests:
SpoofingTest::testADuplicatedIdentityHeaderNeverReachesTheAppsends the identity header twice in one raw request (two values, two spellings, and twice beside the email header) and proves noX-Authenticated-*value reaches the echo app, anonymous on a public path and signed in on a protected one. - Tests:
E2eProvidersTestpins the shape ofSpoofingTest::duplicatedIdentityHeaders, so each data set stays one list argument instead of spreading into a string per line. - Tests:
GatewayTest::testAnApiPathAnswers401ForADeadSessionsigns in, keeps a copy of the session cookie, ends the session through the logout callback, then replays the dead cookie on an api path with anAccept: application/jsonheader and proves the answer is a bare 401 with no Location header. - Docs/Tests:
BEST_PRACTICES.mdno longer claims that every rule has a test. Each rule now names the tests that prove it, or says plainly that it has none yet, andBestPracticesTest::testEveryRuleNamesItsTestsOrSaysNotTestedfails when a rule names neither. (Since 0.4.0 every practice carries one tag instead, andBestPracticesTest::testEveryEnforcedPracticeNamesItsTestsholds theEnforcedones to their tests.) - Tests: the default catch-all host's hardened headers are pinned:
Referrer-Policy: strict-origin-when-cross-originandContent-Security-Policy: frame-ancestors 'none'stand at host level beside the existingno-storeandnosniff, bothsetifemptyso a location that sets its own value keeps it, and the/_drawbridge/uplocation keeps its own plainset. - Tests: the rendered session lifetimes are pinned:
OIDCSessionMaxDurationfollowsgateway.session_seconds(default 28800, 300 to 604800) andOIDCSessionInactivityTimeoutfollowsgateway.session_idle_seconds(default 3600, 60 to 86400), checked with the fixture defaults and with configured values. - Tests:
SignerMapTest::testTheLogCarriesAReasonCodeAndNoSubjectOrTokenproves a refused signing request leaves exactly one reason-code line in the signer's log, with no subject, attribute or token, andSignerMapTest::testAFailureLogsOnlyTheExceptionClassproves a signing failure logs only the exception class, never its message.