docs: add security notes to docs (#1218)

Author: msukkari

CHANGELOG.md

@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+- Documented session lifetime, repository visibility refresh behavior, and how permission sync handles transient code-host errors. [#1218](https://github.com/sourcebot-dev/sourcebot/pull/1218)
+
 ## [4.17.3] - 2026-05-22
 
 ### Fixed

docs/docs/configuration/auth/overview.mdx

@@ -22,6 +22,14 @@ Sourcebot's built-in authentication system gates your deployment, and allows adm
 </CardGroup>
 
 
+# Session lifetime
+
+By default, session cookies remain valid for 30 days from the time they are issued, after which the user is signed out and must authenticate again.
+
+You can change this by setting the [`AUTH_SESSION_MAX_AGE_SECONDS`](/docs/configuration/environment-variables) environment variable to the desired lifetime in seconds.
+
+A session is guaranteed to remain valid for at least its configured lifetime. The JWT verifier applies a small clock-skew tolerance when checking expiry, so a session may continue to be accepted for a brief additional window past that point before it is rejected.
+
 # 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).
@@ -202,4 +204,17 @@ 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       |
+
+# FAQ
+
+### What happens if there are transient errors with the code host?
+
+It depends on the type of error:
+
+- **Authentication errors** (such as `401`, `403`, `410`, or a token refresh failure): Sourcebot immediately revokes the affected user's access to repositories on that code host.
+- **Rate limits or `5xx` responses**: Sourcebot keeps the user's existing access.
+
+### When is a visibility change of a repo (switching from public to private) reflected within Sourcebot?
+
+The visibility state of a repository is updated when the [connection](/docs/connections/overview#connection-syncing) belonging to that repository is synced, not when the repository's permissions are synced. Until the next connection sync runs, Sourcebot continues to apply the repository's previous public/private classification. The connection sync interval is configurable via the `resyncConnectionIntervalMs` setting in the [config file](/docs/configuration/config-file) and defaults to 24 hours. Lower this value if you require faster propagation of visibility changes.