From 176973cb7b618a82eec4d24f7497352ea5da4acc Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 19 Jul 2026 11:51:22 +0800
Subject: [PATCH] docs(session-persistence): clarify SQLite permission limits

---
 docs/config-catalog.md                                 |  7 ++++---
 .../session-persistence-sqlite/README.md               |  2 +-
 .../session-persistence-sqlite/src/index.ts            | 10 ++++++----
 3 files changed, 11 insertions(+), 8 deletions(-)

diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 6069263b8e..05fa3eab67 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -659,8 +659,9 @@ export interface Config {
    * opens an in-process database (tests). On filesystems with POSIX modes,
    * missing directories and databases are created owner-only; existing path
    * modes are preserved. Filesystem setup errors other than an existing database
-   * fail initialization. The backend does not protect integrity when another
-   * principal can replace the database entry in its parent directory.
+   * fail initialization. The backend does not protect confidentiality or
+   * integrity when another principal can replace the database entry in its
+   * parent directory.
    */
   path: string
   /**
@@ -683,7 +684,7 @@ export interface Config {
 export type JournalMode = 'wal' | 'delete' | 'truncate' | 'persist'
 ```
 
-Source: [`packages/session-persistence/session-persistence-sqlite/src/index.ts:54`](../packages/session-persistence/session-persistence-sqlite/src/index.ts)
+Source: [`packages/session-persistence/session-persistence-sqlite/src/index.ts:55`](../packages/session-persistence/session-persistence-sqlite/src/index.ts)
 
 ## `@deepseek-ai/dsh-session-query`
 
diff --git a/packages/session-persistence/session-persistence-sqlite/README.md b/packages/session-persistence/session-persistence-sqlite/README.md
index 602bd4e33f..e9066d3748 100644
--- a/packages/session-persistence/session-persistence-sqlite/README.md
+++ b/packages/session-persistence/session-persistence-sqlite/README.md
@@ -12,7 +12,7 @@ Each `SessionEvent` maps 1:1 onto a row in an `events` table `(session_id, seq,
 
 The repository's Node range supports unflagged `node:sqlite`. The database enables foreign keys and uses the configured journal mode (`wal` by default; use a rollback mode where WAL shared-memory files are unsuitable). `PRAGMA user_version` stores the table-layout version; databases with any other version are rejected because this unreleased format has no migrations.
 
-On filesystems with POSIX modes, the backend creates missing directories as `0700` and exclusively creates a missing database as `0600` before SQLite opens it. New WAL sidecars receive the database's owner-only mode. Existing directories, database files, and sidecars keep their modes; filesystem setup errors other than an existing database fail initialization. These defaults prevent incidental exposure through the process umask, but do not protect database integrity when another principal can replace the database entry in its parent directory.
+On filesystems with POSIX modes, the backend requests mode `0700` for missing directories and exclusively creates a missing database with mode `0600` before SQLite opens it; the process umask may further restrict both. New WAL sidecars receive the database's resulting owner-only mode. Existing directories, database files, and sidecars keep their modes; filesystem setup errors other than an existing database fail initialization. These defaults prevent incidental exposure through a permissive process umask, but do not protect database confidentiality or integrity when another principal can replace the database entry in its parent directory.
 
 ## Contract semantics over rows
 
diff --git a/packages/session-persistence/session-persistence-sqlite/src/index.ts b/packages/session-persistence/session-persistence-sqlite/src/index.ts
index 3515309f9a..4661b41309 100644
--- a/packages/session-persistence/session-persistence-sqlite/src/index.ts
+++ b/packages/session-persistence/session-persistence-sqlite/src/index.ts
@@ -38,8 +38,9 @@ function surfaceBindings(event: SessionEvent): [string | null, string | null] {
 /**
  * Exclusively create a missing database file with owner-only permissions.
  * Existing files retain their modes, and errors other than `EEXIST` propagate.
- * `DatabaseSync` reopens by path, so this does not protect integrity when
- * another principal can replace the database entry in its parent directory.
+ * `DatabaseSync` reopens by path, so this does not protect confidentiality or
+ * integrity when another principal can replace the database entry in its parent
+ * directory.
  */
 async function createDatabaseFile(path: string): Promise<void> {
   try {
@@ -57,8 +58,9 @@ export interface Config {
    * opens an in-process database (tests). On filesystems with POSIX modes,
    * missing directories and databases are created owner-only; existing path
    * modes are preserved. Filesystem setup errors other than an existing database
-   * fail initialization. The backend does not protect integrity when another
-   * principal can replace the database entry in its parent directory.
+   * fail initialization. The backend does not protect confidentiality or
+   * integrity when another principal can replace the database entry in its
+   * parent directory.
    */
   path: string
   /**