capauth 0.3.13__tar.gz → 0.3.14__tar.gz

capauth-0.3.14/AGENTS.md

@@ -0,0 +1,99 @@
+# AGENTS.md (capauth)
+
+CapAuth: PGP-based sovereign identity and authentication for the SK stack (Python library, `capauth`
+CLI and FastAPI verification service). Overview: [README.md](./README.md). Operations:
+[SOP.md](./SOP.md). Architecture: [ARCHITECTURE.md](./ARCHITECTURE.md). This file follows
+[AGENT_INSTRUCTIONS_STANDARD](https://github.com/smilinTux/sk-standards/blob/main/standards/AGENT_INSTRUCTIONS_STANDARD.md).
+There is no `CLAUDE.md` or `.cursorrules`: every agent reads this file.
+
+## Source of truth and invariants
+
+- **CapAuth owns the one canonical agent identity resolver**, `resolve_agent_identity` in
+  `src/capauth/agent_identity.py` (re-exported from `capauth`). skchat, skcomms, skmemory and
+  skcapstone delegate to it; never reimplement identity logic elsewhere. It returns a dual URI:
+  `capauth_uri` (`capauth:<agent>@<domain>`, the wire identity, always derivable) and `fqid`
+  (`<agent>@<operator>.<realm>`, read from `~/.skcapstone/cluster.json`).
+- **Operator vs agents:** the shared `~/.skcapstone/identity/identity.json` holds the operator
+  identity (`role: operator`); each agent's wire identity resolves per agent. No identity carries an
+  `@capauth.local` placeholder (`skcapstone doctor` `identity:*` checks).
+- **DID documents, three tiers** (`src/capauth/did.py`): `did:key` (self-contained), mesh-private
+  `did:web`, and public `did:web` (minimal: key, name, org). `from_profile()` reads only
+  `public_key_armor`; a private key is never touched; no tailnet IPs and no `memory`, `journal` or
+  detailed `soul` fields appear in any document; the public tier respects
+  `publish_to_skworld: false` in `~/.capauth/config.yaml`.
+- **Crypto goes through a backend**, never hand-rolled primitives: `src/capauth/crypto/`
+  (`pgpy_backend.py`, `gnupg_backend.py`, `sequoia_backend.py`). Only `sequoia_backend.py` (the `sq`
+  CLI) can sign post-quantum; GnuPG is signing-disqualified for PQC. Hybrid combiners are HKDF over
+  both shared secrets, never XOR and never pure PQ.
+- **The live root identity is still classical.** PQC root migration is additive-first and
+  reversible, gated on a root-rotation ceremony (epic `PQC-MIGRATION`). Do not claim a PQC root.
+  Per-surface status: [docs/CRYPTO_SPEC.md](./docs/CRYPTO_SPEC.md).
+
+## Commands
+
+CI: `.github/workflows/ci.yml` (test on 3.10 to 3.12, lint, build), `pytest.yml`, `secret-scan.yml`,
+`docs-check.yml` (sk-standards gate, tiers 1 to 3).
+
+```bash
+pip install -e ".[dev,service]"
+python -m pytest tests/ -v --tb=short --cov=capauth             # CI test
+pip install "ruff==0.15.4"
+ruff format --check src/ tests/                                  # CI lint, step 1
+ruff check src/                                                  # CI lint, step 2
+python -m build && twine check dist/*                            # CI build
+scripts/gitleaks-scope.sh full                                   # CI secret scan
+```
+
+On 3.11+ CI also installs `skcapstone` and `skcoord` from git with `--no-deps` so
+`tests/test_integration.py` runs instead of skipping; skcapstone is an optional backbone, never a
+dependency (skcapstone depends on capauth, not the other way round). Ruff config is in
+`pyproject.toml` (line length 99, rules `E,F,I,N,W`, `E501` ignored).
+
+## Start here
+
+1. `src/capauth/cli.py`: every `capauth` command.
+2. `src/capauth/agent_identity.py`: the unified identity resolver.
+3. `src/capauth/identity.py` and `src/capauth/did.py`: challenge-response and DID generation.
+4. `src/capauth/crypto/`: the crypto backends.
+5. `src/capauth/service/`: the FastAPI service (`app.py`, `server.py`, `keystore.py`).
+
+## Rules
+
+- **Writing style:** no em dashes (U+2014) and no en dashes (U+2013) anywhere: code, comments,
+  docs, commits, PR bodies. Use commas, parentheses, colons or a new sentence. Hyphens are fine.
+- **Branch and commit:** never commit to `main`. Branch, commit as soon as a fast check passes and
+  before the full suite, then open a PR. Add an `## [Unreleased]` entry to
+  [CHANGELOG.md](./CHANGELOG.md) for any user-visible change.
+- **Attribution:** a `Co-Authored-By` trailer names the agent that actually did the work, or is
+  left out. Never one you cannot evidence.
+- **Code style:** Python 3.11+ for new code (the package still supports 3.10), type hints, pydantic
+  models, Google-style docstrings, at most 500 lines per file. Tests in `tests/` cover happy path,
+  edge case and failure.
+- **Coordination:** run `skcapstone coord briefing` at the start of a session; claim work with
+  `skcapstone coord claim <id> --agent <you>`. SK packages install into `~/.skenv/`.
+- **Generated files:** none checked in; build artefacts come from `python -m build`.
+
+## Privacy
+
+This repo is public. Never put host names, LAN or tailnet IPs, estate names, personal names or data,
+real key fingerprints, private keys or credentials in code, docs, tests, fixtures or commits.
+Enforced by `secret-scan.yml` (`scripts/gitleaks-scope.sh`) and, for
+DID output, by the invariants in `did.py`; the rest is on review.
+
+## Hazards
+
+- **Environment-gated tests:** `pytest.yml` ignores `tests/test_integration.py` and deselects a few
+  Sequoia and QR-login tests that need tools CI lacks. A green `pytest.yml` is not the full suite;
+  `ci.yml` is.
+- **No `capauth did` CLI group:** the identity card is a library and MCP surface (see SOP section 7).
+- **Stray tracked files:** `ruff-0.15.4-*.whl` and `urllib.error` at the repo root are accidental
+  commits, not inputs; do not depend on them or add more like them.
+
+## See also
+
+- [skcapstone](https://github.com/smilinTux/skcapstone): agent framework, coordination board,
+  `skcapstone doctor`.
+- [skcomms](https://github.com/smilinTux/skcomms) and [skchat](https://github.com/smilinTux/skchat):
+  consumers of the identity resolver.
+- [sk-standards](https://github.com/smilinTux/sk-standards): `CRYPTOGRAPHY_STANDARD`,
+  `SK_REPO_DOC_STANDARD`, `AGENT_INSTRUCTIONS_STANDARD`.

{capauth-0.3.13 → capauth-0.3.14}/CHANGELOG.md

@@ -6,6 +6,16 @@ All notable changes to `capauth` are documented here. The format is based on
 
 ## [Unreleased]
 
+- Agent instructions live in one file, `AGENTS.md`, reshaped to the sk-standards
+  AGENT_INSTRUCTIONS_STANDARD. `CLAUDE.md` and `.cursorrules` are removed (Claude Code reads
+  `AGENTS.md` natively and skips it when a `CLAUDE.md` sits next to it).
+
+- OIDC login asks for the vault passphrase in a masked in-page dialog instead of
+  a browser `prompt()`, which showed the passphrase as it was typed.
+
+- Service discovery no longer invents a nonexistent CapAuth PID file. Without
+  an explicit daemon-owned PID path, health remains unknown.
+
 - Release tags (`v*`) now also publish the service image
   `ghcr.io/smilintux/capauth:<version>` (`.github/workflows/image.yml`): the
   tag must be on main, a published version is never overwritten, the image is
@@ -573,6 +583,7 @@ All notable changes to `capauth` are documented here. The format is based on
 
 ### Security
 
+- Raised `python-multipart` to `>=0.0.31`, `PyJWT` to `>=2.15.0` and `zeroconf` to `>=0.149.16` to clear the 2026-11-13 dependency sweep findings.
 - **Revoked / expired signing-key rejection**: the `pgpy` and `gnupg` verify
   paths now reject a signing key that carries a revocation signature or is expired
   **before** the signature check (`KeyRevokedError` / `KeyExpiredError`), closing

{capauth-0.3.13 → capauth-0.3.14}/Dockerfile.authentik-capauth

@@ -4,16 +4,26 @@
 #
 #  Build:
 #    docker build -f Dockerfile.authentik-capauth \
-#      -t ghcr.io/smilintux/authentik-capauth:2026.5.3 \
-#      -t ghcr.io/smilintux/authentik-capauth:latest .
+#      -t skgit.skstack01.douno.it/skadmin/authentik-capauth:2025.12.6 \
+#      -t skgit.skstack01.douno.it/skadmin/authentik-capauth:latest .
 #
 #  Push:
-#    docker push ghcr.io/smilintux/authentik-capauth:2026.5.3
-#    docker push ghcr.io/smilintux/authentik-capauth:latest
+#    docker push skgit.skstack01.douno.it/skadmin/authentik-capauth:2025.12.6
+#    docker push skgit.skstack01.douno.it/skadmin/authentik-capauth:latest
 #
 #  AK_VERSION tracks the latest STABLE Authentik release (override with --build-arg).
+#
+#  2026-10-23 (Chef decision, tactical patch): pinned to 2025.12.6, the latest
+#  2025.12.x patch, same major line as nor prod's running 2025.12.3. This is the
+#  SAME-LINE security patch (fixes GHSA-xp7f-xjjx-gwm8 Critical SourceStage bypass
+#  and GHSA-c3m2-jqmq-pvp3 SAML XML signature wrapping), not the full 2026.8.5
+#  migration. The 2025.12.x line does not receive the later privilege-escalation
+#  (GHSA-h6c5-mpvq-j4jc) or SAML-DoS (GHSA-cxwx-9x59-28qm) backports -- those land
+#  only with the full upgrade (see docs/AUTHENTIK_STRATEGY_DECISION.md, option b,
+#  decision 2026-10-23: retire this fork for CAPAUTH_ENABLED on stock Authentik as
+#  part of that upgrade).
 # ──────────────────────────────────────────────────────────────────────
-ARG AK_VERSION=2026.5.3
+ARG AK_VERSION=2025.12.6
 
 # ── Stage 1: Rebuild Authentik frontend with ak-stage-capauth ────────
 FROM node:24-bookworm AS web-builder
@@ -60,6 +70,13 @@ USER root
 # instead of hardcoding it — otherwise capauth lands on the wrong path and Django can't import
 # it (ModuleNotFoundError: capauth, live-proven on .13 against 2026.5.3).
 COPY . /app/capauth
+# capauth's pyproject.toml uses setuptools_scm (dynamic version from git tags),
+# but .dockerignore excludes .git from the build context, so `pip install
+# /app/capauth` cannot infer a version and fails with "setuptools-scm was
+# unable to detect version" (hit rebuilding this image 2026-10-23, unrelated
+# to the AK_VERSION bump -- would fail the same way at any Authentik version
+# until this is set). Pin it explicitly to the latest released tag.
+ENV SETUPTOOLS_SCM_PRETEND_VERSION_FOR_CAPAUTH=0.3.13
 RUN VENV_SP="$(ls -d /ak-root/.venv/lib/python3.*/site-packages | head -1)" && \
     echo "Installing capauth into $VENV_SP" && \
     pip install --no-cache-dir --no-deps --target "$VENV_SP" /app/capauth && \

{capauth-0.3.13/src/capauth.egg-info → capauth-0.3.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: capauth
-Version: 0.3.13
+Version: 0.3.14
 Summary: Capability-based Authentication — decentralized, PGP-based identity and authorization
 Author-email: smilinTux <admin@smilintux.org>
 License: GPL-3.0-or-later
@@ -37,8 +37,8 @@ Requires-Dist: python-gnupg>=0.5; extra == "gnupg"
 Provides-Extra: service
 Requires-Dist: fastapi>=0.110; extra == "service"
 Requires-Dist: uvicorn[standard]>=0.27; extra == "service"
-Requires-Dist: python-multipart>=0.0.6; extra == "service"
-Requires-Dist: PyJWT>=2.8; extra == "service"
+Requires-Dist: python-multipart>=0.0.31; extra == "service"
+Requires-Dist: PyJWT>=2.15.0; extra == "service"
 Requires-Dist: python-gnupg>=0.5; extra == "service"
 Requires-Dist: httpx>=0.25; extra == "service"
 Requires-Dist: segno>=1.6; extra == "service"
@@ -53,7 +53,7 @@ Requires-Dist: fastapi>=0.110; extra == "dev"
 Requires-Dist: python-gnupg>=0.5; extra == "dev"
 Requires-Dist: black>=24.0; extra == "dev"
 Requires-Dist: ruff>=0.3; extra == "dev"
-Requires-Dist: zeroconf>=0.38; extra == "dev"
+Requires-Dist: zeroconf>=0.149.16; extra == "dev"
 Requires-Dist: webauthn>=2.0; extra == "dev"
 Requires-Dist: soft-webauthn>=0.1; extra == "dev"
 Requires-Dist: pywebpush>=1.14; extra == "dev"

{capauth-0.3.13 → capauth-0.3.14}/docs/AUTHENTIK_STRATEGY_DECISION.md

@@ -1,18 +1,31 @@
 # Decision Document: Long-Term Strategy for the CapAuth ↔ Authentik Integration
 
-**Status:** Proposed (decision pending Chef)
-**Date:** 2026-06-22
-**Author:** Opus (research + recommendation)
+**Status:** DECIDED. Chef chose CapAuth as an OAuth Source on STOCK Authentik,
+retiring the custom fork. By this document's own lettering that is **Option C2 /
+Track 2** (section 4 Option C, sub-flavor C2; section 5 Track 2). It is NOT
+section 4 "Option B", which means keeping the custom image fork.
+Chef's original words, relayed through the coordinator on 2026-10-23 as part of
+the full Authentik 2026.8.5 upgrade: "patch now, and b for capauth." (Wording as
+recorded in the original version of this PR; the repo holds no other record of it.)
+Clarification 2026-11-07: Chef confirmed that "b for capauth" meant CapAuth as an
+OAuth Source on stock Authentik (this document's C2 / Track 2), not keeping the
+fork. It does not refer to this document's section 4 Option B.
+Scope: this applies to the full 2026.8.5 migration, not the 2026-10-23 tactical
+same-line security patch (nor to 2025.12.6, NAM to 2026.2.7), which keeps both
+images on their current major line and does not touch the fork or the Source
+integration. See "2026-10-23 cutover plan" at the end of this document.
+**Date:** 2026-06-22 (proposed) / 2026-10-23 (decided)
+**Author:** Opus (research + recommendation); decision recorded by Lumina per Chef/coordinator, corrected 2026-11-07 after Chef's clarification
 **Scope:** How to maintain the CapAuth PGP passwordless login *inside* Authentik
-long-term — upstream PR, fork/custom image, redistributable package, or drop
+long-term - upstream PR, fork/custom image, redistributable package, or drop
 Authentik in favor of native per-app plugins.
 
 > TL;DR recommendation: **Stop investing in the forked custom image as the
 > primary path. Adopt a two-track strategy: (1) make native per-app CapAuth
 > plugins the default sovereign login (Nextcloud is already done and works in a
 > real browser); (2) keep Authentik integration alive in a *backend-only,
-> non-web-patching* form — a custom Django app layered on the stock image with
-> NO web-bundle rebuild — and use Authentik's *existing* WebAuthn/passkey or an
+> non-web-patching* form - a custom Django app layered on the stock image with
+> NO web-bundle rebuild - and use Authentik's *existing* WebAuthn/passkey or an
 > OIDC-source bridge for the browser UI rather than shipping our own Lit
 > component.** Only pursue an upstream PR if we first reframe CapAuth as a
 > *Source* (external IdP) rather than a built-in *Stage*. See §5.
@@ -42,7 +55,7 @@ current), which:
 3. Registers the Django app by dropping `/data/user_settings.py` that puts
    `capauth` into `TENANT_APPS`, and bakes a blueprint creating the stage + flow.
 
-### 1.2 Why it is fragile (the cost of forking — observed, not theoretical)
+### 1.2 Why it is fragile (the cost of forking - observed, not theoretical)
 
 Every one of these has already bitten us on `.13`:
 
@@ -51,12 +64,12 @@ Every one of these has already bitten us on `.13`:
   registry are *internal* files. We edit Authentik's own source to register a
   component.
 - **The from-source web build is currently broken and shipped DISABLED.** `npm
-  run build` hits an esbuild code-splitting bug — a shared chunk defines Lit's
+  run build` hits an esbuild code-splitting bug - a shared chunk defines Lit's
   `createRef` but doesn't re-export it across the chunk boundary → runtime SPA
   throws `does not provide an export named 'createRef'` → blank spinner, SPA
   never boots. Identical under `npm ci` *and* `npm install`, so it is the
-  from-source build itself, not version drift. **Net effect: cap9–cap12 ship the
-  stock frontend, so the `ak-stage-capauth` component is ABSENT — the PGP login
+  from-source build itself, not version drift. **Net effect: cap9-cap12 ship the
+  stock frontend, so the `ak-stage-capauth` component is ABSENT - the PGP login
   form does not render in a browser.** PGP login is only proven via the
   flow-executor API. (Our own blueprint comment says: "For in-browser PGP today,
   use the native nextcloud `capauth` plugin instead.")
@@ -95,7 +108,7 @@ maintainer/founder **BeryJu** responded directly (verified via GitHub API):
 This is the governing position. It tells us three things:
 
 1. **Custom Django apps are not a supported public extension path.** They "work"
-   only because Django + `user_settings.py` lets you bolt one on — but the core
+   only because Django + `user_settings.py` lets you bolt one on - but the core
    would need changes for clean dynamic hooking, and those changes don't exist.
    Our `TENANT_APPS` injection is a **hack**, not a sanctioned mechanism.
 2. **The sanctioned answers are: merge upstream, or use the API** (i.e. integrate
@@ -113,29 +126,29 @@ the docs (no plugin/extension API in
 [Contributing](https://docs.goauthentik.io/developer-docs/contributing/) or the
 [developer docs](https://docs.goauthentik.io/developer-docs/)) and by the
 frontend architecture (see the [Web Frontend System](https://deepwiki.com/goauthentik/authentik/2-web-frontend-system)
-overview). To add a stage component you **must** modify and rebuild the bundle —
+overview). To add a stage component you **must** modify and rebuild the bundle -
 exactly what we do, and exactly what breaks.
 
 ### 2.3 What Authentik *does* support as extension points
 
 - **Blueprints** ([docs](https://docs.goauthentik.io/customize/blueprints/)):
   declarative YAML to create/configure stages, flows, providers, brands. This is
-  configuration-as-code, **not** a way to add *new stage types* — it can only
+  configuration-as-code, **not** a way to add *new stage types* - it can only
   instantiate stage classes that already exist in the running image. (We use it
   correctly to wire the flow once the class is baked in.)
 - **The REST API / Terraform**: manage all objects externally. The sanctioned
   "use the API" path.
 - **Sources** ([docs](https://docs.goauthentik.io/users-sources/sources/)):
   Authentik can *consume* external identity from OAuth/OIDC/SAML/LDAP/SCIM
-  sources. **This is the supported way to plug in a foreign IdP** — and it is the
+  sources. **This is the supported way to plug in a foreign IdP** - and it is the
   one extension point that fits CapAuth without touching Authentik's bundle (see
   §4 Option C and §5).
 - **Expression policies / property mappings**: Python snippets evaluated at
-  runtime — useful for claims logic, but cannot render a custom login UI or
+  runtime - useful for claims logic, but cannot render a custom login UI or
   implement a challenge/response stage.
 - **`AUTHENTIK_*` env + `user_settings.py`**: configuration override hook. It
   loads custom settings (and can append to `TENANT_APPS`), but that is settings
-  injection, not a stage-plugin API — and per BeryJu it is not a supported way to
+  injection, not a stage-plugin API - and per BeryJu it is not a supported way to
   ship a custom Django app.
 
 **Conclusion for §2:** Authentik has **rich configuration extensibility (blueprints,
@@ -169,8 +182,8 @@ open-core model, so a CLA may be requested in practice.
   and the maintainers are converging on **passkeys/WebAuthn** (their MFA blog
   argues phishing-resistant FIDO2 is the future:
   [link](https://goauthentik.io/blog/2025-03-05-mfa-in-authentik/)). A
-  PGP-fingerprint primary-login stage — where the fingerprint *is* the user and
-  the user table is a key registry — is a sovereign-identity philosophy that does
+  PGP-fingerprint primary-login stage - where the fingerprint *is* the user and
+  the user table is a key registry - is a sovereign-identity philosophy that does
   not match Authentik's user model (real `User` objects, brands, enterprise RBAC).
 - **The custom-stage appetite is unproven.** The open feature request for
   generic custom stages ([#17726](https://github.com/goauthentik/authentik/issues/17726))
@@ -187,51 +200,51 @@ duplicates the role of their passkey work and carries an unusual identity model.
 Realistically that gets "interesting, but use the API / make it a Source."
 Reframing CapAuth as an **OIDC/OAuth Source** (CapAuth service is the IdP,
 Authentik consumes it) needs **zero** new built-in stage and uses an extension
-point they actively support — that is far more upstream-friendly *and* removes our
+point they actively support - that is far more upstream-friendly *and* removes our
 web-patching problem entirely. (See §5.)
 
 ---
 
 ## 4. Options and tradeoffs
 
-### Option A — Upstream PR to Authentik core (the stage)
+### Option A - Upstream PR to Authentik core (the stage)
 
 | | |
 |---|---|
 | **What** | Submit `CapAuthStage` + web component as a built-in stage PR. |
 | **Maintenance** | Low *if merged* (they carry it). High *until* merged (rebase against a fast-moving codebase) and merge is uncertain. |
 | **Version fragility** | Eliminated if merged (it's in-tree). |
-| **Who can use it** | Everyone, out of the box — best reach. |
+| **Who can use it** | Everyone, out of the box - best reach. |
 | **Time cost** | High + unbounded: shape to their conventions, tests, review cycles, likely a CLA, likely rejection or "make it a Source." |
 | **SKWorld fit** | Good if accepted (sovereign PGP login becomes mainstream IdP capability). Poor expected value given §3 acceptance odds. |
 | **Verdict** | Don't lead with this for the *Stage*. Viable only if reframed as a *Source* (Option C/§5). |
 
-### Option B — Maintain the custom image fork (current state)
+### Option B - Maintain the custom image fork (current state)
 
 | | |
 |---|---|
 | **What** | Keep `Dockerfile.authentik-capauth`, rebuild + re-patch per version. |
-| **Maintenance** | **High and recurring.** Re-patch internal files, fight the esbuild `createRef` bug, re-`npm ci`, re-verify the component renders, re-handle py-minor/imghdr drift, re-test flow internals — every bump. |
+| **Maintenance** | **High and recurring.** Re-patch internal files, fight the esbuild `createRef` bug, re-`npm ci`, re-verify the component renders, re-handle py-minor/imghdr drift, re-test flow internals - every bump. |
 | **Version fragility** | **Worst of all options.** Breaks on web-bundle internals each release; the web build is *currently broken*, so the headline feature (browser PGP form) doesn't ship today. |
 | **Who can use it** | Only us (and anyone who pulls our ghcr image and trusts it). |
 | **Time cost** | Recurring engineer-days per Authentik release, indefinitely. |
 | **SKWorld fit** | Centralized SSO is attractive, but a fork that breaks on every bump and can't render its own UI is a liability, not an asset. |
 | **Verdict** | Not sustainable as the primary path. At most keep a **backend-only** variant (no web rebuild) for API/headless use. |
 
-### Option C — Redistributable Authentik integration (no core fork)
+### Option C - Redistributable Authentik integration (no core fork)
 
 Two sub-flavors, both avoiding the web-bundle patch:
 
-**C1 — Backend-only custom Django app, stock frontend.** Ship the `capauth`
+**C1 - Backend-only custom Django app, stock frontend.** Ship the `capauth`
 Django app as a layer on the *unmodified* official image (the cap9+ reality
 already does this), wire it via blueprint, and **don't** ship a web component.
 The stage works via the flow-executor API / headless / CLI / extension clients,
 not the browser form.
 
-**C2 — CapAuth as an OIDC/OAuth *Source* (recommended sub-flavor).** Run the
+**C2 - CapAuth as an OIDC/OAuth *Source* (recommended sub-flavor).** Run the
 existing standalone CapAuth service (`ghcr.io/smilintux/capauth`) as the IdP;
 register it in Authentik as an **OAuth/OIDC Source**. The browser does PGP login
-*on CapAuth's own page* (which we fully control — no Authentik bundle), then
+*on CapAuth's own page* (which we fully control - no Authentik bundle), then
 Authentik federates the identity in. Authentik then fans out SSO to all
 downstream apps.
 
@@ -244,16 +257,16 @@ downstream apps.
 | **Time cost** | Low ongoing; medium to build a clean redistributable. | Medium one-time to build the OIDC IdP endpoints in the CapAuth service; then near-zero. |
 | **SKWorld fit** | OK as a headless/API capability. | **Excellent:** centralized SSO from one PGP login, sovereign service we own, no fork. |
 
-### Option D — Drop Authentik; native per-app CapAuth plugins
+### Option D - Drop Authentik; native per-app CapAuth plugins
 
 | | |
 |---|---|
 | **What** | Each app gets a native CapAuth plugin using *that app's* supported extension API. **Nextcloud is done and proven.** |
-| **Evidence** | `src/capauth/integrations/nextcloud/` is a complete, idiomatic Nextcloud app: real `IUserBackend` (`lib/User/Backend.php`), `AlternativeLogin/CapAuthLogin.php` ("Sign in with CapAuth" button), challenge/verifier/provisioning/group-sync services, DB migration, nonce-prune background job, registered via `appinfo/info.xml`. It is **passwordless PRIMARY login in a real browser** — the thing the Authentik fork can't currently do. |
+| **Evidence** | `src/capauth/integrations/nextcloud/` is a complete, idiomatic Nextcloud app: real `IUserBackend` (`lib/User/Backend.php`), `AlternativeLogin/CapAuthLogin.php` ("Sign in with CapAuth" button), challenge/verifier/provisioning/group-sync services, DB migration, nonce-prune background job, registered via `appinfo/info.xml`. It is **passwordless PRIMARY login in a real browser** - the thing the Authentik fork can't currently do. |
 | **Maintenance** | Per-app, but each uses *supported* extension points (stable, documented), so far less fragile than patching Authentik's bundle. Cost scales with number of apps. |
 | **Version fragility** | Low per app (app APIs are stable contracts). |
-| **Who can use it** | Anyone running that app — and it's publishable to the app's marketplace (Nextcloud app store), real reach. |
-| **Time cost** | One plugin per target app (Forgejo scaffold exists; others TBD). No central SSO — N integrations for N apps. |
+| **Who can use it** | Anyone running that app - and it's publishable to the app's marketplace (Nextcloud app store), real reach. |
+| **Time cost** | One plugin per target app (Forgejo scaffold exists; others TBD). No central SSO - N integrations for N apps. |
 | **SKWorld fit** | **Excellent for sovereignty** (no central dependency, each app fully owned), **weak for scale** (no single login → many apps; re-implement per ecosystem). |
 
 ---
@@ -262,32 +275,32 @@ downstream apps.
 
 **Adopt a two-track strategy. Retire the web-patching fork as the primary path.**
 
-### Track 1 (now): native per-app plugins are the default sovereign login — Option D
+### Track 1 (now): native per-app plugins are the default sovereign login - Option D
 
 Nextcloud already delivers what the Authentik fork promised: **passwordless PGP
 PRIMARY login that renders in a real browser**, via Nextcloud's *supported*
 extension points. Make this the canonical CapAuth login experience for our
 highest-value apps. It is sovereign, marketplace-publishable, and not fragile.
-Prioritize the next 1–2 apps by actual need (Forgejo scaffold already exists).
+Prioritize the next 1-2 apps by actual need (Forgejo scaffold already exists).
 
-### Track 2 (next): centralized SSO via CapAuth-as-OIDC-Source — Option C2
+### Track 2 (next): centralized SSO via CapAuth-as-OIDC-Source - Option C2
 
 For the "one PGP login → many apps" value that only an IdP gives, **do not** keep
 fighting Authentik's bundle. Instead:
 
 1. Add OIDC/OAuth2 *provider* endpoints to the standalone CapAuth service
    (authorize/token/userinfo/jwks) so it is a real IdP. The PGP challenge UI
-   lives on **CapAuth's own page** — fully ours, zero Authentik web patching.
+   lives on **CapAuth's own page** - fully ours, zero Authentik web patching.
 2. Register CapAuth in **stock** Authentik as an **OAuth/OIDC Source**. Authentik
    then fans SSO out to every downstream app it fronts.
 3. This uses an extension point Authentik *actively supports*, runs on the
    **official unmodified image**, and is decoupled from Authentik internals via
-   the stable OIDC standard — eliminating the version-bump treadmill.
+   the stable OIDC standard - eliminating the version-bump treadmill.
 
 ### What to do with the existing fork: downgrade, don't delete
 
 - **Stop shipping the web-builder stage.** It's already disabled; make that
-  permanent. Do not invest more in the esbuild `createRef` fix — there is no
+  permanent. Do not invest more in the esbuild `createRef` fix - there is no
   supported home for a custom stage component, so even a fixed build re-breaks
   next release.
 - **Keep the backend Django app (Option C1) only as a headless/API capability**
@@ -310,7 +323,7 @@ likely to be accepted. A PGP *Stage* PR is low-EV and should not be our first mo
 - It **keeps both strategic values**: sovereignty + working browser login (Track 1,
   proven) and centralized SSO from one PGP login (Track 2, on stock Authentik).
 - It moves us onto **supported extension points everywhere** (Nextcloud app API;
-  Authentik Sources/OIDC) instead of patching internals — slashing
+  Authentik Sources/OIDC) instead of patching internals - slashing
   version-bump fragility.
 - It is **honest about what ships today**: the fork's headline feature doesn't
   render in a browser; Nextcloud's does.
@@ -319,11 +332,11 @@ likely to be accepted. A PGP *Stage* PR is low-EV and should not be our first mo
 
 ## 6. Concrete next steps
 
-1. **Decision sign-off (Chef):** approve the two-track strategy; mark the
+1. **Decision sign-off (Chef):** done, see Status (C2 / Track 2). Mark the
    web-patching fork as deprecated-for-browser-use.
 2. **Track 1:** publish/polish the Nextcloud CapAuth app (it's complete); pick
    the next target app (Forgejo scaffold → finish, or another high-use app).
-3. **Track 2 (spike):** add OIDC provider endpoints to the standalone CapAuth
+3. **Track 2 (decided; lab proof pending, see the cutover plan):** add OIDC provider endpoints to the standalone CapAuth
    service; stand up stock Authentik with CapAuth registered as an OAuth/OIDC
    **Source**; prove PGP-login→Authentik-session→downstream-app SSO E2E on `.13`.
    This replaces the cap-image deploy.
@@ -337,7 +350,7 @@ likely to be accepted. A PGP *Stage* PR is low-EV and should not be our first mo
 
 ## Sources
 
-- BeryJu (authentik founder) on custom plugins — "merge upstream, or use the API":
+- BeryJu (authentik founder) on custom plugins - "merge upstream, or use the API":
   <https://github.com/goauthentik/authentik/issues/1541> (verified via GitHub API)
 - Custom stages feature request (open, `status/reviewing`, no maintainer commitment):
   <https://github.com/goauthentik/authentik/issues/17726>
@@ -350,13 +363,13 @@ likely to be accepted. A PGP *Stage* PR is low-EV and should not be our first mo
   <https://docs.goauthentik.io/add-secure-apps/flows-stages/stages/>
 - Blueprints (declarative config of existing objects, not new stage types):
   <https://docs.goauthentik.io/customize/blueprints/>
-- Sources (supported way to federate external IdPs — the C2 path):
+- Sources (supported way to federate external IdPs - the C2 path):
   <https://docs.goauthentik.io/users-sources/sources/>
 - WebAuthn / FIDO2 / Passkeys stage (existing passwordless precedent + direction):
   <https://docs.goauthentik.io/add-secure-apps/flows-stages/stages/authenticator_webauthn/>
 - MFA direction blog (phishing-resistant FIDO2/passkeys as the priority):
   <https://goauthentik.io/blog/2025-03-05-mfa-in-authentik/>
-- Release 2026.5 (WebAuthn L3 hints — ongoing passkey investment):
+- Release 2026.5 (WebAuthn L3 hints - ongoing passkey investment):
   <https://docs.goauthentik.io/releases/2026.5/>
 - Flows/stages/policies explainer: <https://goauthentik.io/blog/2024-08-27-flows-stages-and-policies/>
 
@@ -370,3 +383,135 @@ likely to be accepted. A PGP *Stage* PR is low-EV and should not be our first mo
   `src/capauth/integrations/nextcloud/` (`lib/User/Backend.php`,
   `lib/AlternativeLogin/CapAuthLogin.php`)
 - Deploy history / E2E-API-only proof: `HANDOFF-capauth-authentik-2026-06-17.md`
+
+
+---
+
+## 2026-10-23 cutover plan (nor, as part of the 2026.8.5 upgrade)
+
+Chef's decision is Option C2 / Track 2 (CapAuth as an OIDC/OAuth Source on stock
+Authentik). This section records the concrete cutover plan for **nor**, the only
+estate still running the `Dockerfile.authentik-capauth` fork. NAM is unaffected
+(always ran stock Authentik, never had the fork).
+
+### What changes
+
+- nor's `sksso-prod_server`/`_worker` move from the custom image
+  (`skgit.skstack01.douno.it/skadmin/authentik-capauth:*`) to the **stock**
+  `ghcr.io/goauthentik/server:2026.8.5` image. NAM never ran the fork. Its
+  current Authentik version is not recorded in this repo (the scope paragraph at
+  the top says 2026.2.7 after the tactical patch); open question, confirm on NAM.
+- The sksso role's `sksso.CAPAUTH_ENABLED: true` path (documented in
+  `v1/ansible/optional/sksso/README.md`, "CapAuth login (optional)") replaces
+  the baked-in stage: the standalone `capauth` service becomes an Authentik
+  **OAuth Source**, with its own login flow, instead of a flow stage compiled
+  into Authentik's bundle. This is already-shipped, already-tested code (commit
+  `ecc8e50`, "per-client require_nonce so stock Authentik's OAuth source can
+  log in"), not new engineering.
+- The fork-only CapAuth objects are the ones the fork's blueprint
+  (`src/capauth/authentik/blueprints/capauth-pgp-login.yaml`) creates: the
+  `capauth.capauthstage` instance `capauth-pgp`, the authentication flow with
+  slug `capauth-authentication`, and that flow's two stage bindings (CapAuthStage
+  at order 0, `default-authentication-login` at order 10), plus the fork app's
+  tables (`CapAuthStage`, `CapAuthKeyRegistry`). Those are what a later cleanup
+  may retire. Flow `97730dbd-b5fc-4171-8dce-4de5273c1db2` is NOT one of them: it
+  is the general `skstack01-application-authorization` flow that apps such as
+  Forgejo use (see `AUTHENTIK_FORGEJO_DEPLOYMENT.md`), and it must not be
+  retired. `AUTHENTIK_DEPLOYMENT_SKSSO.md` describes adding a CapAuth stage
+  binding to that flow. Open question: whether that binding was actually added
+  on nor; if so, only that binding is fork-only, and it must be unbound without
+  touching the flow itself.
+- Slug clash: the fork's blueprint flow slug `capauth-authentication` is also
+  the default `CAPAUTH_FLOW_SLUG` of `tasks/capauth_provision.yml`. While the
+  fork still runs, the stock OAuth-source flow MUST be provisioned with a
+  distinct slug (for example `capauth-source-authentication`, set through
+  `CAPAUTH_FLOW_SLUG`), or provisioning would overwrite the fork's flow. Open
+  question: confirm the role honours the override in the lab before relying on
+  it; if it does not, a parallel run on the same instance is not possible and
+  step L3 below must be dropped in favour of a separate lab instance.
+- The old fork objects are NOT touched automatically; retiring them is a
+  manual admin-UI cleanup step after the new flow is proven (see "Rollback" in
+  the README's CapAuth section for the exact unbind order, run in reverse as an
+  adopt order).
+- Enrolled users move from the fork's `CapAuthKeyRegistry` (one row per PGP
+  fingerprint, no linked Authentik user) to `sksso.CAPAUTH_USERS`
+  (fingerprint maps to an existing Authentik user). Every current nor CapAuth
+  user must be re-enrolled against an actual Authentik user account before
+  cutover, or their login breaks. This is the one step with real user-facing
+  migration risk and needs its own checklist before the lab run.
+
+### Order of operations (lab first, skstack06, before any nor change)
+
+The order runs from the fork to stock with CapAuth as an OAuth Source. The fork
+is retired FIRST, at nor's current Authentik version, and the stock upgrade hops
+come AFTER on the stock image. Reason: upgrading the fork through the
+intermediate versions would mean rebuilding it against each one for no benefit.
+Lab steps (L) may restore dumps freely. Production steps (P) never restore a
+dump; rollback on nor is the separate conditional section below.
+
+Lab (skstack06):
+
+- L1. Reproduce nor's real pre-cutover shape: nor currently runs the fork image
+  (`Dockerfile.authentik-capauth`) on the 2025.12.6 line, so build
+  `authentik-capauth:2025.12.6` on skstack06 and deploy the sksso role with it.
+  Open question: confirm the exact fork image tag and Authentik version running
+  on nor today.
+- L2. Seed representative data: a handful of users and groups, at least one OIDC
+  provider, the embedded outpost plus a forward-auth proxy provider, and enough
+  CapAuth-fork enrollments (`CapAuthKeyRegistry` rows) to exercise the migration.
+- L3. Parallel-run: enable `sksso.CAPAUTH_ENABLED: true` alongside the
+  still-running fork, with a distinct `CAPAUTH_FLOW_SLUG` (see "Slug clash"
+  above), bring up the `capauth` service and OAuth source, and prove login
+  through the new path end to end (challenge and verify, OAuth source login, SSO
+  fan-out) while the fork path still works.
+- L4. Prepare the user migration: map each fork enrollment (PGP fingerprint) to
+  an existing Authentik user in `sksso.CAPAUTH_USERS`. Open question: the list of
+  current nor CapAuth users and the migration checklist do not exist yet and
+  must be written before L5.
+- L5. Lab cutover, fork to stock at the SAME version: take a dump, swap the fork
+  image for the stock `ghcr.io/goauthentik/server` image at 2025.12.6, keep
+  `CAPAUTH_ENABLED: true`, and re-verify every login path (password, OIDC apps,
+  forward-auth, the CapAuth OAuth source). Then, lab only, rehearse the rollback:
+  restore the dump and confirm the fork image still boots against it. Open
+  question: whether the stock image runs cleanly against a database that carries
+  the fork's extra tables and migrations is untested.
+- L6. Lab upgrade on stock: 2025.12.6 to 2026.2.7 to 2026.5.7 to 2026.8.5, with
+  the L5 login-path checks repeated at each hop.
+
+Production (nor), only after L1 to L6 pass end to end:
+
+- P1. Take and verify a pre-cutover database dump and record the running fork
+  image tag. Open question: the nor change window and change approval record
+  are not captured here.
+- P2. Parallel-run: enable `CAPAUTH_ENABLED: true` with the distinct
+  `CAPAUTH_FLOW_SLUG` alongside the running fork and prove the new login path.
+- P3. Complete the user migration (the L4 checklist) so every CapAuth user maps
+  to an Authentik user.
+- P4. Cutover: swap the fork image for stock at the current version, re-verify
+  every login path.
+- P5. Upgrade on stock through the same hops as L6, verifying login paths at
+  each hop.
+
+### Rollback on nor (conditional, not a plan step)
+
+Only if a production step fails verification. Dump restore is destructive for
+anything written after the dump (new users, sessions, enrollments), so a restore
+needs an explicit decision at the time and is never run as part of P1 to P5. The
+options, in order of preference: (1) revert the image reference to the recorded
+fork tag if the database was not migrated forward; (2) restore the P1 dump only
+once the data written since has been accounted for. Open question: which of
+these is viable after P4 depends on the untested L5 stock-on-fork-database
+question above.
+
+### Fork retirement (after the lab proof and after nor is cut over)
+
+- Freeze `Dockerfile.authentik-capauth` and
+  `scripts/build_authentik_capauth_image.sh`: add a banner pointing at this
+  decision and `CAPAUTH_ENABLED`, do not delete (historical reference and the
+  one documented rollback path if the Source integration needs to be backed
+  out urgently).
+- Archive the `release/authentik-capauth-cap10`, `cap11`, `cap12` branches (do
+  not force-delete; they are the build history for the fork, useful if anyone
+  needs to reconstruct exactly what nor ran).
+- Update `docs/authentik-capauth.md` with a top banner: "superseded by
+  CAPAUTH_ENABLED, see AUTHENTIK_STRATEGY_DECISION.md".

{capauth-0.3.13 → capauth-0.3.14}/pyproject.toml

@@ -45,8 +45,8 @@ gnupg = [
 service = [
     "fastapi>=0.110",
     "uvicorn[standard]>=0.27",
-    "python-multipart>=0.0.6",
-    "PyJWT>=2.8",
+    "python-multipart>=0.0.31",
+    "PyJWT>=2.15.0",
     "python-gnupg>=0.5",
     "httpx>=0.25",
     "segno>=1.6",
@@ -62,7 +62,7 @@ dev = [
     "python-gnupg>=0.5",
     "black>=24.0",
     "ruff>=0.3",
-    "zeroconf>=0.38",
+    "zeroconf>=0.149.16",
     "webauthn>=2.0",
     "soft-webauthn>=0.1",
     "pywebpush>=1.14",