[kriszyp]

⊙ Problem

harper#3755 changes locally trusted requests to a built-in local super user. The reference omits its attribution, reserved-name restriction, token behavior, and session boundary.

🤔 Should this describe 5.4 before its stable release?

Yes, with version annotations and a draft PR. The feature is in the verified v5.4.0-alpha.2 tag and absent from v5.3.5. The badge identifies the minor version; it does not claim stable availability.

💡 Solution

Document the transport identity and its effects at the existing configuration and operation references. Correct the installation-admin claim and link the CLI and JWT pages to the details.

🤔 Keep the version badge on the identity subsection?

Yes. Loopback and MQTT local trust predate 5.4; the fixed identity is the change being dated. The badge sits beside that specific behavior.

⚖️ Alternatives

• A release-note-only entry would leave operation readers without the new 400 and 409 conditions.
• A new identity page would duplicate existing authentication configuration; use cross-links instead.

🔧 Changes

Product and architecture tour

Connection-bound identity

Authentication configuration explains the local identity, MQTT and socket trust, attribution, and session behavior. The CLI reference and application guide identify the same user.

The option summary points to the identity rule. The MQTT overview and MQTT configuration describe the raw-TCP loopback exception.

The abbreviated user_info entry links to the same identity rule.

Stored-user credentials

The user operations reference covers the reserved name, existing users, replacement guidance, and user_info. The token operation specifies user selection, refresh-token replacement, and errors; JWT authentication qualifies credential-free minting and links to those rules.

Pending content migration

documentation#788 removes the reference pages this PR edits. If that migration lands first, carry these edits into its owning content repository before merging this companion. documentation#792 tracks that coordination.

Upgrade discovery

The 5.4 release note links the identity, user, and token rules for upgrade readers.

✅ Verification

• Compared the merged implementation, current core main, and fetched release tags; tag objects match origin.
• Formatting, lint, TypeScript, examples, workflow tests, and the production build passed. The build validates MDX and links.
• No new executable examples or runtime changes.

PR QA: skipped @ 34057ce - documentation-only companion.

Docs: this is the documentation companion to HarperFast/harper#3755.

_{🤖 Generated by OpenAI Codex; posted via @kriszyp.}

Release target: v5.4 - behavior present in v5.4.0-alpha.2.

Related PRs: #788 overlaps

Complexity: easy

Late Grok findings

4 surviving (highest minor) — Grok reviewed 3430af5

• minor — reference/mqtt/overview.md:121 — MQTT guidance omits credential-free loopback trust
• nit — reference/configuration/options.md:142 — Option summary omits the new local attribution
• nit — reference/operations-api/operations.md:555 — Abbreviated user_info entry omits local response identity
• nit — reference/security/configuration.md:22 — Option heading lacks a direct identity-change annotation

Not standing: 1 merged. Grok ran 2m (2m from launch to report); the fold adjudication (cursor-grok@3430af5780a5-bfd4b4b1, codex) took 3m.

Origin — the dispatch brief this PR was written from

Document that local-trust requests act as the built-in local user

Document the behavior change in HarperFast/harper#3755 (HarperFast/harper#3755): requests trusted because they are local now act as a fixed user named local.

What changed (from the PR; verify against the merged code before writing):

• Who a local-trust request is. A request trusted by its transport — authentication.authorizeLocal from 127.x / ::1, any request over the operations API domain socket (which is how the harper CLI talks to a local instance), or a raw-TCP MQTT connection from a loopback address under authorizeLocal — now runs as local, a built-in super user that is not stored in system.hdb_user. Previously it ran as the first stored user whose role was named super_user. Consequences to document: user_info over the socket returns username: "local"; audit-log entries, job owners and similar attribution for such requests read local; the socket and CLI keep working when no users exist, and when the admin role has a name other than super_user.
• Reserved username. add_user refuses the username local (400: 'local' is a reserved username: it identifies requests trusted by their transport (authorizeLocal, the operations domain socket)). A user named local created before this change keeps working as an ordinary stored user and can be altered or dropped; recommend renaming it (drop and re-add under another name).
• Token minting from a local request. create_authentication_tokens with no username/password from a local-trust request mints the operation and refresh tokens for the first active stored user whose role has the super_user permission (users in username order), with the same claims as before; that user's stored refresh token is replaced, as before. If no such user exists it fails with 409 no user to mint a token for; create a user first. A username without a password still requires the password. Tokens are never issued for local itself.
• Sessions. Local trust is never written into a session: a session cookie created during a local-trust request does not authenticate anyone when used from elsewhere. Logging in with real credentials over a local connection still creates a normal session for that user.

Where it likely belongs: the security / authentication reference (the authorizeLocal setting and operations-API domain socket), the users-and-roles reference (add_user), and the create_authentication_tokens operation reference. Keep it short; cross-link the authorizeLocal setting.

_{Dispatch: task docs-harper-3755 · queued by task:harper-local-admin-principal · ran by codex/gpt-6.1-sol/high · worker kzyp-xps-1}

_{Ready-For-Promotion: 34057ce urgency=normal late=folded}

_{Review-Coverage: authored=codex; ran=gemini,cursor-composer,cursor-grok; late=cursor-grok:adjudicated; adjudicated=domain; declined=claude,muse; rounds=2; full=1 @ 34057ce}

_{Review-Attention: skim ~2m (raised: degraded review) @ 34057ce}

[gemini-code-assist]

Code Review

This pull request updates the documentation across multiple files to reflect changes introduced in v5.4.0 regarding local request authorization. Specifically, it documents that requests trusted by authorizeLocal or the operations API domain socket now run as a built-in super user named local instead of a stored user. It also covers the reservation of the local username, changes to credential-free token minting, and updates to MQTT configuration and release notes. I have no feedback to provide as there are no review comments to assess.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-793

This preview will update automatically when you push new commits.