ChatComment 0.2.0__tar.gz → 0.2.1__tar.gz

{chatcomment-0.2.0 → chatcomment-0.2.1}/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.2.1
+
+- `--require-existing-db` 在 Store 初始化之前验证既有 SQLite 完整性、必要表/字段和可读性，拒绝空文件、损坏或错误 schema。
+- 只读源文件并在私有稳定快照上校验，保留活跃 WAL 支持，不在挂载目录创建 SQLite 辅助文件；允许完整 schema 的零留言数据库。
+
 ## 0.2.0
 
 - 平台中立的 `AccessContext` / `SiteAccess` API，复用 ChatLogin 主体并显式检查每站 read/comment/manage/owner；管理 grant 按 session 和站点区分。

{chatcomment-0.2.0 → chatcomment-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ChatComment
-Version: 0.2.0
+Version: 0.2.1
 Summary: Embeddable comments with a Python server, SQLite storage and a small JavaScript widget.
 Author: ChatArch
 License-Expression: MIT

{chatcomment-0.2.0 → chatcomment-0.2.1}/docs/platform.md

@@ -21,6 +21,13 @@ on the direct native application domain, require a signed context. `/health`
 is the only unsigned route. This mode explicitly rejects legacy token mode;
 browser `Role`, nickname, email and Bearer headers do not grant access.
 
+`--require-existing-db` validates the existing SQLite before `Store` can initialize
+anything: header, integrity, required tables/columns and readable schema. Empty,
+corrupt, unrelated or incompatible files fail closed without source changes.
+It reads a stable private snapshot including WAL rather than creating sidecars
+beside the mounted source; valid schemas with zero comments are accepted.
+The same preflight is available as `validate_existing_database(path)`.
+
 The legacy `--token-file` mode remains for existing deployments during staged
 migration. It must not be used as a multi-user platform authorization shortcut.
 

{chatcomment-0.2.0 → chatcomment-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ChatComment"
-version = "0.2.0"
+version = "0.2.1"
 description = "Embeddable comments with a Python server, SQLite storage and a small JavaScript widget."
 readme = "README.md"
 requires-python = ">=3.10"

{chatcomment-0.2.0 → chatcomment-0.2.1}/src/ChatComment.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ChatComment
-Version: 0.2.0
+Version: 0.2.1
 Summary: Embeddable comments with a Python server, SQLite storage and a small JavaScript widget.
 Author: ChatArch
 License-Expression: MIT

{chatcomment-0.2.0 → chatcomment-0.2.1}/src/ChatComment.egg-info/SOURCES.txt

@@ -18,6 +18,7 @@ src/chatcomment/access.py
 src/chatcomment/cli.py
 src/chatcomment/server.py
 src/chatcomment/store.py
+src/chatcomment/validation.py
 src/chatcomment/static/admin.html
 src/chatcomment/static/board.html
 src/chatcomment/static/login.html
@@ -27,4 +28,5 @@ tests/cli-tests/test_cli.py
 tests/code-tests/test_access.py
 tests/code-tests/test_chatlogin_adapter.py
 tests/code-tests/test_comments.py
-tests/code-tests/test_platform_http.py
+tests/code-tests/test_platform_http.py
+tests/code-tests/test_validation.py

{chatcomment-0.2.0 → chatcomment-0.2.1}/src/chatcomment/__init__.py

@@ -1,7 +1,8 @@
 """Reusable comments storage and HTTP service."""
-__version__ = "0.2.0"
+__version__ = "0.2.1"
 
 from .store import Store
 from .access import AccessContext,SiteAccess,sign_context,verify_context
+from .validation import validate_existing_database
 
-__all__ = ["Store", "AccessContext", "SiteAccess", "sign_context", "verify_context", "__version__"]
+__all__ = ["Store", "AccessContext", "SiteAccess", "sign_context", "verify_context", "validate_existing_database", "__version__"]

{chatcomment-0.2.0 → chatcomment-0.2.1}/src/chatcomment/cli.py

@@ -7,6 +7,7 @@ import click
 from chatstyle import add_tree_option
 
 from . import Store, __version__
+from .validation import validate_existing_database
 
 
 @click.group(name='chatcomment')
@@ -29,7 +30,7 @@ def main(ctx, db):
 @click.option('--session-endpoint', default='/api/session',show_default=True)
 @click.option('--reauth-endpoint', default=None,help='Platform same-origin management reauthentication endpoint.')
 @click.option('--return-path', default='/',show_default=True)
-@click.option('--require-existing-db',is_flag=True,help='Fail closed if the persistent database mount is missing.')
+@click.option('--require-existing-db',is_flag=True,help='Validate a readable existing ChatComment SQLite database before initialization.')
 @click.pass_context
 def serve(ctx, host, port, token_file,gateway_key_file,gateway_key_env,session_endpoint,reauth_endpoint,return_path,require_existing_db):
     """Serve API, widget assets and the gateway-protected admin page."""
@@ -40,8 +41,11 @@ def serve(ctx, host, port, token_file,gateway_key_file,gateway_key_env,session_e
     key=gateway_key_file.read_text().strip() if gateway_key_file else os.environ.get(gateway_key_env,'') if gateway_key_env else None
     if len(token if token is not None else key or '')<32:
         raise click.ClickException('Server credential must contain at least 32 characters.')
-    if require_existing_db and not ctx.obj['db'].expanduser().is_file():
-        raise click.ClickException('Persistent database mount is missing; refusing to create an empty database.')
+    if require_existing_db:
+        try:
+            validate_existing_database(ctx.obj['db'])
+        except ValueError as exc:
+            raise click.ClickException(str(exc)) from exc
     run(Store(ctx.obj['db']), token=token,gateway_key=key, host=host, port=port,
         session_endpoint=session_endpoint,reauth_endpoint=reauth_endpoint,return_path=return_path)
 

chatcomment-0.2.1/src/chatcomment/validation.py

@@ -0,0 +1,98 @@
+"""Read-only preflight for an existing persistent ChatComment database.
+
+SQLite mode=ro may still create WAL sidecars, and immutable=1 ignores a live
+WAL. Validate a stable private copy of the main file and journals instead; never
+open the source with SQLite, change its permissions or initialize its schema.
+"""
+from __future__ import annotations
+
+from contextlib import closing
+import os
+from pathlib import Path
+import shutil
+import sqlite3
+import stat
+import tempfile
+
+from .store import Invalid
+
+_COLUMNS = {
+    'sites': {'id':'TEXT','title':'TEXT','origins':'TEXT','pages':'TEXT','private':'INTEGER','settings':'TEXT'},
+    'comments': {'id':'TEXT','site_id':'TEXT','page_key':'TEXT','nickname':'TEXT','email':'TEXT',
+                 'website':'TEXT','content':'TEXT','status':'TEXT','created_at':'TEXT','authenticated':'INTEGER'},
+}
+
+
+def _files_state(path):
+    state={}
+    for suffix in ['', '-wal', '-journal']:
+        candidate=Path(str(path)+suffix)
+        try:
+            info=candidate.stat()
+        except FileNotFoundError:
+            state[suffix]=None
+            continue
+        if not stat.S_ISREG(info.st_mode):
+            raise Invalid('Persistent database validation failed: database and journals must be regular files.')
+        state[suffix]=(info.st_dev,info.st_ino,info.st_size,info.st_mtime_ns,info.st_ctime_ns)
+    return state
+
+
+def _validate_snapshot(path):
+    with closing(sqlite3.connect(path.as_uri()+'?mode=ro',uri=True,timeout=5)) as db:
+        db.execute('PRAGMA query_only=ON')
+        if db.execute('PRAGMA quick_check').fetchall()!=[('ok',)]:
+            raise Invalid('Persistent database validation failed: SQLite integrity check failed.')
+        tables={row[0] for row in db.execute("SELECT name FROM sqlite_master WHERE type='table'")}
+        for table,required in _COLUMNS.items():
+            if table not in tables:
+                raise Invalid(f'Persistent database validation failed: missing ChatComment table {table}.')
+            columns={row[1]:row for row in db.execute(f'PRAGMA table_info({table})')}
+            if ([name for name,row in columns.items() if row[5]]!=['id'] or
+                    any(name not in columns or columns[name][2].strip().upper()!=kind or
+                        (name!='id' and columns[name][3]!=1) for name,kind in required.items())):
+                raise Invalid(f'Persistent database validation failed: incompatible ChatComment schema for {table}.')
+            db.execute('SELECT '+','.join(required)+' FROM '+table+' LIMIT 1').fetchall()
+        foreign_keys={(row[2],row[3],row[4]) for row in db.execute('PRAGMA foreign_key_list(comments)')}
+        if ('sites','site_id','id') not in foreign_keys:
+            raise Invalid('Persistent database validation failed: missing comment site relationship.')
+
+
+def validate_existing_database(value):
+    """Validate a readable, structurally intact existing database without writes.
+
+    Empty files, unrelated SQLite databases, corrupt/incomplete schema and
+    unreadable files are refused before Store initialization. A valid database
+    may contain zero comments or even zero sites. Normal WAL writes may require
+    a retry to obtain a stable snapshot; persistent changes fail closed.
+    """
+    try:
+        path=Path(value).expanduser().resolve()
+        if not path.is_file():
+            raise Invalid('Persistent database mount is missing; refusing to create an empty database.')
+        with path.open('rb') as source:
+            if source.read(16)!=b'SQLite format 3\x00':
+                raise Invalid('Persistent database validation failed: empty or invalid SQLite file.')
+        for _ in range(3):
+            before=_files_state(path)
+            if before[''] is None:
+                continue
+            with tempfile.TemporaryDirectory(prefix='chatcomment-validate-') as directory:
+                snapshot=Path(directory)/'database.sqlite3'
+                try:
+                    for suffix,info in before.items():
+                        if info is None:
+                            continue
+                        target=Path(str(snapshot)+suffix)
+                        descriptor=os.open(target,os.O_CREAT|os.O_EXCL|os.O_WRONLY,0o600)
+                        with os.fdopen(descriptor,'wb') as destination,Path(str(path)+suffix).open('rb') as source:
+                            shutil.copyfileobj(source,destination)
+                    if _files_state(path)!=before:
+                        continue
+                    _validate_snapshot(snapshot)
+                    return path
+                except FileNotFoundError:
+                    continue
+        raise Invalid('Persistent database validation failed: database changed during the read-only check; retry startup.')
+    except (OSError,sqlite3.Error) as exc:
+        raise Invalid('Persistent database validation failed: database or schema is unreadable or corrupt.') from exc

chatcomment-0.2.1/tests/code-tests/test_validation.py

@@ -0,0 +1,89 @@
+import os
+from pathlib import Path
+import sqlite3
+from unittest.mock import patch
+
+from click.testing import CliRunner
+import pytest
+
+from chatcomment import Store,validate_existing_database
+from chatcomment.cli import main
+from chatcomment.store import Invalid
+
+
+def source_state(directory):
+    return {p.name:(p.read_bytes(),p.stat().st_mtime_ns,p.stat().st_mode) for p in directory.iterdir() if p.is_file()}
+
+
+@pytest.mark.parametrize('kind',['empty','garbage','corrupt','unrelated','missing-table','bad-columns','views'])
+def test_invalid_existing_database_never_initializes_or_writes(tmp_path,kind):
+    path=tmp_path/'comments.sqlite3'
+    if kind=='empty':path.touch()
+    elif kind=='garbage':path.write_bytes(b'not a sqlite database')
+    elif kind=='corrupt':
+        Store(path)
+        path.write_bytes(path.read_bytes()[:100])
+    else:
+        with sqlite3.connect(path) as db:
+            if kind=='unrelated':db.execute('CREATE TABLE unrelated(id INTEGER)')
+            elif kind=='missing-table':db.execute('CREATE TABLE sites(id TEXT PRIMARY KEY)')
+            elif kind=='bad-columns':
+                db.execute('CREATE TABLE sites(id INTEGER,title TEXT)')
+                db.execute('CREATE TABLE comments(id TEXT)')
+            else:
+                db.execute('CREATE TABLE data(id TEXT)')
+                db.execute('CREATE VIEW sites AS SELECT * FROM data')
+                db.execute('CREATE VIEW comments AS SELECT * FROM data')
+    before=source_state(tmp_path)
+    with patch('chatcomment.cli.Store') as constructor,patch('chatcomment.server.serve') as run:
+        result=CliRunner().invoke(main,['--db',str(path),'serve','--gateway-key-env','TEST_GATEWAY_KEY','--require-existing-db'],env={'TEST_GATEWAY_KEY':'x'*48})
+        assert result.exit_code!=0 and 'Persistent database validation failed' in result.output
+        constructor.assert_not_called();run.assert_not_called()
+    assert source_state(tmp_path)==before
+
+
+def test_complete_zero_comment_schema_is_accepted_without_source_sidecars(tmp_path):
+    path=tmp_path/'comments.sqlite3';Store(path)
+    before=source_state(tmp_path)
+    assert validate_existing_database(path)==path.resolve()
+    assert source_state(tmp_path)==before
+    with patch('chatcomment.server.serve') as run:
+        result=CliRunner().invoke(main,['--db',str(path),'serve','--gateway-key-env','TEST_GATEWAY_KEY','--require-existing-db'],env={'TEST_GATEWAY_KEY':'x'*48})
+        assert result.exit_code==0,result.output
+        run.assert_called_once()
+
+
+def test_live_wal_schema_is_read_and_source_files_are_untouched(tmp_path):
+    path=tmp_path/'comments.sqlite3'
+    # Keep a writer open so the current schema lives in WAL, not the base file.
+    template=Store(tmp_path/'template.sqlite3')
+    with template.connect() as db:
+        schema=[r[0] for r in db.execute("SELECT sql FROM sqlite_master WHERE sql IS NOT NULL ORDER BY rowid")]
+    writer=sqlite3.connect(path)
+    writer.execute('PRAGMA journal_mode=WAL');writer.execute('PRAGMA wal_autocheckpoint=0')
+    writer.executescript(';\n'.join(schema)+';')
+    with sqlite3.connect(path.as_uri()+'?mode=ro&immutable=1',uri=True) as base_only:
+        assert 'comments' not in {r[0] for r in base_only.execute('SELECT name FROM sqlite_master')}
+    before=source_state(tmp_path)
+    assert validate_existing_database(path)==path.resolve()
+    assert source_state(tmp_path)==before
+    writer.close()
+
+
+def test_wrong_wal_schema_does_not_create_source_sidecars(tmp_path):
+    path=tmp_path/'comments.sqlite3'
+    writer=sqlite3.connect(path);writer.execute('PRAGMA journal_mode=WAL')
+    writer.execute('CREATE TABLE unrelated(id TEXT)');writer.commit()
+    before=source_state(tmp_path)
+    with pytest.raises(Invalid):validate_existing_database(path)
+    assert source_state(tmp_path)==before
+    writer.close()
+
+
+@pytest.mark.skipif(hasattr(os,'geteuid') and os.geteuid()==0,reason='Root can read mode000 files')
+def test_unreadable_file_is_refused_without_changing_permissions(tmp_path):
+    path=tmp_path/'comments.sqlite3';Store(path);path.chmod(0)
+    try:
+        with pytest.raises(Invalid,match='unreadable'):validate_existing_database(path)
+        assert path.stat().st_mode & 0o777==0
+    finally:path.chmod(0o600)