Fill OAuth connection labels from account identity instead of the owner default

Author: RhysSullivan

e2e/scenarios/google-health-checks.test.ts

@@ -116,6 +116,7 @@ const connectGoogleAccount = (input: {
   readonly target: TargetShape;
   readonly integration: IntegrationSlug;
   readonly oauthClient: OAuthClientSlug;
+  readonly newConnection?: boolean;
 }) =>
   Effect.gen(function* () {
     const redirectUri = new URL("/api/oauth/callback", input.target.baseUrl).toString();
@@ -146,6 +147,25 @@ const connectGoogleAccount = (input: {
       },
     });
 
+    return yield* runGoogleOAuthFlow(input, redirectUri);
+  });
+
+/** Run one authorize+complete round through the already-registered app. Split
+ *  from `connectGoogleAccount` so a scenario can connect a SECOND account
+ *  through the same app (`newConnection: true`) without re-registering it. */
+const runGoogleOAuthFlow = (
+  input: {
+    readonly client: Client;
+    readonly target: TargetShape;
+    readonly integration: IntegrationSlug;
+    readonly oauthClient: OAuthClientSlug;
+    readonly newConnection?: boolean;
+  },
+  redirectUriOverride?: string,
+) =>
+  Effect.gen(function* () {
+    const redirectUri =
+      redirectUriOverride ?? new URL("/api/oauth/callback", input.target.baseUrl).toString();
     const started = yield* input.client.oauth.start({
       payload: {
         client: input.oauthClient,
@@ -155,6 +175,7 @@ const connectGoogleAccount = (input: {
         integration: input.integration,
         template: GOOGLE_AUTH_TEMPLATE,
         redirectUri,
+        ...(input.newConnection === true ? { newConnection: true } : {}),
       },
     });
     expect(started.status, "OAuth starts with an emulator redirect").toBe("redirect");
@@ -167,6 +188,7 @@ const connectGoogleAccount = (input: {
     expect(completed.integration, "OAuth completion creates the connection").toBe(
       input.integration,
     );
+    return completed;
   });
 
 scenario(
@@ -334,13 +356,53 @@ scenario(
           refreshed.find((connection) => connection.name === CONNECTION)?.identityLabel,
           "Google Sheets still shows the OAuth grant identity after no-probe health",
         ).toBe(GOOGLE_EMULATOR_ACCOUNT_EMAIL);
+
+        // Reconnecting the SAME connection must not clobber a curated label
+        // with the grant identity.
+        yield* client.connections.update({
+          params: { owner: "org", integration: slug, name: CONNECTION },
+          payload: { identityLabel: "Finance account" },
+        });
+        yield* runGoogleOAuthFlow({ client, target, integration: slug, oauthClient });
+        const reconnected = yield* client.connections.list({
+          query: { owner: "org", integration: slug },
+        });
+        expect(
+          reconnected.find((connection) => connection.name === CONNECTION)?.identityLabel,
+          "reconnect keeps the curated label over the grant identity",
+        ).toBe("Finance account");
+
+        // A `newConnection` connect under a taken name mints a SECOND
+        // connection with a suffixed name instead of replacing the first.
+        const second = yield* runGoogleOAuthFlow({
+          client,
+          target,
+          integration: slug,
+          oauthClient,
+          newConnection: true,
+        });
+        expect(String(second.name), "second account mints a suffixed connection").toBe(
+          `${String(CONNECTION)}2`,
+        );
+        expect(second.identityLabel, "second account label comes from the grant identity").toBe(
+          GOOGLE_EMULATOR_ACCOUNT_EMAIL,
+        );
+        const both = yield* client.connections.list({
+          query: { owner: "org", integration: slug },
+        });
+        expect(
+          both.map((connection) => String(connection.name)).sort(),
+          "both accounts coexist",
+        ).toEqual([String(CONNECTION), `${String(CONNECTION)}2`]);
       }),
       Effect.gen(function* () {
-        yield* client.connections
-          .remove({
-            params: { owner: "org", integration: slug, name: CONNECTION },
-          })
-          .pipe(Effect.ignore);
+        for (const name of [CONNECTION, ConnectionName.make(`${String(CONNECTION)}2`)]) {
+          yield* client.connections
+            .remove({
+              params: { owner: "org", integration: slug, name },
+            })
+            .pipe(Effect.ignore);
+        }
         yield* client.oauth
           .removeClient({ params: { slug: oauthClient }, payload: { owner: "org" } })
           .pipe(Effect.ignore);

packages/core/api/src/handlers/oauth.ts

@@ -161,6 +161,7 @@ export const OAuthHandlers = HttpApiBuilder.group(ExecutorApi, "oauth", (handler
             integration: payload.integration,
             template: payload.template,
             identityLabel: payload.identityLabel,
+            newConnection: payload.newConnection,
             redirectUri: payload.redirectUri,
           });
           return startResultToResponse(result);

packages/core/api/src/oauth/api.ts

@@ -160,6 +160,9 @@ const StartPayload = Schema.Struct({
   integration: IntegrationSlug,
   template: AuthTemplateSlug,
   identityLabel: Schema.optional(Schema.NullOr(Schema.String)),
+  /** Mint a NEW connection: a taken `name` resolves to the next free suffixed
+   *  name server-side instead of re-minting the existing row. */
+  newConnection: Schema.optional(Schema.Boolean),
   redirectUri: Schema.optional(Schema.NullOr(Schema.String)),
 });
 

packages/core/sdk/src/executor.ts

@@ -2489,14 +2489,22 @@ export const createExecutor = <const TPlugins extends readonly AnyPlugin[] = rea
           integration: input.integration,
           name,
         };
+        // Label precedence: an explicit (user-chosen) label always wins; a
+        // derived label (OIDC claims) only FILLS an empty slot. Like
+        // `description` below, a reconnect or token refresh must not erase a
+        // label the user curated. Resolved once, used by every write below.
+        let identityLabel: string | null = null;
         yield* transaction(
           Effect.gen(function* () {
             const existing = yield* findConnectionRow(ref);
+            const existingLabel = existing?.identity_label?.trim() ? existing.identity_label : null;
+            identityLabel =
+              input.identityLabel ?? existingLabel ?? input.derivedIdentityLabel ?? null;
             const set: Record<string, unknown> = {
               template: String(input.template),
               provider: input.provider,
               item_ids: { [PRIMARY_INPUT_VARIABLE]: input.itemId },
-              identity_label: input.identityLabel ?? null,
+              identity_label: identityLabel,
               oauth_client: String(input.oauthClient),
               oauth_client_owner: input.oauthClientOwner,
               refresh_item_id: input.refreshItemId,
@@ -2529,7 +2537,7 @@ export const createExecutor = <const TPlugins extends readonly AnyPlugin[] = rea
                 template: String(input.template),
                 provider: input.provider,
                 item_ids: { [PRIMARY_INPUT_VARIABLE]: input.itemId },
-                identity_label: input.identityLabel ?? null,
+                identity_label: identityLabel,
                 // Curated description: never stamped by a mint — a reconnect
                 // or token refresh must not erase what the user wrote.
                 description: null,
@@ -2568,7 +2576,7 @@ export const createExecutor = <const TPlugins extends readonly AnyPlugin[] = rea
               template: String(input.template),
               provider: input.provider,
               item_ids: { [PRIMARY_INPUT_VARIABLE]: input.itemId },
-              identity_label: input.identityLabel ?? null,
+              identity_label: identityLabel,
               description: null,
               oauth_client: String(input.oauthClient),
               oauth_client_owner: input.oauthClientOwner,
@@ -3848,6 +3856,7 @@ export const createExecutor = <const TPlugins extends readonly AnyPlugin[] = rea
       ownedKeys: (owner: Owner) => ownedKeys(owner),
       defaultWritableProvider,
       mintOAuthConnection: (input: MintOAuthConnectionInput) => mintOAuthConnection(input),
+      connectionNameTaken: (ref) => findConnectionRow(ref).pipe(Effect.map((row) => row !== null)),
       // One integration-row read + one projector run. Resolve the method this
       // template selects exactly as the runtime's `selectAuthMethod` does —
       // exact slug match, else the sole declared method (single-method

packages/core/sdk/src/oauth-client.ts

@@ -127,7 +127,15 @@ export interface OAuthStartInput {
   readonly name: ConnectionName;
   readonly integration: IntegrationSlug;
   readonly template: AuthTemplateSlug;
+  /** Display label for the minted connection. When omitted, the server derives
+   *  one from the provider's OIDC account claims (the account email) when the
+   *  grant carries them; a re-mint of an existing connection keeps its stored
+   *  label. Send a value only for a label the user actually chose. */
   readonly identityLabel?: string | null;
+  /** Mint a NEW connection: when `name` is already taken, the mint picks the
+   *  next free suffixed name (`personalGmail2`) instead of re-minting the
+   *  existing row. Omit for reconnect flows, which target the existing row. */
+  readonly newConnection?: boolean;
   /** Browser-facing callback URL for this flow. Defaults to the executor's configured redirectUri. */
   readonly redirectUri?: string | null;
 }

packages/core/sdk/src/oauth-flow.test.ts

@@ -384,6 +384,115 @@ describe("oauth.start / oauth.complete", () => {
     ),
   );
 
+  it.effect("newConnection resolves a taken name to the next free suffix", () =>
+    Effect.scoped(
+      Effect.gen(function* () {
+        const server = yield* serveOAuthTestServer({
+          scopes: ["openid", "email", "profile", "read"],
+          idTokenClaims: { email: "alice@example.com", sub: "user-1" },
+        });
+        const { executor } = yield* makeTestWorkspaceHarness({ plugins });
+        yield* executor.acme.seed(["openid", "email", "profile", "read"]);
+
+        yield* executor.oauth.createClient({
+          owner: "org",
+          slug: CLIENT,
+          authorizationUrl: server.authorizationEndpoint,
+          tokenUrl: server.tokenEndpoint,
+          grant: "authorization_code",
+          clientId: "test-client",
+          clientSecret: "test-secret",
+        });
+
+        const runFlow = Effect.gen(function* () {
+          const started = yield* executor.oauth.start({
+            owner: "org",
+            client: CLIENT,
+            clientOwner: "org",
+            name: ConnectionName.make("main"),
+            integration: INTEG,
+            template: TEMPLATE,
+            newConnection: true,
+          });
+          expect(started.status).toBe("redirect");
+          if (started.status !== "redirect") return null;
+          const callback = yield* server.completeAuthorizationCodeFlow({
+            authorizationUrl: started.authorizationUrl,
+          });
+          return yield* executor.oauth.complete({
+            state: started.state,
+            code: callback.code,
+          });
+        });
+
+        const first = yield* runFlow;
+        const second = yield* runFlow;
+        expect(String(first?.name)).toBe("main");
+        expect(String(second?.name)).toBe("main2");
+
+        const connections = yield* executor.connections.list({ integration: INTEG });
+        expect(connections.map((connection) => String(connection.name)).sort()).toEqual([
+          "main",
+          "main2",
+        ]);
+      }),
+    ),
+  );
+
+  it.effect("preserves a curated label when reconnecting without an explicit label", () =>
+    Effect.scoped(
+      Effect.gen(function* () {
+        const server = yield* serveOAuthTestServer({
+          scopes: ["openid", "email", "profile", "read"],
+          idTokenClaims: { email: "alice@example.com", sub: "user-1" },
+        });
+        const { executor } = yield* makeTestWorkspaceHarness({ plugins });
+        yield* executor.acme.seed(["openid", "email", "profile", "read"]);
+
+        yield* executor.oauth.createClient({
+          owner: "org",
+          slug: CLIENT,
+          authorizationUrl: server.authorizationEndpoint,
+          tokenUrl: server.tokenEndpoint,
+          grant: "authorization_code",
+          clientId: "test-client",
+          clientSecret: "test-secret",
+        });
+
+        const runFlow = Effect.gen(function* () {
+          const started = yield* executor.oauth.start({
+            owner: "org",
+            client: CLIENT,
+            clientOwner: "org",
+            name: ConnectionName.make("main"),
+            integration: INTEG,
+            template: TEMPLATE,
+          });
+          expect(started.status).toBe("redirect");
+          if (started.status !== "redirect") return null;
+          const callback = yield* server.completeAuthorizationCodeFlow({
+            authorizationUrl: started.authorizationUrl,
+          });
+          return yield* executor.oauth.complete({
+            state: started.state,
+            code: callback.code,
+          });
+        });
+
+        const first = yield* runFlow;
+        expect(first?.identityLabel).toBe("alice@example.com");
+
+        // The user renames the connection, then reconnects (no typed label).
+        yield* executor.connections.update(
+          { owner: "org", integration: INTEG, name: ConnectionName.make("main") },
+          { identityLabel: "Finance account" },
+        );
+        const second = yield* runFlow;
+        expect(second?.identityLabel).toBe("Finance account");
+      }),
+    ),
+  );
+
   it.effect("does not overwrite connection identity from id_token claims on refresh", () =>
     Effect.scoped(
       Effect.gen(function* () {