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/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..9b5e21d56 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 && !tokens) { + 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,8 +661,10 @@ class AuthStore { private async resolveFabricConnectAuth( id: EntityIds, operationsUrl: string | null | undefined, + tokens: InstanceAuthenticationTokens | undefined, ): Promise { const signOutGeneration = this.getSignOutGeneration(id); + const entryGeneration = this.getConnectionGeneration(id); const throwIfSignedOut = () => { if (this.getSignOutGeneration(id) !== signOutGeneration) { throw new SignedOutWhileConnectingError(); @@ -663,11 +676,19 @@ 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. A connection + // claimed after this one started, or after it claimed, owns the state; this one must not overwrite it. + const throwIfReplaced = () => { + if (this.getConnectionGeneration(id) !== (claimedGeneration ?? entryGeneration)) { + throw new Error('Another connection replaced this one while it was connecting.'); + } + }; try { - const { operationToken, refreshToken } = await createInstanceAuthenticationTokens({ + const { operationToken, refreshToken } = tokens ?? await createInstanceAuthenticationTokens({ 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 @@ -685,11 +706,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'); @@ -697,21 +721,26 @@ 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' }); 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); 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 bbdd6590a..9cc47eb28 100644 --- a/src/features/auth/store/establishFabricConnectAuth.test.ts +++ b/src/features/auth/store/establishFabricConnectAuth.test.ts @@ -132,6 +132,106 @@ 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'); + + // The ordinary connect's mint finishing later does not overwrite the connection made meanwhile. + answerMint({ operationToken: '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.allSettled([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(( + { 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 db7f748f6..423bb7090 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. @@ -85,6 +87,48 @@ 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`. 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 +[`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), 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 +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 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 Central manager's `ResetPasswordUpdater` takes no body and only clears `resetPassword` diff --git a/src/features/cluster/FinishSetup.test.tsx b/src/features/cluster/FinishSetup.test.tsx index be25703a0..8187fc8cc 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( @@ -99,7 +99,35 @@ 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 () => { + 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({ 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 }); + + 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 3922cb1d4..1a2240d76 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 { clusterKeyPending, sealedSetupCapability } from './sealedSetup'; import { clusterSignInIds } from './terminatedClusterSignIns'; export function FinishSetup() { @@ -58,6 +59,8 @@ export function FinishSetup() { }, [setFocus]); const tempPassword = cluster?.instances?.find(i => i.tempPassword)?.tempPassword; + const sealedSetup = useMemo(() => sealedSetupCapability(cluster), [cluster]); + const keyPending = useMemo(() => clusterKeyPending(cluster), [cluster]); const instancesReady = allClusterInstancesRunning(cluster); const { mutate: submitInstanceResetPassword, isPending, isSuccess } = useInstanceResetPasswordMutation(); @@ -77,6 +80,8 @@ export function FinishSetup() { clusterId, newPassword: formData.password, tempPassword, + sealedSetup: sealedSetup ?? undefined, + clusterKeyPending: keyPending, initialUsername: defaultClusterUsername, desiredUsername: formData.username, }, { @@ -86,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. @@ -108,12 +116,14 @@ export function FinishSetup() { cluster, clusterId, instancesReady, + keyPending, navigate, operationsUrl, preset, 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..ef79ea4e4 --- /dev/null +++ b/src/features/cluster/sealedSetup.test.ts @@ -0,0 +1,74 @@ +import type { Cluster } from '@/integrations/api/api.patch'; +import { describe, expect, it } from 'vitest'; +import { clusterKeyPending, 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('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); + 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 new file mode 100644 index 000000000..977eea2d5 --- /dev/null +++ b/src/features/cluster/sealedSetup.ts @@ -0,0 +1,60 @@ +import { deletedClusterStatuses } from '@/config/clusterStatuses'; +import { Cluster, Instance } 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). +const SEALED_SETUP_MIN_VERSION = '5.4.0'; + +export interface SealedSetupCapability { + 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 { + 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, 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 { + const live = liveMembers(cluster); + return !!live + && live.every((instance) => !instance.version || wasAReleasedBeforeB(SEALED_SETUP_MIN_VERSION, instance.version)) + && sealedSetupCapability(cluster) === 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 : 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/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..c645b908a 100644 --- a/src/integrations/api/instance/auth/useInstanceResetPasswordMutation.test.tsx +++ b/src/integrations/api/instance/auth/useInstanceResetPasswordMutation.test.tsx @@ -32,13 +32,35 @@ 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}`)) { + await sealedNode.beforeUserInfo?.(); + 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 +71,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 +89,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 +98,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 +117,105 @@ 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[] = []; + /** 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 { + 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 +235,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; clusterKeyPending?: boolean } = {}, +) { + const client = new QueryClient({ defaultOptions: { mutations: { retry: false }, queries: { retry: false } } }); const { result } = renderHook(() => useInstanceResetPasswordMutation(), { wrapper: ({ children }: { children: ReactNode }) => ( {children} @@ -132,6 +253,7 @@ function resetPassword(desiredUsername: string) { desiredUsername, newPassword: 'new-password', tempPassword: 'temp-password', + ...overrides, }); } @@ -502,3 +624,265 @@ 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 [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'); + } + 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(runSealedOperation.mock.calls.every(([params]) => params.mode === 'fields')).toBe(true); + 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(runSealedOperation.mock.calls.every(([params]) => params.mode === 'fields')).toBe(true); + 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('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( + "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(); + }); + + 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 signOut = vi.spyOn(authStore, 'signOutLocally'); + const { user } = await sealed(OWNER); + + expect(user).toBeNull(); + expect(resetPasswordUpdater).toHaveBeenCalledTimes(1); + expect(createInstanceAuthenticationTokens).not.toHaveBeenCalled(); + expect(signOut.mock.calls.map(([id]) => id)).toEqual(['clu-1', 'ins-1']); + 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); + 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..9d908011a 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,9 @@ interface InstanceResetPasswordParams { desiredUsername: string; newPassword: string; tempPassword: string | undefined; + sealedSetup?: SealedSetupCapability; + /** The members could seal, but central manager has not filled in a version and one key for all of them yet. */ + clusterKeyPending?: boolean; } interface InstanceResetPasswordResponse { @@ -29,7 +36,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, @@ -37,10 +54,15 @@ async function onInstanceResetPassword({ 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 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.', + ); } // 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. @@ -134,6 +156,123 @@ async function onInstanceResetPassword({ return loginResponse; } +const SETUP_VISIBLE_FIELDS = ['role', 'active']; + +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 { + 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)); + 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)); + // 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', + mode: 'fields', + visibleFields: SETUP_VISIBLE_FIELDS, + }); + + 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 }); + } + } + // 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 }; + 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) { + 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. 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 }; + } + 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) { + 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 }; + } + return { message: 'Login successful', user }; +} + function isLoginRefused(error: unknown): boolean { return isAxiosError(error) && error.response?.status === 401 && operationOf(error.config?.data) === 'login'; } @@ -274,7 +413,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..a7f98062f --- /dev/null +++ b/src/integrations/api/instance/sealedOperation.test.ts @@ -0,0 +1,299 @@ +// @vitest-environment node +// A fake 5.4 node built from Harper's reference client; it refuses the way `components/encryptedOperation.ts` does. +import { hashOperationText, openValue, 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, randomBytes } from 'node:crypto'; +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; +import { + _resetClockOffsetsForTests, + isSealedRefusal, + runSealedOperation, + SealedOperationError, + UnreadableSealedAnswerError, +} 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[], + 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' }); + } + 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 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 }; + }, +}; + +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 }; + +beforeEach(() => { + node.clockSkewMs = 0; + node.custody = true; + node.execute = (inner) => ({ status: 200, body: { message: `${inner.operation} ran` } }); + node.requests = []; + node.opened = []; + node.answer = answerAsNode; + _resetClockOffsetsForTests(); +}); + +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('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' } }); + + 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 = answerAsNode; + node.clockSkewMs = 0; + await runSealedOperation({ instanceClient, op, key }); + expect(node.requests).toHaveLength(3); + }); + + 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 () => { + 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('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.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.toBeInstanceOf(UnreadableSealedAnswerError); + }); +}); diff --git a/src/integrations/api/instance/sealedOperation.ts b/src/integrations/api/instance/sealedOperation.ts new file mode 100644 index 000000000..fd24bf1e3 --- /dev/null +++ b/src/integrations/api/instance/sealedOperation.ts @@ -0,0 +1,134 @@ +import { InstanceClientConfig } from '@/config/instanceClientConfig'; +import { SecretsPublicKey } from '@/integrations/api/instance/secrets/secrets'; +import { rejectReplicationFailures, ReplicatedResponse } from '@/integrations/api/replication'; +import { + openSealedResponse, + SealableOperation, + SealedMode, + SealedResult, + sealOperation, +} from '@/lib/crypto/sealedOperation'; +import { isAxiosError } from 'axios'; + +/** The sealed operation ran and answered a failure. */ +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; + } +} + +/** 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; + + 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; +} + +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; + 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 +// 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 _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; 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, mode, visibleFields }: RunSealedOperationParams, +): Promise { + const node = instanceClient.defaults.baseURL ?? ''; + 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() + (clockOffsetsMs.get(node) ?? 0), + mode, + visibleFields, + }); + 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; encrypted_response?: unknown } + | undefined; + 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; + } + if (refusal?.status === 409 && typeof detail?.custody_fingerprint === 'string' && refreshKey && !keyRetried) { + currentKey = await refreshKey(); + keyRetried = true; + continue; + } + if (!detail?.encrypted_response) { + throw error; + } + data = detail; + } + const payload = (data as { encrypted_response?: unknown } | null | undefined)?.encrypted_response; + if (!payload) { + 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); + } + 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/__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..4e94aa35e --- /dev/null +++ b/src/lib/crypto/sealedOperation.test.ts @@ -0,0 +1,216 @@ +// @vitest-environment node +// 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 { + hashOperationText, + NONCE_BYTES, + openResponse, + openValue, + RESPONSE_KEY_BYTES, + sealOperation as referenceSealOperation, + sealResponse, +} 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'; + +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('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 }); + 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); + 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..d718fc7c4 --- /dev/null +++ b/src/lib/crypto/sealedOperation.ts @@ -0,0 +1,174 @@ +/** + * 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. + * + * 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'; + +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:'; +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: SealedOperationRequest; + /** The key the node seals its answer, and any sealed leaf, with. */ + responseKey: Uint8Array; + nonce: string; +} + +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; +} + +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; + 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(), 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: Record = { + v: SEALED_OPERATION_VERSION, + rk: toBase64(responseKey), + nonce, + ts: now, + ...(actor === undefined ? {} : { actor }), + }; + 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', mode: 'fields', op: opText, envelope }, responseKey, nonce }; +} + +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) }; +} + +/** + * 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..4436a01d4 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, UnreadableSealedAnswerError } from '@/integrations/api/instance/sealedOperation'; import { RESTART_UNCONFIRMED_MESSAGE, RESTART_UNCONFIRMED_TITLE, @@ -442,6 +443,47 @@ 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, + 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('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('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' }); + 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..e927671a0 100644 --- a/src/react-query/queryClient.ts +++ b/src/react-query/queryClient.ts @@ -7,11 +7,13 @@ 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, UnreadableSealedAnswerError } from '@/integrations/api/instance/sealedOperation'; import { RESTART_UNCONFIRMED_MESSAGE, 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'; @@ -48,6 +50,16 @@ function describeUnknownOutcome(rawErr: unknown): DescribedError | undefined { if (rawErr instanceof BackupJobUnreportedError) { return copy(OUTCOME_UNKNOWN_TITLE, rawErr.message); } + // 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 && !isReadOperation(rawErr.operation)) { + return copy(OUTCOME_UNKNOWN_TITLE, `${rawErr.message} ${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,