feat: add ANONYMOUS_READ.

Author: PttCodingMan

.env.example

@@ -22,6 +22,16 @@ ALLOWED_ORIGINS=
 # client to the proxy's IP.
 TRUST_PROXY=false
 
+# ── Anonymous Read (Demo / Public Wiki Mode) ──
+# When true, visitors without a valid session are treated as a synthetic
+# "guest" viewer (role=viewer) instead of being redirected to /login.
+# They can browse the page tree, search, graph, recent activity, and any
+# page whose ACL chain has no anchor (the open-default set). Writes,
+# personal endpoints (bookmarks, watch, comments POST, profile, tokens),
+# AI chat, and admin endpoints all stay login-required.
+# Default off so existing private deployments are unaffected.
+ANONYMOUS_READ=false
+
 # ── AI Chat (optional) ──
 # Defaults target Gemini. Get an API key at https://aistudio.google.com/apikey
 # Any OpenAI-compatible provider works — just change AI_BASE_URL + AI_MODEL.

CLAUDE.md

@@ -112,6 +112,7 @@ Resolution logic (in `services/acl.py` — routers must use these helpers, never
 - Per-page ACL rows live in `page_acl (page_id, principal_type, principal_id, permission)` where principal is a user or group.
 - To resolve: walk the `parent_id` chain, find the shallowest ancestor with any ACL row (the "anchor"), and take the most-permissive matching row. If no anchor exists, the page is open by default (write for editors, read for viewers).
 - `viewer` role is capped at `read` even when ACL grants write.
+- When `ANONYMOUS_READ=true` (env), unauthenticated requests get a synthetic guest user (`id=0`, `role=viewer`, `anonymous=True`) instead of 401. ACL still gates everything — guests can only read pages with no ACL anchor (the open-default set). All write/personal endpoints (bookmarks, comments POST, watch, profile, tokens, AI) reject the guest via `auth.require_real_user`; admin endpoints reject via `require_admin`. `/api/auth/me` keeps returning 401 for unauthenticated requests so the frontend can distinguish guest from logged-in.
 - Frontend: `usePermissions` store caches per-slug; seeded from `effective_permission` on page-view responses. Helper functions `canEdit`, `canRead`, `canManageAcl` are exported from the store file.
 
 ## Themes

backend/app/auth.py

@@ -17,6 +17,27 @@
 API_TOKEN_PREFIX = "jwk_"
 API_TOKEN_DISPLAY_PREFIX_LEN = 12  # "jwk_" + 8 chars shown in the UI
 
+# Synthetic id for the guest user produced when ANONYMOUS_READ is on and
+# the request carries no valid credentials. The users table starts at 1
+# (AUTOINCREMENT), so 0 cannot collide with any real account.
+ANONYMOUS_USER_ID = 0
+
+
+def anonymous_user() -> dict:
+    """Synthetic viewer used when ANONYMOUS_READ=true and creds are absent.
+
+    Carries the `anonymous=True` flag so write endpoints can reject it via
+    `require_real_user` and the ACL layer can short-circuit cheaply.
+    """
+    return {
+        "id": ANONYMOUS_USER_ID,
+        "username": "guest",
+        "role": "viewer",
+        "display_name": "Guest",
+        "email": "",
+        "anonymous": True,
+    }
+
 
 def hash_api_token(token: str) -> str:
     """Return the canonical hash we store in api_tokens.token_hash.
@@ -98,7 +119,7 @@ async def _resolve_api_token(token: str) -> dict | None:
     }
 
 
-async def _resolve_request_credentials(request: Request) -> dict | None:
+async def resolve_request_credentials(request: Request) -> dict | None:
     """Decode whichever credential the request carries, or return None.
 
     Recognises both personal API tokens (prefixed with `jwk_`) and JWT
@@ -136,21 +157,42 @@ async def _resolve_request_credentials(request: Request) -> dict | None:
 
 
 async def get_current_user(request: Request):
-    user = await _resolve_request_credentials(request)
-    if user is None:
-        raise HTTPException(
-            status_code=status.HTTP_401_UNAUTHORIZED,
-            detail="Not authenticated",
-        )
-    return user
+    user = await resolve_request_credentials(request)
+    if user is not None:
+        return user
+    # When ANONYMOUS_READ is on, fall through to a synthetic guest viewer
+    # rather than 401. ACL caps viewers at `read` and write/admin endpoints
+    # use `require_real_user` / `require_admin` to reject the guest, so this
+    # opens reads without affecting writes.
+    if settings.ANONYMOUS_READ:
+        return anonymous_user()
+    raise HTTPException(
+        status_code=status.HTTP_401_UNAUTHORIZED,
+        detail="Not authenticated",
+    )
 
 
 async def get_optional_user(request: Request) -> dict | None:
     """Same credential resolution as `get_current_user` but returns None
     instead of raising on missing/invalid credentials. Use for endpoints
     that serve both authenticated and anonymous traffic (e.g. media
     files referenced by public pages)."""
-    return await _resolve_request_credentials(request)
+    return await resolve_request_credentials(request)
+
+
+async def require_real_user(user=Depends(get_current_user)):
+    """Reject the synthetic anonymous user.
+
+    Use on endpoints that don't go through ACL (bookmarks, comments POST,
+    tokens, notifications, watch, profile, password, ai). ACL-gated writes
+    don't need this — viewer cap turns them into 403 automatically.
+    """
+    if user.get("anonymous"):
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Login required",
+        )
+    return user
 
 
 async def require_admin(user=Depends(get_current_user)):

backend/app/config.py

@@ -39,6 +39,14 @@ class Settings(BaseSettings):
     OIDC_ENABLED: bool = False
     OIDC_PROVIDERS: str = ""             # comma-separated: google,github,generic
 
+    # When True, requests without valid credentials are treated as a
+    # synthetic "guest" viewer (id=0, role=viewer) instead of being rejected
+    # with 401. ACL still gates access — guests only see pages with no ACL
+    # anchor in their parent chain (the open-default set). All write/admin
+    # endpoints remain login-required (see auth.require_real_user).
+    # Default off so existing private-wiki deployments are unaffected.
+    ANONYMOUS_READ: bool = False
+
     # Access-control layers. Any rule that is set and does not match → 403.
     OIDC_ALLOW_SIGNUP: bool = False      # if False, only pre-provisioned users
     OIDC_ALLOWED_EMAILS: str = ""        # comma-separated individual whitelist

backend/app/routers/activity.py

@@ -2,6 +2,7 @@
 from fastapi import APIRouter, Depends, Query
 from app.auth import get_current_user
 from app.database import get_db
+from app.services.acl import list_readable_page_ids
 
 router = APIRouter(prefix="/api/activity", tags=["activity"])
 
@@ -16,6 +17,24 @@ async def log_activity(db, user_id: int, action: str, target_type: str, target_i
     )
 
 
+def _readable_clause(readable: frozenset[int] | set[int]) -> tuple[str, list]:
+    """SQL fragment + params for "target_type='page' AND target_id ∈ readable".
+
+    Non-page rows (e.g. comment activity) are kept as-is — currently every
+    write that calls log_activity uses target_type='page', so the filter is
+    effectively a whitelist; if non-page targets are added later, they'll
+    pass through and may need their own ACL gate.
+    """
+    if not readable:
+        # No readable pages → drop every page-targeted row.
+        return "(a.target_type != 'page')", []
+    placeholders = ",".join("?" * len(readable))
+    return (
+        f"(a.target_type != 'page' OR a.target_id IN ({placeholders}))",
+        list(readable),
+    )
+
+
 @router.get("")
 async def list_activity(
     page: int = Query(1, ge=1),
@@ -25,17 +44,27 @@ async def list_activity(
     db = await get_db()
     offset = (page - 1) * per_page
 
-    count_rows = await db.execute_fetchall("SELECT COUNT(*) as cnt FROM activity_log")
+    # Filter activity to entries about pages the caller can read; otherwise
+    # the feed leaks titles/slugs of restricted pages via the metadata blob.
+    # Admin is short-circuited inside list_readable_page_ids.
+    readable = await list_readable_page_ids(db, user)
+    where_sql, where_params = _readable_clause(readable)
+
+    count_rows = await db.execute_fetchall(
+        f"SELECT COUNT(*) as cnt FROM activity_log a WHERE {where_sql}",
+        where_params,
+    )
     total = count_rows[0]["cnt"]
 
     rows = await db.execute_fetchall(
-        """SELECT a.id, a.user_id, a.action, a.target_type, a.target_id, a.metadata, a.created_at,
-                  u.username, u.display_name
+        f"""SELECT a.id, a.user_id, a.action, a.target_type, a.target_id, a.metadata, a.created_at,
+                   u.username, u.display_name
            FROM activity_log a
            LEFT JOIN users u ON u.id = a.user_id
+           WHERE {where_sql}
            ORDER BY a.created_at DESC, a.id DESC
            LIMIT ? OFFSET ?""",
-        (per_page, offset),
+        where_params + [per_page, offset],
     )
 
     results = []
@@ -52,36 +81,67 @@ async def list_activity(
 async def activity_stats(user=Depends(get_current_user)):
     db = await get_db()
 
-    # Top viewed pages
+    # Filter every page-derived list by the caller's readable set so guests
+    # (and any role that can't read everything) don't see restricted titles
+    # in top_viewed / recently_updated / orphan_pages.
+    readable = await list_readable_page_ids(db, user)
+
+    if not readable:
+        # No readable pages → all page-keyed lists are empty. Still return
+        # the shape so the dashboard renders without null-checks.
+        return {
+            "top_viewed": [],
+            "recently_updated": [],
+            "orphan_pages": [],
+            "total_pages": 0,
+            # Suppress global user count for callers without read access to
+            # any page — they have no business enumerating the user roster.
+            "total_users": 0,
+        }
+
+    placeholders = ",".join("?" * len(readable))
+    readable_params = list(readable)
+
     top_viewed = await db.execute_fetchall(
-        """SELECT id, slug, title, view_count FROM pages
-           ORDER BY view_count DESC LIMIT 10"""
+        f"""SELECT id, slug, title, view_count FROM pages
+           WHERE id IN ({placeholders})
+           ORDER BY view_count DESC LIMIT 10""",
+        readable_params,
     )
 
-    # Recently updated pages
     recently_updated = await db.execute_fetchall(
-        """SELECT p.id, p.slug, p.title, p.updated_at
+        f"""SELECT p.id, p.slug, p.title, p.updated_at
            FROM pages p
-           ORDER BY p.updated_at DESC LIMIT 10"""
+           WHERE p.id IN ({placeholders})
+           ORDER BY p.updated_at DESC LIMIT 10""",
+        readable_params,
     )
 
-    # Orphan pages (no backlinks pointing to them, not linked from anywhere)
     orphan_pages = await db.execute_fetchall(
-        """SELECT p.id, p.slug, p.title, p.view_count
+        f"""SELECT p.id, p.slug, p.title, p.view_count
            FROM pages p
-           WHERE p.id NOT IN (SELECT target_page_id FROM backlinks)
+           WHERE p.id IN ({placeholders})
+             AND p.id NOT IN (SELECT target_page_id FROM backlinks)
              AND p.parent_id IS NULL
-           ORDER BY p.updated_at DESC LIMIT 20"""
+           ORDER BY p.updated_at DESC LIMIT 20""",
+        readable_params,
     )
 
-    # Total counts
-    total_pages_row = await db.execute_fetchall("SELECT COUNT(*) as cnt FROM pages")
-    total_users_row = await db.execute_fetchall("SELECT COUNT(*) as cnt FROM users")
+    # total_pages reflects what *this user* can read, not the global count.
+    # Anonymous and viewers see the open-default subset; admins see all.
+    total_pages = len(readable)
+    # Hide the user roster size from the synthetic guest. Real users on a
+    # small-team wiki are expected to know the roster, so editors+ see it.
+    if user.get("anonymous"):
+        total_users = 0
+    else:
+        total_users_row = await db.execute_fetchall("SELECT COUNT(*) as cnt FROM users")
+        total_users = total_users_row[0]["cnt"]
 
     return {
         "top_viewed": [dict(r) for r in top_viewed],
         "recently_updated": [dict(r) for r in recently_updated],
         "orphan_pages": [dict(r) for r in orphan_pages],
-        "total_pages": total_pages_row[0]["cnt"],
-        "total_users": total_users_row[0]["cnt"],
+        "total_pages": total_pages,
+        "total_users": total_users,
     }

backend/app/routers/ai.py

@@ -18,13 +18,18 @@
 from fastapi.responses import StreamingResponse
 from pydantic import BaseModel, Field
 
-from app.auth import get_current_user
+from app.auth import get_current_user, require_real_user
 from app.config import settings
 from app.database import get_db
 from app.services.acl import list_readable_page_ids
 from app.services.search import segment
 
-router = APIRouter(prefix="/api/ai", tags=["ai"])
+# AI calls hit a paid upstream — never expose to anonymous traffic.
+router = APIRouter(
+    prefix="/api/ai",
+    tags=["ai"],
+    dependencies=[Depends(require_real_user)],
+)
 
 # FTS5 trigram tokenizer needs ≥3 chars; below that we fall back to LIKE —
 # same threshold as routers/search.py so retrieval behaves identically to

backend/app/routers/auth_router.py

@@ -5,7 +5,13 @@
 from app.schemas import LoginRequest, UserResponse
 from typing import Optional
 from pydantic import BaseModel
-from app.auth import verify_password, create_token, get_current_user, hash_password
+from app.auth import (
+    verify_password,
+    create_token,
+    hash_password,
+    require_real_user,
+    resolve_request_credentials,
+)
 from app.config import settings
 from app.database import get_db
 from app.services.client_ip import client_ip
@@ -104,7 +110,14 @@ async def logout(response: Response):
 
 
 @router.get("/me", response_model=UserResponse)
-async def me(user=Depends(get_current_user)):
+async def me(request: Request):
+    # Always 401 when there's no real session, even with ANONYMOUS_READ on.
+    # The frontend uses this 401 to detect "I'm a guest" vs "I'm logged in";
+    # if /me silently returned the synthetic guest, the UI couldn't tell
+    # the difference and would render the logged-in chrome.
+    user = await resolve_request_credentials(request)
+    if user is None:
+        raise HTTPException(status_code=401, detail="Not authenticated")
     return user
 
 
@@ -114,7 +127,7 @@ class ProfileUpdateRequest(BaseModel):
 
 
 @router.get("/profile")
-async def get_profile(user=Depends(get_current_user)):
+async def get_profile(user=Depends(require_real_user)):
     db = await get_db()
     rows = await db.execute_fetchall(
         "SELECT id, username, role, display_name, email, created_at FROM users WHERE id = ?",
@@ -124,7 +137,7 @@ async def get_profile(user=Depends(get_current_user)):
 
 
 @router.put("/profile")
-async def update_profile(body: ProfileUpdateRequest, user=Depends(get_current_user)):
+async def update_profile(body: ProfileUpdateRequest, user=Depends(require_real_user)):
     db = await get_db()
     updates = []
     values = []
@@ -157,7 +170,7 @@ class ChangePasswordRequest(BaseModel):
 
 
 @router.put("/password")
-async def change_password(body: ChangePasswordRequest, user=Depends(get_current_user)):
+async def change_password(body: ChangePasswordRequest, user=Depends(require_real_user)):
     if len(body.new_password) < 8:
         raise HTTPException(status_code=400, detail="New password must be at least 8 characters")
 

backend/app/routers/bookmarks.py

@@ -1,8 +1,15 @@
 from fastapi import APIRouter, HTTPException, Depends
-from app.auth import get_current_user
+from app.auth import get_current_user, require_real_user
 from app.database import get_db
 
-router = APIRouter(prefix="/api/bookmarks", tags=["bookmarks"])
+# Bookmarks are inherently per-user; the synthetic guest has no place here,
+# so reject it at the router boundary instead of repeating the check on
+# every endpoint.
+router = APIRouter(
+    prefix="/api/bookmarks",
+    tags=["bookmarks"],
+    dependencies=[Depends(require_real_user)],
+)
 
 
 @router.get("")