Foundational changes

backend/src/api/middleware/__init__.py

@@ -1 +1,17 @@
 """FastAPI middleware for authentication and error handling."""
+
+from .auth_middleware import extract_user_id_from_jwt
+from .error_handlers import (
+    http_exception_handler,
+    internal_exception_handler,
+    register_error_handlers,
+    validation_exception_handler,
+)
+
+__all__ = [
+    "extract_user_id_from_jwt",
+    "register_error_handlers",
+    "validation_exception_handler",
+    "http_exception_handler",
+    "internal_exception_handler",
+]

backend/src/api/middleware/auth_middleware.py

@@ -0,0 +1,47 @@
+"""Authentication dependency helpers."""
+
+from __future__ import annotations
+
+from typing import Annotated, Optional
+
+from fastapi import Header, HTTPException, status
+
+from ...services.auth import AuthError, AuthService
+
+auth_service = AuthService()
+
+
+def _unauthorized(message: str, error: str = "unauthorized") -> HTTPException:
+    return HTTPException(
+        status_code=status.HTTP_401_UNAUTHORIZED,
+        detail={"error": error, "message": message},
+    )
+
+
+def extract_user_id_from_jwt(
+    authorization: Annotated[Optional[str], Header(default=None, alias="Authorization")] = None,
+) -> str:
+    """
+    Extract and validate the user_id from a Bearer token.
+
+    Raises HTTPException if the header is missing/invalid.
+    """
+    if not authorization:
+        raise _unauthorized("Authorization header required")
+
+    scheme, _, token = authorization.partition(" ")
+    if scheme.lower() != "bearer" or not token:
+        raise _unauthorized("Authorization header must be in format: Bearer <token>")
+
+    try:
+        payload = auth_service.validate_jwt(token)
+    except AuthError as exc:
+        raise HTTPException(
+            status_code=exc.status_code,
+            detail={"error": exc.error, "message": exc.message, "detail": exc.detail},
+        ) from exc
+
+    return payload.sub
+
+
+__all__ = ["extract_user_id_from_jwt"]

backend/src/api/middleware/error_handlers.py

@@ -0,0 +1,87 @@
+"""FastAPI exception handlers aligned with HTTP API contract."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, Optional, Tuple
+
+from fastapi import FastAPI, Request, status
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+from starlette.exceptions import HTTPException as StarletteHTTPException
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_ERRORS: Dict[int, Tuple[str, str]] = {
+    status.HTTP_400_BAD_REQUEST: ("validation_error", "Invalid request payload"),
+    status.HTTP_401_UNAUTHORIZED: ("unauthorized", "Authorization required"),
+    status.HTTP_403_FORBIDDEN: ("forbidden", "Forbidden"),
+    status.HTTP_404_NOT_FOUND: ("not_found", "Resource not found"),
+    status.HTTP_409_CONFLICT: ("version_conflict", "Resource version conflict"),
+    status.HTTP_413_REQUEST_ENTITY_TOO_LARGE: (
+        "payload_too_large",
+        "Payload exceeds allowed size",
+    ),
+    status.HTTP_500_INTERNAL_SERVER_ERROR: ("internal_error", "Internal server error"),
+}
+
+
+def _normalize_error(
+    status_code: int, detail: Any
+) -> Tuple[str, str, Optional[Dict[str, Any]]]:
+    default_error, default_message = DEFAULT_ERRORS.get(
+        status_code, DEFAULT_ERRORS[status.HTTP_500_INTERNAL_SERVER_ERROR]
+    )
+    if isinstance(detail, dict):
+        error = detail.get("error", default_error)
+        message = detail.get("message", default_message)
+        detail_payload = detail.get("detail")
+        if detail_payload is None:
+            remainder = {
+                k: v for k, v in detail.items() if k not in {"error", "message", "detail"}
+            }
+            detail_payload = remainder or None
+        return error, message, detail_payload
+    if isinstance(detail, str) and detail:
+        return default_error, detail, None
+    return default_error, default_message, None
+
+
+def _response(status_code: int, detail: Any) -> JSONResponse:
+    error, message, extra = _normalize_error(status_code, detail)
+    return JSONResponse(
+        status_code=status_code, content={"error": error, "message": message, "detail": extra}
+    )
+
+
+async def validation_exception_handler(
+    request: Request, exc: RequestValidationError
+) -> JSONResponse:
+    detail = {"detail": {"errors": exc.errors()}}
+    return _response(status.HTTP_400_BAD_REQUEST, detail)
+
+
+async def http_exception_handler(
+    request: Request, exc: StarletteHTTPException
+) -> JSONResponse:
+    return _response(exc.status_code, exc.detail)
+
+
+async def internal_exception_handler(request: Request, exc: Exception) -> JSONResponse:
+    logger.exception("Unhandled exception: %s", exc)
+    return _response(status.HTTP_500_INTERNAL_SERVER_ERROR, exc.args[0] if exc.args else None)
+
+
+def register_error_handlers(app: FastAPI) -> None:
+    """Attach shared exception handlers to the FastAPI application."""
+    app.add_exception_handler(RequestValidationError, validation_exception_handler)
+    app.add_exception_handler(StarletteHTTPException, http_exception_handler)
+    app.add_exception_handler(Exception, internal_exception_handler)
+
+
+__all__ = [
+    "register_error_handlers",
+    "validation_exception_handler",
+    "http_exception_handler",
+    "internal_exception_handler",
+]

backend/src/models/__init__.py

@@ -1,2 +1,25 @@
 """Pydantic models for data validation and serialization."""
 
+from .auth import JWTPayload, TokenResponse
+from .index import IndexHealth, Tag, Wikilink
+from .note import Note, NoteCreate, NoteMetadata, NoteSummary, NoteUpdate
+from .search import SearchRequest, SearchResult
+from .user import HFProfile, User
+
+__all__ = [
+    "User",
+    "HFProfile",
+    "Note",
+    "NoteMetadata",
+    "NoteCreate",
+    "NoteUpdate",
+    "NoteSummary",
+    "Wikilink",
+    "Tag",
+    "IndexHealth",
+    "SearchResult",
+    "SearchRequest",
+    "TokenResponse",
+    "JWTPayload",
+]
+

backend/src/models/auth.py

@@ -0,0 +1,26 @@
+"""Authentication models."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+
+
+class TokenResponse(BaseModel):
+    """JWT issuance response."""
+
+    token: str = Field(..., description="JWT access token")
+    token_type: str = Field("bearer", description="Token type (always bearer)")
+    expires_at: datetime = Field(..., description="Expiration timestamp")
+
+
+class JWTPayload(BaseModel):
+    """JWT claims payload."""
+
+    sub: str = Field(..., description="Subject (user_id)")
+    iat: int = Field(..., description="Issued at timestamp")
+    exp: int = Field(..., description="Expiration timestamp")
+
+
+__all__ = ["TokenResponse", "JWTPayload"]

backend/src/models/index.py

@@ -0,0 +1,60 @@
+"""Index and metadata models."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class Wikilink(BaseModel):
+    """Bidirectional link between notes."""
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "user_id": "alice",
+                "source_path": "api/design.md",
+                "target_path": "api/endpoints.md",
+                "link_text": "Endpoints",
+                "is_resolved": True,
+            }
+        }
+    )
+
+    user_id: str
+    source_path: str
+    target_path: Optional[str] = Field(None, description="Null if unresolved")
+    link_text: str
+    is_resolved: bool
+
+
+class Tag(BaseModel):
+    """Tag with aggregated count."""
+
+    tag_name: str
+    count: int = Field(..., ge=0)
+
+
+class IndexHealth(BaseModel):
+    """Index health metrics per user."""
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "user_id": "alice",
+                "note_count": 142,
+                "last_full_rebuild": "2025-01-01T00:00:00Z",
+                "last_incremental_update": "2025-01-15T14:30:00Z",
+            }
+        }
+    )
+
+    user_id: str
+    note_count: int = Field(..., ge=0)
+    last_full_rebuild: Optional[datetime] = None
+    last_incremental_update: Optional[datetime] = None
+
+
+__all__ = ["Wikilink", "Tag", "IndexHealth"]

backend/src/models/note.py

@@ -0,0 +1,102 @@
+"""Note-related Pydantic models."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Optional
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class NoteMetadata(BaseModel):
+    """Frontmatter metadata (allows arbitrary keys)."""
+
+    model_config = ConfigDict(extra="allow")
+
+    title: Optional[str] = None
+    tags: Optional[list[str]] = None
+    project: Optional[str] = None
+    created: Optional[datetime] = None
+    updated: Optional[datetime] = None
+
+
+class Note(BaseModel):
+    """Complete note with content and metadata."""
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "user_id": "alice",
+                "note_path": "api/design.md",
+                "version": 5,
+                "title": "API Design",
+                "metadata": {
+                    "tags": ["backend", "api"],
+                    "project": "auth-service",
+                },
+                "body": "# API Design\\n\\nThis document describes...",
+                "created": "2025-01-10T09:00:00Z",
+                "updated": "2025-01-15T14:30:00Z",
+                "size_bytes": 4096,
+            }
+        }
+    )
+
+    user_id: str = Field(..., description="Owner user ID")
+    note_path: str = Field(
+        ...,
+        min_length=1,
+        max_length=256,
+        description="Relative path to vault root (includes .md)",
+    )
+    version: int = Field(..., ge=1, description="Optimistic concurrency version")
+    title: str = Field(..., min_length=1, description="Display title")
+    metadata: NoteMetadata = Field(default_factory=NoteMetadata, description="Frontmatter")
+    body: str = Field(..., description="Markdown content")
+    created: datetime = Field(..., description="Creation timestamp")
+    updated: datetime = Field(..., description="Last update timestamp")
+    size_bytes: int = Field(..., ge=0, le=1_048_576, description="File size in bytes")
+
+    @field_validator("note_path")
+    @classmethod
+    def validate_path(cls, value: str) -> str:
+        if not value.endswith(".md"):
+            raise ValueError("Note path must end with .md")
+        if ".." in value:
+            raise ValueError("Note path must not contain '..'")
+        if "\\" in value:
+            raise ValueError("Note path must use Unix-style separators (/)")
+        if value.startswith("/"):
+            raise ValueError("Note path must be relative (no leading /)")
+        return value
+
+
+class NoteCreate(BaseModel):
+    """Request payload to create a note."""
+
+    note_path: str = Field(..., min_length=1, max_length=256)
+    title: Optional[str] = None
+    metadata: Optional[NoteMetadata] = None
+    body: str = Field(..., max_length=1_048_576)
+
+
+class NoteUpdate(BaseModel):
+    """Request payload to update a note."""
+
+    title: Optional[str] = None
+    metadata: Optional[NoteMetadata] = None
+    body: str = Field(..., max_length=1_048_576)
+    if_version: Optional[int] = Field(
+        None, ge=1, description="Expected version for concurrency check"
+    )
+
+
+class NoteSummary(BaseModel):
+    """Lightweight representation used for listings."""
+
+    note_path: str
+    title: str
+    updated: datetime
+
+
+__all__ = ["NoteMetadata", "Note", "NoteCreate", "NoteUpdate", "NoteSummary"]

backend/src/models/search.py

@@ -0,0 +1,27 @@
+"""Search request/response models."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+
+
+class SearchResult(BaseModel):
+    """Full-text search result payload."""
+
+    note_path: str
+    title: str
+    snippet: str = Field(..., description="Highlighted body excerpt")
+    score: float = Field(..., description="Relevance score (weighted by field)")
+    updated: datetime
+
+
+class SearchRequest(BaseModel):
+    """Full-text search query parameters."""
+
+    query: str = Field(..., min_length=1, max_length=256)
+    limit: int = Field(50, ge=1, le=100)
+
+
+__all__ = ["SearchResult", "SearchRequest"]

backend/src/models/user.py

@@ -0,0 +1,43 @@
+"""User and profile models."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class HFProfile(BaseModel):
+    """Hugging Face OAuth profile information."""
+
+    username: str = Field(..., description="HF username")
+    name: Optional[str] = Field(None, description="Display name")
+    avatar_url: Optional[str] = Field(None, description="Profile picture URL")
+
+
+class User(BaseModel):
+    """User account with authentication details."""
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "user_id": "alice",
+                "hf_profile": {
+                    "username": "alice",
+                    "name": "Alice Smith",
+                    "avatar_url": "https://cdn-avatars.huggingface.co/v1/alice",
+                },
+                "vault_path": "/data/vaults/alice",
+                "created": "2025-01-15T10:30:00Z",
+            }
+        }
+    )
+
+    user_id: str = Field(..., min_length=1, max_length=64, description="Internal user ID")
+    hf_profile: Optional[HFProfile] = Field(None, description="HF OAuth profile data")
+    vault_path: str = Field(..., description="Absolute path to the user's vault")
+    created: datetime = Field(..., description="Account creation timestamp")
+
+
+__all__ = ["User", "HFProfile"]

backend/src/services/__init__.py

@@ -1 +1,19 @@
 """Service layer for business logic and external integrations."""
+
+from .auth import AuthError, AuthService
+from .config import AppConfig, get_config, reload_config
+from .database import DatabaseService, init_database
+from .vault import VaultService, sanitize_path, validate_note_path
+
+__all__ = [
+    "AppConfig",
+    "get_config",
+    "reload_config",
+    "DatabaseService",
+    "init_database",
+    "AuthService",
+    "AuthError",
+    "VaultService",
+    "sanitize_path",
+    "validate_note_path",
+]

backend/src/services/auth.py

@@ -0,0 +1,99 @@
+"""Authentication helpers (JWT + HF OAuth placeholder)."""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+from typing import Any, Dict, Optional
+
+import jwt
+from fastapi import status
+
+from ..models.auth import JWTPayload
+from .config import AppConfig, get_config
+
+
+class AuthError(Exception):
+    """Domain-specific authentication error."""
+
+    def __init__(
+        self,
+        error: str,
+        message: str,
+        *,
+        status_code: int = status.HTTP_401_UNAUTHORIZED,
+        detail: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.error = error
+        self.message = message
+        self.status_code = status_code
+        self.detail = detail or {}
+
+
+class AuthService:
+    """Issue and validate JWT tokens (HF OAuth placeholder)."""
+
+    def __init__(
+        self,
+        config: AppConfig | None = None,
+        *,
+        algorithm: str = "HS256",
+        token_ttl_days: int = 90,
+    ) -> None:
+        self.config = config or get_config()
+        self.algorithm = algorithm
+        self.token_ttl_days = token_ttl_days
+
+    def _build_payload(
+        self, user_id: str, expires_in: Optional[timedelta] = None
+    ) -> JWTPayload:
+        now = datetime.now(timezone.utc)
+        lifetime = expires_in or timedelta(days=self.token_ttl_days)
+        return JWTPayload(
+            sub=user_id,
+            iat=int(now.timestamp()),
+            exp=int((now + lifetime).timestamp()),
+        )
+
+    def create_jwt(self, user_id: str, *, expires_in: Optional[timedelta] = None) -> str:
+        """Create a signed JWT for the given user."""
+        payload = self._build_payload(user_id, expires_in)
+        return jwt.encode(
+            payload.model_dump(),
+            self.config.jwt_secret_key,
+            algorithm=self.algorithm,
+        )
+
+    def validate_jwt(self, token: str) -> JWTPayload:
+        """Validate a JWT and return the decoded payload."""
+        try:
+            decoded = jwt.decode(
+                token,
+                self.config.jwt_secret_key,
+                algorithms=[self.algorithm],
+            )
+            return JWTPayload(**decoded)
+        except jwt.ExpiredSignatureError as exc:
+            raise AuthError("token_expired", "Token expired, please re-authenticate") from exc
+        except jwt.InvalidTokenError as exc:
+            raise AuthError("invalid_token", f"Invalid token: {exc}") from exc
+
+    def issue_token_response(
+        self, user_id: str, *, expires_in: Optional[timedelta] = None
+    ) -> tuple[str, datetime]:
+        """Return token string and expiry timestamp (helper for API routes)."""
+        payload = self._build_payload(user_id, expires_in)
+        token = jwt.encode(
+            payload.model_dump(),
+            self.config.jwt_secret_key,
+            algorithm=self.algorithm,
+        )
+        expires_at = datetime.fromtimestamp(payload.exp, tz=timezone.utc)
+        return token, expires_at
+
+    def exchange_hf_oauth_code(self, code: str) -> Dict[str, Any]:
+        """Placeholder for Hugging Face OAuth code exchange."""
+        raise NotImplementedError("HF OAuth integration not implemented yet")
+
+
+__all__ = ["AuthService", "AuthError"]

backend/src/services/config.py

@@ -0,0 +1,78 @@
+"""Application configuration helpers."""
+
+from __future__ import annotations
+
+from functools import lru_cache
+import os
+from pathlib import Path
+from typing import Optional
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+PROJECT_ROOT = Path(__file__).resolve().parents[3]
+DEFAULT_VAULT_BASE = PROJECT_ROOT / "data" / "vaults"
+
+
+class AppConfig(BaseModel):
+    """Runtime configuration loaded from environment variables."""
+
+    model_config = ConfigDict(frozen=True)
+
+    jwt_secret_key: str = Field(..., min_length=16, description="HMAC secret for JWT signing")
+    vault_base_path: Path = Field(..., description="Base directory for per-user vaults")
+    hf_oauth_client_id: Optional[str] = Field(
+        None, description="Hugging Face OAuth client ID (optional)"
+    )
+    hf_oauth_client_secret: Optional[str] = Field(
+        None, description="Hugging Face OAuth client secret (optional)"
+    )
+
+    @field_validator("vault_base_path", mode="before")
+    @classmethod
+    def _normalize_vault_path(cls, value: str | Path | None) -> Path:
+        if value is None or value == "":
+            raise ValueError("VAULT_BASE_PATH is required")
+        if isinstance(value, Path):
+            path = value
+        else:
+            path = Path(value)
+        return path.expanduser().resolve()
+
+    @field_validator("jwt_secret_key")
+    @classmethod
+    def _ensure_secret(cls, value: str) -> str:
+        if not value or not value.strip():
+            raise ValueError("JWT_SECRET_KEY is required")
+        return value.strip()
+
+
+def _read_env(key: str, default: Optional[str] = None) -> Optional[str]:
+    return os.getenv(key, default)
+
+
+@lru_cache(maxsize=1)
+def get_config() -> AppConfig:
+    """Load and cache application configuration."""
+    jwt_secret = _read_env("JWT_SECRET_KEY")
+    vault_base = _read_env("VAULT_BASE_PATH", str(DEFAULT_VAULT_BASE))
+    hf_client_id = _read_env("HF_OAUTH_CLIENT_ID")
+    hf_client_secret = _read_env("HF_OAUTH_CLIENT_SECRET")
+
+    config = AppConfig(
+        jwt_secret_key=jwt_secret,
+        vault_base_path=vault_base,
+        hf_oauth_client_id=hf_client_id,
+        hf_oauth_client_secret=hf_client_secret,
+    )
+    # Ensure vault base directory exists for downstream services.
+    config.vault_base_path.mkdir(parents=True, exist_ok=True)
+    return config
+
+
+def reload_config() -> AppConfig:
+    """Clear cached config (useful for tests) and reload."""
+    get_config.cache_clear()
+    return get_config()
+
+
+__all__ = ["AppConfig", "get_config", "reload_config", "PROJECT_ROOT", "DEFAULT_VAULT_BASE"]

backend/src/services/vault.py

@@ -0,0 +1,73 @@
+"""Filesystem vault management."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Tuple
+
+from .config import AppConfig, get_config
+
+INVALID_PATH_CHARS = {'<', '>', ':', '"', '|', '?', '*'}
+
+
+def validate_note_path(note_path: str) -> Tuple[bool, str]:
+    """
+    Validate a relative Markdown path.
+
+    Returns (is_valid, message). Message is empty when valid.
+    """
+    if not note_path or len(note_path) > 256:
+        return False, "Path must be 1-256 characters"
+    if not note_path.endswith(".md"):
+        return False, "Path must end with .md"
+    if ".." in note_path:
+        return False, "Path must not contain '..'"
+    if "\\" in note_path:
+        return False, "Path must use Unix separators (/)"
+    if note_path.startswith("/"):
+        return False, "Path must be relative (no leading /)"
+    if any(char in INVALID_PATH_CHARS for char in note_path):
+        return False, "Path contains invalid characters"
+    return True, ""
+
+
+def sanitize_path(user_id: str, vault_root: Path, note_path: str) -> Path:
+    """
+    Sanitize and resolve a note path within the vault.
+
+    Raises ValueError if the resolved path escapes the vault root.
+    """
+    vault = (vault_root / user_id).resolve()
+    full_path = (vault / note_path).resolve()
+    if not str(full_path).startswith(str(vault)):
+        raise ValueError(f"Path escapes vault root: {note_path}")
+    return full_path
+
+
+class VaultService:
+    """Service for managing vault directories and basic path validation."""
+
+    def __init__(self, config: AppConfig | None = None) -> None:
+        self.config = config or get_config()
+        self.vault_root = self.config.vault_base_path
+        self.vault_root.mkdir(parents=True, exist_ok=True)
+
+    def initialize_vault(self, user_id: str) -> Path:
+        """Ensure a user's vault directory exists and return its path."""
+        path = (self.vault_root / user_id).resolve()
+        path.mkdir(parents=True, exist_ok=True)
+        return path
+
+    def resolve_note_path(self, user_id: str, note_path: str) -> Path:
+        """
+        Validate and resolve a note path inside a user's vault.
+
+        Raises ValueError for invalid paths.
+        """
+        is_valid, message = validate_note_path(note_path)
+        if not is_valid:
+            raise ValueError(message)
+        return sanitize_path(user_id, self.vault_root, note_path)
+
+
+__all__ = ["VaultService", "validate_note_path", "sanitize_path"]

frontend/src/types/auth.ts

@@ -0,0 +1,18 @@
+/**
+ * Token response returned after authentication.
+ */
+export interface TokenResponse {
+  token: string;
+  token_type: "bearer";
+  expires_at: string; // ISO 8601 timestamp
+}
+
+/**
+ * Standard API error envelope.
+ */
+export interface APIError {
+  error: string;
+  message: string;
+  detail?: Record<string, unknown>;
+}
+

frontend/src/types/note.ts

@@ -0,0 +1,67 @@
+/**
+ * Note metadata/frontmatter representation.
+ */
+export interface NoteMetadata {
+  title?: string;
+  tags?: string[];
+  project?: string;
+  created?: string; // ISO 8601 timestamp
+  updated?: string; // ISO 8601 timestamp
+  [key: string]: unknown;
+}
+
+/**
+ * Complete note payload returned by APIs.
+ */
+export interface Note {
+  user_id: string;
+  note_path: string;
+  version: number;
+  title: string;
+  metadata: NoteMetadata;
+  body: string;
+  created: string; // ISO 8601 timestamp
+  updated: string; // ISO 8601 timestamp
+  size_bytes: number;
+}
+
+/**
+ * Lightweight summary used for listings.
+ */
+export interface NoteSummary {
+  note_path: string;
+  title: string;
+  updated: string; // ISO 8601 timestamp
+}
+
+/**
+ * Request payload for creating a note.
+ */
+export interface NoteCreateRequest {
+  note_path: string;
+  title?: string;
+  metadata?: NoteMetadata;
+  body: string;
+}
+
+/**
+ * Request payload for updating a note.
+ */
+export interface NoteUpdateRequest {
+  title?: string;
+  metadata?: NoteMetadata;
+  body: string;
+  if_version?: number;
+}
+
+/**
+ * Wikilink and backlink representation.
+ */
+export interface Wikilink {
+  user_id: string;
+  source_path: string;
+  target_path: string | null;
+  link_text: string;
+  is_resolved: boolean;
+}
+

frontend/src/types/search.ts

@@ -0,0 +1,29 @@
+/**
+ * Tag with aggregated note count.
+ */
+export interface Tag {
+  tag_name: string;
+  count: number;
+}
+
+/**
+ * Index health metadata per user.
+ */
+export interface IndexHealth {
+  user_id: string;
+  note_count: number;
+  last_full_rebuild: string | null;
+  last_incremental_update: string | null;
+}
+
+/**
+ * Full-text search result entry.
+ */
+export interface SearchResult {
+  note_path: string;
+  title: string;
+  snippet: string;
+  score: number;
+  updated: string; // ISO 8601 timestamp
+}
+

frontend/src/types/user.ts

@@ -0,0 +1,19 @@
+/**
+ * Hugging Face profile metadata attached to a user.
+ */
+export interface HFProfile {
+  username: string;
+  name?: string;
+  avatar_url?: string;
+}
+
+/**
+ * User account returned by the backend.
+ */
+export interface User {
+  user_id: string;
+  hf_profile?: HFProfile;
+  vault_path: string;
+  created: string; // ISO 8601 timestamp
+}
+