Skip to content
Draft
6 changes: 4 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
3 changes: 2 additions & 1 deletion dprint.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
47 changes: 38 additions & 9 deletions src/features/auth/store/authStore.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand Down Expand Up @@ -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<LocalUser> {
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) {
Expand All @@ -650,8 +661,10 @@ class AuthStore {
private async resolveFabricConnectAuth(
id: EntityIds,
operationsUrl: string | null | undefined,
tokens: InstanceAuthenticationTokens | undefined,
): Promise<LocalUser> {
const signOutGeneration = this.getSignOutGeneration(id);
const entryGeneration = this.getConnectionGeneration(id);
const throwIfSignedOut = () => {
if (this.getSignOutGeneration(id) !== signOutGeneration) {
throw new SignedOutWhileConnectingError();
Expand All @@ -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();

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

major β€” Token recovery can replay the admin’s request as another user β€” Scope: in-scope β€” Convergence-Class: original-change

(src/features/auth/store/authStore.ts:697 is not part of this PR's diff β€” anchored to the nearest line this PR's diff can hold)

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
Expand All @@ -685,33 +706,41 @@ 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');
this.setUserForIdAndKey(id, operationsUrl, directUser);
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);
Expand Down
100 changes: 100 additions & 0 deletions src/features/auth/store/establishFabricConnectAuth.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<string, unknown> } } },
) =>
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 });
Expand Down
50 changes: 47 additions & 3 deletions src/features/cluster/DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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`
Expand Down
Loading
Loading