docs: surface known security quirks as info notes

Five small Note cards documenting accepted security trade-offs that
surfaced during the BB Cloud profile acceptance run, so customers can
plan for them without surprise. None are bugs to fix; they are upstream
constraints or design choices worth flagging in-line where users would
otherwise have to derive them empirically.

- Session lifetime: JWT verifier clock-skew tolerance means sessions
  may be accepted briefly past AUTH_SESSION_MAX_AGE_SECONDS.
- Bitbucket Cloud: Atlassian's 14-day account-deletion grace period
  can leave a closed user in BB permission lists until purge or until
  the next permission sync sees an auth error.
- enforcePermissionsForPublicRepos: clarify that this is a host-level
  membership check, not a per-repo permission check.
- Visibility changes are refreshed by connection sync, not permission
  sync, so public/private flips converge on resyncConnectionIntervalMs.
- Permission sync fails closed only on auth-related errors; transient
  rate-limit and 5xx responses leave the previous state in effect.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: msukkari

docs/docs/configuration/auth/overview.mdx

@@ -22,6 +22,10 @@ Sourcebot's built-in authentication system gates your deployment, and allows adm
 </CardGroup>
 
 
+# Session lifetime
+
+<Note>Session cookies are guaranteed to be valid for at least `AUTH_SESSION_MAX_AGE_SECONDS`, but may be accepted for a brief additional window before expiring. This is because the JWT verifier applies a small clock-skew tolerance when checking expiry.</Note>
+
 # Troubleshooting
 
 - If you experience issues logging in, logging out, or accessing an organization you should have access to, try clearing your cookies & performing a full page refresh (`Cmd/Ctrl + Shift + R` on most browsers).

docs/docs/features/permission-syncing.mdx

@@ -102,6 +102,8 @@ These users **will** still gain access via [user-driven syncing](/docs/features/
 If your workspace relies heavily on group or project-level permissions rather than direct user grants, we recommend reducing the `userDrivenPermissionSyncIntervalMs` interval to limit the window of delay.
 </Warning>
 
+<Note>When a Bitbucket Cloud account is closed by its owner, Atlassian applies an account-deletion grace period (currently 14 days for consumer accounts) before the account is fully purged. During this window, Bitbucket's permission APIs may continue to return the closed user in repository permission lists. Sourcebot revokes that user's access once the next permission sync receives an authentication error from Bitbucket, or once Atlassian fully purges the account.</Note>
+
 **Notes:**
 - A Bitbucket Cloud [external identity provider](/docs/configuration/idp#bitbucket-cloud) must be configured to (1) correlate a Sourcebot user with a Bitbucket Cloud user, and (2) to list repositories that the user has access to for [User driven syncing](/docs/features/permission-syncing#how-it-works).
 - OAuth tokens require the `account` and `repository` scopes. The `repository` scope is required to list private repositories during [User driven syncing](/docs/features/permission-syncing#how-it-works).
@@ -176,6 +178,10 @@ These flags are useful when you want different enforcement behavior across conne
 }
 ```
 
+<Note>When `enforcePermissionsForPublicRepos` is `true`, public repositories are visible to any user who has linked an account on the same code host. The check is at the host level rather than per-repo, so users do not need explicit upstream read access to each public repository individually.</Note>
+
+<Note>A repository's public-vs-private state is refreshed by [connection sync](/docs/connections/overview#connection-syncing), not by permission sync. After a visibility change at the code host, Sourcebot continues to apply its previous classification until the next connection sync runs (configurable via `resyncConnectionIntervalMs`, default 24 hours). Lower this value if your deployment expects faster propagation of visibility changes.</Note>
+
 The table below shows when permissions are enforced based on the combination of `PERMISSION_SYNC_ENABLED`, `enforcePermissions`, and `enforcePermissionsForPublicRepos`:
 
 | `PERMISSION_SYNC_ENABLED` | `enforcePermissions` | `enforcePermissionsForPublicRepos` | Private repos enforced? | Public repos enforced? |
@@ -202,4 +208,6 @@ The sync intervals can be configured using the following settings in the [config
 | Setting                                         | Type    | Default    | Minimum |
 |-------------------------------------------------|---------|------------|---------|
 | `repoDrivenPermissionSyncIntervalMs` | number  | 24 hours   | 1       |
-| `userDrivenPermissionSyncIntervalMs` | number  | 24 hours   | 1       |
+| `userDrivenPermissionSyncIntervalMs` | number  | 24 hours   | 1       |
+
+<Note>Permission syncing fails closed only on authentication-related errors (`401`, `403`, `410`, or OAuth token refresh failures), in which case Sourcebot clears the affected account's permission rows immediately. Transient errors such as rate limits or `5xx` responses leave the previous permission state in effect until the next successful sync, so that brief upstream incidents do not strand users without access.</Note>