feat(knowledge): mirror Confluence space permissions and page restrictions

Confluence joins Drive as a source an administrator crawl can mirror, and it is
the case that shaped the contract.

A page's restrictions come back only when that page is asked for, so they cannot
ride along with the listing the way Drive's permissions do. `getDocumentAcls`
resolves them for the whole listing at once, after it — round trips bounded by
the corpus rather than by the page size, with the space's principals, each
page's restriction, and every address resolved once per run and reused. Only an
unrestricted page pays for its ancestry, which is the expensive lookup.

A restriction replaces the space's permissions rather than narrowing them. Real
Confluence access is the intersection, so this over-grants in exactly one case:
somebody named on a page restriction who cannot view the space at all. That is a
misconfiguration in the source, it errs toward a page they were deliberately
named on, and it is what Onyx does. Representing the true intersection would
mean expanding both principal sets to member addresses, which our group tables
could do — but it emits one token per member, and a five-thousand-person space
would carry five-thousand-token ACLs on every restricted page.

`null` and `[]` are different answers throughout: no restriction means inherit
from the nearest restricted ancestor, then the space; a restriction naming
nobody means readable by nobody. Confluence itself only ever produces the first,
but collapsing them would publish every deliberately locked page.

One departure from the plan, which said to identify groups by name as Onyx does.
Onyx uses names because its membership sync is keyed by name; ours is keyed by
whatever the permissions API returns, and that is the id. Using it costs no
lookup per group and survives a rename, which a name-keyed ACL would not.

Directory enumeration moves behind one connector hook. The tenant is baked into
every stored group token, and only the connector knows what a tenant is for its
source — a Workspace domain for Drive, a site's cloud id for Confluence. The
engine previously derived it from the impersonation subject, which Confluence
does not have: its service account authenticates with an API token and
impersonates nobody, so directory refresh would have silently skipped.

The limit worth knowing: Confluence Cloud withholds an address whose owner's
profile hides it, and a person we cannot name cannot be granted access. Those
grants are dropped and counted rather than guessed at, and a group with a
withheld member is reported incomplete so it never replaces a stored membership
with a subset.

Author: waleedlatif1

apps/sim/connectors/confluence/confluence.ts

@@ -5,8 +5,20 @@ import {
   AtlassianSiteNotAccessibleError,
   AtlassianSiteNotMatchedError,
 } from '@/lib/atlassian/discovery'
+import {
+  type ConfluencePrincipal,
+  type ConfluenceRestriction,
+  confluencePageAcl,
+} from '@/lib/knowledge/access/confluence-permissions'
 import { fetchWithRetry, VALIDATE_RETRY_OPTIONS } from '@/lib/knowledge/documents/utils'
 import { confluenceConnectorMeta } from '@/connectors/confluence/meta'
+import {
+  getReadRestriction,
+  listAncestorIds,
+  listSpaceReadPrincipals,
+  openConfluenceDirectory,
+  resolveUserEmails,
+} from '@/connectors/confluence/permissions'
 import type { ConnectorConfig, ExternalDocument, ExternalDocumentList } from '@/connectors/types'
 import { htmlToPlainText, joinTagArray, parseMultiValue, parseTagDate } from '@/connectors/utils'
 import { getConfluenceCloudId, normalizeConfluenceDomainHost } from '@/tools/confluence/utils'
@@ -298,6 +310,137 @@ function cqlResultToStub(item: Record<string, unknown>, domain: string): Externa
   })
 }
 
+/**
+ * The provider segment of every Confluence group token. Fixed, and baked into
+ * stored ACLs, so it must never change.
+ */
+const CONFLUENCE_ACL_PROVIDER_ID = 'confluence'
+
+/** Pages whose restrictions are resolved at once. Bounded to keep a crawl responsive. */
+const ACL_CONCURRENCY = 8
+
+/**
+ * Resolves who may read each listed page.
+ *
+ * Confluence reports a page's restrictions only when asked for that page, so
+ * unlike Drive this cannot ride along with the listing. Three things are cached
+ * for the run: the space's read principals (one call per space), each page's
+ * restriction, and every account id's address — an ancestor's restriction is
+ * consulted by many of its descendants, and one person is usually named on
+ * several pages.
+ */
+async function resolveConfluenceAcls(
+  accessToken: string,
+  sourceConfig: Record<string, unknown>,
+  externalIds: string[],
+  syncContext?: Record<string, unknown>
+): Promise<Record<string, string[]>> {
+  const domain = normalizeConfluenceDomainHost(sourceConfig.domain as string)
+  let cloudId = syncContext?.cloudId as string | undefined
+  if (!cloudId) {
+    cloudId = await getConfluenceCloudId(domain, accessToken)
+    if (syncContext) syncContext.cloudId = cloudId
+  }
+
+  const spaceKeys = parseMultiValue(sourceConfig.spaceKey)
+  const spacePrincipals: ConfluencePrincipal[] = []
+  for (const spaceKey of spaceKeys) {
+    const spaceId = await resolveSpaceId(cloudId, accessToken, spaceKey)
+    spacePrincipals.push(...(await listSpaceReadPrincipals(cloudId, accessToken, spaceId)))
+  }
+
+  const restrictions = new Map<string, ConfluenceRestriction>()
+  const chains = new Map<string, ConfluenceRestriction[]>()
+
+  const readRestriction = async (contentId: string): Promise<ConfluenceRestriction> => {
+    const cached = restrictions.get(contentId)
+    if (cached !== undefined) return cached
+    const restriction = await getReadRestriction(cloudId, accessToken, contentId)
+    restrictions.set(contentId, restriction)
+    return restriction
+  }
+
+  await mapWithConcurrency(externalIds, ACL_CONCURRENCY, async (externalId) => {
+    const own = await readRestriction(externalId)
+    /**
+     * A page carrying its own restriction decides on the spot; only an
+     * unrestricted page needs its ancestry, which is the expensive lookup.
+     */
+    if (own !== null) {
+      chains.set(externalId, [own])
+      return
+    }
+    const ancestorIds = await listAncestorIds(cloudId, accessToken, externalId)
+    const chain: ConfluenceRestriction[] = [null]
+    for (const ancestorId of ancestorIds) {
+      const restriction = await readRestriction(ancestorId)
+      chain.push(restriction)
+      if (restriction !== null) break
+    }
+    chains.set(externalId, chain)
+  })
+
+  /**
+   * Addresses are resolved once for every account named anywhere, rather than
+   * per page: a space's own principals appear on every page that inherits them.
+   */
+  const accountIds = new Set<string>()
+  for (const principal of spacePrincipals) {
+    if (principal.kind === 'user') accountIds.add(principal.id)
+  }
+  for (const restriction of restrictions.values()) {
+    for (const principal of restriction ?? []) {
+      if (principal.kind === 'user') accountIds.add(principal.id)
+    }
+  }
+  const emails = await resolveUserEmails(cloudId, accessToken, [...accountIds])
+  const withEmail = (principals: readonly ConfluencePrincipal[]): ConfluencePrincipal[] =>
+    principals.map((principal) =>
+      principal.kind === 'user' ? { ...principal, email: emails.get(principal.id) } : principal
+    )
+
+  const acls: Record<string, string[]> = {}
+  let unattributed = 0
+  for (const externalId of externalIds) {
+    const chain = chains.get(externalId)
+    /** A page whose restrictions could not be read is readable by nobody, not by everyone. */
+    if (!chain) continue
+    const result = confluencePageAcl({
+      spacePrincipals: withEmail(spacePrincipals),
+      restrictionChain: chain.map((entry) => (entry === null ? null : withEmail(entry))),
+      providerId: CONFLUENCE_ACL_PROVIDER_ID,
+      tenantId: cloudId,
+    })
+    acls[externalId] = result.acl
+    unattributed += result.unattributedUsers
+  }
+
+  if (unattributed > 0) {
+    logger.warn('Confluence withheld addresses for some granted users; those grants were dropped', {
+      cloudId,
+      unattributed,
+    })
+  }
+  return acls
+}
+
+/** Runs `worker` over `items`, at most `limit` at a time, preserving no order. */
+async function mapWithConcurrency<T>(
+  items: readonly T[],
+  limit: number,
+  worker: (item: T) => Promise<void>
+): Promise<void> {
+  let cursor = 0
+  const runners = Array.from({ length: Math.min(limit, items.length) }, async () => {
+    for (;;) {
+      const index = cursor++
+      if (index >= items.length) return
+      await worker(items[index])
+    }
+  })
+  await Promise.all(runners)
+}
+
 export const confluenceConnector: ConnectorConfig = {
   ...confluenceConnectorMeta,
 
@@ -379,6 +522,18 @@ export const confluenceConnector: ConnectorConfig = {
     )
   },
 
+  getDocumentAcls: resolveConfluenceAcls,
+
+  openDirectory: async (accessToken, sourceConfig, syncContext) => {
+    const domain = normalizeConfluenceDomainHost(sourceConfig.domain as string)
+    let cloudId = syncContext?.cloudId as string | undefined
+    if (!cloudId) {
+      cloudId = await getConfluenceCloudId(domain, accessToken)
+      if (syncContext) syncContext.cloudId = cloudId
+    }
+    return openConfluenceDirectory(cloudId, accessToken)
+  },
+
   getDocument: async (
     accessToken: string,
     sourceConfig: Record<string, unknown>,

apps/sim/connectors/confluence/meta.ts

@@ -20,6 +20,24 @@ export const confluenceConnectorMeta: ConnectorMeta = {
       'search:confluence',
       'offline_access',
     ],
+    /**
+     * Mirroring adds the three reads an ACL needs and nothing else: a space's
+     * permissions, a page's restrictions, and the addresses behind the account
+     * ids both return. `read:confluence-user` is what decides whether a person
+     * can be granted access individually at all — without it every principal is
+     * an opaque account id that no Sim reader can be matched to.
+     */
+    serviceAccountScopes: [
+      'read:confluence-content.all',
+      'read:page:confluence',
+      'read:blogpost:confluence',
+      'read:space:confluence',
+      'read:label:confluence',
+      'search:confluence',
+      'read:confluence-space.summary',
+      'read:confluence-user',
+      'read:group:confluence',
+    ],
   },
 
   /**
@@ -34,6 +52,14 @@ export const confluenceConnectorMeta: ConnectorMeta = {
   /** CQL search under a member's token returns only content that member may view. */
   permissionScopedListing: { capFieldIds: ['maxPages'] },
 
+  /**
+   * Space permissions and page restrictions are both readable, so one crawl
+   * under an administrative credential can mirror them. Unlike Drive they come
+   * back per page rather than with the listing, which is what
+   * `getDocumentAcls` exists for.
+   */
+  mirrorsSourceAcls: true,
+
   configFields: [
     {
       id: 'domain',