Skip to content

feat(cluster): create the first admin through the proxy with sealed operations on Harper 5.4.0+ - #2113

Draft
Devin-Holland wants to merge 7 commits into
stagefrom
finish-setup-sealed-operation
Draft

Devin-Holland wants to merge 7 commits into
stagefrom
finish-setup-sealed-operation

Conversation

@Devin-Holland

@Devin-Holland Devin-Holland commented Nov 16, 2026 •

Copy link
Copy Markdown
Member

⊙ Problem

Finish Setup signs in to the instance directly as HDB_ADMIN with 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 tempPassword only 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 (or alter_user for HDB_ADMIN), a token mint with the typed credentials, and drop_user HDB_ADMIN go in fields mode: central manager logs the operation, never the username or password.
  • The browser connects as the admin, directly or not at all.
  • Below 5.4.0, or without a key, the tempPassword flow 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 tempPassword for 5.4.0+ hosted clusters.

⚖️ Alternatives

  • A central manager endpoint that creates the admin — the password would cross central manager in plaintext, the thing this removes.
  • The proxy-minted plain token with direct calls — needs direct reachability, and on 5.4 the proxy mints for its own local principal.
  • Gate on a key read from central manager — that read creates a missing key and restarts the members.
Also weighed

🤔 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 createTokens checks 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

🤔 post-review delta: fields mode and the late-mint fix were read without the graded leg

Gemini and Cursor Composer reviewed b10de64c6, and Composer a8e787677, 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

  • End-to-end: live on Harper 5.4.0 at 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, oxlint and dprint check are clean.
  • The helper's tests open what it seals with Harper's reference client and the reverse; the sender's tests run against a fake node built from that reference; the hook's tests cover both paths.
Live check, 2026-11-16 (ephemeral env 43958766079, Harper 5.4.0)
  • Devin ran Finish Setup at 22:03:31Z on this branch at 07fa3cdf0, in whole-body sealed mode. It succeeded: HDB_ADMIN was dropped on both nodes, his account is the only super_user, and resetPassword is false.
  • Central manager's ProxiedRequestLog shows exactly three requests from his user, each only {operation: 'encrypted_operation', envelope}. Its log shows the three relayed answers as encrypted_response ciphertext, and no add_user, drop_user or create_authentication_tokens in that window.
  • A probe of the credentialed sealed mint passed 10/10: a wrong password answers a sealed 401 and leaves HDB_ADMIN in place; the right one mints a token that signs in as that user.
  • Fields mode was verified live by an earlier smoke on 5.4.0: a fields-mode alter_user through the proxy showed operation and username in the op text, never the password. The setup calls in this head seal username too.
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, executed kept; 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 as SealedOperationError, on a failing HTTP status too; executed kept; 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 as UnreadableSealedAnswerError.
  • 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_ADMIN chosen; exists-then-alter; an inactive or non-super user refused; HDB_ADMIN already gone; the form's admin minted over another super user; custody or envelope refusals changing nothing, with no plaintext fallback; a refused mint leaving HDB_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. The tempPassword tests 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)

Finish Setup, light

Finish Setup, dark

🤖 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

  • 491bb748f27b319b nit maintainability — tsconfig.app.json — global allowImportingTsExtensions — NOT FILED
  • 005ed17d7c98a4a4 nit maintainability — src/lib/crypto/__tests__/harper-v5.4.0/sealedOperation.ts — vendored reference exports unused fields-mode API — NOT FILED

Review-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

Devin-Holland and others added 4 commits November 16, 2026 14:28
…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>
@Devin-Holland

Copy link
Copy Markdown
Member Author

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.

Finish Setup, dark

🤖 Generated by Claude Code (Claude Mythos 5.1); posted via @Devin-Holland.

@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

Coverage Report

Status Category Percentage Covered / Total
🔵 Lines 86% 23460 / 27277
🔵 Statements 85.79% 24891 / 29013
🔵 Functions 81.95% 6497 / 7928
🔵 Branches 81.49% 20448 / 25091
File Coverage
File Stmts Branches Functions Lines Uncovered Lines
Changed Files
src/features/auth/store/authStore.ts 96.31% 88.72% 97.22% 96.22% 139, 282-283, 292-295, 400-411, 425, 534-537, 881, 1135, 1160
src/features/cluster/FinishSetup.tsx 86.95% 80% 100% 85.71% 70-71, 74-75, 135, 141
src/features/cluster/sealedSetup.ts 100% 96% 100% 100%
src/integrations/api/instance/sealedOperation.ts 100% 90.9% 100% 100%
src/integrations/api/instance/auth/useInstanceResetPasswordMutation.ts 95.55% 90.24% 95.45% 96.18% 194, 240, 270-271, 410-411
src/lib/crypto/envSecret.ts 95.65% 89.47% 100% 95% 56, 63
src/lib/crypto/sealedOperation.ts 98.18% 100% 100% 98.18% 168
src/lib/crypto/__tests__/harper-v5.4.0/sealedOperation.ts 91.42% 78.94% 100% 98.46% 46, 106, 109, 117, 125, 165
src/lib/crypto/__tests__/harper-v5.4.0/secretEnvelope.ts 85.71% 76.47% 100% 85.71% 56, 59, 68, 104
src/react-query/queryClient.ts 98.82% 100% 88.88% 98.8% 165
Generated in workflow #2603 for commit b80acd4 by the Vitest Coverage Report Action

@Devin-Holland
Devin-Holland marked this pull request as ready for review November 16, 2026 21:16
@Devin-Holland
Devin-Holland requested a review from a team as a code owner November 16, 2026 21:16
@Devin-Holland
Devin-Holland marked this pull request as draft November 16, 2026 21:18
Devin-Holland and others added 3 commits November 16, 2026 17:17
…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 kriszyp left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 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) {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[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();

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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) {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[minor] Transport failures misreport a sealed read as an unanswered write

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants