docs: add security notes to docs

[msukkari]

Summary by CodeRabbit

• Documentation
  • Added session lifetime details to authentication docs: default 30‑day cookie validity, configurable session lifetime, guaranteed minimum validity, and JWT expiry behavior with clock‑skew tolerance.
  • Clarified permission‑syncing guidance: account‑closure handling, public-vs-private repo visibility is refreshed by connection sync (may lag until next resync), and fail‑closed vs transient error behaviors.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
sourcebot	🟢 Ready	View Preview	May 22, 2026, 1:09 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

Walkthrough

This PR adds clarifying documentation: a "Session lifetime" note describing default 30-day cookie validity and JWT clock-skew tolerance, and expanded permission-syncing docs covering Bitbucket Cloud closed-account behavior, connection-resync repository visibility timing, added user-driven sync interval, and fail-closed error semantics.

Changes

Authentication and Permission Feature Documentation

Layer / File(s)	Summary
Session lifetime documentation docs/docs/configuration/auth/overview.mdx	Session cookies remain valid for at least AUTH_SESSION_MAX_AGE_SECONDS (default 30 days) and may be accepted briefly longer due to JWT expiry clock-skew tolerance in verification.
Permission-syncing behavior clarifications docs/docs/features/permission-syncing.mdx	Notes that repo public/private classification is updated by connection sync (may lag until resyncConnectionIntervalMs), describes Bitbucket Cloud account-deletion grace-period behavior, adds userDrivenPermissionSyncIntervalMs to the intervals table, and documents fail-closed semantics for auth errors versus retention on transient errors.

---

🎯 2 (Simple) | ⏱️ ~10 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title 'docs: add security notes to docs' is vague and generic. It uses non-descriptive language ('add security notes') that doesn't convey what specific security documentation was added or which areas were addressed.	Revise the title to be more specific about the changes, such as 'docs: document session lifetime, connection sync behavior, and permission-sync error handling' or 'docs: clarify authentication session and permission-sync security behavior'.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch msukkari/docs-known-security-quirks

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/docs/configuration/auth/overview.mdx`:
- Line 27: Rewrite the Note block so it speaks directly to the reader in second
person and uses short, direct sentences: start by telling the user that their
session cookie is guaranteed valid for at least AUTH_SESSION_MAX_AGE_SECONDS,
then add a separate sentence that explains it may still be accepted briefly
after that, and finish with a short sentence noting this is due to the JWT
verifier applying a small clock‑skew tolerance when checking expiry. Use "you"
phrasing and keep each idea in its own concise sentence.

In `@docs/docs/features/permission-syncing.mdx`:
- Line 105: Rewrite the Note block text into short, second-person, present-tense
sentences: replace third-person phrasing like “Bitbucket Cloud account is closed
by its owner” with direct “When you close a Bitbucket Cloud account…” and
shorten into two or three concise sentences that state the behavior and action
(e.g., you may still appear in repo permission lists during Atlassian’s grace
period; Sourcebot revokes your access after the next permission sync that
returns an authentication error or when Atlassian purges the account). Do the
same for the two other similar note blocks referenced in the file (the later
notes around the other occurrences) so all notes use “you,” present tense, and
tighter sentence structure.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: bc615d7e-14e8-4c0c-b6cc-0ae3d9c0e3ec

📥 Commits

Reviewing files that changed from the base of the PR and between 3851c66 and efdad7f.

📒 Files selected for processing (2)

• docs/docs/configuration/auth/overview.mdx
• docs/docs/features/permission-syncing.mdx