Repository navigation
feat(cluster): create the first admin through the proxy with sealed operations on Harper 5.4.0+ - #2113
feat(cluster): create the first admin through the proxy with sealed operations on Harper 5.4.0+#2113Devin-Holland wants to merge 7 commits into
Conversation
…perations on Harper 5.4.0+ On a Fabric-hosted cluster whose every live member runs 5.4.0 or later and holds the cluster secrets key, Finish Setup no longer needs the provisioning account's password or a browser that can reach the instance. It seals add_user (or alter_user for HDB_ADMIN), a token mint with the typed credentials, and drop_user HDB_ADMIN to the cluster key as encrypted_operation through central manager's Fabric Connect proxy, which relays ciphertext both ways, then sends the ResetPasswordUpdater PATCH as today and connects the browser with the minted tokens directly or not at all. Below 5.4.0, or without a key, the tempPassword flow is unchanged. The sealing helper is Web Crypto over the existing enc:v1 envelope; its tests open what it seals with Harper's own reference client, copied unchanged from v5.4.0. Co-Authored-By: Claude Mythos 5.1 <noreply@anthropic.com>
…seal the rest the review found A connect with minted tokens no longer registers as the shared in-flight connect, and a resolution another claim replaced while it was verifying no longer records its user. Setup rechecks the sign-out generation before connecting, so a sign-out during the seals leaves no token behind. The sealed runner opens a sealed answer whatever HTTP status carried it, refuses a replicated write a peer refused as the direct path does, and keeps a clock offset per node. The sealed calls name an actor for the node's log, the gate is memoized, the reference copies get a README naming their commit, and AGENTS.md says why allowImportingTsExtensions is on. Co-Authored-By: Claude Mythos 5.1 <noreply@anthropic.com>
… answers as unknown outcomes A failing connect that never claimed no longer clears a newer token- backed connection, and setup no longer signs out a connect that replaced its own. A sealed answer that is missing, malformed or another request's reads as an unknown outcome, since the operation may have run. A clock offset the node refuses again is forgotten. A 5.4.0 cluster whose members do not all hold the key yet, with no temporary password, is told the key is on its way rather than blamed on permissions. Co-Authored-By: Claude Mythos 5.1 <noreply@anthropic.com>
…the pending-key message The page records a user only when setup connected one, so a connect that replaced setup's own is not wiped by the success callback. A hosted cluster whose members have not all reported a version is told its details are still arriving rather than blamed on permissions. A sealed read that may have run is a failed read, not an unknown write. Co-Authored-By: Claude Mythos 5.1 <noreply@anthropic.com>
|
Finish Setup in the dark theme (dev server, central manager answered locally); the light screenshot is in the description, and this upload failed at create time. 🤖 Generated by Claude Code (Claude Mythos 5.1); posted via @Devin-Holland. |
Coverage Report
File Coverage
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
…s each operation Every sealed setup call (add_user or alter_user, the credentialed token mint, drop_user HDB_ADMIN, and the adoption list_users) now goes as an encrypted_operation in fields mode: central manager's proxy log records the operation, role and active, while username and password travel as sealed leaves bound to their JSON Pointer, and the operation text is bound to the envelope by its SHA-256 (oph). The Web Crypto sealer gains fields mode, cross-checked against Harper v5.4.0's reference client. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… and memoize the key check An ordinary Fabric Connect resolution whose mint finishes after another connection has claimed the cluster (setup's token-backed connect) no longer overwrites it: the replacement check now covers the unclaimed window too. The page memoizes the pending-key check, and two comments that restated their code are gone. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…s an unknown outcome Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
kriszyp
left a comment
There was a problem hiding this comment.
🤖 Reviewed with Muse Wonder 1.0 · adjudicated by Codex
| if (!minted?.operation_token) { | ||
| throw new Error("Couldn't finish setup: the cluster did not return a token for the new admin."); | ||
| } | ||
| if (desiredUsername !== defaultClusterUsername) { |
There was a problem hiding this comment.
[major] Changing the username after interrupted setup leaves an unexpected active super user
| const { operationToken, refreshToken } = tokens ?? await createInstanceAuthenticationTokens({ | ||
| instanceClient: getInstanceClient({ id, forceFabricConnect: true }), | ||
| }); | ||
| throwIfSignedOut(); |
There was a problem hiding this comment.
major — Token recovery can replay the admin’s request as another user — Scope: in-scope — Convergence-Class: original-change
(src/features/auth/store/authStore.ts:697 is not part of this PR's diff — anchored to the nearest line this PR's diff can hold)
| keyRetried = true; | ||
| continue; | ||
| } | ||
| if (!detail?.encrypted_response) { |
There was a problem hiding this comment.
[minor] Transport failures misreport a sealed read as an unanswered write

⊙ Problem
Finish Setup signs in to the instance directly as
HDB_ADMINwith the bootstrap password central manager stores on the instance record (tempPassword), which is being removed. The browser must reach the instance, and the login's Fabric Connect fallback can send the chosen password through central manager in plaintext.🤔 Is a second setup path on 5.4.0+ warranted, rather than one path for every cluster?
As specified, yes: central manager stops writing
tempPasswordonly for 5.4.0+ hosted clusters, after this ships; older clusters must keep working unchanged. Deleting the gate restores one path.💡 Solution
On a Fabric-hosted cluster whose every live member runs Harper 5.4.0+ and holds the cluster secrets key, setup runs through the existing Fabric Connect proxy as
encrypted_operation(HarperFast/harper#4205).add_user(oralter_userforHDB_ADMIN), a token mint with the typed credentials, anddrop_user HDB_ADMINgo in fields mode: central manager logs the operation, never the username or password.tempPasswordflow runs as before, except one message.Merge order: HarperFast/host-manager#261 merged; this deploys next; HarperFast/central-manager#963 (after HarperFast/central-manager#1069) then stops
tempPasswordfor 5.4.0+ hosted clusters.⚖️ Alternatives
localprincipal.Also weighed
allowImportingTsExtensionsapp-wide — a few lines either way; AGENTS.md now says why it is on.finish_setupoperation — needs another core release; 5.4.0 nodes are the target.encrypted_operation), starting with the token mint (blocked on harper#3288) #1982.tempPassword, which central manager keeps writing below the released 5.4.0.🤔 Mint the session with the typed credentials, rather than credential-free or not at all
Adopted from the planning review over its do-less of finishing signed out: a credential-free mint names the node's first stored super user, which another attempt may have created, while Harper 5.4.0's
createTokenschecks given credentials and names that user. The mint is also the sign-in proof before the drop, and the page keeps its signed-in promise.🔧 Changes
src/lib/crypto/sealedOperation.ts— seals an operation into the existingenc:v1envelope with a fresh response key and nonce, and opens the node's sealed answer (AES-GCM under that key, the nonce as additional data). Fields mode sends the operation as readable text with chosen values as sealed leaves bound to their JSON Pointer, and the text's SHA-256 (oph) in the envelope.src/lib/crypto/envSecret.ts— exports the byte helpers the sealer shares, plus a strict base64 decoder.src/lib/crypto/__tests__/harper-v5.4.0/sealedOperation.ts,secretEnvelope.ts,README.md— Harper's reference client, copied unchanged from the v5.4.0 tag, with the commit it came from;dprint.jsonexcludes the folder,tsconfig.app.jsonallows its.tsimports, andAGENTS.mdsays why.src/integrations/api/instance/sealedOperation.ts— sends a sealed operation through a client: one retry on a clock refusal (the offset is remembered per node, and forgotten if the retry is refused too) and one on a key refusal (the key is refetched); a sealed failing status, whatever HTTP status carried it, becomesSealedOperationError; an answer that is missing, malformed or another request's becomesUnreadableSealedAnswerError; a replicated write a peer refused is refused as on the direct path.src/features/cluster/sealedSetup.ts— the gate, from the cluster record alone: hosted, every live member 5.4.0+ carrying onesecretsKeyFingerprint, so the key fetch never creates a key, which would restart the members;clusterKeyPendingnames a hosted cluster whose members have not all reported a version and one key yet.src/integrations/api/instance/auth/useInstanceResetPasswordMutation.ts— the sealed path, in fields mode withroleandactivereadable, beside thetempPasswordpath, unchanged but for that message; the hook takes the query client for the key; a sign-out during the seals leaves the admin unconnected, and a connect another connect replaced signs nothing out. With notempPasswordand the key still on its way, the old path says so instead of blaming permissions.src/features/auth/store/authStore.ts—establishFabricConnectAuthaccepts minted tokens, connects directly with them or throws, neither joins nor becomes the shared in-flight connect; no resolution records its user once another claim replaced it, and a failing one that never claimed clears nothing a newer one holds.src/react-query/queryClient.ts— a sealed write that ran but could not answer, or whose answer could not be read, reads as an unknown outcome; a sealed read in that state is a failed read.src/integrations/api/api.patch.d.ts—secretsKeyFingerprinton the instance record (central manager returns it; not in the generated schema yet).src/features/cluster/FinishSetup.tsx— passes the gate's result to the mutation, and records a user only when setup connected one, so a connect that replaced setup's own survives the success callback.src/features/cluster/DESIGN.md(and its account of Fabric Connect on 5.4),DESIGN.md— the invariant and the gate.🤔 post-review delta: fields mode and the late-mint fix were read without the graded leg
Gemini and Cursor Composer reviewed
b10de64c6, and Composera8e787677, without Codex or adjudication; their findings were fixed or matched earlier rulings. Four later rounds failed on the reviewer machine (OpenAI unreachable, load near 62, Composer's model id retired).✅ Verification
07fa3cdf0(details below). Setup succeeded, central manager relayed only ciphertext, and a wrong password on the credentialed mint was refused. Fields mode came later and was verified live separately; this head was not re-run.vitest run: 733 files, 8,814 tests pass.tsc -b,oxlintanddprint checkare clean.Live check, 2026-11-16 (ephemeral env 43958766079, Harper 5.4.0)
07fa3cdf0, in whole-body sealed mode. It succeeded:HDB_ADMINwas dropped on both nodes, his account is the onlysuper_user, andresetPasswordis false.ProxiedRequestLogshows exactly three requests from his user, each only{operation: 'encrypted_operation', envelope}. Its log shows the three relayed answers asencrypted_responseciphertext, and noadd_user,drop_userorcreate_authentication_tokensin that window.HDB_ADMINin place; the right one mints a token that signs in as that user.alter_userthrough the proxy showedoperationandusernamein the op text, never the password. The setup calls in this head sealusernametoo.Test cases
src/lib/crypto/sealedOperation.test.ts: the header the node opens (version, 32-byte response key, 16-byte nonce, timestamp, operation, optional actor); fresh keys per call; the same header shape as the reference client; the reference's sealed answer opened,executedkept; a tampered tag or ciphertext, another request's nonce or key, another version, a missing field and a status-less answer refused.src/integrations/api/instance/sealedOperation.test.ts: only the envelope leaves (no password in the body); a sealed failing status asSealedOperationError, on a failing HTTP status too;executedkept; one clock retry with the offset remembered per node, never two, and forgotten when refused again; one key refetch, never two, and none without a refetcher; a node without custody thrown as answered; a replicated refusal rejected; an unsealed, malformed or foreign answer asUnreadableSealedAnswerError.src/integrations/api/instance/auth/useInstanceResetPasswordMutation.test.tsx: the sealed call order (key,add_user, mint with credentials,drop_user, PATCH, direct connect) on the proxy client with the direct helpers untouched;HDB_ADMINchosen; exists-then-alter; an inactive or non-super user refused;HDB_ADMINalready gone; the form's admin minted over another super user; custody or envelope refusals changing nothing, with no plaintext fallback; a refused mint leavingHDB_ADMIN; a failed drop, then a retry that finishes; an unreachable direct connect finishing signed out; a key fingerprint refetched once then refused; a key fetch failure surfaced; nothing sealed below 5.4.0. ThetempPasswordtests are unchanged.src/features/cluster/sealedSetup.test.ts: versions, prereleases, missing versions, missing or differing fingerprints, deleted members, self-hosted, unloaded.src/features/auth/store/establishFabricConnectAuth.test.ts: given tokens connect directly and mint nothing; throw instead of the proxy fallback; neither join nor become the shared in-flight connect; a resolution replaced while verifying records nothing; a failing unclaimed mint leaves a newer token-backed connection alone.src/features/cluster/FinishSetup.test.tsx: the capability reaches the mutation for a 5.4.0 cluster with the key, the key-pending flag for one without it, and nothing otherwise.src/react-query/queryClient.test.ts: an unanswered sealed operation, an executed sealed failure and an unreadable sealed answer as unknown outcomes; an ordinary sealed refusal as a plain failure.Finish Setup, light and dark (dev server, central manager answered locally)
🤖 Generated by Claude Code (Claude Mythos 5.1, Claude Opus 5.5); posted via @Devin-Holland.
Related PRs: #2104 overlaps (same resolver), 1 other independent
Complexity: complicated
Deferred findings
491bb748f27b319bnit maintainability —tsconfig.app.json— global allowImportingTsExtensions — NOT FILED005ed17d7c98a4a4nit maintainability —src/lib/crypto/__tests__/harper-v5.4.0/sealedOperation.ts— vendored reference exports unused fields-mode API — NOT FILEDReview-Coverage: authored=claude; ran=cursor-composer,gemini,codex,cursor-grok,gemini-carbon; late=cursor-grok:adjudicated,gemini-carbon:adjudicated; adjudicated=domain; blocked=claude(fallback)(timeout); declined=muse; rounds=5; full=1 @ b80acd4
Review-Attention: deep ~60m (sensitive: authStore.ts, useInstanceResetPasswordMutation.ts +2; raised: degraded review) @ b80acd4