feat(apps): generic OAuth provider support for app SDK (#20181)

## Summary App developers can now declare third-party OAuth integrations (GitHub, Linear, Slack, etc.) in their manifest and the platform handles the full authorize → callback → token-exchange → refresh → injection lifecycle. The dev writes ~10 lines of config and reads tokens via `useOAuth('linear')` inside any logic function. ```ts // app/src/oauth-providers/linear.ts export default defineOAuthProvider({ universalIdentifier: '...', name: 'linear', displayName: 'Linear', authorizationEndpoint: 'https://linear.app/oauth/authorize', tokenEndpoint: 'https://api.linear.app/oauth/token', scopes: ['read', 'write'], connectionMode: 'per-user', clientIdVariable: 'LINEAR_CLIENT_ID', clientSecretVariable: 'LINEAR_CLIENT_SECRET', tokenRequestContentType: 'form-urlencoded', }); // app/src/logic-functions/handlers/... const { accessToken } = useOAuth('linear'); // throws OAuthNotConnectedError if missing ``` ## Architecture - **Storage**: extends the existing `connectedAccount` table — new nullable `applicationOAuthProviderId` FK + new `app` value on the `ConnectedAccountProvider` enum. Existing Google/Microsoft flows are untouched. - **OAuth flow**: a single `/apps/oauth/authorize` + `/apps/oauth/callback` controller pair handles every app provider. State travels in a JWT signed via the existing `JwtWrapperService` (new `APP_OAUTH_STATE` token type). - **Token exchange**: goes through `SecureHttpClientService.createSsrfSafeFetch()` (so an installed app can't point `tokenEndpoint` at internal hosts). - **Refresh**: piggybacks on the existing `ConnectedAccountRefreshTokensService` dispatch — Google/Microsoft drivers untouched, new app driver lives engine-side under `application-oauth-provider/refresh/`. - **Injection**: the executor injects refreshed tokens as env vars (`OAUTH_<NAME>_ACCESS_TOKEN`, `_HANDLE`, `_SCOPES`, `_CONNECTED`); the SDK helpers `useOAuth` / `useOptionalOAuth` read them. - **Frontend**: auto-rendered "OAuth Connections" section under each app's settings tab (no custom front component needed). App-managed connections are filtered out of `/settings/accounts` so the email/calendar page stays focused. - **Disconnect**: best-effort revoke against the manifest's `revokeEndpoint` before deleting the row. ## Reference app `packages/twenty-apps/internal/twenty-linear/` exercises the full pipeline: - `defineOAuthProvider` for Linear - `POST /linear/create-issue` and `GET /linear/teams` HTTP-route logic functions - Vitest tests for the handlers ## Tests - 14 server-side Jest tests: token-exchange util (form-urlencoded vs JSON, PKCE, error paths), flow service (authorize URL shape, state binding, ConnectedAccount upsert on first/reconnect, per-workspace mode, invalid state) - 8 app-level Vitest tests: handler error paths, GraphQL request shape, Linear error propagation - All 4 packages clean: `npx nx lint:diff-with-main` and `npx tsc --noEmit` ## Test plan - [ ] Apply migration on a dev DB: `npx nx run twenty-server:database:migrate:prod` - [ ] Regenerate frontend types: `npx nx run twenty-front:graphql:generate --configuration=metadata` - [ ] Create a Linear OAuth app at https://linear.app/settings/api/applications/new with redirect URI `<SERVER_URL>/apps/oauth/callback` - [ ] Deploy + install `twenty-linear` on a workspace, paste the Linear client id/secret into the app's variables - [ ] Click "Connect Linear" in the app's settings tab → complete OAuth → verify `connectedAccount` row created with `provider = 'app'` - [ ] Trigger `POST /linear/create-issue` with a valid teamId → verify issue lands in Linear - [ ] Disconnect → verify the row is deleted and (if Linear's revoke endpoint is configured in the manifest) the revoke call fires - [ ] Verify `/settings/accounts` does NOT show the Linear connection — it appears only under the Linear app's settings tab ## Out of scope (deliberately) - **Cron + per-user providers**: a cron-triggered function with a per-user OAuth provider currently returns `CONNECTED=false` (no user context). The follow-up design is `useOAuthForUser(name, userWorkspaceId)` paired with a `POST /apps/oauth/connection-token` endpoint, deferred to keep this PR focused. - **Token encryption at rest**: tokens stored as plain `varchar` matching the existing Google/Microsoft pattern. Worth a separate cross-cutting PR. - **Manifest endpoint pinning**: a malicious app upgrade could change `tokenEndpoint` silently. Same trust model as logic-function source code (which already runs arbitrary server-side); worth tightening across the whole upgrade pipeline rather than just OAuth. - **CLI helpers** (`twenty oauth show-callback-url`, `twenty oauth connect`): manual setup for v1. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
2026-05-04 11:26:34 +02:00
parent ff22988caf
commit 9e94045fa5
132 changed files with 6533 additions and 595 deletions
@@ -0,0 +1,133 @@
+import { type MigrationInterface, type QueryRunner } from 'typeorm';
+
+export class AddApplicationOAuthProviderAndConnectedAccountColumn1777558657640
+  implements MigrationInterface
+{
+  name = 'AddApplicationOAuthProviderAndConnectedAccountColumn1777558657640';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(
+      `CREATE TABLE "core"."applicationOAuthProvider" (
+        "id" uuid NOT NULL DEFAULT uuid_generate_v4(),
+        "workspaceId" uuid NOT NULL,
+        "applicationId" uuid NOT NULL,
+        "universalIdentifier" uuid NOT NULL,
+        "name" varchar NOT NULL,
+        "displayName" varchar NOT NULL,
+        "authorizationEndpoint" varchar NOT NULL,
+        "tokenEndpoint" varchar NOT NULL,
+        "revokeEndpoint" varchar,
+        "scopes" varchar array NOT NULL DEFAULT '{}',
+        "clientIdVariable" varchar NOT NULL,
+        "clientSecretVariable" varchar NOT NULL,
+        "authorizationParams" jsonb,
+        "tokenRequestContentType" varchar NOT NULL DEFAULT 'json',
+        "usePkce" boolean NOT NULL DEFAULT true,
+        "createdAt" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now(),
+        "updatedAt" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now(),
+        CONSTRAINT "IDX_APP_OAUTH_PROVIDER_NAME_APPLICATION_UNIQUE" UNIQUE ("name", "applicationId"),
+        CONSTRAINT "IDX_APP_OAUTH_PROVIDER_UNIVERSAL_ID_APPLICATION_UNIQUE" UNIQUE ("universalIdentifier", "applicationId"),
+        CONSTRAINT "PK_applicationOAuthProvider_id" PRIMARY KEY ("id")
+      )`,
+    );
+
+    await queryRunner.query(
+      `CREATE INDEX "IDX_APP_OAUTH_PROVIDER_APPLICATION_ID" ON "core"."applicationOAuthProvider" ("applicationId")`,
+    );
+
+    await queryRunner.query(
+      `CREATE INDEX "IDX_APP_OAUTH_PROVIDER_WORKSPACE_ID" ON "core"."applicationOAuthProvider" ("workspaceId")`,
+    );
+
+    // FK constraint names match the hashes that TypeORM auto-generates from
+    // the @ManyToOne decorators in the entities. Keeping them in sync here
+    // avoids a "pending migration" diff on every CI run.
+    await queryRunner.query(
+      `ALTER TABLE "core"."applicationOAuthProvider"
+       ADD CONSTRAINT "FK_c63de8b90514de1798876c30f2e"
+       FOREIGN KEY ("workspaceId") REFERENCES "core"."workspace"("id")
+       ON DELETE CASCADE ON UPDATE NO ACTION`,
+    );
+
+    await queryRunner.query(
+      `ALTER TABLE "core"."applicationOAuthProvider"
+       ADD CONSTRAINT "FK_2d01320998547c2f5059d8b09d6"
+       FOREIGN KEY ("applicationId") REFERENCES "core"."application"("id")
+       ON DELETE CASCADE ON UPDATE NO ACTION`,
+    );
+
+    await queryRunner.query(
+      `ALTER TABLE "core"."connectedAccount"
+       ADD COLUMN "applicationOAuthProviderId" uuid,
+       ADD COLUMN "applicationId" uuid,
+       ADD COLUMN "name" varchar,
+       ADD COLUMN "visibility" varchar NOT NULL DEFAULT 'user'`,
+    );
+
+    await queryRunner.query(
+      `CREATE INDEX "IDX_CONNECTED_ACCOUNT_APP_OAUTH_PROVIDER_ID" ON "core"."connectedAccount" ("applicationOAuthProviderId")`,
+    );
+
+    await queryRunner.query(
+      `CREATE INDEX "IDX_CONNECTED_ACCOUNT_APPLICATION_ID" ON "core"."connectedAccount" ("applicationId")`,
+    );
+
+    await queryRunner.query(
+      `ALTER TABLE "core"."connectedAccount"
+       ADD CONSTRAINT "FK_344a905bc2041c998d5b57f9bde"
+       FOREIGN KEY ("applicationOAuthProviderId") REFERENCES "core"."applicationOAuthProvider"("id")
+       ON DELETE CASCADE ON UPDATE NO ACTION`,
+    );
+
+    await queryRunner.query(
+      `ALTER TABLE "core"."connectedAccount"
+       ADD CONSTRAINT "FK_21b8e7d3a21ff5712c4dd4875ac"
+       FOREIGN KEY ("applicationId") REFERENCES "core"."application"("id")
+       ON DELETE CASCADE ON UPDATE NO ACTION`,
+    );
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(
+      `ALTER TABLE "core"."connectedAccount" DROP CONSTRAINT "FK_21b8e7d3a21ff5712c4dd4875ac"`,
+    );
+
+    await queryRunner.query(
+      `ALTER TABLE "core"."connectedAccount" DROP CONSTRAINT "FK_344a905bc2041c998d5b57f9bde"`,
+    );
+
+    await queryRunner.query(
+      `DROP INDEX "core"."IDX_CONNECTED_ACCOUNT_APPLICATION_ID"`,
+    );
+
+    await queryRunner.query(
+      `DROP INDEX "core"."IDX_CONNECTED_ACCOUNT_APP_OAUTH_PROVIDER_ID"`,
+    );
+
+    await queryRunner.query(
+      `ALTER TABLE "core"."connectedAccount"
+       DROP COLUMN "visibility",
+       DROP COLUMN "name",
+       DROP COLUMN "applicationId",
+       DROP COLUMN "applicationOAuthProviderId"`,
+    );
+
+    await queryRunner.query(
+      `ALTER TABLE "core"."applicationOAuthProvider" DROP CONSTRAINT "FK_2d01320998547c2f5059d8b09d6"`,
+    );
+
+    await queryRunner.query(
+      `ALTER TABLE "core"."applicationOAuthProvider" DROP CONSTRAINT "FK_c63de8b90514de1798876c30f2e"`,
+    );
+
+    await queryRunner.query(
+      `DROP INDEX "core"."IDX_APP_OAUTH_PROVIDER_WORKSPACE_ID"`,
+    );
+
+    await queryRunner.query(
+      `DROP INDEX "core"."IDX_APP_OAUTH_PROVIDER_APPLICATION_ID"`,
+    );
+
+    await queryRunner.query(`DROP TABLE "core"."applicationOAuthProvider"`);
+  }
+}