From 405c88dd9e8ff29b6064c2ccc1b20f8d0f3fe469 Mon Sep 17 00:00:00 2001 From: Devin Holland <50112339+Devin-Holland@users.noreply.github.com> Date: Mon, 16 Nov 2026 14:28:25 -0500 Subject: [PATCH 1/7] feat(cluster): create the first admin through the proxy with sealed operations 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 --- DESIGN.md | 2 +- dprint.json | 3 +- src/features/auth/store/authStore.ts | 27 +- src/features/cluster/DESIGN.md | 35 ++ src/features/cluster/FinishSetup.tsx | 4 + src/features/cluster/sealedSetup.test.ts | 60 +++ src/features/cluster/sealedSetup.ts | 40 ++ src/integrations/api/api.patch.d.ts | 3 + .../useInstanceResetPasswordMutation.test.tsx | 358 +++++++++++++++++- .../auth/useInstanceResetPasswordMutation.ts | 124 +++++- .../api/instance/sealedOperation.test.ts | 195 ++++++++++ .../api/instance/sealedOperation.ts | 92 +++++ .../harper-v5.4.0/sealedOperation.ts | 184 +++++++++ .../__tests__/harper-v5.4.0/secretEnvelope.ts | 113 ++++++ src/lib/crypto/envSecret.ts | 17 +- src/lib/crypto/sealedOperation.test.ts | 139 +++++++ src/lib/crypto/sealedOperation.ts | 115 ++++++ src/react-query/queryClient.test.ts | 21 + src/react-query/queryClient.ts | 7 + tsconfig.app.json | 1 + 20 files changed, 1516 insertions(+), 24 deletions(-) create mode 100644 src/features/cluster/sealedSetup.test.ts create mode 100644 src/features/cluster/sealedSetup.ts create mode 100644 src/integrations/api/instance/sealedOperation.test.ts create mode 100644 src/integrations/api/instance/sealedOperation.ts create mode 100644 src/lib/crypto/__tests__/harper-v5.4.0/sealedOperation.ts create mode 100644 src/lib/crypto/__tests__/harper-v5.4.0/secretEnvelope.ts create mode 100644 src/lib/crypto/sealedOperation.test.ts create mode 100644 src/lib/crypto/sealedOperation.ts diff --git a/DESIGN.md b/DESIGN.md index eee42036b..c3e839df2 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -8,7 +8,7 @@ This file collects architecture and design notes for studio that aren't otherwis - [`src/features/clusters/DESIGN.md`](src/features/clusters/DESIGN.md) — cluster list lifecycle classification, optional metadata and notification scope, where a saved cluster draft reopens, and when the cluster form may terminate a cluster. -- [`src/features/cluster/DESIGN.md`](src/features/cluster/DESIGN.md) — when the Starting-up and Scaling screens may report done, how clone progress is read, where the cluster card's sync chip gets its data, how custom-domain cert intent, certificate progress and the Bind selection work, why a domain change is built from a fresh read, why nothing connects to a cluster before its setup, how an interrupted setup finishes, which pages a terminated cluster still opens, how a delete that central manager runs as a workflow is told from a finished one and reported when it stops, and when its sign-ins are forgotten. +- [`src/features/cluster/DESIGN.md`](src/features/cluster/DESIGN.md) — when the Starting-up and Scaling screens may report done, how clone progress is read, where the cluster card's sync chip gets its data, how custom-domain cert intent, certificate progress and the Bind selection work, why a domain change is built from a fresh read, why nothing connects to a cluster before its setup, how setup on 5.4.0+ seals its writes through the proxy, how an interrupted setup finishes, which pages a terminated cluster still opens, how a delete that central manager runs as a workflow is told from a finished one and reported when it stops, and when its sign-ins are forgotten. - [`src/features/instance/databases/DESIGN.md`](src/features/instance/databases/DESIGN.md) — when the browse grid may show its spinner, why a table without a primary key can't be listed, why a filtered list pages without a count, why Export CSV writes the file in the browser instead of asking Harper for `text/csv`, where columns for undeclared properties come from, why a filter no index can answer asks first, and why an import job Studio stopped following reads as outcome unknown. diff --git a/dprint.json b/dprint.json index a995322b0..b8f9c5b55 100644 --- a/dprint.json +++ b/dprint.json @@ -21,7 +21,8 @@ "**/*-lock.json", "pnpm-lock.yaml", "src/assets/**", - "src/integrations/api/api.gen.d.ts" + "src/integrations/api/api.gen.d.ts", + "src/lib/crypto/__tests__/harper-v5.4.0/**" ], "plugins": [ "https://plugins.dprint.dev/typescript-0.95.13.wasm", diff --git a/src/features/auth/store/authStore.ts b/src/features/auth/store/authStore.ts index 91b0be16d..42147bed7 100644 --- a/src/features/auth/store/authStore.ts +++ b/src/features/auth/store/authStore.ts @@ -11,6 +11,7 @@ import { SchemaCluster, SchemaHdbInstance } from '@/integrations/api/api.gen'; import { Cluster, Instance, LocalUser, User } from '@/integrations/api/api.patch'; import { createInstanceAuthenticationTokens, + type InstanceAuthenticationTokens, refreshInstanceOperationToken, } from '@/integrations/api/instance/auth/createInstanceAuthenticationTokens'; import { onInstanceLogoutSubmit } from '@/integrations/api/instance/auth/onInstanceLogoutSubmit'; @@ -628,17 +629,27 @@ class AuthStore { * drop the token and fall back to routing everything through the proxy. The verified user is * recorded in the connection state either way. The JWT is held in memory only. * - * Concurrent calls for the same id share one in-flight request. + * `tokens` minted for one user stand in for the proxy's own mint and connect directly or not at all: setup's sealed + * mint names the new admin, where on Harper 5.4+ the proxy runs as its own `local` principal, so routing through + * it would not be that user's session. Such a call shares no in-flight mint, whose tokens are not these. + * + * Concurrent calls for the same id otherwise share one in-flight request. */ public establishFabricConnectAuth( - { id, operationsUrl }: { id: EntityIds; operationsUrl?: string | null }, + { id, operationsUrl, tokens }: { + id: EntityIds; + operationsUrl?: string | null; + tokens?: InstanceAuthenticationTokens; + }, ): Promise { const inFlight = this.fabricConnectInFlight.get(id); - if (inFlight) { + if (inFlight && !tokens) { return inFlight; } - const promise = this.resolveFabricConnectAuth(id, operationsUrl); - this.fabricConnectInFlight.set(id, promise); + const promise = this.resolveFabricConnectAuth(id, operationsUrl, tokens); + if (!inFlight) { + this.fabricConnectInFlight.set(id, promise); + } return promise.finally(() => { // A sign-out empties the map, so a replacement may already be registered under this id. if (this.fabricConnectInFlight.get(id) === promise) { @@ -650,6 +661,7 @@ class AuthStore { private async resolveFabricConnectAuth( id: EntityIds, operationsUrl: string | null | undefined, + tokens: InstanceAuthenticationTokens | undefined, ): Promise { const signOutGeneration = this.getSignOutGeneration(id); const throwIfSignedOut = () => { @@ -664,7 +676,7 @@ class AuthStore { this.fabricConnectAuth.set(id, auth); }; try { - const { operationToken, refreshToken } = await createInstanceAuthenticationTokens({ + const { operationToken, refreshToken } = tokens ?? await createInstanceAuthenticationTokens({ instanceClient: getInstanceClient({ id, forceFabricConnect: true }), }); throwIfSignedOut(); @@ -697,6 +709,9 @@ class AuthStore { return directUser; } } + if (tokens) { + throw new Error('The cluster could not be reached directly, so the admin could not be connected.'); + } // Proxy fallback: route every operation through the central-manager proxy. claim({ mode: 'proxy' }); diff --git a/src/features/cluster/DESIGN.md b/src/features/cluster/DESIGN.md index db7f748f6..cf2a32bd7 100644 --- a/src/features/cluster/DESIGN.md +++ b/src/features/cluster/DESIGN.md @@ -85,6 +85,41 @@ the `Authorization` header before the session cookie. If its own login still fal again once `HDB_ADMIN` is gone. If that fails, or still names `HDB_ADMIN` (the proxy can reach an instance the drop has not replicated to yet), setup finishes signed out instead, and the user connects from the overview. +## Setup on 5.4.0+ seals its writes through the proxy + +Harper 5.4.0 runs an operation the client sealed to the cluster's secrets key (`encrypted_operation`, +[HarperFast/harper#4205](https://github.com/HarperFast/harper/pull/4205)), and seals the answer back, so central manager's +Fabric Connect proxy relays ciphertext both ways. On such a cluster Finish Setup no longer needs the provisioning +account's password, which central manager will stop writing for 5.4.0+ hosted clusters once this is deployed +([HarperFast/central-manager#963](https://github.com/HarperFast/central-manager/pull/963)), nor a browser that can reach +the instance directly. + +The cluster record decides, in [`sealedSetup.ts`](sealedSetup.ts): a Fabric-hosted cluster whose every live member +reports 5.4.0 or later and carries the same `secretsKeyFingerprint`. The fingerprint is what proves the key exists and +reached each host; without it, asking central manager for the key would create one and restart the members +(`ClusterSecretsKey.js`), in the middle of setup. Anything else keeps the `tempPassword` flow above, unchanged, and a +5.4.0 prerelease counts as below the floor. The sealed path never reads `tempPassword`. + +Every write goes through `getInstanceClient({ forceFabricConnect: true })` as `encrypted_operation` +([`runSealedOperation`](../../integrations/api/instance/sealedOperation.ts), over +[`lib/crypto/sealedOperation.ts`](../../lib/crypto/sealedOperation.ts), whose tests open what it seals with Harper's +own reference client, copied unchanged from v5.4.0): `add_user` (or `alter_user` when the form names `HDB_ADMIN`), then +`create_authentication_tokens` with the typed username and password, then `drop_user HDB_ADMIN`, then the PATCH. The +mint comes before the drop and carries the credentials on purpose: the node checks the password and names that user, +so the tokens are the admin's whatever other super users an earlier attempt left, and a wrong password stops setup while +the provisioning account still exists. A credential-free mint would name the node's first stored super user, which +need not be the form's. The proxy itself runs every request as Harper's record-less `local` principal, so the browser +connects afterwards with those tokens directly or not at all (`establishFabricConnectAuth` with `tokens`): a session +through the proxy would be `local`'s, and setup then finishes signed out rather than report it as the admin's. + +A retry reads the cluster's state the same way: `add_user` answering "already exists" adopts the user only if +`list_users` reports it an active super user, and a `drop_user` answering "does not exist" means an earlier attempt +dropped it and never sent the PATCH. The node answers a timestamp outside its window with its own clock and an +envelope for another key with its fingerprint; each is retried once, with the offset remembered for the session and +the key fetched again. A sealed answer that ran but could not return its result (`executed`) is reported as an unknown +outcome, like an unanswered write, since the user was created or dropped all the same. There is no plaintext fallback: +a node without custody (503) or a refused envelope is an error. + ## An interrupted setup finishes from the admin it already created Central manager's `ResetPasswordUpdater` takes no body and only clears `resetPassword` diff --git a/src/features/cluster/FinishSetup.tsx b/src/features/cluster/FinishSetup.tsx index 3922cb1d4..c34491585 100644 --- a/src/features/cluster/FinishSetup.tsx +++ b/src/features/cluster/FinishSetup.tsx @@ -25,6 +25,7 @@ import { toast } from 'sonner'; import { z } from 'zod'; import { allClusterInstancesRunning } from './allInstancesRunning'; import { getClusterInfoQueryOptions, markClusterPasswordSet } from './queries/getClusterInfoQuery'; +import { sealedSetupCapability } from './sealedSetup'; import { clusterSignInIds } from './terminatedClusterSignIns'; export function FinishSetup() { @@ -58,6 +59,7 @@ export function FinishSetup() { }, [setFocus]); const tempPassword = cluster?.instances?.find(i => i.tempPassword)?.tempPassword; + const sealedSetup = sealedSetupCapability(cluster); const instancesReady = allClusterInstancesRunning(cluster); const { mutate: submitInstanceResetPassword, isPending, isSuccess } = useInstanceResetPasswordMutation(); @@ -77,6 +79,7 @@ export function FinishSetup() { clusterId, newPassword: formData.password, tempPassword, + sealedSetup: sealedSetup ?? undefined, initialUsername: defaultClusterUsername, desiredUsername: formData.username, }, { @@ -114,6 +117,7 @@ export function FinishSetup() { queryClient, redirect, router, + sealedSetup, submitInstanceResetPassword, tempPassword, ]); diff --git a/src/features/cluster/sealedSetup.test.ts b/src/features/cluster/sealedSetup.test.ts new file mode 100644 index 000000000..cadb14dec --- /dev/null +++ b/src/features/cluster/sealedSetup.test.ts @@ -0,0 +1,60 @@ +import type { Cluster } from '@/integrations/api/api.patch'; +import { describe, expect, it } from 'vitest'; +import { sealedSetupCapability } from './sealedSetup'; + +function cluster( + instances: Array<{ version?: string; status?: string; secretsKeyFingerprint?: string | null }>, + planId = 'standard', +): Cluster { + return { + id: 'clu-1', + plans: [{ planId }], + instances: instances.map((instance, index) => ({ + id: `ins-${index}`, + status: 'RUNNING', + secretsKeyFingerprint: 'fp-1', + ...instance, + })), + } as unknown as Cluster; +} + +describe(sealedSetupCapability, () => { + it('names the key every live member holds once all of them run 5.4.0 or later', () => { + expect(sealedSetupCapability(cluster([{ version: '5.4.0' }, { version: '5.5.1' }]))).toEqual({ + keyFingerprint: 'fp-1', + }); + expect(sealedSetupCapability(cluster([{ version: '5.4.0' }, { version: '5.3.9' }]))).toBeNull(); + }); + + it.each([ + ['a prerelease of 5.4.0', { version: '5.4.0-beta.1' }], + ['no version', { version: undefined }], + ['a version that is not semver', { version: 'latest' }], + ['a member without the key', { version: '5.4.0', secretsKeyFingerprint: null }], + ])('fails closed on %s', (_, instance) => { + expect(sealedSetupCapability(cluster([{ version: '5.4.0' }, instance]))).toBeNull(); + }); + + it('fails closed when the members hold different keys', () => { + expect(sealedSetupCapability(cluster([{ version: '5.4.0' }, { version: '5.4.0', secretsKeyFingerprint: 'fp-2' }]))) + .toBeNull(); + }); + + it('ignores members that are being removed', () => { + expect( + sealedSetupCapability( + cluster([{ version: '5.4.0' }, { version: '5.2.0', status: 'TERMINATED', secretsKeyFingerprint: null }]), + ), + ).toEqual({ keyFingerprint: 'fp-1' }); + expect(sealedSetupCapability(cluster([{ version: '5.4.0', status: 'TERMINATED' }]))).toBeNull(); + }); + + it('is never on for a self-hosted cluster, which has no central manager key', () => { + expect(sealedSetupCapability(cluster([{ version: '5.4.0' }], 'self-hosted-free'))).toBeNull(); + }); + + it('is off until the cluster is loaded', () => { + expect(sealedSetupCapability(undefined)).toBeNull(); + expect(sealedSetupCapability(cluster([]))).toBeNull(); + }); +}); diff --git a/src/features/cluster/sealedSetup.ts b/src/features/cluster/sealedSetup.ts new file mode 100644 index 000000000..3271ae163 --- /dev/null +++ b/src/features/cluster/sealedSetup.ts @@ -0,0 +1,40 @@ +import { deletedClusterStatuses } from '@/config/clusterStatuses'; +import { Cluster } from '@/integrations/api/api.patch'; +import { clusterIsSelfManaged } from '@/integrations/api/clusterIsSelfManaged'; +import { wasAReleasedBeforeB } from '@/lib/string/wasAReleasedBeforeB'; + +/** `encrypted_operation` shipped in Harper 5.4.0 (HarperFast/harper#4205). */ +export const SEALED_SETUP_MIN_VERSION = '5.4.0'; + +export interface SealedSetupCapability { + /** The cluster secrets key every live member holds, by its fingerprint. */ + keyFingerprint: string; +} + +/** + * Whether setup can seal its writes to the cluster's key, read from the cluster record alone: a Fabric-hosted cluster + * whose every live member reports 5.4.0 or later and carries the same secrets key fingerprint. The fingerprint is what + * says the key exists and reached each host, so the key fetch that follows is a plain read; asking central manager + * for a key it does not hold yet would create one and restart the members. A member with no version, a prerelease of + * 5.4.0, or no fingerprint fails closed. + */ +export function sealedSetupCapability(cluster: Cluster | undefined): SealedSetupCapability | null { + if (!cluster || clusterIsSelfManaged(cluster)) { + return null; + } + const live = (cluster.instances ?? []).filter( + (instance) => !(instance.status && deletedClusterStatuses.includes(instance.status)), + ); + const keyFingerprint = live[0]?.secretsKeyFingerprint; + if ( + !keyFingerprint + || !live.every((instance) => + instance.secretsKeyFingerprint === keyFingerprint + && !!instance.version + && wasAReleasedBeforeB(SEALED_SETUP_MIN_VERSION, instance.version) + ) + ) { + return null; + } + return { keyFingerprint }; +} diff --git a/src/integrations/api/api.patch.d.ts b/src/integrations/api/api.patch.d.ts index 4e7659d66..2301a770e 100644 --- a/src/integrations/api/api.patch.d.ts +++ b/src/integrations/api/api.patch.d.ts @@ -418,6 +418,9 @@ export interface Instance extends Omit { diff --git a/src/integrations/api/instance/auth/useInstanceResetPasswordMutation.test.tsx b/src/integrations/api/instance/auth/useInstanceResetPasswordMutation.test.tsx index 26e3bd4d2..00f64d401 100644 --- a/src/integrations/api/instance/auth/useInstanceResetPasswordMutation.test.tsx +++ b/src/integrations/api/instance/auth/useInstanceResetPasswordMutation.test.tsx @@ -32,13 +32,34 @@ vi.mock('@/integrations/api/instance/auth/createInstanceAuthenticationTokens', ( })); let ownerIsSuperUser = true; vi.mock('@/integrations/api/instance/status/getInstanceUserInfo', () => ({ - getInstanceUserInfo: async ({ instanceClient }: { instanceClient: AxiosInstance }) => - instanceClient.defaults.headers.Authorization === 'Bearer owner-token' + getInstanceUserInfo: async ({ instanceClient }: { instanceClient: AxiosInstance }) => { + const authorization = instanceClient.defaults.headers.Authorization; + if (typeof authorization === 'string' && authorization.startsWith(`Bearer ${sealedNode.tokenPrefix}`)) { + return sealedNode.userInfo(authorization.slice(`Bearer ${sealedNode.tokenPrefix}`.length)); + } + return authorization === 'Bearer owner-token' ? localUser(OWNER, ownerIsSuperUser) - : localUser(defaultClusterUsername), + : localUser(defaultClusterUsername); + }, +})); + +// The sealed path: what a 5.4 node answers inside the envelope, and the key central manager holds for the cluster. +const runSealedOperation = vi.fn(); +vi.mock('@/integrations/api/instance/sealedOperation', async (importOriginal) => ({ + ...(await importOriginal()), + runSealedOperation: (...args: unknown[]) => runSealedOperation(...args), +})); +const fetchClusterKey = vi.fn(); +vi.mock('@/integrations/api/instance/secrets/secrets', () => ({ + secretsPublicKeyQueryOptions: (params: { entityId: string; managedClusterId?: string }) => ({ + queryKey: [params.entityId, 'get_secrets_public_key', params.managedClusterId ?? 'node'], + queryFn: () => fetchClusterKey(params), + retry: false, + }), })); import { resetPasswordUpdater } from '@/features/cluster/queries/resetPasswordUpdater'; +import { SealedOperationError } from '@/integrations/api/instance/sealedOperation'; import { onAddUserSubmit } from './addUser'; import { onAlterUser } from './alterUser'; import { onDeleteUser } from './deleteUser'; @@ -49,10 +70,11 @@ import { useInstanceResetPasswordMutation } from './useInstanceResetPasswordMuta const OWNER = 'owner@example.com'; const CLUSTER_URL = 'https://clu-1.example.com:9925/'; const INSTANCE_URL = 'https://ins-1.example.com:9925/'; +const CLUSTER_KEY = { publicKey: '-----BEGIN PUBLIC KEY-----\nMIIB\n-----END PUBLIC KEY-----\n', fingerprint: 'fp-1' }; -function localUser(username: string, superUser = true): LocalUser { +function localUser(username: string, superUser = true, active = true): LocalUser { return { - active: true, + active, username, role: { id: 'r1', @@ -66,8 +88,8 @@ function localUser(username: string, superUser = true): LocalUser { }; } -/** A failed operations request as axios rejects it; no `status` is a network error. */ -function failedRequest(status?: number, operation = 'login') { +/** A failed request as axios rejects it; no `status` is a network error. */ +function failedRequest(status?: number, operation = 'login', data?: Record) { const config = { data: JSON.stringify({ operation }), headers: new AxiosHeaders() }; if (status === undefined) { return new AxiosError('Network Error', AxiosError.ERR_NETWORK, config); @@ -75,7 +97,7 @@ function failedRequest(status?: number, operation = 'login') { return new AxiosError(`Request failed with status code ${status}`, AxiosError.ERR_BAD_REQUEST, config, undefined, { status, statusText: '', - data: { error: status === 401 ? 'Login failed' : 'Unavailable' }, + data: data ?? { error: status === 401 ? 'Login failed' : 'Unavailable' }, headers: {}, config, }); @@ -94,10 +116,102 @@ function conflict(error: string) { }); } +/** + * A 5.4 node as the sealed path sees it. Every proxied request runs as the record-less `local` super user; a token + * mint with credentials checks them and names that user, and one without names the first active stored super user. + */ +class SealedNode { + readonly tokenPrefix = 'token:'; + users = new Map(); + operations: string[] = []; + clients: AxiosInstance[] = []; + + reset() { + this.users = new Map([[defaultClusterUsername, { superUser: true, active: true }]]); + this.operations = []; + this.clients = []; + } + + userInfo(username: string): LocalUser { + const user = this.users.get(username); + if (!user) { + throw failedRequest(401, 'user_info'); + } + return localUser(username, user.superUser, user.active); + } + + async run( + { op, instanceClient }: { op: Record & { operation: string }; instanceClient: AxiosInstance }, + ) { + this.operations.push(op.operation); + this.clients.push(instanceClient); + const result = this.execute(op); + if (result.status >= 400) { + throw new SealedOperationError(op.operation, result); + } + return result; + } + + execute(op: Record & { operation: string }): { status: number; body: unknown } { + const username = op.username as string; + switch (op.operation) { + case 'add_user': + if (this.users.has(username)) { + return { status: 409, body: { error: `User ${username} already exists` } }; + } + this.users.set(username, { + password: op.password as string, + superUser: op.role === 'super_user', + active: true, + }); + return { status: 200, body: { message: `${username} successfully added` } }; + case 'alter_user': { + const user = this.users.get(username); + if (!user) { + return { status: 404, body: { error: `User ${username} does not exist` } }; + } + user.password = op.password as string; + return { status: 200, body: { message: 'updated' } }; + } + case 'drop_user': + if (!this.users.delete(username)) { + return { status: 404, body: { error: `User ${username} does not exist` } }; + } + return { status: 200, body: { message: `${username} successfully deleted` } }; + case 'list_users': + return { + status: 200, + body: [...this.users].map(([name, { superUser, active }]) => localUser(name, superUser, active)), + }; + case 'create_authentication_tokens': { + const named = username ? this.users.get(username) : undefined; + if (username && (!named || named.password !== op.password)) { + return { status: 401, body: { error: 'Invalid credentials' } }; + } + const subject = username || [...this.users].find(([, user]) => user.superUser && user.active)?.[0]; + if (!subject) { + return { status: 409, body: { error: 'No stored super user to mint a token for' } }; + } + return { + status: 200, + body: { operation_token: this.tokenPrefix + subject, refresh_token: 'refresh:' + subject }, + }; + } + default: + return { status: 400, body: { error: `${op.operation} cannot be sealed` } }; + } + } +} + +const sealedNode = new SealedNode(); + beforeEach(() => { vi.clearAllMocks(); provisioningAccountDropped = false; ownerIsSuperUser = true; + sealedNode.reset(); + fetchClusterKey.mockResolvedValue(CLUSTER_KEY); + runSealedOperation.mockImplementation((params: Parameters[0]) => sealedNode.run(params)); onInstanceLoginSubmit.mockReset(); onInstanceLoginSubmit.mockImplementation(async ({ username }: { username: string }) => ({ message: 'Login successful', @@ -117,8 +231,11 @@ afterEach(() => { localStorage.clear(); }); -function resetPassword(desiredUsername: string) { - const client = new QueryClient({ defaultOptions: { mutations: { retry: false } } }); +function resetPassword( + desiredUsername: string, + overrides: { sealedSetup?: { keyFingerprint: string }; tempPassword?: string } = {}, +) { + const client = new QueryClient({ defaultOptions: { mutations: { retry: false }, queries: { retry: false } } }); const { result } = renderHook(() => useInstanceResetPasswordMutation(), { wrapper: ({ children }: { children: ReactNode }) => ( {children} @@ -132,6 +249,7 @@ function resetPassword(desiredUsername: string) { desiredUsername, newPassword: 'new-password', tempPassword: 'temp-password', + ...overrides, }); } @@ -502,3 +620,223 @@ describe('an interrupted setup: the setup account is gone, the admin exists, and expect(resetPasswordUpdater).not.toHaveBeenCalled(); }); }); + +describe('sealed setup on a 5.4.0+ cluster', () => { + const SEALED = { sealedSetup: { keyFingerprint: 'fp-1' }, tempPassword: undefined }; + const sealed = (desiredUsername: string) => resetPassword(desiredUsername, SEALED); + + function expectNothingDirect() { + expect(onInstanceLoginSubmit).not.toHaveBeenCalled(); + expect(onAddUserSubmit).not.toHaveBeenCalled(); + expect(onAlterUser).not.toHaveBeenCalled(); + expect(onDeleteUser).not.toHaveBeenCalled(); + expect(createInstanceAuthenticationTokens).not.toHaveBeenCalled(); + } + + function expectNothingSignedIn() { + expect(authStore.getOperationToken('clu-1')).toBeUndefined(); + expect(authStore.checkForFabricConnect('clu-1')).toBe(false); + expect(authStore.getConnectionById('clu-1').user).toBeNull(); + } + + it("seals the admin, proves its sign-in with the admin's own tokens, drops the provisioning account, tells central manager, then connects", async () => { + const { user } = await sealed(OWNER); + + expect(user?.username).toBe(OWNER); + expect(sealedNode.operations).toEqual(['add_user', 'create_authentication_tokens', 'drop_user']); + expect(vi.mocked(resetPasswordUpdater).mock.invocationCallOrder[0]).toBeGreaterThan( + runSealedOperation.mock.invocationCallOrder.at(-1)!, + ); + expect(fetchClusterKey).toHaveBeenCalledWith( + expect.objectContaining({ entityId: 'clu-1', managedClusterId: 'clu-1' }), + ); + expect(runSealedOperation.mock.calls.map(([{ op }]) => op)).toEqual([ + { operation: 'add_user', username: OWNER, password: 'new-password', role: 'super_user', active: true }, + { operation: 'create_authentication_tokens', username: OWNER, password: 'new-password' }, + { operation: 'drop_user', username: defaultClusterUsername }, + ]); + expect(runSealedOperation.mock.calls[0][0]).toMatchObject({ key: CLUSTER_KEY }); + for (const instanceClient of sealedNode.clients) { + expect(instanceClient.defaults.baseURL).toContain('/Cluster/clu-1/operation'); + } + expect(sealedNode.users.has(defaultClusterUsername)).toBe(false); + expect(authStore.getOperationToken('clu-1')).toBe(`token:${OWNER}`); + expect(authStore.getConnectionById('clu-1').user).toMatchObject({ username: OWNER }); + expectNothingDirect(); + }); + + it('sets the password of the provisioning account instead when the form names it, and drops nothing', async () => { + const { user } = await sealed(defaultClusterUsername); + + expect(user?.username).toBe(defaultClusterUsername); + expect(sealedNode.operations).toEqual(['alter_user', 'create_authentication_tokens']); + expect(sealedNode.users.get(defaultClusterUsername)?.password).toBe('new-password'); + expect(resetPasswordUpdater).toHaveBeenCalledTimes(1); + expectNothingDirect(); + }); + + it('adopts an admin an earlier attempt created, once it is an active super user', async () => { + sealedNode.users.set(OWNER, { password: 'first-password', superUser: true, active: true }); + + const { user } = await sealed(OWNER); + + expect(user?.username).toBe(OWNER); + expect(sealedNode.operations).toEqual([ + 'add_user', + 'list_users', + 'alter_user', + 'create_authentication_tokens', + 'drop_user', + ]); + expect(sealedNode.users.get(OWNER)?.password).toBe('new-password'); + expect(resetPasswordUpdater).toHaveBeenCalledTimes(1); + }); + + it.each([ + ['not a super user', { superUser: false, active: true }], + ['inactive', { superUser: true, active: false }], + ])('refuses, changing nothing, when the user that exists is %s', async (_, state) => { + sealedNode.users.set(OWNER, { password: 'first-password', ...state }); + + await expect(sealed(OWNER)).rejects.toThrow("already exists on this cluster but isn't an active super user"); + + expect(sealedNode.operations).toEqual(['add_user', 'list_users']); + expect(sealedNode.users.has(defaultClusterUsername)).toBe(true); + expect(resetPasswordUpdater).not.toHaveBeenCalled(); + }); + + it('finishes when an earlier attempt already dropped the provisioning account and never told central manager', async () => { + sealedNode.users.delete(defaultClusterUsername); + sealedNode.users.set(OWNER, { password: 'first-password', superUser: true, active: true }); + + const { user } = await sealed(OWNER); + + expect(user?.username).toBe(OWNER); + expect(sealedNode.operations).toEqual([ + 'add_user', + 'list_users', + 'alter_user', + 'create_authentication_tokens', + 'drop_user', + ]); + expect(resetPasswordUpdater).toHaveBeenCalledTimes(1); + }); + + it("mints for the form's admin and no other super user another attempt may have left", async () => { + sealedNode.users.set('alice@example.com', { password: 'alice', superUser: true, active: true }); + + const { user } = await sealed(OWNER); + + expect(user?.username).toBe(OWNER); + expect(authStore.getOperationToken('clu-1')).toBe(`token:${OWNER}`); + }); + + it.each([ + [ + 'the node holds no custody', + () => + runSealedOperation.mockRejectedValueOnce( + failedRequest(503, 'encrypted_operation', { error: 'secrets custody is not initialized on this node' }), + ), + ], + [ + 'the envelope is refused', + () => + runSealedOperation.mockRejectedValueOnce( + failedRequest(400, 'encrypted_operation', { error: 'The envelope could not be decrypted' }), + ), + ], + ])( + 'surfaces the refusal, changes nothing, and never falls back to a plaintext request when %s', + async (_, arrange) => { + arrange(); + + await expect(sealed(OWNER)).rejects.toThrow(); + + expect(sealedNode.users.has(defaultClusterUsername)).toBe(true); + expect(resetPasswordUpdater).not.toHaveBeenCalled(); + expectNothingSignedIn(); + expectNothingDirect(); + }, + ); + + it('does not drop the provisioning account when the admin cannot sign in', async () => { + runSealedOperation.mockImplementation(async (params: Parameters[0]) => { + if (params.op.operation === 'create_authentication_tokens') { + throw new SealedOperationError(params.op.operation, { status: 401, body: { error: 'Invalid credentials' } }); + } + return sealedNode.run(params); + }); + + await expect(sealed(OWNER)).rejects.toThrow('Invalid credentials'); + + expect(sealedNode.operations).toEqual(['add_user']); + expect(sealedNode.users.has(defaultClusterUsername)).toBe(true); + expect(resetPasswordUpdater).not.toHaveBeenCalled(); + }); + + it('surfaces a drop that fails and sends no PATCH, so a retry can finish', async () => { + runSealedOperation.mockImplementation(async (params: Parameters[0]) => { + if (params.op.operation === 'drop_user') { + throw failedRequest(502, 'encrypted_operation', { error: 'Bad gateway' }); + } + return sealedNode.run(params); + }); + + await expect(sealed(OWNER)).rejects.toThrow(); + expect(resetPasswordUpdater).not.toHaveBeenCalled(); + + runSealedOperation.mockImplementation((params: Parameters[0]) => sealedNode.run(params)); + const { user } = await sealed(OWNER); + + expect(user?.username).toBe(OWNER); + expect(sealedNode.users.has(defaultClusterUsername)).toBe(false); + expect(resetPasswordUpdater).toHaveBeenCalledTimes(1); + }); + + it('finishes signed out, after telling central manager, when the cluster cannot be reached directly', async () => { + runSealedOperation.mockImplementation(async (params: Parameters[0]) => { + const result = await sealedNode.run(params); + return params.op.operation === 'create_authentication_tokens' + ? { ...result, body: { operation_token: 'token:unreachable', refresh_token: 'r' } } + : result; + }); + + const { user } = await sealed(OWNER); + + expect(user).toBeNull(); + expect(resetPasswordUpdater).toHaveBeenCalledTimes(1); + // The proxy's own session would be the `local` principal's, never the admin's, so none is kept. + expect(createInstanceAuthenticationTokens).not.toHaveBeenCalled(); + expectNothingSignedIn(); + }); + + it('refetches a key whose fingerprint is not the one the members hold, and refuses one that stays different', async () => { + fetchClusterKey.mockResolvedValueOnce({ ...CLUSTER_KEY, fingerprint: 'fp-0' }); + const { user } = await sealed(OWNER); + expect(user?.username).toBe(OWNER); + expect(fetchClusterKey).toHaveBeenCalledTimes(2); + + sealedNode.reset(); + fetchClusterKey.mockResolvedValue({ ...CLUSTER_KEY, fingerprint: 'fp-0' }); + await expect(sealed(OWNER)).rejects.toThrow('not the one its members hold'); + expect(sealedNode.operations).toEqual([]); + }); + + it('surfaces a failure to fetch the key rather than falling back to the temporary password', async () => { + const outage = failedRequest(503, 'get_secrets_public_key'); + fetchClusterKey.mockRejectedValueOnce(outage); + + await expect(sealed(OWNER)).rejects.toBe(outage); + + expect(runSealedOperation).not.toHaveBeenCalled(); + expectNothingDirect(); + }); + + it('never looks for the key, or seals anything, below 5.4.0', async () => { + await resetPassword(OWNER); + + expect(fetchClusterKey).not.toHaveBeenCalled(); + expect(runSealedOperation).not.toHaveBeenCalled(); + }); +}); diff --git a/src/integrations/api/instance/auth/useInstanceResetPasswordMutation.ts b/src/integrations/api/instance/auth/useInstanceResetPasswordMutation.ts index 5c2931922..eda9e95c7 100644 --- a/src/integrations/api/instance/auth/useInstanceResetPasswordMutation.ts +++ b/src/integrations/api/instance/auth/useInstanceResetPasswordMutation.ts @@ -2,9 +2,13 @@ import { defaultClusterUsername } from '@/config/constants'; import { connectsThroughProxy, getInstanceClient } from '@/config/getInstanceClient'; import { authStore } from '@/features/auth/store/authStore'; import { resetPasswordUpdater } from '@/features/cluster/queries/resetPasswordUpdater'; +import { SealedSetupCapability } from '@/features/cluster/sealedSetup'; import { LocalUser } from '@/integrations/api/api.patch'; +import { isSealedRefusal, runSealedOperation } from '@/integrations/api/instance/sealedOperation'; +import { SecretsPublicKey, secretsPublicKeyQueryOptions } from '@/integrations/api/instance/secrets/secrets'; import { operationOf } from '@/integrations/api/isReadOperation'; -import { useMutation } from '@tanstack/react-query'; +import { SealableOperation } from '@/lib/crypto/sealedOperation'; +import { QueryClient, useMutation, useQueryClient } from '@tanstack/react-query'; import { type AxiosInstance, isAxiosError } from 'axios'; import { onAddUserSubmit } from './addUser'; import { onAlterUser } from './alterUser'; @@ -21,6 +25,8 @@ interface InstanceResetPasswordParams { desiredUsername: string; newPassword: string; tempPassword: string | undefined; + /** Set when every live member can run sealed operations against one cluster key (`sealedSetupCapability`). */ + sealedSetup?: SealedSetupCapability; } interface InstanceResetPasswordResponse { @@ -29,7 +35,17 @@ interface InstanceResetPasswordResponse { user: LocalUser | null; } -async function onInstanceResetPassword({ +async function onInstanceResetPassword( + queryClient: QueryClient, + params: InstanceResetPasswordParams, +): Promise { + if (params.sealedSetup) { + return finishSetupSealed(queryClient, params, params.sealedSetup); + } + return finishSetupWithTemporaryPassword(params); +} + +async function finishSetupWithTemporaryPassword({ clusterId, operationsUrl, signInIds, @@ -134,6 +150,107 @@ async function onInstanceResetPassword({ return loginResponse; } +function clusterKeyQuery(clusterId: string) { + return secretsPublicKeyQueryOptions({ + entityId: clusterId, + instanceClient: getInstanceClient({ id: clusterId, forceFabricConnect: true }), + managedClusterId: clusterId, + }); +} + +async function refetchClusterKey(queryClient: QueryClient, clusterId: string): Promise { + queryClient.removeQueries({ queryKey: clusterKeyQuery(clusterId).queryKey }); + return queryClient.ensureQueryData(clusterKeyQuery(clusterId)); +} + +/** See "Setup on 5.4.0+ seals its writes through the proxy" in `src/features/cluster/DESIGN.md`. */ +async function finishSetupSealed( + queryClient: QueryClient, + { clusterId, operationsUrl, signInIds, desiredUsername, newPassword }: InstanceResetPasswordParams, + { keyFingerprint }: SealedSetupCapability, +): Promise { + // A connection made before setup is the provisioning account's, and it stops working once that account is dropped. + authStore.signOutEntitiesLocally(signInIds); + // The members hold the key by its fingerprint; a cached key with another is stale, and one that stays different + // after a fresh read is a cluster whose key is changing under setup. + let key = await queryClient.ensureQueryData(clusterKeyQuery(clusterId)); + if (key.fingerprint !== keyFingerprint) { + key = await refetchClusterKey(queryClient, clusterId); + if (key.fingerprint !== keyFingerprint) { + throw new Error( + "Couldn't finish setup: central manager's key for this cluster is not the one its members hold. Try again in a moment.", + ); + } + } + const instanceClient = getInstanceClient({ id: clusterId, forceFabricConnect: true }); + const refreshKey = async () => (key = await refetchClusterKey(queryClient, clusterId)); + const seal = (op: SealableOperation) => runSealedOperation({ instanceClient, op, key, refreshKey }); + + if (desiredUsername === defaultClusterUsername) { + await seal({ operation: 'alter_user', username: desiredUsername, password: newPassword }); + } else { + try { + await seal({ + operation: 'add_user', + username: desiredUsername, + password: newPassword, + role: 'super_user', + active: true, + }); + } catch (err) { + if (!isSealedRefusal(err, 409, `User ${desiredUsername} already exists`)) { + throw err; + } + // An earlier attempt created the admin and stopped before the drop: adopt it, as the direct flow does. The + // password set below does not activate a user, so an inactive one could never sign in afterwards. + const users = (await seal({ operation: 'list_users' })).body as LocalUser[]; + const existing = users.find((user) => user.username === desiredUsername); + if (existing?.role?.permission?.super_user !== true || !existing.active) { + throw new Error( + `Couldn't finish setup: "${desiredUsername}" already exists on this cluster but isn't an active super user. Choose another username.`, + ); + } + await seal({ operation: 'alter_user', username: desiredUsername, password: newPassword }); + } + } + // Minted with the typed credentials, the tokens are the admin's and nobody else's: the node checks the password + // and names that user, however many super users another attempt left. This is also the proof the admin signs in, + // taken before the account that created it goes. + const minted = + (await seal({ operation: 'create_authentication_tokens', username: desiredUsername, password: newPassword })) + .body as { operation_token?: string; refresh_token?: string }; + 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) { + try { + await seal({ operation: 'drop_user', username: defaultClusterUsername }); + } catch (err) { + // An earlier attempt dropped it and never told central manager. + if (!isSealedRefusal(err, 404, `User ${defaultClusterUsername} does not exist`)) { + throw err; + } + } + } + await resetPasswordUpdater(clusterId); + + // Setup is done; this only connects the browser as the admin, directly or not at all: through the proxy the session + // would be the proxy's own principal, not the admin's. A failed connect leaves the cluster signed out. + const user = await authStore.establishFabricConnectAuth({ + id: clusterId, + operationsUrl, + tokens: { operationToken: minted.operation_token, refreshToken: minted.refresh_token }, + }).catch((error: unknown) => { + console.debug('Could not connect after setup', error instanceof Error ? error.message : error); + return null; + }); + if (user?.username !== desiredUsername || user.role?.permission?.super_user !== true || !user.active) { + authStore.signOutLocally(clusterId); + return { message: 'Login successful', user: null }; + } + return { message: 'Login successful', user }; +} + function isLoginRefused(error: unknown): boolean { return isAxiosError(error) && error.response?.status === 401 && operationOf(error.config?.data) === 'login'; } @@ -274,7 +391,8 @@ async function finishInterruptedSetup({ } export function useInstanceResetPasswordMutation() { + const queryClient = useQueryClient(); return useMutation({ - mutationFn: onInstanceResetPassword, + mutationFn: (params) => onInstanceResetPassword(queryClient, params), }); } diff --git a/src/integrations/api/instance/sealedOperation.test.ts b/src/integrations/api/instance/sealedOperation.test.ts new file mode 100644 index 000000000..e0d4fe7e0 --- /dev/null +++ b/src/integrations/api/instance/sealedOperation.test.ts @@ -0,0 +1,195 @@ +// @vitest-environment node +// A fake 5.4 node built from Harper's own reference client (copied unchanged under src/lib/crypto/__tests__): it opens +// what the helper seals and seals what the helper opens, and refuses the way `components/encryptedOperation.ts` does. +import { sealResponse } from '@/lib/crypto/__tests__/harper-v5.4.0/sealedOperation.ts'; +import { fingerprintOf } from '@/lib/crypto/__tests__/harper-v5.4.0/secretEnvelope.ts'; +import { decryptEnvelope, parseEnvelopeFields } from '@/lib/crypto/__tests__/harper-v5.4.0/secretEnvelope.ts'; +import { ENV_ENCRYPTED_PREFIX } from '@/lib/crypto/envSecret'; +import { AxiosError, AxiosHeaders, type AxiosInstance } from 'axios'; +import { generateKeyPairSync } from 'node:crypto'; +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; +import { + _resetClockOffsetForTests, + isSealedRefusal, + runSealedOperation, + SealedOperationError, +} from './sealedOperation'; + +function keyPair() { + const { publicKey, privateKey } = generateKeyPairSync('rsa', { + modulusLength: 2048, + publicKeyEncoding: { type: 'spki', format: 'pem' }, + privateKeyEncoding: { type: 'pkcs8', format: 'pem' }, + }); + const publicKeyPem = publicKey as unknown as string; + return { + publicKey: publicKeyPem, + privateKey: privateKey as unknown as string, + fingerprint: fingerprintOf(publicKeyPem), + }; +} + +const custody = keyPair(); +const otherKey = keyPair(); +const MAX_AGE_MS = 300_000; + +function refusal(status: number, data: Record) { + const config = { headers: new AxiosHeaders() }; + return new AxiosError(`Request failed with status code ${status}`, AxiosError.ERR_BAD_REQUEST, config, undefined, { + status, + statusText: '', + data, + headers: {}, + config, + }); +} + +/** The node: its clock may be skewed from the browser's, and it answers each sealed operation through `execute`. */ +const node = { + clockSkewMs: 0, + custody: false, + execute: (op: { operation: string }): { status: number; body: unknown; executed?: true } => ({ + status: 200, + body: { message: `${op.operation} ran` }, + }), + requests: [] as unknown[], + answer(body: { operation?: unknown; envelope?: unknown }) { + this.requests.push(body); + if (body.operation !== 'encrypted_operation' || typeof body.envelope !== 'string') { + throw refusal(400, { error: 'The request is malformed' }); + } + if (!this.custody) { + throw refusal(503, { error: 'secrets custody is not initialized on this node' }); + } + const envelopeBody = body.envelope.slice(ENV_ENCRYPTED_PREFIX.length); + if (parseEnvelopeFields(envelopeBody).kid !== custody.fingerprint) { + throw refusal(409, { + error: "The envelope's kid does not match this node's secrets key", + custody_fingerprint: custody.fingerprint, + }); + } + const header = JSON.parse(decryptEnvelope(envelopeBody, custody.privateKey, custody.fingerprint)); + const now = Date.now() + this.clockSkewMs; + if (Math.abs(now - header.ts) > MAX_AGE_MS) { + throw refusal(400, { error: 'The sealed request is outside the accepted time window', server_time: now }); + } + const result = this.execute(header.op); + return { encrypted_response: sealResponse(JSON.stringify(result), Buffer.from(header.rk, 'base64'), header.nonce) }; + }, +}; + +const instanceClient = { + post: vi.fn(async (_url: string, body: { operation?: unknown; envelope?: unknown }) => ({ data: node.answer(body) })), +} as unknown as AxiosInstance; + +const op = { operation: 'add_user', username: 'owner@example.com', password: 'secret-password', role: 'super_user' }; +const key = { publicKey: custody.publicKey, fingerprint: custody.fingerprint }; + +beforeEach(() => { + node.clockSkewMs = 0; + node.custody = true; + node.execute = (inner) => ({ status: 200, body: { message: `${inner.operation} ran` } }); + node.requests = []; + _resetClockOffsetForTests(); +}); + +afterEach(() => { + vi.clearAllMocks(); +}); + +describe(runSealedOperation, () => { + it("sends only the sealed envelope and opens the node's answer", async () => { + const result = await runSealedOperation({ instanceClient, op, key }); + + expect(result).toEqual({ status: 200, body: { message: 'add_user ran' } }); + expect(instanceClient.post).toHaveBeenCalledWith('/', { + operation: 'encrypted_operation', + envelope: expect.any(String), + }); + expect(JSON.stringify(node.requests)).not.toContain('secret-password'); + }); + + it("throws the operation's own failure, with its status and body", async () => { + node.execute = () => ({ status: 409, body: { error: 'User owner@example.com already exists' } }); + + const failure = await runSealedOperation({ instanceClient, op, key }).then(() => undefined, (e: unknown) => e); + + expect(failure).toBeInstanceOf(SealedOperationError); + expect(failure).toMatchObject({ + operation: 'add_user', + status: 409, + message: 'User owner@example.com already exists', + }); + expect(isSealedRefusal(failure, 409, 'User owner@example.com already exists')).toBe(true); + expect(isSealedRefusal(failure, 404, 'User owner@example.com already exists')).toBe(false); + }); + + it('keeps a failure that ran but could not answer, so the caller does not resend it', async () => { + node.execute = () => ({ status: 500, body: { error: 'The sealed operation failed' }, executed: true }); + + await expect(runSealedOperation({ instanceClient, op, key })).rejects.toMatchObject({ + status: 500, + executed: true, + }); + }); + + it("retries once with the node's clock when the browser's is outside its window, and remembers the offset", async () => { + node.clockSkewMs = 10 * 60_000; + + await runSealedOperation({ instanceClient, op, key }); + expect(node.requests).toHaveLength(2); + + await runSealedOperation({ instanceClient, op, key }); + expect(node.requests).toHaveLength(3); + }); + + it('does not retry a second time on a clock refusal', async () => { + node.clockSkewMs = 10 * 60_000; + const skewedNode = node.answer.bind(node); + node.answer = (body) => { + node.clockSkewMs += 10 * 60_000; + return skewedNode(body); + }; + + await expect(runSealedOperation({ instanceClient, op, key })).rejects.toMatchObject({ response: { status: 400 } }); + expect(node.requests).toHaveLength(2); + node.answer = skewedNode; + }); + + it('fetches the key again, once, when the envelope was sealed to another key', async () => { + const stale = { publicKey: otherKey.publicKey, fingerprint: otherKey.fingerprint }; + const refreshKey = vi.fn(async () => key); + + const result = await runSealedOperation({ instanceClient, op, key: stale, refreshKey }); + + expect(result.status).toBe(200); + expect(refreshKey).toHaveBeenCalledTimes(1); + expect(node.requests).toHaveLength(2); + }); + + it('throws the key refusal when there is no way to fetch the key, or the fetched key is refused too', async () => { + const stale = { publicKey: otherKey.publicKey, fingerprint: otherKey.fingerprint }; + + await expect(runSealedOperation({ instanceClient, op, key: stale })).rejects.toMatchObject({ + response: { status: 409, data: { custody_fingerprint: custody.fingerprint } }, + }); + await expect(runSealedOperation({ instanceClient, op, key: stale, refreshKey: async () => stale })).rejects + .toMatchObject({ response: { status: 409 } }); + expect(node.requests).toHaveLength(3); + }); + + it('throws a node without custody as it answered', async () => { + node.custody = false; + + await expect(runSealedOperation({ instanceClient, op, key })).rejects.toMatchObject({ response: { status: 503 } }); + expect(node.requests).toHaveLength(1); + }); + + it('refuses an answer that is not sealed', async () => { + vi.mocked(instanceClient.post).mockResolvedValueOnce({ data: { message: 'add_user ran' } }); + + await expect(runSealedOperation({ instanceClient, op, key })).rejects.toThrow( + 'did not answer add_user with a sealed response', + ); + }); +}); diff --git a/src/integrations/api/instance/sealedOperation.ts b/src/integrations/api/instance/sealedOperation.ts new file mode 100644 index 000000000..7a82fa1c0 --- /dev/null +++ b/src/integrations/api/instance/sealedOperation.ts @@ -0,0 +1,92 @@ +import { InstanceClientConfig } from '@/config/instanceClientConfig'; +import { SecretsPublicKey } from '@/integrations/api/instance/secrets/secrets'; +import { openSealedResponse, SealableOperation, SealedResult, sealOperation } from '@/lib/crypto/sealedOperation'; +import { isAxiosError } from 'axios'; + +/** The sealed operation ran and answered a failure; `status` and `body` are the operation's own. */ +export class SealedOperationError extends Error { + operation: string; + status: number; + body: unknown; + executed?: true; + + constructor(operation: string, { status, body, executed }: SealedResult) { + const detail = (body as { error?: unknown } | null | undefined)?.error; + super(typeof detail === 'string' ? detail : `${operation} failed with status ${status}`); + this.name = 'SealedOperationError'; + this.operation = operation; + this.status = status; + this.body = body; + this.executed = executed; + } +} + +export function isSealedRefusal(error: unknown, status: number, message: string): boolean { + return error instanceof SealedOperationError && error.status === status && error.message === message; +} + +export interface RunSealedOperationParams extends InstanceClientConfig { + op: SealableOperation; + key: SecretsPublicKey; + /** Fetches the key again when the node reports another fingerprint; asked once per call. */ + refreshKey?: () => Promise; + actor?: string; +} + +// The node accepts a timestamp only within its window around its own clock. A refusal names that clock, and the +// difference serves every later request, so a skewed browser pays the round trip once. +let clockOffsetMs = 0; + +export function _resetClockOffsetForTests(): void { + clockOffsetMs = 0; +} + +/** + * Sends `op` sealed as `encrypted_operation` through `instanceClient` and opens the answer. A plaintext refusal is + * retried once when it is one the client can repair: a timestamp outside the node's window (400 with `server_time`) + * or an envelope sealed to another key (409 with `custody_fingerprint`). Everything else is thrown as the request's + * own failure, and a sealed answer with a failing status as a `SealedOperationError`. + */ +export async function runSealedOperation( + { instanceClient, op, key, refreshKey, actor }: RunSealedOperationParams, +): Promise { + let currentKey = key; + let clockRetried = false; + let keyRetried = false; + for (;;) { + const { request, responseKey, nonce } = await sealOperation({ + op, + publicKey: currentKey.publicKey, + kid: currentKey.fingerprint, + actor, + now: Date.now() + clockOffsetMs, + }); + let data: unknown; + try { + ({ data } = await instanceClient.post('/', request)); + } catch (error) { + const refusal = isAxiosError(error) ? error.response : undefined; + const detail = refusal?.data as { server_time?: unknown; custody_fingerprint?: unknown } | undefined; + if (refusal?.status === 400 && typeof detail?.server_time === 'number' && !clockRetried) { + clockOffsetMs = detail.server_time - Date.now(); + clockRetried = true; + continue; + } + if (refusal?.status === 409 && typeof detail?.custody_fingerprint === 'string' && refreshKey && !keyRetried) { + currentKey = await refreshKey(); + keyRetried = true; + continue; + } + throw error; + } + const payload = (data as { encrypted_response?: unknown } | null | undefined)?.encrypted_response; + if (!payload) { + throw new Error(`The cluster did not answer ${op.operation} with a sealed response.`); + } + const result = await openSealedResponse(payload, responseKey, nonce); + if (result.status >= 400) { + throw new SealedOperationError(op.operation, result); + } + return result; + } +} diff --git a/src/lib/crypto/__tests__/harper-v5.4.0/sealedOperation.ts b/src/lib/crypto/__tests__/harper-v5.4.0/sealedOperation.ts new file mode 100644 index 000000000..9236fa164 --- /dev/null +++ b/src/lib/crypto/__tests__/harper-v5.4.0/sealedOperation.ts @@ -0,0 +1,184 @@ +/** + * Pure cryptography for `encrypted_operation`. Its only Harper import is `secretEnvelope.ts`, itself + * dependency-free, so it is unit-testable alone and is the reference client. + * + * Request: `{ operation: 'encrypted_operation', envelope: 'enc:v1:…', mode?, op? }`. The envelope is + * an ordinary `enc:v1` envelope sealed to the node's custody public key; its plaintext is the sealed + * header `{ v, rk, nonce, ts, actor?, op? | oph? }`. In `sealed` mode the inner operation rides in the + * header. In `fields` mode the outer body carries the operation as JSON text in `op`, the header + * carries `oph`, the SHA-256 of that text, and any value may be a sealed leaf `{ "$sealed": … }`. + * + * Everything the node returns after admission is AES-256-GCM under the client-chosen `rk`, so only + * the client and the node can read it. + */ +import { createCipheriv, createDecipheriv, createHash, randomBytes } from 'node:crypto'; +import { BASE64_REGEX, encryptEnvelope } from './secretEnvelope.ts'; + +export const SEALED_OPERATION_VERSION = 1; +export const SEALED_LEAF_KEY = '$sealed'; +export const RESPONSE_KEY_BYTES = 32; +export const NONCE_BYTES = 16; +export const OPERATION_HASH_BYTES = 32; +const IV_BYTES = 12; +const TAG_BYTES = 16; +const RESPONSE_AAD_PREFIX = 'harper.encrypted_operation.response:'; +const FIELD_AAD_PREFIX = 'harper.encrypted_operation.field:'; +const ENVELOPE_PREFIX = 'enc:v1:'; +const DEFAULT_VISIBLE_FIELDS = ['database', 'schema', 'table']; + +export type SealedMode = 'sealed' | 'fields'; + +export interface SealedPayload { + v: number; + iv: string; + ct: string; + tag: string; +} + +export interface SealedResult { + status: number; + body: unknown; + executed?: true; +} + +/** Strict base64 to bytes, or undefined when the text is not base64 or not `byteLength` long. */ +export function decodeBase64(value: unknown, byteLength?: number): Buffer | undefined { + if (typeof value !== 'string' || !BASE64_REGEX.test(value)) return undefined; + const bytes = Buffer.from(value, 'base64'); + return byteLength === undefined || bytes.length === byteLength ? bytes : undefined; +} + +function responseAad(nonce: string): Buffer { + return Buffer.from(RESPONSE_AAD_PREFIX + nonce, 'utf8'); +} + +function fieldAad(nonce: string, pointer: string): Buffer { + return Buffer.from(`${FIELD_AAD_PREFIX}${nonce}:${pointer}`, 'utf8'); +} + +/** RFC 6901 reference token for one key. */ +export function pointerToken(key: string | number): string { + return String(key).replaceAll('~', '~0').replaceAll('/', '~1'); +} + +export function hashOperationText(text: string): string { + return createHash('sha256').update(text, 'utf8').digest('base64'); +} + +function aesGcmSeal(plaintext: Buffer, key: Buffer, aad: Buffer) { + const iv = randomBytes(IV_BYTES); + const cipher = createCipheriv('aes-256-gcm', key, iv); + cipher.setAAD(aad); + // GCM is a stream mode: final() emits no bytes, so update() already holds the whole ciphertext. + const ct = cipher.update(plaintext); + cipher.final(); + return { iv, ct, tag: cipher.getAuthTag() }; +} + +function aesGcmOpen(iv: Buffer, ct: Buffer, tag: Buffer, key: Buffer, aad: Buffer): Buffer { + const decipher = createDecipheriv('aes-256-gcm', key, iv, { authTagLength: TAG_BYTES }); + decipher.setAAD(aad); + decipher.setAuthTag(tag); + return Buffer.concat([decipher.update(ct), decipher.final()]); +} + +/** Seal the node's answer: `result` is the UTF-8 JSON of a {@link SealedResult}. */ +export function sealResponse(result: string | Buffer, responseKey: Buffer, nonce: string): SealedPayload { + const plaintext = typeof result === 'string' ? Buffer.from(result, 'utf8') : result; + const { iv, ct, tag } = aesGcmSeal(plaintext, responseKey, responseAad(nonce)); + return { + v: SEALED_OPERATION_VERSION, + iv: iv.toString('base64'), + ct: ct.toString('base64'), + tag: tag.toString('base64'), + }; +} + +/** + * Open the node's answer. The decrypted `status` is authoritative; the plaintext `status` a fields-mode + * reply also carries is for relays and is not authenticated. `executed: true` means the operation ran + * but its result could not be delivered: do not resend a non-idempotent operation. + */ +export function openResponse(sealed: SealedPayload, responseKey: Buffer, nonce: string): SealedResult { + const iv = decodeBase64(sealed?.iv, IV_BYTES); + const ct = decodeBase64(sealed?.ct); + const tag = decodeBase64(sealed?.tag, TAG_BYTES); + if (sealed?.v !== SEALED_OPERATION_VERSION || !iv || !ct || !tag) throw new Error('malformed sealed response'); + const result = JSON.parse(aesGcmOpen(iv, ct, tag, responseKey, responseAad(nonce)).toString('utf8')); + if (!result || typeof result !== 'object' || !Number.isInteger(result.status)) { + throw new Error('malformed sealed response'); + } + return result; +} + +/** Seal one value of a fields-mode operation; `pointer` is its RFC 6901 location within `op`. */ +export function sealValue(value: unknown, responseKey: Buffer, nonce: string, pointer: string) { + const json = JSON.stringify(value); + if (json === undefined) throw new TypeError(`value at '${pointer}' has no JSON representation`); + const { iv, ct, tag } = aesGcmSeal(Buffer.from(json, 'utf8'), responseKey, fieldAad(nonce, pointer)); + return { [SEALED_LEAF_KEY]: Buffer.concat([iv, ct, tag]).toString('base64') }; +} + +/** Open one sealed leaf; throws when it was tampered with or moved to another location. */ +export function openValue(sealed: string, responseKey: Buffer, nonce: string, pointer: string): unknown { + const bytes = decodeBase64(sealed); + if (!bytes || bytes.length < IV_BYTES + TAG_BYTES) throw new Error('malformed sealed value'); + const iv = bytes.subarray(0, IV_BYTES); + const ct = bytes.subarray(IV_BYTES, bytes.length - TAG_BYTES); + const tag = bytes.subarray(bytes.length - TAG_BYTES); + return JSON.parse(aesGcmOpen(iv, ct, tag, responseKey, fieldAad(nonce, pointer)).toString('utf8')); +} + +export interface SealOperationOptions { + op: Record & { operation: string }; + publicKey: string; + kid: string; + mode?: SealedMode; + /** fields mode: top-level keys left visible besides `operation` (default: database, schema, table). */ + visibleFields?: readonly string[]; + actor?: string; + now?: number; +} + +/** + * Reference client: seal `op` for `encrypted_operation`. Returns the request body plus the response + * key and nonce needed to {@link openResponse} the reply. In fields mode every top-level value outside + * `visibleFields` becomes one sealed leaf. + */ +export function sealOperation({ + op, + publicKey, + kid, + mode = 'sealed', + visibleFields = DEFAULT_VISIBLE_FIELDS, + actor, + now = Date.now(), +}: SealOperationOptions) { + const responseKey = randomBytes(RESPONSE_KEY_BYTES); + const nonce = randomBytes(NONCE_BYTES).toString('base64'); + const header: Record = { + v: SEALED_OPERATION_VERSION, + rk: responseKey.toString('base64'), + nonce, + ts: now, + }; + if (actor !== undefined) header.actor = actor; + const request: Record = { operation: 'encrypted_operation' }; + if (mode === 'fields') { + const visible: Record = {}; + for (const [key, value] of Object.entries(op)) { + visible[key] = + key === 'operation' || visibleFields.includes(key) + ? value + : sealValue(value, responseKey, nonce, '/' + pointerToken(key)); + } + const opText = JSON.stringify(visible); + header.oph = hashOperationText(opText); + request.mode = 'fields'; + request.op = opText; + } else { + header.op = op; + } + request.envelope = ENVELOPE_PREFIX + encryptEnvelope(JSON.stringify(header), publicKey, kid); + return { request, responseKey, nonce }; +} diff --git a/src/lib/crypto/__tests__/harper-v5.4.0/secretEnvelope.ts b/src/lib/crypto/__tests__/harper-v5.4.0/secretEnvelope.ts new file mode 100644 index 000000000..6253e3929 --- /dev/null +++ b/src/lib/crypto/__tests__/harper-v5.4.0/secretEnvelope.ts @@ -0,0 +1,113 @@ +/** + * Pure secret-envelope cryptography — intentionally free of Harper imports so it is unit-testable + * on its own and safe to publish. Hybrid scheme (see docs/env-secret-encryption.md): AES-256-GCM + * encrypts the value, RSA-OAEP(SHA-256) wraps the AES key. Functions operate on the base64url + * envelope BODY (the bytes after the `enc:v1:` marker); marker handling lives with the callers + * (utility/envFile.ts exports the `ENV_ENCRYPTED_PREFIX` marker). + * + * Ported from harper-pro security/envSecretCrypto.ts (Dawson Toth) so core and pro share one wire + * format for `.env` secrets and the hdb_secret store. + */ +import { + publicEncrypt, + privateDecrypt, + createCipheriv, + createDecipheriv, + createPublicKey, + createHash, + randomBytes, + constants, +} from 'node:crypto'; + +export interface EnvelopeFields { + kid?: string; + k: string; + iv: string; + ct: string; + tag: string; +} + +/** SHA-256 (hex) of the DER SPKI public key — a stable key id used as the envelope `kid`. */ +export function fingerprintOf(publicKeyPem: string): string { + const der = createPublicKey(publicKeyPem).export({ type: 'spki', format: 'der' }); + return createHash('sha256').update(der).digest('hex'); +} + +// Base64 with OPTIONAL padding (the field encoding inside the envelope JSON). Buffer.from(s, +// 'base64') silently ignores invalid characters, so decodability has to be checked by pattern — +// but it decodes unpadded input fine, and browser/WebCrypto clients commonly emit unpadded +// base64, so padding is accepted rather than required. Charset stays strict; a trailing group of +// one character (never valid base64) is still rejected. +export const BASE64_REGEX = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}(?:==)?|[A-Za-z0-9+/]{3}=?)?$/; + +/** + * Parse and shape-validate a base64url envelope body without decrypting it. Throws on a + * malformed/incomplete envelope: non-JSON, wrong type, missing/non-base64 `k`/`iv`/`ct`/`tag` + * (`ct` may be empty — the empty plaintext), or a non-string `kid`. This is how the server derives + * `kid` from a submitted envelope (the `kid` inside the sealed body is the only one trusted — + * never a separate client field) and structurally vets envelopes on ingest without ever + * decrypting them server-side. + */ +export function parseEnvelopeFields(body: string): EnvelopeFields { + let env: EnvelopeFields; + try { + env = JSON.parse(Buffer.from(body, 'base64url').toString('utf8')); + } catch { + throw new Error('malformed secret envelope'); + } + if (!env || typeof env !== 'object' || Array.isArray(env) || (env.kid !== undefined && typeof env.kid !== 'string')) { + throw new Error('malformed secret envelope'); + } + for (const field of ['k', 'iv', 'ct', 'tag'] as const) { + const fieldValue = env[field]; + if ( + typeof fieldValue !== 'string' || + (fieldValue.length === 0 && field !== 'ct') || + !BASE64_REGEX.test(fieldValue) + ) { + throw new Error('malformed secret envelope'); + } + } + return env; +} + +/** + * Reference client-side encryption: returns the base64url envelope body for `enc:v1:`. The + * server only encrypts on ingest (set_secret with a plaintext `value`); this is the single source + * of truth for the wire format and what the tests and the documented client example exercise. + */ +export function encryptEnvelope(plaintext: string, publicKeyPem: string, kid: string): string { + const aesKey = randomBytes(32); + const iv = randomBytes(12); + const cipher = createCipheriv('aes-256-gcm', aesKey, iv); + const ct = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]); + const tag = cipher.getAuthTag(); + const k = publicEncrypt({ key: publicKeyPem, padding: constants.RSA_PKCS1_OAEP_PADDING, oaepHash: 'sha256' }, aesKey); + const envelope: EnvelopeFields = { + kid, + k: k.toString('base64'), + iv: iv.toString('base64'), + ct: ct.toString('base64'), + tag: tag.toString('base64'), + }; + return Buffer.from(JSON.stringify(envelope)).toString('base64url'); +} + +/** + * Decrypt a base64url envelope body. These are the security guarantees of the feature and throw on: + * a malformed/incomplete envelope, a `kid` that doesn't match this node's key, or a failed GCM + * authentication tag (any tampering with `ct`/`tag` makes `decipher.final()` throw). + */ +export function decryptEnvelope(body: string, privateKeyPem: string, keyFingerprint: string): string { + const env = parseEnvelopeFields(body); + if (env.kid && env.kid !== keyFingerprint) { + throw new Error(`no secrets key for kid ${env.kid}`); + } + const aesKey = privateDecrypt( + { key: privateKeyPem, padding: constants.RSA_PKCS1_OAEP_PADDING, oaepHash: 'sha256' }, + Buffer.from(env.k, 'base64') + ); + const decipher = createDecipheriv('aes-256-gcm', aesKey, Buffer.from(env.iv, 'base64')); + decipher.setAuthTag(Buffer.from(env.tag, 'base64')); + return Buffer.concat([decipher.update(Buffer.from(env.ct, 'base64')), decipher.final()]).toString('utf8'); +} diff --git a/src/lib/crypto/envSecret.ts b/src/lib/crypto/envSecret.ts index 77b4ca0ef..cf1e47916 100644 --- a/src/lib/crypto/envSecret.ts +++ b/src/lib/crypto/envSecret.ts @@ -19,12 +19,23 @@ function pemToDer(pem: string): Uint8Array { return bytes; } -function toBase64(bytes: Uint8Array): string { +export function toBase64(bytes: Uint8Array): string { let s = ''; for (let i = 0; i < bytes.length; i++) { s += String.fromCharCode(bytes[i]); } return btoa(s); } +/** Standard base64 to bytes; undefined for text that is not base64, or not `byteLength` long. */ +export function fromBase64(value: unknown, byteLength?: number): Uint8Array | undefined { + if (typeof value !== 'string' || !/^[A-Za-z0-9+/]*={0,2}$/.test(value) || value.length % 4 !== 0) { + return undefined; + } + const bin = atob(value); + const bytes = new Uint8Array(bin.length); + for (let i = 0; i < bin.length; i++) { bytes[i] = bin.charCodeAt(i); } + return byteLength === undefined || bytes.length === byteLength ? bytes : undefined; +} + function toBase64Url(bytes: Uint8Array): string { return toBase64(bytes).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, ''); } @@ -37,7 +48,7 @@ function toHex(buffer: ArrayBuffer): string { // Web Crypto's BufferSource typing (TS 5.7+) rejects Uint8Array; hand it a plain // ArrayBuffer copy of the bytes. -function ab(bytes: Uint8Array): ArrayBuffer { +export function ab(bytes: Uint8Array): ArrayBuffer { // Avoid a copy when the view already spans its whole buffer (the common case here). if (bytes.byteOffset === 0 && bytes.byteLength === bytes.buffer.byteLength) { return bytes.buffer as ArrayBuffer; @@ -47,7 +58,7 @@ function ab(bytes: Uint8Array): ArrayBuffer { // Web Crypto's SubtleCrypto is only available in secure contexts (HTTPS or localhost). Fail with a // clear message rather than a cryptic `undefined` access when the app is served over plain HTTP. -function requireSubtle(): SubtleCrypto { +export function requireSubtle(): SubtleCrypto { if (typeof crypto === 'undefined' || !crypto.subtle) { throw new Error('Secret encryption requires a secure context (HTTPS or localhost).'); } diff --git a/src/lib/crypto/sealedOperation.test.ts b/src/lib/crypto/sealedOperation.test.ts new file mode 100644 index 000000000..26ccee2cd --- /dev/null +++ b/src/lib/crypto/sealedOperation.test.ts @@ -0,0 +1,139 @@ +// @vitest-environment node +// Node env: Web Crypto (globalThis.crypto.subtle, used by the helper) and node:crypto (used by Harper's reference) are +// both available. The reference under __tests__/harper-v5.4.0/ is the node's own client, copied unchanged from +// HarperFast/harper at v5.4.0, so what this opens is what the node accepts and what it answers. +import { generateKeyPairSync } from 'node:crypto'; +import { describe, expect, it } from 'vitest'; +import { + NONCE_BYTES, + openResponse, + RESPONSE_KEY_BYTES, + sealOperation as referenceSealOperation, + sealResponse, +} from './__tests__/harper-v5.4.0/sealedOperation.ts'; +import { decryptEnvelope, fingerprintOf, parseEnvelopeFields } from './__tests__/harper-v5.4.0/secretEnvelope.ts'; +import { ENV_ENCRYPTED_PREFIX } from './envSecret'; +import { openSealedResponse, SEALED_OPERATION_VERSION, sealOperation } from './sealedOperation'; + +const { publicKey, privateKey } = generateKeyPairSync('rsa', { + modulusLength: 2048, + publicKeyEncoding: { type: 'spki', format: 'pem' }, + privateKeyEncoding: { type: 'pkcs8', format: 'pem' }, +}); +const publicKeyPem = publicKey as unknown as string; +const privateKeyPem = privateKey as unknown as string; +const kid = fingerprintOf(publicKeyPem); + +const op = { + operation: 'add_user', + username: 'owner@example.com', + password: 'p@ss "word"', + role: 'super_user', + active: true, +}; + +/** Opens a request the way the node does (`components/encryptedOperation.ts`'s `openHeader`). */ +function openHeader(envelope: string) { + expect(envelope.startsWith(ENV_ENCRYPTED_PREFIX)).toBe(true); + const body = envelope.slice(ENV_ENCRYPTED_PREFIX.length); + expect(parseEnvelopeFields(body).kid).toBe(kid); + return JSON.parse(decryptEnvelope(body, privateKeyPem, kid)) as Record; +} + +describe('sealOperation', () => { + it('seals a header the node opens, with a fresh response key and nonce of the right sizes', async () => { + const now = 1_763_300_000_000; + const { request, responseKey, nonce } = await sealOperation({ op, publicKey: publicKeyPem, kid, now }); + + expect(Object.keys(request)).toEqual(['operation', 'envelope']); + expect(request.operation).toBe('encrypted_operation'); + const header = openHeader(request.envelope); + expect(header).toEqual({ + v: SEALED_OPERATION_VERSION, + rk: Buffer.from(responseKey).toString('base64'), + nonce, + ts: now, + op, + }); + expect(responseKey).toHaveLength(RESPONSE_KEY_BYTES); + expect(Buffer.from(nonce, 'base64')).toHaveLength(NONCE_BYTES); + expect(request.envelope).not.toContain(op.password); + }); + + it('carries the actor only when given', async () => { + const { request } = await sealOperation({ op, publicKey: publicKeyPem, kid, actor: 'studio' }); + expect(openHeader(request.envelope).actor).toBe('studio'); + }); + + it('never repeats a response key or nonce', async () => { + const seen = await Promise.all( + Array.from({ length: 5 }, () => sealOperation({ op, publicKey: publicKeyPem, kid })), + ); + expect(new Set(seen.map(({ nonce }) => nonce)).size).toBe(5); + expect(new Set(seen.map(({ responseKey }) => Buffer.from(responseKey).toString('base64'))).size).toBe(5); + }); + + it('writes the same header the reference client writes', async () => { + const now = Date.now(); + const ours = openHeader((await sealOperation({ op, publicKey: publicKeyPem, kid, now })).request.envelope); + const theirs = openHeader( + referenceSealOperation({ op, publicKey: publicKeyPem, kid, now }).request.envelope as string, + ); + expect(Object.keys(ours).sort()).toEqual(Object.keys(theirs).sort()); + expect(ours.op).toEqual(theirs.op); + }); +}); + +describe('openSealedResponse', () => { + async function sealedByTheNode(result: object) { + const { responseKey, nonce } = await sealOperation({ op, publicKey: publicKeyPem, kid }); + return { payload: sealResponse(JSON.stringify(result), Buffer.from(responseKey), nonce), responseKey, nonce }; + } + + it("opens the node's answer to this request", async () => { + const result = { status: 200, body: { message: 'owner@example.com successfully added' } }; + const { payload, responseKey, nonce } = await sealedByTheNode(result); + + expect(await openSealedResponse(payload, responseKey, nonce)).toEqual(result); + // and reads it the same way the reference does + expect(openResponse(payload, Buffer.from(responseKey), nonce)).toEqual(result); + }); + + it('keeps a failing status and the executed flag', async () => { + const result = { status: 500, body: { error: 'The sealed operation failed' }, executed: true }; + const { payload, responseKey, nonce } = await sealedByTheNode(result); + + expect(await openSealedResponse(payload, responseKey, nonce)).toEqual(result); + }); + + it.each([ + ['a tampered ciphertext', (p: { ct: string }) => ({ ...p, ct: flipFirstByte(p.ct) })], + ['a tampered tag', (p: { tag: string }) => ({ ...p, tag: flipFirstByte(p.tag) })], + ['another version', (p: object) => ({ ...p, v: 2 })], + ['a missing field', (p: { tag: string }) => ({ ...p, tag: undefined })], + ])('refuses %s', async (_, tamper) => { + const { payload, responseKey, nonce } = await sealedByTheNode({ status: 200, body: {} }); + + await expect(openSealedResponse(tamper(payload), responseKey, nonce)).rejects.toThrow(); + }); + + it("refuses another request's nonce and another request's key", async () => { + const { payload, responseKey, nonce } = await sealedByTheNode({ status: 200, body: {} }); + const other = await sealOperation({ op, publicKey: publicKeyPem, kid }); + + await expect(openSealedResponse(payload, responseKey, other.nonce)).rejects.toThrow('did not authenticate'); + await expect(openSealedResponse(payload, other.responseKey, nonce)).rejects.toThrow('did not authenticate'); + }); + + it('refuses an answer that is not a status and body', async () => { + const { payload, responseKey, nonce } = await sealedByTheNode({ body: 'no status' }); + + await expect(openSealedResponse(payload, responseKey, nonce)).rejects.toThrow('malformed'); + }); +}); + +function flipFirstByte(base64: string): string { + const bytes = Buffer.from(base64, 'base64'); + bytes[0] ^= 0xff; + return bytes.toString('base64'); +} diff --git a/src/lib/crypto/sealedOperation.ts b/src/lib/crypto/sealedOperation.ts new file mode 100644 index 000000000..8ef73935d --- /dev/null +++ b/src/lib/crypto/sealedOperation.ts @@ -0,0 +1,115 @@ +/** + * The client side of Harper's `encrypted_operation` (5.4.0+), in Web Crypto. The operation rides inside an + * `enc:v1:` envelope sealed to the node's secrets key, and the node's answer comes back AES-256-GCM under a key only + * this client chose, so a relay sees ciphertext both ways. The wire format is harper's `utility/sealedOperation.ts`; + * `__tests__/harper-v5.4.0/` keeps that reference unchanged, and the tests open with it what this seals. + * + * Sealed mode only: the whole operation is inside the envelope. Fields mode, which leaves chosen keys visible to a + * relay, is not needed by any caller yet. + */ +import { ab, encryptEnvelope, fromBase64, requireSubtle, toBase64 } from './envSecret'; + +export const SEALED_OPERATION_VERSION = 1; +const RESPONSE_KEY_BYTES = 32; +const NONCE_BYTES = 16; +const IV_BYTES = 12; +const TAG_BYTES = 16; +const RESPONSE_AAD_PREFIX = 'harper.encrypted_operation.response:'; + +export type SealableOperation = Record & { operation: string }; + +export interface SealedOperationRequest { + operation: 'encrypted_operation'; + envelope: string; +} + +export interface SealedOperation { + request: SealedOperationRequest; + /** The key the node seals its answer with; needed once, to open that answer. */ + responseKey: Uint8Array; + nonce: string; +} + +/** What the node answered inside the sealed response: the operation's own status and body. */ +export interface SealedResult { + status: number; + body: unknown; + /** The operation ran but its result could not be returned; do not resend one that is not idempotent. */ + executed?: true; +} + +export interface SealOperationOptions { + op: SealableOperation; + publicKey: string; + /** The key's fingerprint, as the server reports it; the node refuses an envelope whose `kid` is not its own. */ + kid: string; + /** Attribution for the node's log. */ + actor?: string; + /** The client's clock in milliseconds; the node accepts it only within its window. */ + now?: number; +} + +export async function sealOperation( + { op, publicKey, kid, actor, now = Date.now() }: SealOperationOptions, +): Promise { + const responseKey = crypto.getRandomValues(new Uint8Array(RESPONSE_KEY_BYTES)); + const nonce = toBase64(crypto.getRandomValues(new Uint8Array(NONCE_BYTES))); + const header = { + v: SEALED_OPERATION_VERSION, + rk: toBase64(responseKey), + nonce, + ts: now, + ...(actor === undefined ? {} : { actor }), + op, + }; + const envelope = await encryptEnvelope(JSON.stringify(header), publicKey, kid); + return { request: { operation: 'encrypted_operation', envelope }, responseKey, nonce }; +} + +/** + * Opens the node's `encrypted_response` with the request's own key and nonce. Throws on a payload that is not the + * node's answer to this request: a wrong version or shape, a tampered or moved payload, or another request's nonce. + */ +export async function openSealedResponse( + payload: unknown, + responseKey: Uint8Array, + nonce: string, +): Promise { + const sealed = payload as { v?: unknown; iv?: unknown; ct?: unknown; tag?: unknown } | null | undefined; + const iv = fromBase64(sealed?.iv, IV_BYTES); + const ct = fromBase64(sealed?.ct); + const tag = fromBase64(sealed?.tag, TAG_BYTES); + if (sealed?.v !== SEALED_OPERATION_VERSION || !iv || !ct || !tag) { + throw new Error('The cluster answered with a malformed sealed response.'); + } + const subtle = requireSubtle(); + const key = await subtle.importKey('raw', ab(responseKey), { name: 'AES-GCM' }, false, ['decrypt']); + const sealedBytes = new Uint8Array(ct.length + tag.length); + sealedBytes.set(ct); + sealedBytes.set(tag, ct.length); + let plaintext: ArrayBuffer; + try { + plaintext = await subtle.decrypt( + { + name: 'AES-GCM', + iv: ab(iv), + additionalData: ab(new TextEncoder().encode(RESPONSE_AAD_PREFIX + nonce)), + tagLength: 128, + }, + key, + ab(sealedBytes), + ); + } catch { + throw new Error('The sealed response did not authenticate as the answer to this request.'); + } + let result: unknown; + try { + result = JSON.parse(new TextDecoder().decode(plaintext)); + } catch { + throw new Error('The cluster answered with a malformed sealed response.'); + } + if (!result || typeof result !== 'object' || !Number.isInteger((result as { status?: unknown }).status)) { + throw new Error('The cluster answered with a malformed sealed response.'); + } + return result as SealedResult; +} diff --git a/src/react-query/queryClient.test.ts b/src/react-query/queryClient.test.ts index ef84d1453..d0519b9d1 100644 --- a/src/react-query/queryClient.test.ts +++ b/src/react-query/queryClient.test.ts @@ -1,5 +1,6 @@ import { UnconfirmedWriteError } from '@/features/instance/extensions/dataSource'; import { ImportJobError, ImportJobUnconfirmedError } from '@/integrations/api/instance/database/getJob'; +import { SealedOperationError } from '@/integrations/api/instance/sealedOperation'; import { RESTART_UNCONFIRMED_MESSAGE, RESTART_UNCONFIRMED_TITLE, @@ -442,6 +443,26 @@ describe('a write that got no verdict', () => { }); }); + it('includes a sealed operation that ran but could not return its result', () => { + const executed = new SealedOperationError('drop_user', { + status: 500, + body: { error: 'serialization failed' }, + executed: true, + }); + expect(describeError(executed)).toMatchObject({ + title: OUTCOME_UNKNOWN_TITLE, + description: + 'The cluster ran drop_user but could not return its result. Check whether it took effect before you try again.', + }); + expect(shouldToastOwnFailure(executed)).toBe(false); + }); + + it("describes a sealed operation's own refusal by its text, as a plain failure", () => { + const refused = new SealedOperationError('add_user', { status: 409, body: { error: 'User x already exists' } }); + expect(describeError(refused)).toMatchObject({ description: 'User x already exists' }); + expect(shouldToastOwnFailure(refused)).toBe(true); + }); + it('leaves a read with the same failure to the usual extraction', () => { expect(describeError(gatewayTimeout(sent({ operation: 'get_job' })))).toEqual({ title: 'GATEWAY_TIMEOUT', diff --git a/src/react-query/queryClient.ts b/src/react-query/queryClient.ts index a8a858e9e..3dab9daa8 100644 --- a/src/react-query/queryClient.ts +++ b/src/react-query/queryClient.ts @@ -7,6 +7,7 @@ import { } from '@/integrations/api/cluster/clusterHeldByWorkflow'; import { BackupJobUnreportedError } from '@/integrations/api/instance/backups/backups'; import { describeImportJobUnconfirmed, ImportJobUnconfirmedError } from '@/integrations/api/instance/database/getJob'; +import { SealedOperationError } from '@/integrations/api/instance/sealedOperation'; import { RESTART_UNCONFIRMED_MESSAGE, RESTART_UNCONFIRMED_TITLE, @@ -48,6 +49,12 @@ function describeUnknownOutcome(rawErr: unknown): DescribedError | undefined { if (rawErr instanceof BackupJobUnreportedError) { return copy(OUTCOME_UNKNOWN_TITLE, rawErr.message); } + if (rawErr instanceof SealedOperationError && rawErr.executed) { + return copy( + OUTCOME_UNKNOWN_TITLE, + `The cluster ran ${rawErr.operation} but could not return its result. ${UNCONFIRMED_WRITE_ADVICE}`, + ); + } return undefined; } diff --git a/tsconfig.app.json b/tsconfig.app.json index 3b2292c96..cd05ded00 100644 --- a/tsconfig.app.json +++ b/tsconfig.app.json @@ -17,6 +17,7 @@ ], /* Bundler mode */ "moduleResolution": "bundler", + "allowImportingTsExtensions": true, "isolatedModules": true, "moduleDetection": "force", "noEmit": true, From 10446d06fd769e74cdb7e7fa8281efe21d17b5f6 Mon Sep 17 00:00:00 2001 From: Devin Holland <50112339+Devin-Holland@users.noreply.github.com> Date: Mon, 16 Nov 2026 14:48:04 -0500 Subject: [PATCH 2/7] fix(cluster): bind a token-backed connect to its own resolution, and 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 --- AGENTS.md | 6 +- src/features/auth/store/authStore.ts | 15 +++- .../store/establishFabricConnectAuth.test.ts | 80 +++++++++++++++++++ src/features/cluster/DESIGN.md | 13 +-- src/features/cluster/FinishSetup.test.tsx | 20 ++++- src/features/cluster/FinishSetup.tsx | 2 +- src/features/cluster/sealedSetup.ts | 5 +- .../useInstanceResetPasswordMutation.test.tsx | 12 +++ .../auth/useInstanceResetPasswordMutation.ts | 13 +-- .../api/instance/sealedOperation.test.ts | 52 ++++++++++-- .../api/instance/sealedOperation.ts | 34 +++++--- .../crypto/__tests__/harper-v5.4.0/README.md | 13 +++ src/lib/crypto/sealedOperation.ts | 16 ++-- src/react-query/queryClient.test.ts | 7 ++ 14 files changed, 241 insertions(+), 47 deletions(-) create mode 100644 src/lib/crypto/__tests__/harper-v5.4.0/README.md diff --git a/AGENTS.md b/AGENTS.md index fc6504023..514ab47ec 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -35,8 +35,10 @@ imports stay extensionless (`from './wafRuleForm'`, `from '@/lib/stableJson'`), in the repo already is. Harper's TypeStrip checklist asks for `.ts` on every import; studio is exempt (decided in #1994). Reviewers: don't raise a missing extension as a finding. -Adding one wouldn't compile anyway: neither `tsconfig.app.json` nor `tsconfig.node.json` sets -`allowImportingTsExtensions`, so a `.ts` specifier fails `tsc -b` with TS5097. +`tsconfig.app.json` sets `allowImportingTsExtensions` only so that Harper's reference crypto, copied +unchanged under `src/lib/crypto/__tests__/harper-v5.4.0/` with its own `.ts` specifier, compiles for the +tests that cross-check against it. That is the one place a `.ts` specifier belongs; studio's own +imports stay extensionless. ## Routing — keep `getParentRoute` and `addChildren` in lockstep diff --git a/src/features/auth/store/authStore.ts b/src/features/auth/store/authStore.ts index 42147bed7..ba29ae951 100644 --- a/src/features/auth/store/authStore.ts +++ b/src/features/auth/store/authStore.ts @@ -647,7 +647,7 @@ class AuthStore { return inFlight; } const promise = this.resolveFabricConnectAuth(id, operationsUrl, tokens); - if (!inFlight) { + if (!inFlight && !tokens) { this.fabricConnectInFlight.set(id, promise); } return promise.finally(() => { @@ -675,6 +675,13 @@ class AuthStore { claimedGeneration = this.getConnectionGeneration(id); this.fabricConnectAuth.set(id, auth); }; + // Two resolutions can overlap once a token-backed one declines to share the in-flight connect: whichever claimed + // last owns the state, and the other must not record its user over it. + const throwIfReplaced = () => { + if (claimedGeneration !== undefined && this.getConnectionGeneration(id) !== claimedGeneration) { + throw new Error('Another connection replaced this one while it was connecting.'); + } + }; try { const { operationToken, refreshToken } = tokens ?? await createInstanceAuthenticationTokens({ instanceClient: getInstanceClient({ id, forceFabricConnect: true }), @@ -697,11 +704,14 @@ class AuthStore { // Direct connect unreachable — fall back to the proxy. Log only the message: the full // axios error carries the Bearer token in error.config.headers. console.debug( - 'Fabric Connect direct connect unavailable; falling back to proxy', + tokens + ? 'Fabric Connect direct connect unavailable' + : 'Fabric Connect direct connect unavailable; falling back to proxy', directErr instanceof Error ? directErr.message : directErr, ); } throwIfSignedOut(); + throwIfReplaced(); if (directUser) { this.flagForFabricConnect(id, true); this.setLastConnectMode(id, 'fabric'); @@ -718,6 +728,7 @@ class AuthStore { const proxyClient = getInstanceClient({ id, forceFabricConnect: true }); const user = await getInstanceUserInfo({ instanceClient: proxyClient }); throwIfSignedOut(); + throwIfReplaced(); this.flagForFabricConnect(id, true); this.setLastConnectMode(id, 'fabric'); this.setUserForIdAndKey(id, operationsUrl || proxyClient.defaults.baseURL!, user); diff --git a/src/features/auth/store/establishFabricConnectAuth.test.ts b/src/features/auth/store/establishFabricConnectAuth.test.ts index bbdd6590a..b19177ca9 100644 --- a/src/features/auth/store/establishFabricConnectAuth.test.ts +++ b/src/features/auth/store/establishFabricConnectAuth.test.ts @@ -132,6 +132,86 @@ describe('authStore.establishFabricConnectAuth', () => { expect(getInstanceUserInfo.mock.calls[0][0].instanceClient.defaults.baseURL).toBe(PROXY_URL); }); + describe('with tokens minted elsewhere', () => { + const tokens = { operationToken: 'setup-token', refreshToken: 'setup-refresh' }; + + it('connects directly with them, minting nothing', async () => { + getInstanceUserInfo.mockResolvedValue(directUser); + + const user = await authStore.establishFabricConnectAuth({ id: 'ins-1', operationsUrl: DIRECT_URL, tokens }); + + expect(user).toBe(directUser); + expect(authStore.getOperationToken('ins-1')).toBe('setup-token'); + expect(createInstanceAuthenticationTokens).not.toHaveBeenCalled(); + }); + + it('throws instead of falling back to the proxy, and keeps nothing resolved', async () => { + getInstanceUserInfo.mockRejectedValue(new Error('CORS')); + + await expect(authStore.establishFabricConnectAuth({ id: 'ins-1', operationsUrl: DIRECT_URL, tokens })).rejects + .toThrow('could not be reached directly'); + + expect(getInstanceUserInfo).toHaveBeenCalledTimes(1); + expect(authStore.hasResolvedFabricConnect('ins-1')).toBe(false); + expect(authStore.checkForFabricConnect('ins-1')).toBe(false); + }); + + it('neither joins nor becomes the shared in-flight connect', async () => { + let answerMint: (value: { operationToken: string }) => void = () => undefined; + createInstanceAuthenticationTokens.mockReturnValueOnce( + new Promise((resolve) => { + answerMint = resolve; + }), + ); + getInstanceUserInfo.mockResolvedValue(directUser); + const plain = authStore.establishFabricConnectAuth({ id: 'ins-1', operationsUrl: DIRECT_URL }); + + const withTokens = authStore.establishFabricConnectAuth({ id: 'ins-1', operationsUrl: DIRECT_URL, tokens }); + await expect(withTokens).resolves.toBe(directUser); + expect(authStore.getOperationToken('ins-1')).toBe('setup-token'); + + answerMint({ operationToken: 'jwt-token' }); + await expect(plain).resolves.toBe(directUser); + expect(authStore.getOperationToken('ins-1')).toBe('jwt-token'); + + const joined = authStore.establishFabricConnectAuth({ id: 'ins-1', operationsUrl: DIRECT_URL, tokens }); + const later = authStore.establishFabricConnectAuth({ id: 'ins-1', operationsUrl: DIRECT_URL }); + expect(later).not.toBe(joined); + await Promise.all([joined, later]); + }); + + it('does not record its user over a connection that replaced it while it was verifying', async () => { + let answerDirect: (value: unknown) => void = () => undefined; + getInstanceUserInfo.mockImplementation(( + { instanceClient }: { instanceClient: { defaults: { baseURL: string; headers?: Record } } }, + ) => + instanceClient.defaults.headers?.Authorization === 'Bearer setup-token' + ? new Promise((resolve) => { + answerDirect = resolve; + }) + : Promise.resolve(proxyUser) + ); + getInstanceClient.mockImplementation(( + { forceFabricConnect, forceOperationToken }: { forceFabricConnect?: boolean; forceOperationToken?: boolean }, + ) => ({ + defaults: { + baseURL: forceFabricConnect ? PROXY_URL : DIRECT_URL, + headers: forceOperationToken ? { Authorization: `Bearer ${authStore.getOperationToken('ins-1')}` } : {}, + }, + })); + const withTokens = authStore.establishFabricConnectAuth({ id: 'ins-1', operationsUrl: DIRECT_URL, tokens }); + await new Promise((resolve) => setTimeout(resolve, 0)); + + const plain = await authStore.establishFabricConnectAuth({ id: 'ins-1', operationsUrl: null }); + expect(plain).toBe(proxyUser); + answerDirect(directUser); + + await expect(withTokens).rejects.toThrow('replaced'); + expect(authStore.getOperationToken('ins-1')).toBeUndefined(); + expect(authStore.hasResolvedFabricConnect('ins-1')).toBe(true); + }); + }); + it('drops the in-memory token when Fabric Connect is flagged off (e.g. on logout)', async () => { getInstanceUserInfo.mockResolvedValue(directUser); await authStore.establishFabricConnectAuth({ id: 'ins-1', operationsUrl: DIRECT_URL }); diff --git a/src/features/cluster/DESIGN.md b/src/features/cluster/DESIGN.md index cf2a32bd7..f0fddfe69 100644 --- a/src/features/cluster/DESIGN.md +++ b/src/features/cluster/DESIGN.md @@ -70,9 +70,11 @@ non-admin on a new cluster lands on that message instead of a dead card ## Nothing connects to a cluster before its setup, and setup keeps no earlier connection -Fabric Connect is whoever Harper resolves the central-manager proxy's request to, its first super user: the proxy -forwards no credential, and Harper answers a credential-less request on its operations socket as that user. Until Finish -Setup runs, that is the provisioning `HDB_ADMIN`, which setup then drops. A token minted for it still verifies after +Fabric Connect is whoever Harper resolves the central-manager proxy's request to: the proxy forwards no credential, and +Harper answers a credential-less request on its operations socket as its first super user, which until Finish Setup runs +is the provisioning `HDB_ADMIN`, which setup then drops. From Harper 5.4 that request runs instead as a built-in +record-less super user named `local` (HarperFast/harper#3755), before and after the drop; the sealed setup below is +written for that. A token minted for it still verifies after that, but resolves to a user with no role, so every operation through it answers 403 "not authorized due to role restrictions". Studio recovers a token only on a 401, so the pages stay denied until a reload mints again. @@ -117,8 +119,9 @@ A retry reads the cluster's state the same way: `add_user` answering "already ex dropped it and never sent the PATCH. The node answers a timestamp outside its window with its own clock and an envelope for another key with its fingerprint; each is retried once, with the offset remembered for the session and the key fetched again. A sealed answer that ran but could not return its result (`executed`) is reported as an unknown -outcome, like an unanswered write, since the user was created or dropped all the same. There is no plaintext fallback: -a node without custody (503) or a refused envelope is an error. +outcome, like an unanswered write, since the user was created or dropped all the same; so does a node's 503, which the +toast cannot tell from a gateway's, though a refusal before admission ran nothing and is safe to retry. There is no +plaintext fallback: a node without custody or a refused envelope stops setup. ## An interrupted setup finishes from the admin it already created diff --git a/src/features/cluster/FinishSetup.test.tsx b/src/features/cluster/FinishSetup.test.tsx index be25703a0..297b5793c 100644 --- a/src/features/cluster/FinishSetup.test.tsx +++ b/src/features/cluster/FinishSetup.test.tsx @@ -70,7 +70,7 @@ afterEach(() => { resetPendingPresetSetupsForTests(); }); -async function createAdminUser(fields: { preset?: string } = {}) { +async function createAdminUser(fields: { preset?: string; instances?: unknown[] } = {}) { const client = new QueryClient({ defaultOptions: { queries: { retry: false } } }); client.setQueryData(['clu-1'], { ...cluster, ...fields }); render( @@ -102,6 +102,24 @@ describe(FinishSetup, () => { expect(setUser).toHaveBeenCalledWith(expect.objectContaining({ id: 'clu-1' }), null); }); + it('hands setup the sealed capability once every member runs 5.4.0 and holds the cluster key, and nothing otherwise', async () => { + vi.spyOn(authStore, 'setUserForEntity').mockImplementation(() => undefined); + await createAdminUser({ + instances: [ + { id: 'ins-1', status: 'RUNNING', version: '5.4.0', secretsKeyFingerprint: 'fp-1' }, + { id: 'ins-2', status: 'RUNNING', version: '5.4.1', secretsKeyFingerprint: 'fp-1' }, + ], + }); + await waitFor(() => expect(mutate).toHaveBeenCalledTimes(1)); + expect(mutate.mock.calls[0][0]).toMatchObject({ sealedSetup: { keyFingerprint: 'fp-1' } }); + + cleanup(); + mutate.mockClear(); + await createAdminUser(); + await waitFor(() => expect(mutate).toHaveBeenCalledTimes(1)); + expect(mutate.mock.calls[0][0]).toMatchObject({ sealedSetup: undefined }); + }); + it('hands setup the direct URL and every id it must sign out first', async () => { vi.spyOn(authStore, 'setUserForEntity').mockImplementation(() => undefined); await createAdminUser(); diff --git a/src/features/cluster/FinishSetup.tsx b/src/features/cluster/FinishSetup.tsx index c34491585..96efac1e7 100644 --- a/src/features/cluster/FinishSetup.tsx +++ b/src/features/cluster/FinishSetup.tsx @@ -59,7 +59,7 @@ export function FinishSetup() { }, [setFocus]); const tempPassword = cluster?.instances?.find(i => i.tempPassword)?.tempPassword; - const sealedSetup = sealedSetupCapability(cluster); + const sealedSetup = useMemo(() => sealedSetupCapability(cluster), [cluster]); const instancesReady = allClusterInstancesRunning(cluster); const { mutate: submitInstanceResetPassword, isPending, isSuccess } = useInstanceResetPasswordMutation(); diff --git a/src/features/cluster/sealedSetup.ts b/src/features/cluster/sealedSetup.ts index 3271ae163..5fbdd50c3 100644 --- a/src/features/cluster/sealedSetup.ts +++ b/src/features/cluster/sealedSetup.ts @@ -3,11 +3,10 @@ import { Cluster } from '@/integrations/api/api.patch'; import { clusterIsSelfManaged } from '@/integrations/api/clusterIsSelfManaged'; import { wasAReleasedBeforeB } from '@/lib/string/wasAReleasedBeforeB'; -/** `encrypted_operation` shipped in Harper 5.4.0 (HarperFast/harper#4205). */ -export const SEALED_SETUP_MIN_VERSION = '5.4.0'; +// `encrypted_operation` shipped in Harper 5.4.0 (HarperFast/harper#4205). +const SEALED_SETUP_MIN_VERSION = '5.4.0'; export interface SealedSetupCapability { - /** The cluster secrets key every live member holds, by its fingerprint. */ keyFingerprint: string; } diff --git a/src/integrations/api/instance/auth/useInstanceResetPasswordMutation.test.tsx b/src/integrations/api/instance/auth/useInstanceResetPasswordMutation.test.tsx index 00f64d401..ed8545277 100644 --- a/src/integrations/api/instance/auth/useInstanceResetPasswordMutation.test.tsx +++ b/src/integrations/api/instance/auth/useInstanceResetPasswordMutation.test.tsx @@ -811,6 +811,18 @@ describe('sealed setup on a 5.4.0+ cluster', () => { expectNothingSignedIn(); }); + it('leaves the admin unconnected when a sign-out lands during setup, keeping no token in a signed-out tab', async () => { + vi.mocked(resetPasswordUpdater).mockImplementationOnce(async () => { + authStore.signOutLocally('clu-1'); + }); + + const { user } = await sealed(OWNER); + + expect(user).toBeNull(); + expect(sealedNode.users.has(defaultClusterUsername)).toBe(false); + expectNothingSignedIn(); + }); + it('refetches a key whose fingerprint is not the one the members hold, and refuses one that stays different', async () => { fetchClusterKey.mockResolvedValueOnce({ ...CLUSTER_KEY, fingerprint: 'fp-0' }); const { user } = await sealed(OWNER); diff --git a/src/integrations/api/instance/auth/useInstanceResetPasswordMutation.ts b/src/integrations/api/instance/auth/useInstanceResetPasswordMutation.ts index eda9e95c7..a07534412 100644 --- a/src/integrations/api/instance/auth/useInstanceResetPasswordMutation.ts +++ b/src/integrations/api/instance/auth/useInstanceResetPasswordMutation.ts @@ -25,7 +25,6 @@ interface InstanceResetPasswordParams { desiredUsername: string; newPassword: string; tempPassword: string | undefined; - /** Set when every live member can run sealed operations against one cluster key (`sealedSetupCapability`). */ sealedSetup?: SealedSetupCapability; } @@ -169,8 +168,8 @@ async function finishSetupSealed( { clusterId, operationsUrl, signInIds, desiredUsername, newPassword }: InstanceResetPasswordParams, { keyFingerprint }: SealedSetupCapability, ): Promise { - // A connection made before setup is the provisioning account's, and it stops working once that account is dropped. authStore.signOutEntitiesLocally(signInIds); + const signOutGeneration = authStore.getSignOutGeneration(clusterId); // The members hold the key by its fingerprint; a cached key with another is stale, and one that stays different // after a fresh read is a cluster whose key is changing under setup. let key = await queryClient.ensureQueryData(clusterKeyQuery(clusterId)); @@ -184,7 +183,8 @@ async function finishSetupSealed( } const instanceClient = getInstanceClient({ id: clusterId, forceFabricConnect: true }); const refreshKey = async () => (key = await refetchClusterKey(queryClient, clusterId)); - const seal = (op: SealableOperation) => runSealedOperation({ instanceClient, op, key, refreshKey }); + const seal = (op: SealableOperation) => + runSealedOperation({ instanceClient, op, key, refreshKey, actor: 'Studio Finish Setup' }); if (desiredUsername === defaultClusterUsername) { await seal({ operation: 'alter_user', username: desiredUsername, password: newPassword }); @@ -226,7 +226,6 @@ async function finishSetupSealed( try { await seal({ operation: 'drop_user', username: defaultClusterUsername }); } catch (err) { - // An earlier attempt dropped it and never told central manager. if (!isSealedRefusal(err, 404, `User ${defaultClusterUsername} does not exist`)) { throw err; } @@ -235,7 +234,11 @@ async function finishSetupSealed( await resetPasswordUpdater(clusterId); // Setup is done; this only connects the browser as the admin, directly or not at all: through the proxy the session - // would be the proxy's own principal, not the admin's. A failed connect leaves the cluster signed out. + // would be the proxy's own principal, not the admin's. A failed connect, or a sign-out that landed meanwhile, leaves + // the cluster signed out. + if (authStore.getSignOutGeneration(clusterId) !== signOutGeneration) { + return { message: 'Login successful', user: null }; + } const user = await authStore.establishFabricConnectAuth({ id: clusterId, operationsUrl, diff --git a/src/integrations/api/instance/sealedOperation.test.ts b/src/integrations/api/instance/sealedOperation.test.ts index e0d4fe7e0..4ba0a8717 100644 --- a/src/integrations/api/instance/sealedOperation.test.ts +++ b/src/integrations/api/instance/sealedOperation.test.ts @@ -9,7 +9,7 @@ import { AxiosError, AxiosHeaders, type AxiosInstance } from 'axios'; import { generateKeyPairSync } from 'node:crypto'; import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; import { - _resetClockOffsetForTests, + _resetClockOffsetsForTests, isSealedRefusal, runSealedOperation, SealedOperationError, @@ -78,9 +78,18 @@ const node = { }, }; -const instanceClient = { - post: vi.fn(async (_url: string, body: { operation?: unknown; envelope?: unknown }) => ({ data: node.answer(body) })), -} as unknown as AxiosInstance; +const answerAsNode = node.answer; + +function clientFor(baseURL: string): AxiosInstance { + return { + defaults: { baseURL }, + post: vi.fn(async (_url: string, body: { operation?: unknown; envelope?: unknown }) => ({ + data: node.answer(body), + })), + } as unknown as AxiosInstance; +} + +const instanceClient = clientFor('https://cm.example.com/Cluster/clu-1/operation'); const op = { operation: 'add_user', username: 'owner@example.com', password: 'secret-password', role: 'super_user' }; const key = { publicKey: custody.publicKey, fingerprint: custody.fingerprint }; @@ -90,7 +99,8 @@ beforeEach(() => { node.custody = true; node.execute = (inner) => ({ status: 200, body: { message: `${inner.operation} ran` } }); node.requests = []; - _resetClockOffsetForTests(); + node.answer = answerAsNode; + _resetClockOffsetsForTests(); }); afterEach(() => { @@ -153,7 +163,15 @@ describe(runSealedOperation, () => { await expect(runSealedOperation({ instanceClient, op, key })).rejects.toMatchObject({ response: { status: 400 } }); expect(node.requests).toHaveLength(2); - node.answer = skewedNode; + }); + + it("learns each node's clock on its own", async () => { + node.clockSkewMs = 10 * 60_000; + await runSealedOperation({ instanceClient, op, key }); + expect(node.requests).toHaveLength(2); + + await runSealedOperation({ instanceClient: clientFor('https://cm.example.com/Cluster/clu-2/operation'), op, key }); + expect(node.requests).toHaveLength(4); }); it('fetches the key again, once, when the envelope was sealed to another key', async () => { @@ -185,6 +203,28 @@ describe(runSealedOperation, () => { expect(node.requests).toHaveLength(1); }); + it('opens a sealed answer that arrived on a failing HTTP status', async () => { + vi.mocked(instanceClient.post).mockImplementationOnce(async (_url, body) => { + const data = answerAsNode.call(node, body as { operation?: unknown; envelope?: unknown }); + throw refusal(409, data as unknown as Record); + }); + node.execute = () => ({ status: 409, body: { error: 'User owner@example.com already exists' } }); + + await expect(runSealedOperation({ instanceClient, op, key })).rejects.toMatchObject({ + name: 'SealedOperationError', + status: 409, + }); + }); + + it('refuses a replicated write some peer refused, as the direct path does', async () => { + node.execute = () => ({ + status: 200, + body: { message: 'added', replicated: [{ node: 'ins-2', status: 'failed', reason: 'peer down' }] }, + }); + + await expect(runSealedOperation({ instanceClient, op, key })).rejects.toMatch(/Failed to replicate/); + }); + it('refuses an answer that is not sealed', async () => { vi.mocked(instanceClient.post).mockResolvedValueOnce({ data: { message: 'add_user ran' } }); diff --git a/src/integrations/api/instance/sealedOperation.ts b/src/integrations/api/instance/sealedOperation.ts index 7a82fa1c0..61d0d6911 100644 --- a/src/integrations/api/instance/sealedOperation.ts +++ b/src/integrations/api/instance/sealedOperation.ts @@ -1,9 +1,10 @@ import { InstanceClientConfig } from '@/config/instanceClientConfig'; import { SecretsPublicKey } from '@/integrations/api/instance/secrets/secrets'; +import { rejectReplicationFailures, ReplicatedResponse } from '@/integrations/api/replication'; import { openSealedResponse, SealableOperation, SealedResult, sealOperation } from '@/lib/crypto/sealedOperation'; import { isAxiosError } from 'axios'; -/** The sealed operation ran and answered a failure; `status` and `body` are the operation's own. */ +/** The sealed operation ran and answered a failure. */ export class SealedOperationError extends Error { operation: string; status: number; @@ -25,31 +26,34 @@ export function isSealedRefusal(error: unknown, status: number, message: string) return error instanceof SealedOperationError && error.status === status && error.message === message; } -export interface RunSealedOperationParams extends InstanceClientConfig { +interface RunSealedOperationParams extends InstanceClientConfig { op: SealableOperation; key: SecretsPublicKey; /** Fetches the key again when the node reports another fingerprint; asked once per call. */ refreshKey?: () => Promise; + /** Attribution for the node's log. */ actor?: string; } // The node accepts a timestamp only within its window around its own clock. A refusal names that clock, and the -// difference serves every later request, so a skewed browser pays the round trip once. -let clockOffsetMs = 0; +// difference serves every later request to the same address, so a skewed browser pays the round trip once per node. +const clockOffsetsMs = new Map(); -export function _resetClockOffsetForTests(): void { - clockOffsetMs = 0; +export function _resetClockOffsetsForTests(): void { + clockOffsetsMs.clear(); } /** * Sends `op` sealed as `encrypted_operation` through `instanceClient` and opens the answer. A plaintext refusal is * retried once when it is one the client can repair: a timestamp outside the node's window (400 with `server_time`) * or an envelope sealed to another key (409 with `custody_fingerprint`). Everything else is thrown as the request's - * own failure, and a sealed answer with a failing status as a `SealedOperationError`. + * own failure; a sealed answer with a failing status, whatever HTTP status carried it, as a `SealedOperationError`; + * and a replicated write some peer refused as the direct path refuses it. */ export async function runSealedOperation( { instanceClient, op, key, refreshKey, actor }: RunSealedOperationParams, ): Promise { + const node = instanceClient.defaults.baseURL ?? ''; let currentKey = key; let clockRetried = false; let keyRetried = false; @@ -59,16 +63,18 @@ export async function runSealedOperation( publicKey: currentKey.publicKey, kid: currentKey.fingerprint, actor, - now: Date.now() + clockOffsetMs, + now: Date.now() + (clockOffsetsMs.get(node) ?? 0), }); let data: unknown; try { ({ data } = await instanceClient.post('/', request)); } catch (error) { const refusal = isAxiosError(error) ? error.response : undefined; - const detail = refusal?.data as { server_time?: unknown; custody_fingerprint?: unknown } | undefined; + const detail = refusal?.data as + | { server_time?: unknown; custody_fingerprint?: unknown; encrypted_response?: unknown } + | undefined; if (refusal?.status === 400 && typeof detail?.server_time === 'number' && !clockRetried) { - clockOffsetMs = detail.server_time - Date.now(); + clockOffsetsMs.set(node, detail.server_time - Date.now()); clockRetried = true; continue; } @@ -77,7 +83,10 @@ export async function runSealedOperation( keyRetried = true; continue; } - throw error; + if (!detail?.encrypted_response) { + throw error; + } + data = detail; } const payload = (data as { encrypted_response?: unknown } | null | undefined)?.encrypted_response; if (!payload) { @@ -87,6 +96,9 @@ export async function runSealedOperation( if (result.status >= 400) { throw new SealedOperationError(op.operation, result); } + if (result.body && typeof result.body === 'object') { + await rejectReplicationFailures({ data: result.body as ReplicatedResponse }); + } return result; } } diff --git a/src/lib/crypto/__tests__/harper-v5.4.0/README.md b/src/lib/crypto/__tests__/harper-v5.4.0/README.md new file mode 100644 index 000000000..bc57ca524 --- /dev/null +++ b/src/lib/crypto/__tests__/harper-v5.4.0/README.md @@ -0,0 +1,13 @@ +# Harper's reference client for `encrypted_operation` + +`sealedOperation.ts` and `secretEnvelope.ts` are `utility/sealedOperation.ts` and `utility/secretEnvelope.ts` from +HarperFast/harper at tag `v5.4.0` (commit `c5d82cff73e4088ea25150ae7d26c4ace6c2d3ed`), copied unchanged: the node's own +tests use them, so what opens here is what the node accepts and answers. They are excluded from `dprint` for that +reason, and `tsconfig.app.json` allows their `.ts` import specifier. Check them against the tag with: + +```bash +git -C show v5.4.0:utility/sealedOperation.ts | diff - sealedOperation.ts +git -C show v5.4.0:utility/secretEnvelope.ts | diff - secretEnvelope.ts +``` + +Only `src/lib/crypto/sealedOperation.test.ts` and `src/integrations/api/instance/sealedOperation.test.ts` import them. diff --git a/src/lib/crypto/sealedOperation.ts b/src/lib/crypto/sealedOperation.ts index 8ef73935d..c0fff41eb 100644 --- a/src/lib/crypto/sealedOperation.ts +++ b/src/lib/crypto/sealedOperation.ts @@ -18,19 +18,14 @@ const RESPONSE_AAD_PREFIX = 'harper.encrypted_operation.response:'; export type SealableOperation = Record & { operation: string }; -export interface SealedOperationRequest { - operation: 'encrypted_operation'; - envelope: string; -} - -export interface SealedOperation { - request: SealedOperationRequest; - /** The key the node seals its answer with; needed once, to open that answer. */ +interface SealedOperation { + request: { operation: 'encrypted_operation'; envelope: string }; + /** The key the node seals its answer with. */ responseKey: Uint8Array; nonce: string; } -/** What the node answered inside the sealed response: the operation's own status and body. */ +/** What the node answered inside the sealed response. */ export interface SealedResult { status: number; body: unknown; @@ -38,12 +33,11 @@ export interface SealedResult { executed?: true; } -export interface SealOperationOptions { +interface SealOperationOptions { op: SealableOperation; publicKey: string; /** The key's fingerprint, as the server reports it; the node refuses an envelope whose `kid` is not its own. */ kid: string; - /** Attribution for the node's log. */ actor?: string; /** The client's clock in milliseconds; the node accepts it only within its window. */ now?: number; diff --git a/src/react-query/queryClient.test.ts b/src/react-query/queryClient.test.ts index d0519b9d1..7a56b3e10 100644 --- a/src/react-query/queryClient.test.ts +++ b/src/react-query/queryClient.test.ts @@ -443,6 +443,13 @@ describe('a write that got no verdict', () => { }); }); + it('counts an unanswered sealed operation as a write, whatever it sealed', () => { + expect(describeError(gatewayTimeout(sent({ operation: 'encrypted_operation', envelope: 'enc:v1:x' })))) + .toMatchObject({ + title: OUTCOME_UNKNOWN_TITLE, + }); + }); + it('includes a sealed operation that ran but could not return its result', () => { const executed = new SealedOperationError('drop_user', { status: 500, From f7baa77da07f68592ffc30bfca7e41431391472c Mon Sep 17 00:00:00 2001 From: Devin Holland <50112339+Devin-Holland@users.noreply.github.com> Date: Mon, 16 Nov 2026 15:18:08 -0500 Subject: [PATCH 3/7] fix(cluster): keep replacement connections and read unreadable sealed 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 --- src/features/auth/store/authStore.ts | 6 ++- .../store/establishFabricConnectAuth.test.ts | 18 +++++++++ src/features/cluster/DESIGN.md | 4 +- src/features/cluster/FinishSetup.test.tsx | 8 +++- src/features/cluster/FinishSetup.tsx | 5 ++- src/features/cluster/sealedSetup.test.ts | 14 ++++++- src/features/cluster/sealedSetup.ts | 34 +++++++++------- .../useInstanceResetPasswordMutation.test.tsx | 33 +++++++++++++++- .../auth/useInstanceResetPasswordMutation.ts | 24 ++++++++---- .../api/instance/sealedOperation.test.ts | 39 ++++++++++++++----- .../api/instance/sealedOperation.ts | 26 +++++++++++-- src/lib/crypto/sealedOperation.test.ts | 5 +-- src/lib/crypto/sealedOperation.ts | 3 +- src/react-query/queryClient.test.ts | 8 +++- src/react-query/queryClient.ts | 5 ++- 15 files changed, 184 insertions(+), 48 deletions(-) diff --git a/src/features/auth/store/authStore.ts b/src/features/auth/store/authStore.ts index ba29ae951..63cc3856d 100644 --- a/src/features/auth/store/authStore.ts +++ b/src/features/auth/store/authStore.ts @@ -664,6 +664,7 @@ class AuthStore { tokens: InstanceAuthenticationTokens | undefined, ): Promise { const signOutGeneration = this.getSignOutGeneration(id); + const entryGeneration = this.getConnectionGeneration(id); const throwIfSignedOut = () => { if (this.getSignOutGeneration(id) !== signOutGeneration) { throw new SignedOutWhileConnectingError(); @@ -735,9 +736,10 @@ class AuthStore { return user; } catch (err) { // Couldn't establish either mode — clear the half-resolved state so we retry next time. Only - // this resolution's own: after a sign-out, a newer one for the same id may have claimed it. + // this resolution's own: after a sign-out, or while this one was still minting, a newer one for the same + // id may have claimed it. const ownsState = claimedGeneration === undefined - ? this.getSignOutGeneration(id) === signOutGeneration + ? this.getSignOutGeneration(id) === signOutGeneration && this.getConnectionGeneration(id) === entryGeneration : this.getConnectionGeneration(id) === claimedGeneration; if (ownsState) { this.fabricConnectAuth.delete(id); diff --git a/src/features/auth/store/establishFabricConnectAuth.test.ts b/src/features/auth/store/establishFabricConnectAuth.test.ts index b19177ca9..f689db80a 100644 --- a/src/features/auth/store/establishFabricConnectAuth.test.ts +++ b/src/features/auth/store/establishFabricConnectAuth.test.ts @@ -180,6 +180,24 @@ describe('authStore.establishFabricConnectAuth', () => { await Promise.all([joined, later]); }); + it('is not erased when an ordinary connect that never claimed fails afterwards', async () => { + let refuseMint: (error: Error) => void = () => undefined; + createInstanceAuthenticationTokens.mockReturnValueOnce( + new Promise((_resolve, reject) => { + refuseMint = reject; + }), + ); + getInstanceUserInfo.mockResolvedValue(directUser); + const plain = authStore.establishFabricConnectAuth({ id: 'ins-1', operationsUrl: DIRECT_URL }); + await authStore.establishFabricConnectAuth({ id: 'ins-1', operationsUrl: DIRECT_URL, tokens }); + + refuseMint(new Error('proxy down')); + await expect(plain).rejects.toThrow('proxy down'); + + expect(authStore.getOperationToken('ins-1')).toBe('setup-token'); + expect(authStore.hasResolvedFabricConnect('ins-1')).toBe(true); + }); + it('does not record its user over a connection that replaced it while it was verifying', async () => { let answerDirect: (value: unknown) => void = () => undefined; getInstanceUserInfo.mockImplementation(( diff --git a/src/features/cluster/DESIGN.md b/src/features/cluster/DESIGN.md index f0fddfe69..33ec96a72 100644 --- a/src/features/cluster/DESIGN.md +++ b/src/features/cluster/DESIGN.md @@ -100,7 +100,9 @@ The cluster record decides, in [`sealedSetup.ts`](sealedSetup.ts): a Fabric-host reports 5.4.0 or later and carries the same `secretsKeyFingerprint`. The fingerprint is what proves the key exists and reached each host; without it, asking central manager for the key would create one and restart the members (`ClusterSecretsKey.js`), in the middle of setup. Anything else keeps the `tempPassword` flow above, unchanged, and a -5.4.0 prerelease counts as below the floor. The sealed path never reads `tempPassword`. +5.4.0 prerelease counts as below the floor. The sealed path never reads `tempPassword`. Members that could seal but do +not all carry the key yet get their own message when there is no `tempPassword` either (`clusterKeyPending`): the key is +on its way, not a permission problem. Every write goes through `getInstanceClient({ forceFabricConnect: true })` as `encrypted_operation` ([`runSealedOperation`](../../integrations/api/instance/sealedOperation.ts), over diff --git a/src/features/cluster/FinishSetup.test.tsx b/src/features/cluster/FinishSetup.test.tsx index 297b5793c..88301abf4 100644 --- a/src/features/cluster/FinishSetup.test.tsx +++ b/src/features/cluster/FinishSetup.test.tsx @@ -117,7 +117,13 @@ describe(FinishSetup, () => { mutate.mockClear(); await createAdminUser(); await waitFor(() => expect(mutate).toHaveBeenCalledTimes(1)); - expect(mutate.mock.calls[0][0]).toMatchObject({ sealedSetup: undefined }); + expect(mutate.mock.calls[0][0]).toMatchObject({ sealedSetup: undefined, clusterKeyPending: false }); + + cleanup(); + mutate.mockClear(); + await createAdminUser({ instances: [{ id: 'ins-1', status: 'RUNNING', version: '5.4.0' }] }); + await waitFor(() => expect(mutate).toHaveBeenCalledTimes(1)); + expect(mutate.mock.calls[0][0]).toMatchObject({ sealedSetup: undefined, clusterKeyPending: true }); }); it('hands setup the direct URL and every id it must sign out first', async () => { diff --git a/src/features/cluster/FinishSetup.tsx b/src/features/cluster/FinishSetup.tsx index 96efac1e7..0733ee549 100644 --- a/src/features/cluster/FinishSetup.tsx +++ b/src/features/cluster/FinishSetup.tsx @@ -25,7 +25,7 @@ import { toast } from 'sonner'; import { z } from 'zod'; import { allClusterInstancesRunning } from './allInstancesRunning'; import { getClusterInfoQueryOptions, markClusterPasswordSet } from './queries/getClusterInfoQuery'; -import { sealedSetupCapability } from './sealedSetup'; +import { clusterKeyPending, sealedSetupCapability } from './sealedSetup'; import { clusterSignInIds } from './terminatedClusterSignIns'; export function FinishSetup() { @@ -60,6 +60,7 @@ export function FinishSetup() { const tempPassword = cluster?.instances?.find(i => i.tempPassword)?.tempPassword; const sealedSetup = useMemo(() => sealedSetupCapability(cluster), [cluster]); + const keyPending = clusterKeyPending(cluster); const instancesReady = allClusterInstancesRunning(cluster); const { mutate: submitInstanceResetPassword, isPending, isSuccess } = useInstanceResetPasswordMutation(); @@ -80,6 +81,7 @@ export function FinishSetup() { newPassword: formData.password, tempPassword, sealedSetup: sealedSetup ?? undefined, + clusterKeyPending: keyPending, initialUsername: defaultClusterUsername, desiredUsername: formData.username, }, { @@ -111,6 +113,7 @@ export function FinishSetup() { cluster, clusterId, instancesReady, + keyPending, navigate, operationsUrl, preset, diff --git a/src/features/cluster/sealedSetup.test.ts b/src/features/cluster/sealedSetup.test.ts index cadb14dec..6be232e33 100644 --- a/src/features/cluster/sealedSetup.test.ts +++ b/src/features/cluster/sealedSetup.test.ts @@ -1,6 +1,6 @@ import type { Cluster } from '@/integrations/api/api.patch'; import { describe, expect, it } from 'vitest'; -import { sealedSetupCapability } from './sealedSetup'; +import { clusterKeyPending, sealedSetupCapability } from './sealedSetup'; function cluster( instances: Array<{ version?: string; status?: string; secretsKeyFingerprint?: string | null }>, @@ -53,6 +53,18 @@ describe(sealedSetupCapability, () => { expect(sealedSetupCapability(cluster([{ version: '5.4.0' }], 'self-hosted-free'))).toBeNull(); }); + it('reports the key pending only where the members could seal but do not all hold one key', () => { + expect(clusterKeyPending(cluster([{ version: '5.4.0', secretsKeyFingerprint: null }]))).toBe(true); + expect(clusterKeyPending(cluster([{ version: '5.4.0' }, { version: '5.4.0', secretsKeyFingerprint: 'fp-2' }]))) + .toBe(true); + expect(clusterKeyPending(cluster([{ version: '5.4.0' }]))).toBe(false); + expect(clusterKeyPending(cluster([{ version: '5.3.0', secretsKeyFingerprint: null }]))).toBe(false); + expect(clusterKeyPending(cluster([{ version: '5.4.0', secretsKeyFingerprint: null }], 'self-hosted-free'))).toBe( + false, + ); + expect(clusterKeyPending(undefined)).toBe(false); + }); + it('is off until the cluster is loaded', () => { expect(sealedSetupCapability(undefined)).toBeNull(); expect(sealedSetupCapability(cluster([]))).toBeNull(); diff --git a/src/features/cluster/sealedSetup.ts b/src/features/cluster/sealedSetup.ts index 5fbdd50c3..d5ec4e856 100644 --- a/src/features/cluster/sealedSetup.ts +++ b/src/features/cluster/sealedSetup.ts @@ -1,5 +1,5 @@ import { deletedClusterStatuses } from '@/config/clusterStatuses'; -import { Cluster } from '@/integrations/api/api.patch'; +import { Cluster, Instance } from '@/integrations/api/api.patch'; import { clusterIsSelfManaged } from '@/integrations/api/clusterIsSelfManaged'; import { wasAReleasedBeforeB } from '@/lib/string/wasAReleasedBeforeB'; @@ -18,22 +18,30 @@ export interface SealedSetupCapability { * 5.4.0, or no fingerprint fails closed. */ export function sealedSetupCapability(cluster: Cluster | undefined): SealedSetupCapability | null { + const live = liveMembersAbleToSeal(cluster); + if (!live) { + return null; + } + const keyFingerprint = live[0].secretsKeyFingerprint; + return keyFingerprint && live.every((instance) => instance.secretsKeyFingerprint === keyFingerprint) + ? { keyFingerprint } + : null; +} + +/** The members could seal, but central manager has not stamped one key on all of them yet. */ +export function clusterKeyPending(cluster: Cluster | undefined): boolean { + return !!liveMembersAbleToSeal(cluster) && sealedSetupCapability(cluster) === null; +} + +function liveMembersAbleToSeal(cluster: Cluster | undefined): Instance[] | null { if (!cluster || clusterIsSelfManaged(cluster)) { return null; } const live = (cluster.instances ?? []).filter( (instance) => !(instance.status && deletedClusterStatuses.includes(instance.status)), ); - const keyFingerprint = live[0]?.secretsKeyFingerprint; - if ( - !keyFingerprint - || !live.every((instance) => - instance.secretsKeyFingerprint === keyFingerprint - && !!instance.version - && wasAReleasedBeforeB(SEALED_SETUP_MIN_VERSION, instance.version) - ) - ) { - return null; - } - return { keyFingerprint }; + return live.length > 0 + && live.every((instance) => !!instance.version && wasAReleasedBeforeB(SEALED_SETUP_MIN_VERSION, instance.version)) + ? live + : null; } diff --git a/src/integrations/api/instance/auth/useInstanceResetPasswordMutation.test.tsx b/src/integrations/api/instance/auth/useInstanceResetPasswordMutation.test.tsx index ed8545277..b03709a45 100644 --- a/src/integrations/api/instance/auth/useInstanceResetPasswordMutation.test.tsx +++ b/src/integrations/api/instance/auth/useInstanceResetPasswordMutation.test.tsx @@ -35,6 +35,7 @@ vi.mock('@/integrations/api/instance/status/getInstanceUserInfo', () => ({ getInstanceUserInfo: async ({ instanceClient }: { instanceClient: AxiosInstance }) => { const authorization = instanceClient.defaults.headers.Authorization; if (typeof authorization === 'string' && authorization.startsWith(`Bearer ${sealedNode.tokenPrefix}`)) { + await sealedNode.beforeUserInfo?.(); return sealedNode.userInfo(authorization.slice(`Bearer ${sealedNode.tokenPrefix}`.length)); } return authorization === 'Bearer owner-token' @@ -125,11 +126,14 @@ class SealedNode { users = new Map(); operations: string[] = []; clients: AxiosInstance[] = []; + /** Runs while a token's `user_info` is in flight, once. */ + beforeUserInfo?: () => Promise; reset() { this.users = new Map([[defaultClusterUsername, { superUser: true, active: true }]]); this.operations = []; this.clients = []; + this.beforeUserInfo = undefined; } userInfo(username: string): LocalUser { @@ -233,7 +237,7 @@ afterEach(() => { function resetPassword( desiredUsername: string, - overrides: { sealedSetup?: { keyFingerprint: string }; tempPassword?: string } = {}, + overrides: { sealedSetup?: { keyFingerprint: string }; tempPassword?: string; clusterKeyPending?: boolean } = {}, ) { const client = new QueryClient({ defaultOptions: { mutations: { retry: false }, queries: { retry: false } } }); const { result } = renderHook(() => useInstanceResetPasswordMutation(), { @@ -794,6 +798,30 @@ describe('sealed setup on a 5.4.0+ cluster', () => { expect(resetPasswordUpdater).toHaveBeenCalledTimes(1); }); + it('keeps a connection that replaced its own while it was connecting, finishing without a user', async () => { + const signOut = vi.spyOn(authStore, 'signOutLocally'); + sealedNode.beforeUserInfo = async () => { + sealedNode.beforeUserInfo = undefined; + await authStore.establishFabricConnectAuth({ id: 'clu-1', operationsUrl: CLUSTER_URL }); + }; + + const { user } = await sealed(OWNER); + + expect(user).toBeNull(); + expect(resetPasswordUpdater).toHaveBeenCalledTimes(1); + expect(signOut.mock.calls.map(([id]) => id)).toEqual(['clu-1', 'ins-1']); + expect(authStore.getOperationToken('clu-1')).toBe('provisioning-token'); + expect(authStore.getConnectionById('clu-1').user).toMatchObject({ username: defaultClusterUsername }); + }); + + it('says the key is still on its way when a 5.4 cluster has no temporary password and no key on every member', async () => { + await expect(resetPassword(OWNER, { tempPassword: undefined, clusterKeyPending: true })).rejects.toThrow( + "secrets key hasn't reached every member yet", + ); + await expect(resetPassword(OWNER, { tempPassword: undefined })).rejects.toThrow('may not have permission'); + expect(onInstanceLoginSubmit).not.toHaveBeenCalled(); + }); + it('finishes signed out, after telling central manager, when the cluster cannot be reached directly', async () => { runSealedOperation.mockImplementation(async (params: Parameters[0]) => { const result = await sealedNode.run(params); @@ -802,12 +830,13 @@ describe('sealed setup on a 5.4.0+ cluster', () => { : result; }); + const signOut = vi.spyOn(authStore, 'signOutLocally'); const { user } = await sealed(OWNER); expect(user).toBeNull(); expect(resetPasswordUpdater).toHaveBeenCalledTimes(1); - // The proxy's own session would be the `local` principal's, never the admin's, so none is kept. expect(createInstanceAuthenticationTokens).not.toHaveBeenCalled(); + expect(signOut.mock.calls.map(([id]) => id)).toEqual(['clu-1', 'ins-1']); expectNothingSignedIn(); }); diff --git a/src/integrations/api/instance/auth/useInstanceResetPasswordMutation.ts b/src/integrations/api/instance/auth/useInstanceResetPasswordMutation.ts index a07534412..b3b1817ee 100644 --- a/src/integrations/api/instance/auth/useInstanceResetPasswordMutation.ts +++ b/src/integrations/api/instance/auth/useInstanceResetPasswordMutation.ts @@ -26,6 +26,8 @@ interface InstanceResetPasswordParams { newPassword: string; tempPassword: string | undefined; sealedSetup?: SealedSetupCapability; + /** Every live member could seal, but central manager has not stamped the cluster key on all of them yet. */ + clusterKeyPending?: boolean; } interface InstanceResetPasswordResponse { @@ -52,10 +54,15 @@ async function finishSetupWithTemporaryPassword({ desiredUsername, newPassword, tempPassword, + clusterKeyPending, }: InstanceResetPasswordParams): Promise { // Do we have a temporary password? if (!tempPassword) { - throw new Error('You may not have permission to set the password on this cluster.'); + throw new Error( + clusterKeyPending + ? "The cluster's secrets key hasn't reached every member yet, so the admin user can't be created. Try again in a moment." + : 'You may not have permission to set the password on this cluster.', + ); } // A connection made before setup is the provisioning account's: every step below would run as it, whatever // credentials they present, and it stops working once that account is dropped. @@ -213,9 +220,8 @@ async function finishSetupSealed( await seal({ operation: 'alter_user', username: desiredUsername, password: newPassword }); } } - // Minted with the typed credentials, the tokens are the admin's and nobody else's: the node checks the password - // and names that user, however many super users another attempt left. This is also the proof the admin signs in, - // taken before the account that created it goes. + // With the typed credentials the node names the admin, not its first stored super user; and a wrong password stops + // setup while the provisioning account still exists. const minted = (await seal({ operation: 'create_authentication_tokens', username: desiredUsername, password: newPassword })) .body as { operation_token?: string; refresh_token?: string }; @@ -233,9 +239,8 @@ async function finishSetupSealed( } await resetPasswordUpdater(clusterId); - // Setup is done; this only connects the browser as the admin, directly or not at all: through the proxy the session - // would be the proxy's own principal, not the admin's. A failed connect, or a sign-out that landed meanwhile, leaves - // the cluster signed out. + // Setup is done; this only connects the browser as the admin, directly or not at all. A connect that fails has + // already cleared its own state, and one another connect replaced must not sign that one out. if (authStore.getSignOutGeneration(clusterId) !== signOutGeneration) { return { message: 'Login successful', user: null }; } @@ -247,7 +252,10 @@ async function finishSetupSealed( console.debug('Could not connect after setup', error instanceof Error ? error.message : error); return null; }); - if (user?.username !== desiredUsername || user.role?.permission?.super_user !== true || !user.active) { + if (!user) { + return { message: 'Login successful', user: null }; + } + if (user.username !== desiredUsername || user.role?.permission?.super_user !== true || !user.active) { authStore.signOutLocally(clusterId); return { message: 'Login successful', user: null }; } diff --git a/src/integrations/api/instance/sealedOperation.test.ts b/src/integrations/api/instance/sealedOperation.test.ts index 4ba0a8717..6bcbcc691 100644 --- a/src/integrations/api/instance/sealedOperation.test.ts +++ b/src/integrations/api/instance/sealedOperation.test.ts @@ -1,18 +1,22 @@ // @vitest-environment node // A fake 5.4 node built from Harper's own reference client (copied unchanged under src/lib/crypto/__tests__): it opens // what the helper seals and seals what the helper opens, and refuses the way `components/encryptedOperation.ts` does. -import { sealResponse } from '@/lib/crypto/__tests__/harper-v5.4.0/sealedOperation.ts'; -import { fingerprintOf } from '@/lib/crypto/__tests__/harper-v5.4.0/secretEnvelope.ts'; -import { decryptEnvelope, parseEnvelopeFields } from '@/lib/crypto/__tests__/harper-v5.4.0/secretEnvelope.ts'; +import { sealResponse } from '@/lib/crypto/__tests__/harper-v5.4.0/sealedOperation'; +import { + decryptEnvelope, + fingerprintOf, + parseEnvelopeFields, +} from '@/lib/crypto/__tests__/harper-v5.4.0/secretEnvelope'; import { ENV_ENCRYPTED_PREFIX } from '@/lib/crypto/envSecret'; import { AxiosError, AxiosHeaders, type AxiosInstance } from 'axios'; -import { generateKeyPairSync } from 'node:crypto'; +import { generateKeyPairSync, randomBytes } from 'node:crypto'; import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; import { _resetClockOffsetsForTests, isSealedRefusal, runSealedOperation, SealedOperationError, + UnreadableSealedAnswerError, } from './sealedOperation'; function keyPair() { @@ -163,6 +167,11 @@ describe(runSealedOperation, () => { await expect(runSealedOperation({ instanceClient, op, key })).rejects.toMatchObject({ response: { status: 400 } }); expect(node.requests).toHaveLength(2); + + node.answer = answerAsNode; + node.clockSkewMs = 0; + await runSealedOperation({ instanceClient, op, key }); + expect(node.requests).toHaveLength(3); }); it("learns each node's clock on its own", async () => { @@ -225,11 +234,23 @@ describe(runSealedOperation, () => { await expect(runSealedOperation({ instanceClient, op, key })).rejects.toMatch(/Failed to replicate/); }); - it('refuses an answer that is not sealed', async () => { - vi.mocked(instanceClient.post).mockResolvedValueOnce({ data: { message: 'add_user ran' } }); + it.each([ + ['not sealed', () => ({ data: { message: 'add_user ran' } })], + ['malformed', () => ({ data: { encrypted_response: { v: 1, iv: 'AAAA', ct: 'AAAA', tag: 'AAAA' } } })], + [ + "another request's", + () => ({ + data: { + encrypted_response: sealResponse(JSON.stringify({ status: 200, body: {} }), randomBytes(32), 'b3RoZXI='), + }, + }), + ], + ])('reports an answer that is %s as one the operation may have run before', async (_, answer) => { + vi.mocked(instanceClient.post).mockImplementationOnce(async (_url, body) => { + answerAsNode.call(node, body as { operation?: unknown; envelope?: unknown }); + return answer(); + }); - await expect(runSealedOperation({ instanceClient, op, key })).rejects.toThrow( - 'did not answer add_user with a sealed response', - ); + await expect(runSealedOperation({ instanceClient, op, key })).rejects.toBeInstanceOf(UnreadableSealedAnswerError); }); }); diff --git a/src/integrations/api/instance/sealedOperation.ts b/src/integrations/api/instance/sealedOperation.ts index 61d0d6911..e57b91d03 100644 --- a/src/integrations/api/instance/sealedOperation.ts +++ b/src/integrations/api/instance/sealedOperation.ts @@ -22,6 +22,17 @@ export class SealedOperationError extends Error { } } +/** The request went out, but the answer was missing, malformed or not this request's: the operation may have run. */ +export class UnreadableSealedAnswerError extends Error { + operation: string; + + constructor(operation: string, cause: unknown) { + super(`The cluster's answer to ${operation} could not be read.`, { cause }); + this.name = 'UnreadableSealedAnswerError'; + this.operation = operation; + } +} + export function isSealedRefusal(error: unknown, status: number, message: string): boolean { return error instanceof SealedOperationError && error.status === status && error.message === message; } @@ -73,7 +84,11 @@ export async function runSealedOperation( const detail = refusal?.data as | { server_time?: unknown; custody_fingerprint?: unknown; encrypted_response?: unknown } | undefined; - if (refusal?.status === 400 && typeof detail?.server_time === 'number' && !clockRetried) { + if (refusal?.status === 400 && typeof detail?.server_time === 'number') { + if (clockRetried) { + clockOffsetsMs.delete(node); + throw error; + } clockOffsetsMs.set(node, detail.server_time - Date.now()); clockRetried = true; continue; @@ -90,9 +105,14 @@ export async function runSealedOperation( } const payload = (data as { encrypted_response?: unknown } | null | undefined)?.encrypted_response; if (!payload) { - throw new Error(`The cluster did not answer ${op.operation} with a sealed response.`); + throw new UnreadableSealedAnswerError(op.operation, new Error('The answer was not sealed.')); + } + let result: SealedResult; + try { + result = await openSealedResponse(payload, responseKey, nonce); + } catch (error) { + throw new UnreadableSealedAnswerError(op.operation, error); } - const result = await openSealedResponse(payload, responseKey, nonce); if (result.status >= 400) { throw new SealedOperationError(op.operation, result); } diff --git a/src/lib/crypto/sealedOperation.test.ts b/src/lib/crypto/sealedOperation.test.ts index 26ccee2cd..baf0d1c00 100644 --- a/src/lib/crypto/sealedOperation.test.ts +++ b/src/lib/crypto/sealedOperation.test.ts @@ -10,8 +10,8 @@ import { RESPONSE_KEY_BYTES, sealOperation as referenceSealOperation, sealResponse, -} from './__tests__/harper-v5.4.0/sealedOperation.ts'; -import { decryptEnvelope, fingerprintOf, parseEnvelopeFields } from './__tests__/harper-v5.4.0/secretEnvelope.ts'; +} from './__tests__/harper-v5.4.0/sealedOperation'; +import { decryptEnvelope, fingerprintOf, parseEnvelopeFields } from './__tests__/harper-v5.4.0/secretEnvelope'; import { ENV_ENCRYPTED_PREFIX } from './envSecret'; import { openSealedResponse, SEALED_OPERATION_VERSION, sealOperation } from './sealedOperation'; @@ -95,7 +95,6 @@ describe('openSealedResponse', () => { const { payload, responseKey, nonce } = await sealedByTheNode(result); expect(await openSealedResponse(payload, responseKey, nonce)).toEqual(result); - // and reads it the same way the reference does expect(openResponse(payload, Buffer.from(responseKey), nonce)).toEqual(result); }); diff --git a/src/lib/crypto/sealedOperation.ts b/src/lib/crypto/sealedOperation.ts index c0fff41eb..7a611bee5 100644 --- a/src/lib/crypto/sealedOperation.ts +++ b/src/lib/crypto/sealedOperation.ts @@ -4,8 +4,7 @@ * this client chose, so a relay sees ciphertext both ways. The wire format is harper's `utility/sealedOperation.ts`; * `__tests__/harper-v5.4.0/` keeps that reference unchanged, and the tests open with it what this seals. * - * Sealed mode only: the whole operation is inside the envelope. Fields mode, which leaves chosen keys visible to a - * relay, is not needed by any caller yet. + * Sealed mode only: the whole operation is inside the envelope. */ import { ab, encryptEnvelope, fromBase64, requireSubtle, toBase64 } from './envSecret'; diff --git a/src/react-query/queryClient.test.ts b/src/react-query/queryClient.test.ts index 7a56b3e10..825e15dfa 100644 --- a/src/react-query/queryClient.test.ts +++ b/src/react-query/queryClient.test.ts @@ -1,6 +1,6 @@ import { UnconfirmedWriteError } from '@/features/instance/extensions/dataSource'; import { ImportJobError, ImportJobUnconfirmedError } from '@/integrations/api/instance/database/getJob'; -import { SealedOperationError } from '@/integrations/api/instance/sealedOperation'; +import { SealedOperationError, UnreadableSealedAnswerError } from '@/integrations/api/instance/sealedOperation'; import { RESTART_UNCONFIRMED_MESSAGE, RESTART_UNCONFIRMED_TITLE, @@ -464,6 +464,12 @@ describe('a write that got no verdict', () => { expect(shouldToastOwnFailure(executed)).toBe(false); }); + it('includes a sealed operation whose answer could not be read', () => { + const unreadable = new UnreadableSealedAnswerError('drop_user', new Error('tag')); + expect(describeError(unreadable)).toMatchObject({ title: OUTCOME_UNKNOWN_TITLE }); + expect(shouldToastOwnFailure(unreadable)).toBe(false); + }); + it("describes a sealed operation's own refusal by its text, as a plain failure", () => { const refused = new SealedOperationError('add_user', { status: 409, body: { error: 'User x already exists' } }); expect(describeError(refused)).toMatchObject({ description: 'User x already exists' }); diff --git a/src/react-query/queryClient.ts b/src/react-query/queryClient.ts index 3dab9daa8..5b88c6afe 100644 --- a/src/react-query/queryClient.ts +++ b/src/react-query/queryClient.ts @@ -7,7 +7,7 @@ import { } from '@/integrations/api/cluster/clusterHeldByWorkflow'; import { BackupJobUnreportedError } from '@/integrations/api/instance/backups/backups'; import { describeImportJobUnconfirmed, ImportJobUnconfirmedError } from '@/integrations/api/instance/database/getJob'; -import { SealedOperationError } from '@/integrations/api/instance/sealedOperation'; +import { SealedOperationError, UnreadableSealedAnswerError } from '@/integrations/api/instance/sealedOperation'; import { RESTART_UNCONFIRMED_MESSAGE, RESTART_UNCONFIRMED_TITLE, @@ -55,6 +55,9 @@ function describeUnknownOutcome(rawErr: unknown): DescribedError | undefined { `The cluster ran ${rawErr.operation} but could not return its result. ${UNCONFIRMED_WRITE_ADVICE}`, ); } + if (rawErr instanceof UnreadableSealedAnswerError) { + return copy(OUTCOME_UNKNOWN_TITLE, `${rawErr.message} ${UNCONFIRMED_WRITE_ADVICE}`); + } return undefined; } From 07fa3cdf082970d2f20e61694b0241308765826c Mon Sep 17 00:00:00 2001 From: Devin Holland <50112339+Devin-Holland@users.noreply.github.com> Date: Mon, 16 Nov 2026 15:36:16 -0500 Subject: [PATCH 4/7] fix(cluster): keep a replacement connection past the form, and widen 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 --- src/features/cluster/FinishSetup.test.tsx | 18 +++++++++------ src/features/cluster/FinishSetup.tsx | 5 +++- src/features/cluster/sealedSetup.test.ts | 4 +++- src/features/cluster/sealedSetup.ts | 23 +++++++++++++++---- .../useInstanceResetPasswordMutation.test.tsx | 2 +- .../auth/useInstanceResetPasswordMutation.ts | 4 ++-- .../api/instance/sealedOperation.test.ts | 3 +-- src/lib/crypto/sealedOperation.test.ts | 4 +--- src/react-query/queryClient.test.ts | 8 +++++++ src/react-query/queryClient.ts | 6 +++-- 10 files changed, 53 insertions(+), 24 deletions(-) diff --git a/src/features/cluster/FinishSetup.test.tsx b/src/features/cluster/FinishSetup.test.tsx index 88301abf4..8187fc8cc 100644 --- a/src/features/cluster/FinishSetup.test.tsx +++ b/src/features/cluster/FinishSetup.test.tsx @@ -99,7 +99,7 @@ describe(FinishSetup, () => { await createAdminUser(); await waitFor(() => expect(toastSuccess).toHaveBeenCalledTimes(1)); expect(toastSuccess).toHaveBeenCalledWith('Admin user created. Connect to your cluster to continue.'); - expect(setUser).toHaveBeenCalledWith(expect.objectContaining({ id: 'clu-1' }), null); + expect(setUser).not.toHaveBeenCalled(); }); it('hands setup the sealed capability once every member runs 5.4.0 and holds the cluster key, and nothing otherwise', async () => { @@ -115,15 +115,19 @@ describe(FinishSetup, () => { cleanup(); mutate.mockClear(); - await createAdminUser(); + await createAdminUser({ instances: [{ id: 'ins-1', status: 'RUNNING', version: '5.3.0' }] }); await waitFor(() => expect(mutate).toHaveBeenCalledTimes(1)); expect(mutate.mock.calls[0][0]).toMatchObject({ sealedSetup: undefined, clusterKeyPending: false }); - cleanup(); - mutate.mockClear(); - await createAdminUser({ instances: [{ id: 'ins-1', status: 'RUNNING', version: '5.4.0' }] }); - await waitFor(() => expect(mutate).toHaveBeenCalledTimes(1)); - expect(mutate.mock.calls[0][0]).toMatchObject({ sealedSetup: undefined, clusterKeyPending: true }); + for ( + const instances of [[{ id: 'ins-1', status: 'RUNNING', version: '5.4.0' }], [{ id: 'ins-1', status: 'RUNNING' }]] + ) { + cleanup(); + mutate.mockClear(); + await createAdminUser({ instances }); + await waitFor(() => expect(mutate).toHaveBeenCalledTimes(1)); + expect(mutate.mock.calls[0][0]).toMatchObject({ sealedSetup: undefined, clusterKeyPending: true }); + } }); it('hands setup the direct URL and every id it must sign out first', async () => { diff --git a/src/features/cluster/FinishSetup.tsx b/src/features/cluster/FinishSetup.tsx index 0733ee549..73916e661 100644 --- a/src/features/cluster/FinishSetup.tsx +++ b/src/features/cluster/FinishSetup.tsx @@ -91,7 +91,10 @@ export function FinishSetup() { ? "Admin user created. You're now signed in to your cluster." : 'Admin user created. Connect to your cluster to continue.', ); - authStore.setUserForEntity(cluster!, user); + // Signed out, the mutation already cleared the store, and a connect that replaced setup's own must be kept. + if (user) { + authStore.setUserForEntity(cluster!, user); + } // The mutation already told CM the password changed (resetPasswordUpdater); reflect // that in the cached cluster before navigating so ClusterHome's resetPassword guard // doesn't bounce us back here off a stale poll. diff --git a/src/features/cluster/sealedSetup.test.ts b/src/features/cluster/sealedSetup.test.ts index 6be232e33..ef79ea4e4 100644 --- a/src/features/cluster/sealedSetup.test.ts +++ b/src/features/cluster/sealedSetup.test.ts @@ -53,8 +53,10 @@ describe(sealedSetupCapability, () => { expect(sealedSetupCapability(cluster([{ version: '5.4.0' }], 'self-hosted-free'))).toBeNull(); }); - it('reports the key pending only where the members could seal but do not all hold one key', () => { + it('reports the key pending where the members could seal, or have no version yet, but do not all hold one key', () => { expect(clusterKeyPending(cluster([{ version: '5.4.0', secretsKeyFingerprint: null }]))).toBe(true); + expect(clusterKeyPending(cluster([{ version: undefined, secretsKeyFingerprint: null }]))).toBe(true); + expect(clusterKeyPending(cluster([{ version: undefined }, { version: '5.4.0' }]))).toBe(true); expect(clusterKeyPending(cluster([{ version: '5.4.0' }, { version: '5.4.0', secretsKeyFingerprint: 'fp-2' }]))) .toBe(true); expect(clusterKeyPending(cluster([{ version: '5.4.0' }]))).toBe(false); diff --git a/src/features/cluster/sealedSetup.ts b/src/features/cluster/sealedSetup.ts index d5ec4e856..977eea2d5 100644 --- a/src/features/cluster/sealedSetup.ts +++ b/src/features/cluster/sealedSetup.ts @@ -28,20 +28,33 @@ export function sealedSetupCapability(cluster: Cluster | undefined): SealedSetup : null; } -/** The members could seal, but central manager has not stamped one key on all of them yet. */ +/** + * The members could seal, or have not said yet, but the record does not carry what sealing needs: a version for every + * member and one key stamped on all of them. Central manager fills both in; a submit before that is not a permission + * problem. + */ export function clusterKeyPending(cluster: Cluster | undefined): boolean { - return !!liveMembersAbleToSeal(cluster) && sealedSetupCapability(cluster) === null; + const live = liveMembers(cluster); + return !!live + && live.every((instance) => !instance.version || wasAReleasedBeforeB(SEALED_SETUP_MIN_VERSION, instance.version)) + && sealedSetupCapability(cluster) === null; } -function liveMembersAbleToSeal(cluster: Cluster | undefined): Instance[] | null { +function liveMembers(cluster: Cluster | undefined): Instance[] | null { if (!cluster || clusterIsSelfManaged(cluster)) { return null; } const live = (cluster.instances ?? []).filter( (instance) => !(instance.status && deletedClusterStatuses.includes(instance.status)), ); - return live.length > 0 - && live.every((instance) => !!instance.version && wasAReleasedBeforeB(SEALED_SETUP_MIN_VERSION, instance.version)) + return live.length > 0 ? live : null; +} + +function liveMembersAbleToSeal(cluster: Cluster | undefined): Instance[] | null { + const live = liveMembers(cluster); + return live?.every((instance) => + !!instance.version && wasAReleasedBeforeB(SEALED_SETUP_MIN_VERSION, instance.version) + ) ? live : null; } diff --git a/src/integrations/api/instance/auth/useInstanceResetPasswordMutation.test.tsx b/src/integrations/api/instance/auth/useInstanceResetPasswordMutation.test.tsx index b03709a45..3898e71f8 100644 --- a/src/integrations/api/instance/auth/useInstanceResetPasswordMutation.test.tsx +++ b/src/integrations/api/instance/auth/useInstanceResetPasswordMutation.test.tsx @@ -816,7 +816,7 @@ describe('sealed setup on a 5.4.0+ cluster', () => { it('says the key is still on its way when a 5.4 cluster has no temporary password and no key on every member', async () => { await expect(resetPassword(OWNER, { tempPassword: undefined, clusterKeyPending: true })).rejects.toThrow( - "secrets key hasn't reached every member yet", + "hasn't reported every member's Harper version and secrets key yet", ); await expect(resetPassword(OWNER, { tempPassword: undefined })).rejects.toThrow('may not have permission'); expect(onInstanceLoginSubmit).not.toHaveBeenCalled(); diff --git a/src/integrations/api/instance/auth/useInstanceResetPasswordMutation.ts b/src/integrations/api/instance/auth/useInstanceResetPasswordMutation.ts index b3b1817ee..1120371d9 100644 --- a/src/integrations/api/instance/auth/useInstanceResetPasswordMutation.ts +++ b/src/integrations/api/instance/auth/useInstanceResetPasswordMutation.ts @@ -26,7 +26,7 @@ interface InstanceResetPasswordParams { newPassword: string; tempPassword: string | undefined; sealedSetup?: SealedSetupCapability; - /** Every live member could seal, but central manager has not stamped the cluster key on all of them yet. */ + /** The members could seal, but central manager has not filled in a version and one key for all of them yet. */ clusterKeyPending?: boolean; } @@ -60,7 +60,7 @@ async function finishSetupWithTemporaryPassword({ if (!tempPassword) { throw new Error( clusterKeyPending - ? "The cluster's secrets key hasn't reached every member yet, so the admin user can't be created. Try again in a moment." + ? "The cluster hasn't reported every member's Harper version and secrets key yet, so the admin user can't be created. Try again in a moment." : 'You may not have permission to set the password on this cluster.', ); } diff --git a/src/integrations/api/instance/sealedOperation.test.ts b/src/integrations/api/instance/sealedOperation.test.ts index 6bcbcc691..e69d5299c 100644 --- a/src/integrations/api/instance/sealedOperation.test.ts +++ b/src/integrations/api/instance/sealedOperation.test.ts @@ -1,6 +1,5 @@ // @vitest-environment node -// A fake 5.4 node built from Harper's own reference client (copied unchanged under src/lib/crypto/__tests__): it opens -// what the helper seals and seals what the helper opens, and refuses the way `components/encryptedOperation.ts` does. +// A fake 5.4 node built from Harper's reference client; it refuses the way `components/encryptedOperation.ts` does. import { sealResponse } from '@/lib/crypto/__tests__/harper-v5.4.0/sealedOperation'; import { decryptEnvelope, diff --git a/src/lib/crypto/sealedOperation.test.ts b/src/lib/crypto/sealedOperation.test.ts index baf0d1c00..20a8ceb30 100644 --- a/src/lib/crypto/sealedOperation.test.ts +++ b/src/lib/crypto/sealedOperation.test.ts @@ -1,7 +1,5 @@ // @vitest-environment node -// Node env: Web Crypto (globalThis.crypto.subtle, used by the helper) and node:crypto (used by Harper's reference) are -// both available. The reference under __tests__/harper-v5.4.0/ is the node's own client, copied unchanged from -// HarperFast/harper at v5.4.0, so what this opens is what the node accepts and what it answers. +// Node env: Web Crypto (the helper) and node:crypto (Harper's reference client, see __tests__/harper-v5.4.0/README.md). import { generateKeyPairSync } from 'node:crypto'; import { describe, expect, it } from 'vitest'; import { diff --git a/src/react-query/queryClient.test.ts b/src/react-query/queryClient.test.ts index 825e15dfa..4436a01d4 100644 --- a/src/react-query/queryClient.test.ts +++ b/src/react-query/queryClient.test.ts @@ -470,6 +470,14 @@ describe('a write that got no verdict', () => { expect(shouldToastOwnFailure(unreadable)).toBe(false); }); + it('leaves a sealed read that may have run to the usual extraction', () => { + const unreadable = new UnreadableSealedAnswerError('list_users', new Error('tag')); + expect(describeError(unreadable)).toMatchObject({ description: unreadable.message }); + expect(shouldToastOwnFailure(unreadable)).toBe(true); + const executed = new SealedOperationError('list_users', { status: 500, body: {}, executed: true }); + expect(shouldToastOwnFailure(executed)).toBe(true); + }); + it("describes a sealed operation's own refusal by its text, as a plain failure", () => { const refused = new SealedOperationError('add_user', { status: 409, body: { error: 'User x already exists' } }); expect(describeError(refused)).toMatchObject({ description: 'User x already exists' }); diff --git a/src/react-query/queryClient.ts b/src/react-query/queryClient.ts index 5b88c6afe..e927671a0 100644 --- a/src/react-query/queryClient.ts +++ b/src/react-query/queryClient.ts @@ -13,6 +13,7 @@ import { RESTART_UNCONFIRMED_TITLE, RestartUnconfirmedError, } from '@/integrations/api/instance/status/restartUnconfirmed'; +import { isReadOperation } from '@/integrations/api/isReadOperation'; import { isUnansweredWrite, OUTCOME_UNKNOWN_TITLE, UNANSWERED_WRITE_MESSAGE } from '@/integrations/api/unansweredWrite'; import { errorText } from '@/lib/errorText'; import { isRestartNoise } from '@/lib/restart/restartGate'; @@ -49,13 +50,14 @@ function describeUnknownOutcome(rawErr: unknown): DescribedError | undefined { if (rawErr instanceof BackupJobUnreportedError) { return copy(OUTCOME_UNKNOWN_TITLE, rawErr.message); } - if (rawErr instanceof SealedOperationError && rawErr.executed) { + // A sealed read that may have run is only a failed read; a sealed write that may have run is an unknown outcome. + if (rawErr instanceof SealedOperationError && rawErr.executed && !isReadOperation(rawErr.operation)) { return copy( OUTCOME_UNKNOWN_TITLE, `The cluster ran ${rawErr.operation} but could not return its result. ${UNCONFIRMED_WRITE_ADVICE}`, ); } - if (rawErr instanceof UnreadableSealedAnswerError) { + if (rawErr instanceof UnreadableSealedAnswerError && !isReadOperation(rawErr.operation)) { return copy(OUTCOME_UNKNOWN_TITLE, `${rawErr.message} ${UNCONFIRMED_WRITE_ADVICE}`); } return undefined; From b10de64c60f8e9d1b10f1ddb30e37d9d00de7bba Mon Sep 17 00:00:00 2001 From: Devin Holland <50112339+Devin-Holland@users.noreply.github.com> Date: Mon, 16 Nov 2026 17:17:44 -0500 Subject: [PATCH 5/7] feat(cluster): seal Finish Setup in fields mode so the proxy log shows 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 --- src/features/cluster/DESIGN.md | 5 +- .../useInstanceResetPasswordMutation.test.tsx | 5 ++ .../auth/useInstanceResetPasswordMutation.ts | 13 ++- .../api/instance/sealedOperation.test.ts | 52 +++++++++++- .../api/instance/sealedOperation.ts | 14 +++- src/lib/crypto/sealedOperation.test.ts | 80 ++++++++++++++++++ src/lib/crypto/sealedOperation.ts | 82 +++++++++++++++++-- 7 files changed, 236 insertions(+), 15 deletions(-) diff --git a/src/features/cluster/DESIGN.md b/src/features/cluster/DESIGN.md index 33ec96a72..ae99ea230 100644 --- a/src/features/cluster/DESIGN.md +++ b/src/features/cluster/DESIGN.md @@ -107,7 +107,10 @@ on its way, not a permission problem. Every write goes through `getInstanceClient({ forceFabricConnect: true })` as `encrypted_operation` ([`runSealedOperation`](../../integrations/api/instance/sealedOperation.ts), over [`lib/crypto/sealedOperation.ts`](../../lib/crypto/sealedOperation.ts), whose tests open what it seals with Harper's -own reference client, copied unchanged from v5.4.0): `add_user` (or `alter_user` when the form names `HDB_ADMIN`), then +own reference client, copied unchanged from v5.4.0), in fields mode: central manager's proxy log shows each request's +`operation`, `role` and `active`, so it records what setup ran, while `username` and `password` travel as sealed +values bound to their place in the operation, and the operation text is bound to the envelope by its hash. The calls +are `add_user` (or `alter_user` when the form names `HDB_ADMIN`), then `create_authentication_tokens` with the typed username and password, then `drop_user HDB_ADMIN`, then the PATCH. The mint comes before the drop and carries the credentials on purpose: the node checks the password and names that user, so the tokens are the admin's whatever other super users an earlier attempt left, and a wrong password stops setup while diff --git a/src/integrations/api/instance/auth/useInstanceResetPasswordMutation.test.tsx b/src/integrations/api/instance/auth/useInstanceResetPasswordMutation.test.tsx index 3898e71f8..c645b908a 100644 --- a/src/integrations/api/instance/auth/useInstanceResetPasswordMutation.test.tsx +++ b/src/integrations/api/instance/auth/useInstanceResetPasswordMutation.test.tsx @@ -660,6 +660,9 @@ describe('sealed setup on a 5.4.0+ cluster', () => { { operation: 'drop_user', username: defaultClusterUsername }, ]); expect(runSealedOperation.mock.calls[0][0]).toMatchObject({ key: CLUSTER_KEY }); + for (const [params] of runSealedOperation.mock.calls) { + expect(params).toMatchObject({ mode: 'fields', visibleFields: ['role', 'active'] }); + } for (const instanceClient of sealedNode.clients) { expect(instanceClient.defaults.baseURL).toContain('/Cluster/clu-1/operation'); } @@ -674,6 +677,7 @@ describe('sealed setup on a 5.4.0+ cluster', () => { expect(user?.username).toBe(defaultClusterUsername); expect(sealedNode.operations).toEqual(['alter_user', 'create_authentication_tokens']); + expect(runSealedOperation.mock.calls.every(([params]) => params.mode === 'fields')).toBe(true); expect(sealedNode.users.get(defaultClusterUsername)?.password).toBe('new-password'); expect(resetPasswordUpdater).toHaveBeenCalledTimes(1); expectNothingDirect(); @@ -693,6 +697,7 @@ describe('sealed setup on a 5.4.0+ cluster', () => { 'drop_user', ]); expect(sealedNode.users.get(OWNER)?.password).toBe('new-password'); + expect(runSealedOperation.mock.calls.every(([params]) => params.mode === 'fields')).toBe(true); expect(resetPasswordUpdater).toHaveBeenCalledTimes(1); }); diff --git a/src/integrations/api/instance/auth/useInstanceResetPasswordMutation.ts b/src/integrations/api/instance/auth/useInstanceResetPasswordMutation.ts index 1120371d9..9d908011a 100644 --- a/src/integrations/api/instance/auth/useInstanceResetPasswordMutation.ts +++ b/src/integrations/api/instance/auth/useInstanceResetPasswordMutation.ts @@ -156,6 +156,8 @@ async function finishSetupWithTemporaryPassword({ return loginResponse; } +const SETUP_VISIBLE_FIELDS = ['role', 'active']; + function clusterKeyQuery(clusterId: string) { return secretsPublicKeyQueryOptions({ entityId: clusterId, @@ -190,8 +192,17 @@ async function finishSetupSealed( } const instanceClient = getInstanceClient({ id: clusterId, forceFabricConnect: true }); const refreshKey = async () => (key = await refetchClusterKey(queryClient, clusterId)); + // Fields mode, so central manager's proxy log records which operation ran; usernames and passwords stay sealed. const seal = (op: SealableOperation) => - runSealedOperation({ instanceClient, op, key, refreshKey, actor: 'Studio Finish Setup' }); + runSealedOperation({ + instanceClient, + op, + key, + refreshKey, + actor: 'Studio Finish Setup', + mode: 'fields', + visibleFields: SETUP_VISIBLE_FIELDS, + }); if (desiredUsername === defaultClusterUsername) { await seal({ operation: 'alter_user', username: desiredUsername, password: newPassword }); diff --git a/src/integrations/api/instance/sealedOperation.test.ts b/src/integrations/api/instance/sealedOperation.test.ts index e69d5299c..a7f98062f 100644 --- a/src/integrations/api/instance/sealedOperation.test.ts +++ b/src/integrations/api/instance/sealedOperation.test.ts @@ -1,6 +1,6 @@ // @vitest-environment node // A fake 5.4 node built from Harper's reference client; it refuses the way `components/encryptedOperation.ts` does. -import { sealResponse } from '@/lib/crypto/__tests__/harper-v5.4.0/sealedOperation'; +import { hashOperationText, openValue, sealResponse } from '@/lib/crypto/__tests__/harper-v5.4.0/sealedOperation'; import { decryptEnvelope, fingerprintOf, @@ -56,7 +56,8 @@ const node = { body: { message: `${op.operation} ran` }, }), requests: [] as unknown[], - answer(body: { operation?: unknown; envelope?: unknown }) { + opened: [] as unknown[], + answer(body: { operation?: unknown; envelope?: unknown; mode?: unknown; op?: unknown }) { this.requests.push(body); if (body.operation !== 'encrypted_operation' || typeof body.envelope !== 'string') { throw refusal(400, { error: 'The request is malformed' }); @@ -76,8 +77,23 @@ const node = { if (Math.abs(now - header.ts) > MAX_AGE_MS) { throw refusal(400, { error: 'The sealed request is outside the accepted time window', server_time: now }); } - const result = this.execute(header.op); - return { encrypted_response: sealResponse(JSON.stringify(result), Buffer.from(header.rk, 'base64'), header.nonce) }; + const responseKey = Buffer.from(header.rk, 'base64'); + let inner = header.op; + if (body.mode === 'fields') { + if (typeof body.op !== 'string' || hashOperationText(body.op) !== header.oph) { + throw refusal(400, { error: 'The visible operation does not match the sealed request' }); + } + inner = Object.fromEntries( + Object.entries(JSON.parse(body.op) as Record).map(([field, value]) => [ + field, + value?.$sealed ? openValue(value.$sealed, responseKey, header.nonce, `/${field}`) : value, + ]), + ); + } + this.opened.push(inner); + const result = this.execute(inner); + const encrypted_response = sealResponse(JSON.stringify(result), responseKey, header.nonce); + return body.mode === 'fields' ? { status: result.status, encrypted_response } : { encrypted_response }; }, }; @@ -102,6 +118,7 @@ beforeEach(() => { node.custody = true; node.execute = (inner) => ({ status: 200, body: { message: `${inner.operation} ran` } }); node.requests = []; + node.opened = []; node.answer = answerAsNode; _resetClockOffsetsForTests(); }); @@ -122,6 +139,33 @@ describe(runSealedOperation, () => { expect(JSON.stringify(node.requests)).not.toContain('secret-password'); }); + it('in fields mode, shows the relay the operation and chosen keys, and the node opens the rest', async () => { + const result = await runSealedOperation({ + instanceClient, + op, + key, + mode: 'fields', + visibleFields: ['role'], + }); + + expect(result).toEqual({ status: 200, body: { message: 'add_user ran' } }); + expect(node.opened).toEqual([op]); + const [sent] = node.requests as Array<{ mode: string; op: string }>; + expect(sent.mode).toBe('fields'); + expect(JSON.parse(sent.op)).toMatchObject({ operation: 'add_user', role: 'super_user' }); + expect(JSON.stringify(node.requests)).not.toContain('secret-password'); + expect(JSON.stringify(node.requests)).not.toContain('owner@example.com'); + }); + + it('in fields mode, still retries once on a clock refusal with a freshly sealed request', async () => { + node.clockSkewMs = 10 * 60_000; + + await runSealedOperation({ instanceClient, op, key, mode: 'fields', visibleFields: ['role'] }); + + expect(node.requests).toHaveLength(2); + expect(node.opened).toEqual([op]); + }); + it("throws the operation's own failure, with its status and body", async () => { node.execute = () => ({ status: 409, body: { error: 'User owner@example.com already exists' } }); diff --git a/src/integrations/api/instance/sealedOperation.ts b/src/integrations/api/instance/sealedOperation.ts index e57b91d03..abdb6d7d1 100644 --- a/src/integrations/api/instance/sealedOperation.ts +++ b/src/integrations/api/instance/sealedOperation.ts @@ -1,7 +1,13 @@ import { InstanceClientConfig } from '@/config/instanceClientConfig'; import { SecretsPublicKey } from '@/integrations/api/instance/secrets/secrets'; import { rejectReplicationFailures, ReplicatedResponse } from '@/integrations/api/replication'; -import { openSealedResponse, SealableOperation, SealedResult, sealOperation } from '@/lib/crypto/sealedOperation'; +import { + openSealedResponse, + SealableOperation, + SealedMode, + SealedResult, + sealOperation, +} from '@/lib/crypto/sealedOperation'; import { isAxiosError } from 'axios'; /** The sealed operation ran and answered a failure. */ @@ -44,6 +50,8 @@ interface RunSealedOperationParams extends InstanceClientConfig { refreshKey?: () => Promise; /** Attribution for the node's log. */ actor?: string; + mode?: SealedMode; + visibleFields?: readonly string[]; } // The node accepts a timestamp only within its window around its own clock. A refusal names that clock, and the @@ -62,7 +70,7 @@ export function _resetClockOffsetsForTests(): void { * and a replicated write some peer refused as the direct path refuses it. */ export async function runSealedOperation( - { instanceClient, op, key, refreshKey, actor }: RunSealedOperationParams, + { instanceClient, op, key, refreshKey, actor, mode, visibleFields }: RunSealedOperationParams, ): Promise { const node = instanceClient.defaults.baseURL ?? ''; let currentKey = key; @@ -75,6 +83,8 @@ export async function runSealedOperation( kid: currentKey.fingerprint, actor, now: Date.now() + (clockOffsetsMs.get(node) ?? 0), + mode, + visibleFields, }); let data: unknown; try { diff --git a/src/lib/crypto/sealedOperation.test.ts b/src/lib/crypto/sealedOperation.test.ts index 20a8ceb30..4e94aa35e 100644 --- a/src/lib/crypto/sealedOperation.test.ts +++ b/src/lib/crypto/sealedOperation.test.ts @@ -3,8 +3,10 @@ import { generateKeyPairSync } from 'node:crypto'; import { describe, expect, it } from 'vitest'; import { + hashOperationText, NONCE_BYTES, openResponse, + openValue, RESPONSE_KEY_BYTES, sealOperation as referenceSealOperation, sealResponse, @@ -82,6 +84,84 @@ describe('sealOperation', () => { }); }); +describe('sealOperation in fields mode', () => { + const visibleFields = ['role', 'active']; + const sealFields = (operation: Record & { operation: string } = op) => + sealOperation({ op: operation, publicKey: publicKeyPem, kid, mode: 'fields', visibleFields }); + + it('sends the operation as readable text with only the chosen keys in the clear', async () => { + const { request } = await sealFields(); + + expect(Object.keys(request)).toEqual(['operation', 'mode', 'op', 'envelope']); + expect(request).toMatchObject({ operation: 'encrypted_operation', mode: 'fields' }); + const visible = JSON.parse((request as { op: string }).op); + expect(Object.keys(visible)).toEqual(Object.keys(op)); + expect(visible).toMatchObject({ operation: 'add_user', role: 'super_user', active: true }); + expect(Object.keys(visible.username)).toEqual(['$sealed']); + expect(Object.keys(visible.password)).toEqual(['$sealed']); + for (const secret of [op.username, op.password]) { + expect(JSON.stringify(request)).not.toContain(secret); + } + }); + + it("binds the text to the envelope by the reference's hash, and carries no operation in the header", async () => { + const { request, responseKey, nonce } = await sealFields(); + const header = openHeader(request.envelope); + + expect(header).not.toHaveProperty('op'); + expect(header).toEqual({ + v: SEALED_OPERATION_VERSION, + rk: Buffer.from(responseKey).toString('base64'), + nonce, + ts: expect.any(Number), + oph: hashOperationText((request as { op: string }).op), + }); + }); + + it('seals each leaf so the reference opens it only at its own location and under its own nonce', async () => { + const { request, responseKey, nonce } = await sealFields(); + const visible = JSON.parse((request as { op: string }).op); + const rk = Buffer.from(responseKey); + + expect(openValue(visible.username.$sealed, rk, nonce, '/username')).toBe(op.username); + expect(openValue(visible.password.$sealed, rk, nonce, '/password')).toBe(op.password); + expect(() => openValue(visible.username.$sealed, rk, nonce, '/password')).toThrow(); + const other = await sealFields(); + expect(() => openValue(visible.password.$sealed, rk, other.nonce, '/password')).toThrow(); + }); + + it('escapes a key into its JSON Pointer token the way the reference does', async () => { + const awkward = { operation: 'insert', 'a/b~c': { nested: [1, 'two'] } }; + const { request, responseKey, nonce } = await sealFields(awkward); + const visible = JSON.parse((request as { op: string }).op); + + expect(openValue(visible['a/b~c'].$sealed, Buffer.from(responseKey), nonce, '/a~1b~0c')).toEqual({ + nested: [1, 'two'], + }); + }); + + it('leaves the same keys readable as the reference client by default', async () => { + const tableOp = { operation: 'insert', database: 'data', table: 'dog', records: [{ id: 1 }] }; + const ours = JSON.parse( + ((await sealOperation({ op: tableOp, publicKey: publicKeyPem, kid, mode: 'fields' })).request as { op: string }) + .op, + ); + const theirs = JSON.parse( + referenceSealOperation({ op: tableOp, publicKey: publicKeyPem, kid, mode: 'fields' }).request.op as string, + ); + const shape = (value: Record) => + Object.fromEntries( + Object.entries(value).map(([k, v]) => [k, (v as { $sealed?: string })?.$sealed ? 'sealed' : v]), + ); + + expect(shape(ours)).toEqual(shape(theirs)); + }); + + it('refuses a value with no JSON form rather than sending a leaf the node cannot open', async () => { + await expect(sealFields({ operation: 'add_user', username: undefined })).rejects.toThrow('/username'); + }); +}); + describe('openSealedResponse', () => { async function sealedByTheNode(result: object) { const { responseKey, nonce } = await sealOperation({ op, publicKey: publicKeyPem, kid }); diff --git a/src/lib/crypto/sealedOperation.ts b/src/lib/crypto/sealedOperation.ts index 7a611bee5..a41f77465 100644 --- a/src/lib/crypto/sealedOperation.ts +++ b/src/lib/crypto/sealedOperation.ts @@ -4,7 +4,9 @@ * this client chose, so a relay sees ciphertext both ways. The wire format is harper's `utility/sealedOperation.ts`; * `__tests__/harper-v5.4.0/` keeps that reference unchanged, and the tests open with it what this seals. * - * Sealed mode only: the whole operation is inside the envelope. + * Two modes, as the node offers them. `sealed` puts the whole operation inside the envelope. `fields` sends the operation + * as JSON text a relay can read, with chosen values replaced by sealed leaves, and binds that text to the envelope by + * its hash (`oph`), so a relay can record what ran but can neither read nor alter the sealed values. */ import { ab, encryptEnvelope, fromBase64, requireSubtle, toBase64 } from './envSecret'; @@ -14,12 +16,21 @@ const NONCE_BYTES = 16; const IV_BYTES = 12; const TAG_BYTES = 16; const RESPONSE_AAD_PREFIX = 'harper.encrypted_operation.response:'; +const FIELD_AAD_PREFIX = 'harper.encrypted_operation.field:'; +const SEALED_LEAF_KEY = '$sealed'; +const DEFAULT_VISIBLE_FIELDS: readonly string[] = ['database', 'schema', 'table']; export type SealableOperation = Record & { operation: string }; +export type SealedMode = 'sealed' | 'fields'; + +type SealedOperationRequest = + | { operation: 'encrypted_operation'; envelope: string } + | { operation: 'encrypted_operation'; mode: 'fields'; op: string; envelope: string }; + interface SealedOperation { - request: { operation: 'encrypted_operation'; envelope: string }; - /** The key the node seals its answer with. */ + request: SealedOperationRequest; + /** The key the node seals its answer, and any sealed leaf, with. */ responseKey: Uint8Array; nonce: string; } @@ -40,23 +51,80 @@ interface SealOperationOptions { actor?: string; /** The client's clock in milliseconds; the node accepts it only within its window. */ now?: number; + mode?: SealedMode; + /** Fields mode: the top-level keys left readable besides `operation`; every other top-level value is sealed. */ + visibleFields?: readonly string[]; } export async function sealOperation( - { op, publicKey, kid, actor, now = Date.now() }: SealOperationOptions, + { op, publicKey, kid, actor, now = Date.now(), mode = 'sealed', visibleFields = DEFAULT_VISIBLE_FIELDS }: + SealOperationOptions, ): Promise { const responseKey = crypto.getRandomValues(new Uint8Array(RESPONSE_KEY_BYTES)); const nonce = toBase64(crypto.getRandomValues(new Uint8Array(NONCE_BYTES))); - const header = { + const header: Record = { v: SEALED_OPERATION_VERSION, rk: toBase64(responseKey), nonce, ts: now, ...(actor === undefined ? {} : { actor }), - op, }; + if (mode === 'sealed') { + header.op = op; + const envelope = await encryptEnvelope(JSON.stringify(header), publicKey, kid); + return { request: { operation: 'encrypted_operation', envelope }, responseKey, nonce }; + } + const leafKey = await requireSubtle().importKey('raw', ab(responseKey), { name: 'AES-GCM' }, false, ['encrypt']); + const visible: Record = {}; + for (const [key, value] of Object.entries(op)) { + visible[key] = key === 'operation' || visibleFields.includes(key) + ? value + : await sealValue(value, leafKey, nonce, '/' + pointerToken(key)); + } + const opText = JSON.stringify(visible); + header.oph = await hashOperationText(opText); const envelope = await encryptEnvelope(JSON.stringify(header), publicKey, kid); - return { request: { operation: 'encrypted_operation', envelope }, responseKey, nonce }; + return { request: { operation: 'encrypted_operation', mode: 'fields', op: opText, envelope }, responseKey, nonce }; +} + +/** RFC 6901 reference token for one key. */ +function pointerToken(key: string): string { + return key.replaceAll('~', '~0').replaceAll('/', '~1'); +} + +async function hashOperationText(text: string): Promise { + return toBase64(new Uint8Array(await requireSubtle().digest('SHA-256', ab(new TextEncoder().encode(text))))); +} + +/** One sealed leaf: the value's JSON text under the response key, bound to its location by the additional data. */ +async function sealValue( + value: unknown, + key: CryptoKey, + nonce: string, + pointer: string, +): Promise<{ [SEALED_LEAF_KEY]: string }> { + const json = JSON.stringify(value); + if (json === undefined) { + throw new TypeError(`The value at '${pointer}' has no JSON representation.`); + } + const iv = crypto.getRandomValues(new Uint8Array(IV_BYTES)); + // Web Crypto appends the tag to the ciphertext, which is the leaf's iv, ciphertext, tag order once iv leads. + const sealed = new Uint8Array( + await requireSubtle().encrypt( + { + name: 'AES-GCM', + iv: ab(iv), + additionalData: ab(new TextEncoder().encode(`${FIELD_AAD_PREFIX}${nonce}:${pointer}`)), + tagLength: 128, + }, + key, + ab(new TextEncoder().encode(json)), + ), + ); + const leaf = new Uint8Array(iv.length + sealed.length); + leaf.set(iv); + leaf.set(sealed, iv.length); + return { [SEALED_LEAF_KEY]: toBase64(leaf) }; } /** From a8e7876774ed8d094fdd4bb90896ed7875fe108a Mon Sep 17 00:00:00 2001 From: Devin Holland <50112339+Devin-Holland@users.noreply.github.com> Date: Mon, 16 Nov 2026 18:38:33 -0500 Subject: [PATCH 6/7] fix(cluster): keep a connection a late ordinary mint would overwrite, 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 --- src/features/auth/store/authStore.ts | 7 ++++--- .../auth/store/establishFabricConnectAuth.test.ts | 8 +++++--- src/features/cluster/FinishSetup.tsx | 2 +- src/lib/crypto/sealedOperation.ts | 2 -- 4 files changed, 10 insertions(+), 9 deletions(-) diff --git a/src/features/auth/store/authStore.ts b/src/features/auth/store/authStore.ts index 63cc3856d..9b5e21d56 100644 --- a/src/features/auth/store/authStore.ts +++ b/src/features/auth/store/authStore.ts @@ -676,10 +676,10 @@ class AuthStore { claimedGeneration = this.getConnectionGeneration(id); this.fabricConnectAuth.set(id, auth); }; - // Two resolutions can overlap once a token-backed one declines to share the in-flight connect: whichever claimed - // last owns the state, and the other must not record its user over it. + // Two resolutions can overlap once a token-backed one declines to share the in-flight connect. A connection + // claimed after this one started, or after it claimed, owns the state; this one must not overwrite it. const throwIfReplaced = () => { - if (claimedGeneration !== undefined && this.getConnectionGeneration(id) !== claimedGeneration) { + if (this.getConnectionGeneration(id) !== (claimedGeneration ?? entryGeneration)) { throw new Error('Another connection replaced this one while it was connecting.'); } }; @@ -688,6 +688,7 @@ class AuthStore { instanceClient: getInstanceClient({ id, forceFabricConnect: true }), }); throwIfSignedOut(); + throwIfReplaced(); // Only attempt a direct Bearer connection when we have a concrete DIRECT operations URL. // Without one, getInstanceClient would fall back to the stored connection key, and if that diff --git a/src/features/auth/store/establishFabricConnectAuth.test.ts b/src/features/auth/store/establishFabricConnectAuth.test.ts index f689db80a..9cc47eb28 100644 --- a/src/features/auth/store/establishFabricConnectAuth.test.ts +++ b/src/features/auth/store/establishFabricConnectAuth.test.ts @@ -170,14 +170,16 @@ describe('authStore.establishFabricConnectAuth', () => { await expect(withTokens).resolves.toBe(directUser); expect(authStore.getOperationToken('ins-1')).toBe('setup-token'); + // The ordinary connect's mint finishing later does not overwrite the connection made meanwhile. answerMint({ operationToken: 'jwt-token' }); - await expect(plain).resolves.toBe(directUser); - expect(authStore.getOperationToken('ins-1')).toBe('jwt-token'); + await expect(plain).rejects.toThrow('replaced'); + expect(authStore.getOperationToken('ins-1')).toBe('setup-token'); + expect(authStore.hasResolvedFabricConnect('ins-1')).toBe(true); const joined = authStore.establishFabricConnectAuth({ id: 'ins-1', operationsUrl: DIRECT_URL, tokens }); const later = authStore.establishFabricConnectAuth({ id: 'ins-1', operationsUrl: DIRECT_URL }); expect(later).not.toBe(joined); - await Promise.all([joined, later]); + await Promise.allSettled([joined, later]); }); it('is not erased when an ordinary connect that never claimed fails afterwards', async () => { diff --git a/src/features/cluster/FinishSetup.tsx b/src/features/cluster/FinishSetup.tsx index 73916e661..1a2240d76 100644 --- a/src/features/cluster/FinishSetup.tsx +++ b/src/features/cluster/FinishSetup.tsx @@ -60,7 +60,7 @@ export function FinishSetup() { const tempPassword = cluster?.instances?.find(i => i.tempPassword)?.tempPassword; const sealedSetup = useMemo(() => sealedSetupCapability(cluster), [cluster]); - const keyPending = clusterKeyPending(cluster); + const keyPending = useMemo(() => clusterKeyPending(cluster), [cluster]); const instancesReady = allClusterInstancesRunning(cluster); const { mutate: submitInstanceResetPassword, isPending, isSuccess } = useInstanceResetPasswordMutation(); diff --git a/src/lib/crypto/sealedOperation.ts b/src/lib/crypto/sealedOperation.ts index a41f77465..d718fc7c4 100644 --- a/src/lib/crypto/sealedOperation.ts +++ b/src/lib/crypto/sealedOperation.ts @@ -35,7 +35,6 @@ interface SealedOperation { nonce: string; } -/** What the node answered inside the sealed response. */ export interface SealedResult { status: number; body: unknown; @@ -87,7 +86,6 @@ export async function sealOperation( return { request: { operation: 'encrypted_operation', mode: 'fields', op: opText, envelope }, responseKey, nonce }; } -/** RFC 6901 reference token for one key. */ function pointerToken(key: string): string { return key.replaceAll('~', '~0').replaceAll('/', '~1'); } From b80acd486c8fe4679e9021f38beac4fe7b773a87 Mon Sep 17 00:00:00 2001 From: Devin Holland <50112339+Devin-Holland@users.noreply.github.com> Date: Mon, 16 Nov 2026 22:38:08 -0500 Subject: [PATCH 7/7] docs(cluster): say that only a sealed write with no readable answer is an unknown outcome Co-Authored-By: Claude Opus 5.5 --- src/features/cluster/DESIGN.md | 9 +++++---- src/integrations/api/instance/sealedOperation.ts | 2 +- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/src/features/cluster/DESIGN.md b/src/features/cluster/DESIGN.md index ae99ea230..423bb7090 100644 --- a/src/features/cluster/DESIGN.md +++ b/src/features/cluster/DESIGN.md @@ -123,10 +123,11 @@ A retry reads the cluster's state the same way: `add_user` answering "already ex `list_users` reports it an active super user, and a `drop_user` answering "does not exist" means an earlier attempt dropped it and never sent the PATCH. The node answers a timestamp outside its window with its own clock and an envelope for another key with its fingerprint; each is retried once, with the offset remembered for the session and -the key fetched again. A sealed answer that ran but could not return its result (`executed`) is reported as an unknown -outcome, like an unanswered write, since the user was created or dropped all the same; so does a node's 503, which the -toast cannot tell from a gateway's, though a refusal before admission ran nothing and is safe to retry. There is no -plaintext fallback: a node without custody or a refused envelope stops setup. +the key fetched again. A sealed write that ran but could not return its result (`executed`), or whose answer could not +be read, is reported as an unknown outcome, like an unanswered write, since the user may have been created or dropped +all the same; a sealed read in that state (`list_users`) is only a failed read. A node's 503 also reads as an unknown +outcome, since the toast cannot tell it from a gateway's, though a refusal before admission ran nothing and is safe to +retry. There is no plaintext fallback: a node without custody or a refused envelope stops setup. ## An interrupted setup finishes from the admin it already created diff --git a/src/integrations/api/instance/sealedOperation.ts b/src/integrations/api/instance/sealedOperation.ts index abdb6d7d1..fd24bf1e3 100644 --- a/src/integrations/api/instance/sealedOperation.ts +++ b/src/integrations/api/instance/sealedOperation.ts @@ -28,7 +28,7 @@ export class SealedOperationError extends Error { } } -/** The request went out, but the answer was missing, malformed or not this request's: the operation may have run. */ +/** The request went out, but the answer was missing, malformed or not this request's: a write may have run. */ export class UnreadableSealedAnswerError extends Error { operation: string;