Add demo token endpoint and read-only frontend handling

backend/src/api/main.py

@@ -21,7 +21,7 @@ from starlette.responses import Response
 from fastmcp.server.http import StreamableHTTPSessionManager
 from fastapi.responses import FileResponse
 
-from .routes import auth, index, notes, search, graph
+from .routes import auth, index, notes, search, graph, demo
 from ..mcp.server import mcp
 from ..services.seed import init_and_seed
 
@@ -95,6 +95,7 @@ app.include_router(notes.router, tags=["notes"])
 app.include_router(search.router, tags=["search"])
 app.include_router(index.router, tags=["index"])
 app.include_router(graph.router, tags=["graph"])
+app.include_router(demo.router, tags=["demo"])
 
 # Hosted MCP HTTP endpoint (mounted Starlette app)
 

backend/src/api/routes/__init__.py

@@ -1,5 +1,5 @@
 """HTTP API route handlers."""
 
-from . import auth, index, notes, search
+from . import auth, index, notes, search, graph, demo
 
-__all__ = ["auth", "notes", "search", "index"]
+__all__ = ["auth", "notes", "search", "index", "graph", "demo"]

backend/src/api/routes/demo.py

@@ -0,0 +1,39 @@
+"""Public endpoints for demo mode access."""
+
+from __future__ import annotations
+
+from datetime import timedelta
+
+from fastapi import APIRouter
+
+from ...services.auth import AuthService
+from ...services.seed import ensure_welcome_note
+
+DEMO_USER_ID = "demo-user"
+DEMO_TOKEN_TTL_HOURS = 12
+
+router = APIRouter()
+auth_service = AuthService()
+
+
+@router.get("/api/demo/token")
+async def issue_demo_token():
+    """
+    Issue a short-lived JWT for the shared demo vault.
+
+    The caller can use this token to explore the application in read-only mode.
+    """
+    ensure_welcome_note(DEMO_USER_ID)
+    token, expires_at = auth_service.issue_token_response(
+        DEMO_USER_ID, expires_in=timedelta(hours=DEMO_TOKEN_TTL_HOURS)
+    )
+    return {
+        "token": token,
+        "token_type": "bearer",
+        "expires_at": expires_at.isoformat(),
+        "user_id": DEMO_USER_ID,
+    }
+
+
+__all__ = ["router", "DEMO_USER_ID"]
+

backend/src/api/routes/index.py

@@ -14,6 +14,19 @@ from ...services.indexer import IndexerService
 from ...services.vault import VaultService
 from ..middleware import AuthContext, get_auth_context
 
+DEMO_USER_ID = "demo-user"
+
+
+def _ensure_index_mutation_allowed(user_id: str) -> None:
+    if user_id == DEMO_USER_ID:
+        raise HTTPException(
+            status_code=403,
+            detail={
+                "error": "demo_read_only",
+                "message": "Demo mode does not allow index rebuilds. Sign in to manage the index.",
+            },
+        )
+
 router = APIRouter()
 
 
@@ -79,6 +92,7 @@ async def rebuild_index(auth: AuthContext = Depends(get_auth_context)):
     """Rebuild the entire index from scratch."""
     start_time = time.time()
     user_id = auth.user_id
+    _ensure_index_mutation_allowed(user_id)
     vault_service = VaultService()
     indexer_service = IndexerService()
     

backend/src/api/routes/notes.py

@@ -16,6 +16,19 @@ from ..middleware import AuthContext, get_auth_context
 
 router = APIRouter()
 
+DEMO_USER_ID = "demo-user"
+
+
+def _ensure_write_allowed(user_id: str) -> None:
+    if user_id == DEMO_USER_ID:
+        raise HTTPException(
+            status_code=403,
+            detail={
+                "error": "demo_read_only",
+                "message": "Demo mode is read-only. Sign in with Hugging Face to make changes.",
+            },
+        )
+
 
 class ConflictError(Exception):
     """Raised when optimistic concurrency check fails."""
@@ -60,6 +73,7 @@ async def list_notes(
 async def create_note(create: NoteCreate, auth: AuthContext = Depends(get_auth_context)):
     """Create a new note."""
     user_id = auth.user_id
+    _ensure_write_allowed(user_id)
     vault_service = VaultService()
     indexer_service = IndexerService()
     db_service = DatabaseService()
@@ -230,6 +244,7 @@ async def update_note(
 ):
     """Update a note with optimistic concurrency control."""
     user_id = auth.user_id
+    _ensure_write_allowed(user_id)
     vault_service = VaultService()
     indexer_service = IndexerService()
     db_service = DatabaseService()
@@ -337,9 +352,14 @@ class NoteMoveRequest(BaseModel):
 
 
 @router.patch("/api/notes/{path:path}", response_model=Note)
-async def move_note(path: str, move_request: NoteMoveRequest):
+async def move_note(
+    path: str,
+    move_request: NoteMoveRequest,
+    auth: AuthContext = Depends(get_auth_context),
+):
     """Move or rename a note to a new path."""
-    user_id = get_user_id()
+    user_id = auth.user_id
+    _ensure_write_allowed(user_id)
     vault_service = VaultService()
     indexer_service = IndexerService()
     db_service = DatabaseService()

frontend/src/App.tsx

@@ -3,7 +3,7 @@ import { BrowserRouter, Routes, Route, Navigate, useNavigate, useLocation } from
 import { MainApp } from './pages/MainApp';
 import { Login } from './pages/Login';
 import { Settings } from './pages/Settings';
-import { isAuthenticated, getCurrentUser, setAuthTokenFromHash } from './services/auth';
+import { isAuthenticated, getCurrentUser, setAuthTokenFromHash, ensureDemoToken, isDemoSession } from './services/auth';
 import { AuthLoadingSkeleton } from './components/AuthLoadingSkeleton';
 import { Toaster } from './components/ui/toaster';
 import './App.css';
@@ -28,13 +28,21 @@ function ProtectedRoute({ children }: { children: React.ReactNode }) {
       }
 
       if (!isAuthenticated()) {
-        setHasToken(false);
-        setIsChecking(false);
-        return;
+        const demoReady = await ensureDemoToken();
+        if (!demoReady) {
+          setHasToken(false);
+          setIsChecking(false);
+          return;
+        }
       }
 
       setHasToken(true);
 
+      if (isDemoSession()) {
+        setIsChecking(false);
+        return;
+      }
+
       const token = localStorage.getItem('auth_token');
       // Skip validation for local dev token
       if (token === 'local-dev-token') {

frontend/src/pages/MainApp.tsx

@@ -41,6 +41,7 @@ import type { IndexHealth } from '@/types/search';
 import type { Note, NoteSummary } from '@/types/note';
 import { normalizeSlug } from '@/lib/wikilink';
 import { Network } from 'lucide-react';
+import { AUTH_TOKEN_CHANGED_EVENT, isDemoSession, login } from '@/services/auth';
 
 export function MainApp() {
   const navigate = useNavigate();
@@ -61,6 +62,21 @@ export function MainApp() {
   const [isNewFolderDialogOpen, setIsNewFolderDialogOpen] = useState(false);
   const [newFolderName, setNewFolderName] = useState('');
   const [isCreatingFolder, setIsCreatingFolder] = useState(false);
+  const [isDemoMode, setIsDemoMode] = useState<boolean>(isDemoSession());
+
+  useEffect(() => {
+    const handleAuthChange = () => {
+      const demo = isDemoSession();
+      setIsDemoMode(demo);
+      if (demo) {
+        setIsEditMode(false);
+      }
+    };
+    window.addEventListener(AUTH_TOKEN_CHANGED_EVENT, handleAuthChange);
+    return () => {
+      window.removeEventListener(AUTH_TOKEN_CHANGED_EVENT, handleAuthChange);
+    };
+  }, []);
 
   // T083: Load directory tree on mount
   // T119: Load index health
@@ -169,6 +185,10 @@ export function MainApp() {
 
   // T093: Handle edit button click
   const handleEdit = () => {
+    if (isDemoMode) {
+      toast.error('Demo mode is read-only. Sign in with Hugging Face to edit notes.');
+      return;
+    }
     setIsEditMode(true);
   };
 
@@ -188,6 +208,10 @@ export function MainApp() {
 
   // Handle note dialog open change
   const handleDialogOpenChange = (open: boolean) => {
+    if (open && isDemoMode) {
+      toast.error('Demo mode is read-only. Sign in with Hugging Face to create notes.');
+      return;
+    }
     setIsNewNoteDialogOpen(open);
     if (!open) {
       // Clear input when dialog closes
@@ -197,6 +221,10 @@ export function MainApp() {
 
   // Handle folder dialog open change
   const handleFolderDialogOpenChange = (open: boolean) => {
+    if (open && isDemoMode) {
+      toast.error('Demo mode is read-only. Sign in with Hugging Face to create folders.');
+      return;
+    }
     setIsNewFolderDialogOpen(open);
     if (!open) {
       // Clear input when dialog closes
@@ -206,6 +234,10 @@ export function MainApp() {
 
   // Handle create new note
   const handleCreateNote = async () => {
+    if (isDemoMode) {
+      toast.error('Demo mode is read-only. Sign in to create notes.');
+      return;
+    }
     if (!newNoteName.trim() || isCreatingNote) return;
 
     setIsCreatingNote(true);
@@ -270,6 +302,10 @@ export function MainApp() {
 
   // Handle create new folder
   const handleCreateFolder = async () => {
+    if (isDemoMode) {
+      toast.error('Demo mode is read-only. Sign in to create folders.');
+      return;
+    }
     if (!newFolderName.trim() || isCreatingFolder) return;
 
     setIsCreatingFolder(true);
@@ -309,6 +345,10 @@ export function MainApp() {
 
   // Handle dragging file to folder
   const handleMoveNoteToFolder = async (oldPath: string, targetFolderPath: string) => {
+    if (isDemoMode) {
+      toast.error('Demo mode is read-only. Sign in to move notes.');
+      return;
+    }
     try {
       // Get the filename from the old path
       const fileName = oldPath.split('/').pop();
@@ -360,9 +400,19 @@ export function MainApp() {
       
       {/* Top bar */}
       <div className="border-b border-border p-4 animate-fade-in">
-        <div className="flex items-center justify-between">
+        <div className="flex items-center justify-between gap-2">
           <h1 className="text-xl font-semibold">📚 Document Viewer</h1>
           <div className="flex gap-2">
+            {isDemoMode && (
+              <Button
+                variant="default"
+                size="sm"
+                onClick={() => login()}
+                title="Sign in with Hugging Face"
+              >
+                Sign in
+              </Button>
+            )}
             <Button
               variant={isGraphView ? "secondary" : "ghost"}
               size="sm"
@@ -380,6 +430,16 @@ export function MainApp() {
 
       {/* Main content */}
       <div className="flex-1 overflow-hidden animate-fade-in" style={{ animationDelay: '0.1s' }}>
+        {isDemoMode && (
+          <div className="border-b border-border bg-muted/40 px-4 py-2 text-sm text-muted-foreground flex flex-wrap items-center justify-between gap-2">
+            <span>
+              You are browsing the shared demo vault in read-only mode. Sign in with your Hugging Face account to create and edit notes.
+            </span>
+            <Button variant="outline" size="sm" onClick={() => login()}>
+              Sign in
+            </Button>
+          </div>
+        )}
         <ResizablePanelGroup direction="horizontal">
           {/* Left sidebar */}
           <ResizablePanel defaultSize={25} minSize={15} maxSize={40}>
@@ -390,7 +450,7 @@ export function MainApp() {
                   onOpenChange={handleDialogOpenChange}
                 >
                   <DialogTrigger asChild>
-                    <Button variant="outline" size="sm" className="w-full">
+                    <Button variant="outline" size="sm" className="w-full" disabled={isDemoMode}>
                       <Plus className="h-4 w-4 mr-1" />
                       New Note
                     </Button>
@@ -440,7 +500,7 @@ export function MainApp() {
                   onOpenChange={handleFolderDialogOpenChange}
                 >
                   <DialogTrigger asChild>
-                    <Button variant="outline" size="sm" className="w-full">
+                    <Button variant="outline" size="sm" className="w-full" disabled={isDemoMode}>
                       <FolderPlus className="h-4 w-4 mr-1" />
                       New Folder
                     </Button>
@@ -536,7 +596,7 @@ export function MainApp() {
                     <NoteViewer
                       note={currentNote}
                       backlinks={backlinks}
-                      onEdit={handleEdit}
+                      onEdit={isDemoMode ? undefined : handleEdit}
                       onWikilinkClick={handleWikilinkClick}
                     />
                   )

frontend/src/pages/Settings.tsx

@@ -11,7 +11,7 @@ import { Alert, AlertDescription } from '@/components/ui/alert';
 import { Avatar, AvatarFallback, AvatarImage } from '@/components/ui/avatar';
 import { Separator } from '@/components/ui/separator';
 import { SettingsSectionSkeleton } from '@/components/SettingsSectionSkeleton';
-import { getCurrentUser, getToken, logout, getStoredToken } from '@/services/auth';
+import { getCurrentUser, getToken, logout, getStoredToken, isDemoSession, AUTH_TOKEN_CHANGED_EVENT } from '@/services/auth';
 import { getIndexHealth, rebuildIndex, type RebuildResponse } from '@/services/api';
 import type { User } from '@/types/user';
 import type { IndexHealth } from '@/types/search';
@@ -25,11 +25,18 @@ export function Settings() {
   const [isRebuilding, setIsRebuilding] = useState(false);
   const [rebuildResult, setRebuildResult] = useState<RebuildResponse | null>(null);
   const [error, setError] = useState<string | null>(null);
+  const [isDemoMode, setIsDemoMode] = useState<boolean>(isDemoSession());
 
   useEffect(() => {
     loadData();
   }, []);
 
+  useEffect(() => {
+    const handler = () => setIsDemoMode(isDemoSession());
+    window.addEventListener(AUTH_TOKEN_CHANGED_EVENT, handler);
+    return () => window.removeEventListener(AUTH_TOKEN_CHANGED_EVENT, handler);
+  }, []);
+
   const loadData = async () => {
     try {
       const token = getStoredToken();
@@ -60,6 +67,10 @@ export function Settings() {
   };
 
   const handleGenerateToken = async () => {
+    if (isDemoMode) {
+      setError('Demo mode is read-only. Sign in to generate new tokens.');
+      return;
+    }
     try {
       setError(null);
       const tokenResponse = await getToken();
@@ -81,6 +92,10 @@ export function Settings() {
   };
 
   const handleRebuildIndex = async () => {
+    if (isDemoMode) {
+      setError('Demo mode is read-only. Sign in to rebuild the index.');
+      return;
+    }
     setIsRebuilding(true);
     setError(null);
     setRebuildResult(null);
@@ -125,6 +140,13 @@ export function Settings() {
 
       {/* Content */}
       <div className="max-w-4xl mx-auto p-6 space-y-6">
+        {isDemoMode && (
+          <Alert variant="destructive">
+            <AlertDescription>
+              You are viewing the shared demo vault. Sign in with Hugging Face from the main app to enable token generation and index management.
+            </AlertDescription>
+          </Alert>
+        )}
         {error && (
           <Alert variant="destructive">
             <AlertDescription>{error}</AlertDescription>
@@ -203,7 +225,7 @@ export function Settings() {
               </div>
             </div>
 
-            <Button onClick={handleGenerateToken}>
+            <Button onClick={handleGenerateToken} disabled={isDemoMode}>
               <RefreshCw className="h-4 w-4 mr-2" />
               Generate New Token
             </Button>
@@ -285,7 +307,7 @@ export function Settings() {
 
               <Button
                 onClick={handleRebuildIndex}
-                disabled={isRebuilding}
+                disabled={isDemoMode || isRebuilding}
                 variant="outline"
               >
                 <RefreshCw className={`h-4 w-4 mr-2 ${isRebuilding ? 'animate-spin' : ''}`} />

frontend/src/services/api.ts

@@ -139,6 +139,17 @@ export async function getBacklinks(path: string): Promise<BacklinkResult[]> {
   return apiFetch<BacklinkResult[]>(`/api/backlinks/${encodedPath}`);
 }
 
+export interface DemoTokenResponse {
+  token: string;
+  token_type: string;
+  expires_at: string;
+  user_id: string;
+}
+
+export async function getDemoToken(): Promise<DemoTokenResponse> {
+  return apiFetch<DemoTokenResponse>('/api/demo/token');
+}
+
 /**
  * T070: Get all tags with counts
  */

frontend/src/services/auth.ts

@@ -3,9 +3,42 @@
  */
 import type { User } from '@/types/user';
 import type { TokenResponse } from '@/types/auth';
+import type { DemoTokenResponse } from '@/services/api';
+import { getDemoToken } from '@/services/api';
+
+const AUTH_TOKEN_KEY = 'auth_token';
+const AUTH_TOKEN_SOURCE_KEY = 'auth_token_source';
+const AUTH_TOKEN_EXPIRES_KEY = 'auth_token_expires_at';
+export const AUTH_TOKEN_CHANGED_EVENT = 'auth-token-changed';
+
+type TokenSource = 'user' | 'demo';
 
 const API_BASE = '';
 
+function notifyTokenChange(): void {
+  if (typeof window !== 'undefined') {
+    window.dispatchEvent(new CustomEvent(AUTH_TOKEN_CHANGED_EVENT));
+  }
+}
+
+function storeAuthToken(token: string, source: TokenSource, expiresAt?: string): void {
+  localStorage.setItem(AUTH_TOKEN_KEY, token);
+  localStorage.setItem(AUTH_TOKEN_SOURCE_KEY, source);
+  if (expiresAt) {
+    localStorage.setItem(AUTH_TOKEN_EXPIRES_KEY, expiresAt);
+  } else {
+    localStorage.removeItem(AUTH_TOKEN_EXPIRES_KEY);
+  }
+  notifyTokenChange();
+}
+
+function clearStoredAuthToken(): void {
+  localStorage.removeItem(AUTH_TOKEN_KEY);
+  localStorage.removeItem(AUTH_TOKEN_SOURCE_KEY);
+  localStorage.removeItem(AUTH_TOKEN_EXPIRES_KEY);
+  notifyTokenChange();
+}
+
 /**
  * T105: Redirect to HF OAuth login
  */
@@ -17,7 +50,7 @@ export function login(): void {
  * Logout - clear token and redirect
  */
 export function logout(): void {
-  localStorage.removeItem('auth_token');
+  clearStoredAuthToken();
   window.location.href = '/';
 }
 
@@ -25,7 +58,7 @@ export function logout(): void {
  * T106: Get current authenticated user
  */
 export async function getCurrentUser(): Promise<User> {
-  const token = localStorage.getItem('auth_token');
+  const token = localStorage.getItem(AUTH_TOKEN_KEY);
   
   const response = await fetch(`${API_BASE}/api/me`, {
     headers: {
@@ -45,7 +78,7 @@ export async function getCurrentUser(): Promise<User> {
  * T107: Generate new API token for MCP access
  */
 export async function getToken(): Promise<TokenResponse> {
-  const token = localStorage.getItem('auth_token');
+  const token = localStorage.getItem(AUTH_TOKEN_KEY);
   
   const response = await fetch(`${API_BASE}/api/tokens`, {
     method: 'POST',
@@ -62,7 +95,7 @@ export async function getToken(): Promise<TokenResponse> {
   const tokenResponse: TokenResponse = await response.json();
   
   // Store the new token
-  localStorage.setItem('auth_token', tokenResponse.token);
+  storeAuthToken(tokenResponse.token, 'user', tokenResponse.expires_at);
   
   return tokenResponse;
 }
@@ -71,14 +104,25 @@ export async function getToken(): Promise<TokenResponse> {
  * Check if user is authenticated
  */
 export function isAuthenticated(): boolean {
-  return !!localStorage.getItem('auth_token');
+  const token = localStorage.getItem(AUTH_TOKEN_KEY);
+  if (!token) {
+    return false;
+  }
+  if (isDemoSession()) {
+    return !demoTokenExpired();
+  }
+  return true;
 }
 
 /**
  * Get stored token
  */
 export function getStoredToken(): string | null {
-  return localStorage.getItem('auth_token');
+  return localStorage.getItem(AUTH_TOKEN_KEY);
+}
+
+export function isDemoSession(): boolean {
+  return localStorage.getItem(AUTH_TOKEN_SOURCE_KEY) === 'demo';
 }
 
 /**
@@ -91,7 +135,7 @@ export function setAuthTokenFromHash(): boolean {
   if (hash.startsWith('#token=')) {
     const token = hash.substring(7); // Remove '#token='
     if (token) {
-      localStorage.setItem('auth_token', token);
+      storeAuthToken(token, 'user');
       // Clean up the URL
       window.history.replaceState(null, '', window.location.pathname);
       return true;
@@ -100,3 +144,38 @@ export function setAuthTokenFromHash(): boolean {
   return false;
 }
 
+function demoTokenExpired(): boolean {
+  const expiresAt = localStorage.getItem(AUTH_TOKEN_EXPIRES_KEY);
+  if (!expiresAt) {
+    return false;
+  }
+  const now = Date.now();
+  return new Date(expiresAt).getTime() <= now;
+}
+
+async function requestDemoToken(): Promise<DemoTokenResponse> {
+  return getDemoToken();
+}
+
+export async function ensureDemoToken(): Promise<boolean> {
+  // If we already have a user token, nothing to do
+  if (isAuthenticated() && !isDemoSession()) {
+    return true;
+  }
+
+  // If we have a demo token that hasn't expired, reuse it
+  if (isAuthenticated() && isDemoSession() && !demoTokenExpired()) {
+    return true;
+  }
+
+  try {
+    const demoResponse = await requestDemoToken();
+    storeAuthToken(demoResponse.token, 'demo', demoResponse.expires_at);
+    return true;
+  } catch (error) {
+    console.warn('Failed to obtain demo token', error);
+    clearStoredAuthToken();
+    return false;
+  }
+}
+