docs: reflect changes from lamassuiot#749 (refactor(authz): unify x-current-user and x-principal-id into a single header)

[gh-lamassu-docsagent]

Documents the user-facing changes from lamassuiot/lamassuiot.

Source: lamassuiot/lamassuiot#749

Summary

I'll load both skills first.
Both skills loaded. Now let me read the supplied context: PR metadata, changed-file list, and the conventions file.
The skill base directory is outside my allowed area. Let me check for a conventions file within the workspace and look at the overall structure.
No CONVENTIONS.md accessible (the skill dir is read-protected; I'll follow the workflow guidance in the skill text itself). Now let me read the diff — it's small (2 non-test files).
A tiny refactor diff: x-current-user → X-Principal-ID in the ext-authz controller and the monolithic gateway's header propagation. The feature behind it is the external authorization (ext-authz) flow. Let me create my notes file and explore both the source behavior and existing docs coverage.
Key find: access-control.mdx line 60 documents x-current-user — the exact header this PR removes. Let me search for all header references and the ext-authz docs.
Only one stale reference in docs. Now let me understand the full ext-authz behavior from source. Reading the controller and the gateway assembler:
Now the monolithic gateway's header propagation and related header handling:
Now let me see how services consume X-Principal-ID (admin-mode sentinel, authz middleware):
I now have the full picture. Let me record facts and check the docs structure — the access-control page and any ext-authz related config docs:
The docs page is well-structured; only the line-60 statement is now stale. Let me check whether other docs mention the ext-authz gateway flow, config keys, or the monolithic gateway:
Let me check the deployment docs to understand which gateway carries the ext_authz flow in production, and read the troubleshooting page section:
Let me check if the source contains any Envoy ext_authz configuration that shows how the header propagates in the Kubernetes deployment, and check whether docs mention the monolithic gateway:
The docs describe the Envoy flow. Let me check whether any docs page covers the gateway's header handling (stripping) and look at the docs repo structure for the pki section:
Let me verify whether the source contains any Envoy config (for the helm path) showing how X-Principal-ID propagates, and check the wfx HTTP schema action names mentioned in the docs:
All context gathered. The PR's user-facing impact is exactly one stale docs statement: the identity header returned by the ext-authz decision. Everything else in the access-control page remains accurate. Let me record the decision and apply the fix:
Now the embedded review pass. Let me verify the edited paragraph in context, confirm no remaining x-current-user references anywhere in docs, and re-check the surrounding section for coherence:
The edit reads coherently after the numbered decision flow, and no stale header references remain. Now the build gate:
No shell tool is available in this session, so I can't invoke ./context/check-build directly. Let me inspect what the check script validates so I can verify the same criteria manually:
No shell tool is available to me, so I'll compensate with a rigorous manual verification of everything check-build covers (frontmatter, meta.json slugs, MDX parsing, links) and flag the build step explicitly. First, final coherence checks across the docs:
All structural checks pass. Let me do one last sweep for any Job Manager / integration page that might describe the identity header, then finalize:
Coverage assessment complete. Let me finalize my working notes with the done/left state:

Feature assessment (source PR #749)

The diff is a two-line header unification, but the feature behind it is the external authorization flow: the authz service exposes the Envoy-compatible /v1/ext_authz/check endpoint; when it allows a request it returns the selected principal (the principal whose policy granted the HTTP route, else the first matched principal) in a response header, which the Gateway propagates downstream as the identity context. Before this PR the ext-authz service set x-current-user, which the monolithic gateway immediately translated into x-principal-id; nothing consumed x-current-user on its own. The PR standardizes on X-Principal-ID in both the ext-authz controller and propagateAuthzHeaders — the header already used as the internal trust sentinel (admin-mode bypass in the authz gin-middleware, gateway header stripping, internal service-to-service clients).

Doc-worthiness: yes — a small diff that reveals a stale docs statement. A reader following access-control.mdx would be told the wrong header name.

What I changed

• docs/content/docs/platform/pki/access-control.mdx (1 sentence, line 60): the sentence describing the allow path now reads authz devuelve el principal seleccionado en la cabecera de respuesta X-Principal-ID (previously x-current-user), keeping the existing hedged "El Gateway puede propagar esa cabecera al servicio…". Verified against source: only this page referenced the removed header; the rest of the page (ext-authz flow steps, failOpen, multi-principal semantics, bootstrap, troubleshooting) remains accurate, so no restructuring.

Embedded review findings (software-documentation-reviewer)

• Type: mixed (concept/service description for the authorization model + one procedural Steps section). The changed section is conceptual — primary purpose intact.
• Outline: no change needed; the fix slots into the existing numbered decision flow (step 8 → identity-context sentence).
• Coherence: "el principal seleccionado" stays consistent with the page's multi-principal semantics and with the engine's MatchedPrincipalID behavior; header spelling matches the PR and code (header names are case-insensitive on the wire).
• Deliberately omitted: the gateway's stripping of client-injected X-Principal-Id is verified only for the monolithic gateway, while this section describes the Envoy flow — documenting it would overstate; not part of this PR's user-facing change.

Build readiness

⚠️ I could not run ./context/check-build: this session exposes no shell/execute tool (only file tools). Instead I manually verified everything the script's failure classes cover: frontmatter intact (string title/description), meta.json files untouched and valid (the access-control slug still resolves), the edit is prose-only with inline backticks — no <, {, JSX, imports, or new links — and no files added/moved/deleted. The application must run the build before publishing; the risk from this edit is minimal.

Summary for the docs PR body

Update the access-control page for the authz header unification (lamassuiot/lamassuiot#749). The ext-authz decision now returns the selected principal in the X-Principal-ID response header; the previous x-current-user header no longer exists. The docs referenced that header in a single sentence on the Control de acceso page; that sentence now names X-Principal-ID and describes the Gateway propagation as before. No other docs content mentioned the removed header, so no further changes were needed.

[gh-lamassu-docsagent]

📖 Preview status: preview-ready

https://www.lamassu.io/docs/pr-preview/pr-27/

Preview workflow run

The workflow succeeded and the preview URL is reachable.

Affected pages (1) — turn on Mostrar cambios in the preview to highlight what changed:

• https://www.lamassu.io/docs/pr-preview/pr-27/platform/pki/access-control/

[haritzsaiz]

fix it