fix(search): support GitHub App grants and verify connector ACLs

Author: waleedlatif1

apps/docs/content/docs/search/github.mdx

@@ -11,7 +11,7 @@ GitHub Search indexes text files from a repository on `github.com`. A workspace
 
 ## Before you start
 
-Your Sim deployment needs a GitHub App configured as described below. An owner or administrator of the target repositories must install that App on them. Each person needs a verified GitHub email address matching their Sim account; the address can be private or secondary.
+Your Sim deployment needs a GitHub App configured as described below. For private repositories, an owner or administrator must install that App on them. Each person needs a verified GitHub email address matching their Sim account; the address can be private or secondary.
 
 ## Configure the GitHub App
 
@@ -68,6 +68,8 @@ Expand **Account permissions** and set **Email addresses → Access: Read-only**
 
 Leave every other permission at **No access**. Sim does not need issue, pull-request, administration, or write permissions. GitHub's [registration guide](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app) explains these settings.
 
+GitHub App user tokens use these permissions rather than OAuth scopes. An empty `scope` value in the token response is expected; see GitHub's [user token reference](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app).
+
 Under **Where can this GitHub App be installed?**, choose **Only on this account** for an organization-owned App used only by members of that organization. Choose **Any account** when teammates or repository owners are outside that organization, or the App is owned by your personal account. A private App owned by a personal account can only be authorized by its owner; see GitHub's [App visibility rules](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/making-a-github-app-public-or-private).
 
 Select **Create GitHub App**.
@@ -84,7 +86,7 @@ GITHUB_APP_CLIENT_ID=<Client ID>
 GITHUB_APP_CLIENT_SECRET=<Client secret>
 ```
 
-Use the **Client ID**, not the numeric **App ID**. These settings are separate from GitHub sign-in. An App private key is not required. Keep expiring user tokens enabled so Sim can [refresh them](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/refreshing-user-access-tokens).
+Use the **Client ID** and **client secret** from **Developer settings → GitHub Apps**. OAuth App credentials used for GitHub sign-in are not compatible. The numeric **App ID** and downloaded private key are not used by this connector. Keep expiring user tokens enabled so Sim can [refresh them](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/refreshing-user-access-tokens).
 
 In the App's sidebar, choose **Install App**, select the target account, and grant access to the repositories you want to search. Return to Sim and select **Connect account**. Every teammate must authorize from Sim too.
 
@@ -123,7 +125,7 @@ You can instead select an existing account under **Sync documents with** to supp
 
 ### Connect your account
 
-On the GitHub source row, select **Connect account** and authorize the App. Teammates repeat this step after joining the Sim workspace. A person only gains access to repository files that their account and the App installation can both read.
+On the GitHub source row, select **Connect account** and authorize the App. Teammates repeat this step after joining the Sim workspace. For private repositories, both the person's account and the App installation must have access. GitHub also permits App user tokens to read public repositories without an installation; see [GitHub's permission rules](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/choosing-permissions-for-a-github-app).
 
 With **Connected members**, indexing begins after someone connects. A dedicated indexing account can start syncing immediately; each teammate still connects before searching. Admins can open **Manage** on the source to inspect sync progress and errors.
 
@@ -135,6 +137,8 @@ With **Connected members**, indexing begins after someone connects. A dedicated
 | Problem | Next step |
 |---|---|
 | GitHub is unavailable in Search | Ask the deployment admin to configure the App client credentials and enable member connections. |
+| GitHub rejects `redirect_uri` | Register the exact callback on the GitHub App whose Client ID Sim uses: `http://localhost:3000/api/auth/oauth2/callback/github-repositories` for the default local server, or your production Sim origin followed by `/api/auth/oauth2/callback/github-repositories`. The scheme, host, port, and path must match; keep wildcard matching disabled. See [callback matching](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/about-the-user-authorization-callback-url). |
+| Wrong app credentials | Copy the Client ID and client secret from **GitHub Apps**, not **OAuth Apps**. Set `GITHUB_APP_CLIENT_ID` and `GITHUB_APP_CLIENT_SECRET`, then restart Sim. A numeric App ID or private-key file cannot replace them. |
 | Repository cannot be read | Confirm the App is installed on that repository and your GitHub account has access. For SAML organizations, establish your GitHub SSO session before reconnecting. |
 | A teammate cannot authorize the App | Check **Where can this GitHub App be installed?** and the App owner. A private organization App accepts only organization members; a private personal App accepts only its owner. |
 | Identity verification fails | Verify the email used by your Sim account in GitHub's email settings, then reconnect. A public profile email alone is insufficient. |

apps/docs/content/docs/search/jira.mdx

@@ -96,6 +96,7 @@ Sim checks Jira separately using each connected person's account. Issue content
 | Projects are empty or disabled | Enter the domain and connect a browsing account, or switch to manual project keys. Check that the account can browse those projects. |
 | Connected, but no issues | Confirm the authorized site matches the configured domain. Check project access, issue security, and the JQL filter. An admin's Jira access does not grant access to other members. |
 | Email mismatch | Sign in to Atlassian with the email shown by Sim's connection flow. |
+| Atlassian says the callback URL is invalid | Ask the deployment operator to check the OAuth app identified by `JIRA_CLIENT_ID`. Its saved callback must exactly match the authorization request's `redirect_uri`, including scheme, hostname, port, and `/api/auth/oauth2/callback/jira` path. |
 | **Reconnect** | Reauthorize the Jira account and grant all requested permissions. This is needed after a grant is revoked or its required permissions change. |
 | Connection tab does not open | Allow pop-ups for Sim, then click **Connect account** again. |
 
@@ -131,8 +132,8 @@ The deployment operator configures one shared Jira OAuth integration. Teammates
 
    Example callback in Atlassian's developer console. Replace `sim.example.com` with your Sim domain.
 
-3. Under **Permissions**, add the Jira and Jira Service Management APIs and configure the full scope set requested by Sim's Jira integration. Also add **User Identity API** with `read:me`. Sim requests `offline_access` for refresh tokens. The Search read scopes above are only a subset of this shared integration's permissions. Check the `jira` scope list for your release in [Sim's OAuth configuration](https://github.com/simstudioai/sim/blob/staging/apps/sim/lib/oauth/oauth.ts).
+3. Under **Permissions**, add **Jira API**, then **Configure** its classic and granular scopes for Jira, Jira Service Management, and Assets. Separately add **User Identity API** with `read:me`. Sim requests `offline_access` in the authorization URL for refresh tokens. Configure the full `jira` scope list for your release in [Sim's OAuth configuration](https://github.com/simstudioai/sim/blob/staging/apps/sim/lib/oauth/oauth.ts); the Search read scopes above are only a subset of this shared integration's permissions.
 4. Under **Distribution**, enable sharing so teammates can authorize the app. Copy the client ID and secret from **Settings** into `JIRA_CLIENT_ID` and `JIRA_CLIENT_SECRET`, set the correct `NEXT_PUBLIC_APP_URL`, and restart Sim.
 5. Start a connection from Search. Confirm that Atlassian lists the intended site, then return to Sim. After changing requested scopes, reconnect previously authorized accounts.
 
-If Atlassian reports a callback mismatch, compare the registered callback with the exact Sim origin and `/jira` callback path. If only the app owner can connect, check **Distribution**. See Atlassian's [OAuth configuration and sharing guide](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/) and Sim's [deployment reference](/platform/self-hosting/integrations-oauth).
+For a local instance using `NEXT_PUBLIC_APP_URL=http://localhost:3000`, register `http://localhost:3000/api/auth/oauth2/callback/jira`. Use a separate development OAuth app when production callbacks must remain unchanged. After updating local client credentials or the app URL, restart Sim and begin a new connection from Search. If only the app owner can connect, check **Distribution**. See Atlassian's [OAuth configuration and sharing guide](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/) and Sim's [deployment reference](/platform/self-hosting/integrations-oauth).

apps/sim/lib/credential-groups/oauth-state.test.ts

@@ -114,6 +114,34 @@ describe('credential group OAuth state', () => {
     ).rejects.toThrow('Credential group OAuth requires Redis')
   })
 
+  it('round-trips a scopeless GitHub App attempt with PKCE and one-time state', async () => {
+    const created = await createCredentialGroupOAuthAttempt({
+      provider: 'github-repositories',
+      workspaceId: 'workspace-1',
+      email: 'person@example.com',
+      enrollmentId: 'enrollment-1',
+      credentialGroupId: 'group-1',
+      optionId: 'option-1',
+      authorizationAppId: 'github-app:fixture',
+      scopeVersion: 1,
+      requiredScopes: [],
+      redirectUri: 'https://sim.example.com/api/auth/oauth2/callback/github-repositories',
+      codeVerifier: 'github-code-verifier',
+      invitationToken: 'invitation-token',
+      returnTo: 'search',
+    })
+
+    const consumed = await consumeCredentialGroupOAuthAttempt(created.state)
+    expect(consumed).toMatchObject({
+      provider: 'github-repositories',
+      requiredScopes: [],
+      codeVerifier: 'github-code-verifier',
+      returnTo: 'search',
+    })
+    expect(credentialGroupOAuthNonceMatches(created.nonce, consumed!.nonceHash)).toBe(true)
+    await expect(consumeCredentialGroupOAuthAttempt(created.state)).resolves.toBeNull()
+  })
+
   it('supports providers without PKCE while preserving one-time state', async () => {
     const created = await createCredentialGroupOAuthAttempt({
       provider: 'slack',
@@ -201,7 +229,7 @@ describe('credential group OAuth state', () => {
     await expect(consumeCredentialGroupOAuthAttempt(created.state)).rejects.toThrow('malformed')
     await expect(consumeCredentialGroupOAuthAttempt(created.state)).resolves.toBeNull()
   })
-  it.each(['workspaceId', 'email'])(
+  it.each(['workspaceId', 'email', 'requiredScopes'])(
     'rejects stored attempts missing the pinned %s and burns them',
     async (field) => {
       const created = await createCredentialGroupOAuthAttempt({

apps/sim/lib/credential-groups/oauth-state.ts

@@ -110,7 +110,6 @@ function isStoredAttempt(value: unknown): value is StoredCredentialGroupOAuthAtt
     Number.isInteger(candidate.scopeVersion) &&
     candidate.scopeVersion > 0 &&
     Array.isArray(candidate.requiredScopes) &&
-    candidate.requiredScopes.length > 0 &&
     candidate.requiredScopes.every((scope) => typeof scope === 'string' && scope.length > 0) &&
     typeof candidate.redirectUri === 'string' &&
     (candidate.completionRedirect === undefined ||

apps/sim/lib/credentials/managed-oauth.test.ts

@@ -1,7 +1,7 @@
 /**
  * @vitest-environment node
  */
-import { dbChainMockFns, resetDbChainMock } from '@sim/testing'
+import { dbChainMockFns, resetDbChainMock, resetEnvMock, setEnv } from '@sim/testing'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
 const mocks = vi.hoisted(() => ({
@@ -45,6 +45,7 @@ import {
   SLACK_SEARCH_USER_SCOPES,
 } from '@/lib/credential-groups/slack-managed-user-scopes'
 import { slackCredentialGroupProviderAdapter } from '@/lib/credential-groups/slack-provider'
+import { createStandardOAuthCredentialGroupProviderAdapter } from '@/lib/credential-groups/standard-oauth-provider'
 import { rejectManagedOAuthToken, resolveManagedOAuthToken } from '@/lib/credentials/managed-oauth'
 
 function mondayCredentialRow() {
@@ -102,6 +103,61 @@ describe('managed OAuth token resolution', () => {
 
   afterEach(() => {
     vi.useRealTimers()
+    resetEnvMock()
+  })
+
+  it('resolves a scopeless GitHub grant through the canonical provider policy', async () => {
+    setEnv({ GITHUB_APP_CLIENT_ID: 'fixture-client', GITHUB_APP_CLIENT_SECRET: 'fixture-secret' })
+    const adapter = createStandardOAuthCredentialGroupProviderAdapter('github-repositories')
+    const policy = await adapter.getPolicy(undefined, { workspaceId: 'workspace-1' })
+    expect(policy.requiredScopes).toEqual([])
+    mocks.getAdapter.mockReturnValue(adapter)
+    dbChainMockFns.limit.mockResolvedValueOnce([
+      {
+        ...mondayCredentialRow(),
+        providerId: policy.providerId,
+        authorizationAppId: policy.authorizationAppId,
+        managedOauthScopeVersion: policy.scopeVersion,
+        grantedScopes: [],
+        accessTokenExpiresAt: new Date('2026-09-01T13:00:00Z'),
+      },
+    ])
+    await expect(
+      resolveManagedOAuthToken({
+        ...mondayTokenResolutionParams(),
+        expectedProviderId: policy.providerId,
+        requiredScopes: [],
+      })
+    ).resolves.toMatchObject({ refreshed: false })
+    expect(mocks.decryptSecret).toHaveBeenCalledWith('encrypted-token-set')
+  })
+
+  it.each([null, undefined])(
+    'rejects missing granted-scope metadata: %s',
+    async (grantedScopes) => {
+      dbChainMockFns.limit.mockResolvedValueOnce([{ ...mondayCredentialRow(), grantedScopes }])
+      await expect(resolveManagedOAuthToken(mondayTokenResolutionParams())).rejects.toMatchObject({
+        code: 'MANAGED_CREDENTIAL_INVALID_TOKEN_SET',
+      })
+      expect(mocks.decryptSecret).not.toHaveBeenCalled()
+    }
+  )
+
+  it('rejects an empty grant when the provider policy requires scopes', async () => {
+    mocks.getAdapter.mockReturnValue({
+      getPolicy: vi.fn().mockResolvedValue({
+        authorizationAppId: 'monday:monday-client-1',
+        scopeVersion: 1,
+        requiredScopes: ['boards:read', 'me:read'],
+      }),
+      hasRequiredScopes: (granted: string[], required: string[]) =>
+        required.every((scope) => granted.includes(scope)),
+    })
+    dbChainMockFns.limit.mockResolvedValueOnce([{ ...mondayCredentialRow(), grantedScopes: [] }])
+    await expect(
+      resolveManagedOAuthToken({ ...mondayTokenResolutionParams(), requiredScopes: [] })
+    ).rejects.toMatchObject({ code: 'MANAGED_CREDENTIAL_INSUFFICIENT_SCOPE' })
+    expect(mocks.decryptSecret).not.toHaveBeenCalled()
   })
 
   function seedSlackSearchCredential(

apps/sim/lib/credentials/managed-oauth.ts

@@ -214,7 +214,7 @@ async function assertManagedCredentialUsable(
       401
     )
   }
-  if (!row.authorizationAppId || !row.encryptedOauthTokenSet || !row.grantedScopes?.length) {
+  if (!row.authorizationAppId || !row.encryptedOauthTokenSet || !row.grantedScopes) {
     throw new ManagedOAuthCredentialError(
       'MANAGED_CREDENTIAL_INVALID_TOKEN_SET',
       'Managed credential metadata is incomplete',
@@ -251,6 +251,7 @@ async function assertManagedCredentialUsable(
   }
 
   if (
+    (row.grantedScopes.length === 0 && policy.requiredScopes.length > 0) ||
     !adapter.hasRequiredScopes(policy.requiredScopes, requiredScopes) ||
     !adapter.hasRequiredScopes(row.grantedScopes, requiredScopes)
   ) {