feat: integrate Keycloak 26 commercial hardening

.env.example

@@ -16,6 +16,9 @@ IDP_DB_PASSWORD=                       # from KV: secret/idp/db
 IDP_EXTERNAL_PORT=8080
 # Public base URL / hostname Keycloak advertises (behind the WAF in prod).
 IDP_EXTERNAL_HOSTNAME=http://localhost:8080
+# Cache stack: `local` (default; single-node standalone compose) or `ispn`
+# for clustered deployments. See the KC_CACHE note in docker-compose.yml.
+IDP_CACHE_MODE=local
 
 # Bootstrap admin. Created ONCE; retire after registering a passkey.
 IDP_BOOTSTRAP_ADMIN_USERNAME=idp-admin

.github/workflows/ci.yml

@@ -5,6 +5,12 @@ on:
     branches: [main]
   pull_request:
 
+# Cancel superseded evidence for the same pull request or branch. This keeps the
+# runner queue bounded during review-fix loops while preserving the newest head.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
 # Least-privilege default token (OSSF Scorecard: Token-Permissions).
 permissions:
   contents: read

.github/workflows/codeql.yml

@@ -5,6 +5,12 @@ on:
     branches: [main]
   pull_request:
 
+# Code scanning evidence is head-specific; cancel scans made obsolete by a
+# newer commit on the same pull request or branch.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
 permissions:
   actions: read
   contents: read

.github/workflows/hourly-pr-steward.yml

@@ -0,0 +1,105 @@
+name: Hourly PR steward
+
+on:
+  schedule:
+    # Avoid the top-of-hour congestion window. Scheduled runs use UTC and the
+    # latest commit on the default branch.
+    - cron: "17 * * * *"
+  workflow_dispatch:
+
+# Keep the workflow token read-only by default. Only the single steward job
+# receives the narrowly scoped writes required to update trusted branches and
+# arm GitHub-native auto-merge after protected evidence is complete.
+permissions:
+  contents: read
+
+concurrency:
+  group: hourly-pr-steward
+  cancel-in-progress: false
+
+jobs:
+  advance-approved-pull-requests:
+    name: Advance approved pull requests
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: write
+      pull-requests: write
+      checks: read
+    steps:
+      - name: Update, verify, and arm trusted pull requests
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPOSITORY: ${{ github.repository }}
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          gh pr list \
+            --repo "$REPOSITORY" \
+            --state open \
+            --limit 100 \
+            --json number,isDraft,author,headRepositoryOwner,headRefOid,mergeStateStatus,reviewDecision \
+            > "$RUNNER_TEMP/open-pull-requests.json"
+
+          jq -c '.[]' "$RUNNER_TEMP/open-pull-requests.json" | while IFS= read -r pull_request; do
+            number="$(jq -r '.number' <<<"$pull_request")"
+            is_draft="$(jq -r '.isDraft' <<<"$pull_request")"
+            author="$(jq -r '.author.login // ""' <<<"$pull_request")"
+            head_owner="$(jq -r '.headRepositoryOwner.login // ""' <<<"$pull_request")"
+            head_sha="$(jq -r '.headRefOid' <<<"$pull_request")"
+            merge_state="$(jq -r '.mergeStateStatus // "UNKNOWN"' <<<"$pull_request")"
+            review_decision="$(jq -r '.reviewDecision // ""' <<<"$pull_request")"
+
+            if [[ "$is_draft" != "false" || "$head_owner" != "ContextualWisdomLab" ]]; then
+              continue
+            fi
+
+            trusted_author=false
+            for allowed_author in \
+              seonghobae \
+              dependabot \
+              'dependabot[bot]' \
+              app/dependabot \
+              github-actions \
+              'github-actions[bot]' \
+              app/github-actions \
+              opencode-agent
+            do
+              if [[ "$author" == "$allowed_author" ]]; then
+                trusted_author=true
+                break
+              fi
+            done
+            if [[ "$trusted_author" != "true" ]]; then
+              continue
+            fi
+
+            # Keep trusted branches current. A successful update invalidates the
+            # old check evidence, so the steward waits for the next hourly pass.
+            if [[ "$merge_state" == "BEHIND" ]]; then
+              gh pr update-branch "$number" --repo "$REPOSITORY" || true
+              continue
+            fi
+
+            if [[ "$review_decision" != "APPROVED" ]]; then
+              continue
+            fi
+
+            # Never infer safety from optional checks. The repository's required
+            # check set remains the source of truth. `gh pr checks` exits nonzero
+            # for failed checks and uses exit code 8 for pending checks, so either
+            # condition leaves the PR untouched.
+            if ! gh pr checks "$number" --repo "$REPOSITORY" --required; then
+              continue
+            fi
+
+            # Arm GitHub's native auto-merge service rather than creating the
+            # merge commit directly with GITHUB_TOKEN. Rulesets remain final,
+            # and the exact reviewed/check head must still match.
+            gh pr merge "$number" \
+              --repo "$REPOSITORY" \
+              --auto \
+              --squash \
+              --match-head-commit "$head_sha"
+          done

CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+All notable changes to Keyverse are documented in this file. The format follows
+Keep a Changelog, and releases use semantic versioning.
+
+## [Unreleased]
+
+### Added
+
+- Password-free headless registration that sends one bounded Keycloak action
+  email for address verification and passkey enrollment, with failure-atomic
+  account rollback.
+- Modular product-facing Keycloak Admin API extensions for registration and
+  runtime identity-provider federation.
+- Runtime federation desired-state convergence with explicit applied-state
+  reporting and fail-closed operator-response redaction.
+- Router-level validation for decoded privileged and SCIM path parameters,
+  including protocol-native SCIM error responses.
+- Persistent Compose and Helm storage for audit and user-operation lock data.
+- Optional Helm enforcement of immutable account-unification image digests.
+- Concurrency and lifecycle regressions for SQLite-backed configuration, audit,
+  and mutation-lock persistence.
+
+### Changed
+
+- The bound Keycloak browser flow is now strictly passkey-only; registration no
+  longer creates a bootstrap password or runs a credential janitor.
+- The public `naruon-web` access-token lifespan is reduced to five minutes while
+  the longer SSO session remains available through token refresh and reissue.
+- Registration configuration is all-or-nothing and requires a distinct bearer
+  token, relying-party client, HTTPS redirect URI, and bounded action-link
+  lifetime.
+- Registration throttling is isolated by direct peer address rather than one
+  process-wide counter.
+- Account merge and SCIM replacement now share the same user-operation lock
+  boundary.
+- SQLite configuration and audit stores support safe multi-threaded access with
+  WAL mode and bounded busy timeouts.
+- Application shutdown closes Keycloak, audit, and configuration resources and
+  removes temporary test-only mutation-lock sidecars deterministically.
+- Keycloak Admin API requests refresh an expired bearer token once, including
+  account creation and action-email enrollment.
+
+### Fixed
+
+- Prevented registration races from surfacing raw Keycloak duplicate-user
+  errors by mapping exact HTTP 409 responses to a stable product conflict.
+- Prevented unusable registration orphans by deleting accounts when Keycloak
+  rejects the verification/passkey action email.
+- Prevented external network calls from executing while the federation desired-
+  state storage lock is held.
+- Prevented unknown federation configuration keys, credentials, and private
+  values from being echoed through list, get, or update responses.
+- Rejected Unicode-confusable federation aliases outside the explicit ASCII
+  slug alphabet.
+- Raised non-success health responses correctly in the restricted stdlib HTTP
+  opener.
+- Replaced a potentially expensive registration email regular expression with
+  deterministic bounded parsing.
+- Made standalone audit history survive container replacement.

deploy/keycloak/README.md

@@ -1,43 +1,86 @@
 # Keycloak config-as-code
 
-cwl-idp runs on **Keycloak** (Apache-2.0). The realm is declared as-code and
-imported at container start; secrets are patched afterwards from the KV store.
+Keyverse runs on **Keycloak** (Apache-2.0). The portable `cwl` realm shape is
+imported at container start; deployment-specific secrets and external identity
+providers are converged afterwards from the KV/DB source of truth.
 
-| File | What |
+| File | Responsibility |
 | --- | --- |
-| `realm-cwl.json` | The `cwl` realm: passkey-first passwordless browser flow, OIDC/OAuth2.1 RP client template, employer ADFS SAML IdP (inbound), LDAP/AD federation, and the account-unification service-account client. Imported via `start --import-realm`. |
-| `kcadm-bootstrap.sh` | Post-import patch: injects secrets/URLs (ADFS metadata, LDAP bind credential, service-account client secret) from KV using `kcadm.sh`, and grants the service account `realm-management` view-users/manage-users. |
+| `realm-cwl.json` | Portable passwordless realm, shared client scopes, RP template, concrete `naruon-web` PKCE client, and account-unification service client |
+| `kcadm-bootstrap.sh` | Idempotently inject the service-client secret, grant least-privilege realm-management roles, and reconcile the role mapper |
+| `../templates/` | Reference payloads for runtime federation and additional relying-party registrations |
 
-## Passwordless-first (passkeys)
+## Passwordless browser and enrollment flows
 
-`realm-cwl.json` defines an authentication flow **`browser-passwordless`** with
-`auth-username-form` → `webauthn-authenticator-passwordless` and **no password
-authenticator**, and binds it as the realm `browserFlow`. Combined with
-`resetPasswordAllowed:false`, `registrationAllowed:false`, and a default
-`webauthn-register-passwordless` required action, ecosystem-local accounts
-authenticate with a **passkey (FIDO2/WebAuthn)**, never a password. See
-[`../../docs/passwordless-policy.md`](../../docs/passwordless-policy.md).
+The bound `browser-passwordless` flow accepts an existing session, a federated
+identity, or username followed by `webauthn-authenticator-passwordless`. It has
+**no password authenticator**.
 
-## What is committed vs. patched from KV
+First-party products create password-free accounts through
+`POST /registration/accounts`. The account-unification service then invokes
+Keycloak's `execute-actions-email` Admin REST operation with `VERIFY_EMAIL` and
+`webauthn-register-passwordless`. The resulting bounded link verifies control of
+the address and enrolls the first passkey before normal login. A failed email
+request rolls the new account back.
 
-Committed (non-secret shape): realm, flows, client template, IdP + LDAP
-*structure*, mappers. Patched from KV at bootstrap (never committed): ADFS
-metadata URL, LDAP connection URL / bind DN / bind credential, and every client
-secret. Placeholders read `__set_from_kv__`.
+A deployment that enables registration must configure Keycloak SMTP and set the
+following account-unification KV entries:
 
-## Apply
+- `registration_api_token`
+- `registration_client_id`
+- `registration_redirect_uri`
+- `registration_action_lifespan_seconds`
+
+Without the registration token the endpoint is unavailable rather than open.
+See [`../../docs/passwordless-policy.md`](../../docs/passwordless-policy.md).
+
+## Portable realm versus deployment data
+
+The committed realm contains no employer ADFS, LDAP/AD source, or other external
+federation. Those objects are customer/deployment data and are managed through
+`/federation/identity-providers`. Desired state is stored in the KV/DB backend
+and can be reapplied after a realm rebuild with
+`POST /federation/identity-providers:apply`.
+
+This separation also avoids Keycloak 26 import failures from placeholder SAML
+URLs or invalid placeholder LDAP distinguished names.
+
+## Keycloak 26 import rules
+
+`scripts/validate_realm.py` enforces these fail-closed rules:
+
+- no `$`-prefixed annotation keys;
+- no committed external federation or user-storage provider;
+- no password authenticator in any subflow reachable from `browserFlow`;
+- `webauthn-register-passwordless` remains enabled;
+- `basic`, `profile`, and `email` scopes exist, with `basic` providing `sub`;
+- public `naruon-web` requires PKCE S256 and an access-token lifespan no greater
+  than 900 seconds;
+- committed client secrets are placeholders only.
+
+## RP clients
+
+`ecosystem-rp-template` is a confidential PKCE S256 blueprint. It uses the
+reserved `rp.example.invalid` host so no product-specific deployment value is
+silently inherited. Clones must replace redirect/origin values, client ID,
+secret, and audience mapper together.
+
+`naruon-web` is the first concrete public PKCE client. It carries the audience
+and `role`/`org`/`workspace` claims required by the current Naruon session
+contract. Its access tokens last 300 seconds; the longer SSO session is serviced
+through normal token refresh/reissue rather than a twelve-hour bearer token.
+
+## Bootstrap
 
 ```bash
-# 1. Keycloak imports realm-cwl.json automatically on first start
-#    (docker-compose mounts it at /opt/keycloak/data/import).
+# Keycloak imports the realm at first start.
 docker compose up -d
 
-# 2. Once Keycloak is READY, patch secrets from KV:
+# Once Keycloak is ready, converge the service client and its scoped roles.
 KC_SERVER=http://localhost:8080 deploy/keycloak/kcadm-bootstrap.sh
 ```
 
-## Federation & client registration templates
-
-Additional Admin-API request bodies for registering more RPs / IdPs live in
-[`../templates/`](../templates/) (Keycloak client / SAML IdP / LDAP component
-representations).
+The bootstrap obtains credentials from the platform `kv` helper, keeps kcadm
+session material inside a private temporary directory, never places reusable
+secrets in process arguments, validates every resolved identifier, and
+reconciles the protocol mapper without creating duplicates.