ltcai 8.9.0 → 9.1.0

package/docs/security-model.md

@@ -22,15 +22,23 @@ Lattice AI는 **개인 AI 워크스페이스**로 설계되었습니다. 기본
 
 ### 세션
 
-- UUID 토큰, `~/.ltcai/sessions.json` 파일 저장
+- `secrets.token_urlsafe`로 생성한 토큰은 SHA-256 해시만
+  `~/.ltcai/sessions.json`에 저장(레거시 평문 토큰은 로드 시 자동 마이그레이션)
 - TTL: 24시간 + sliding refresh (활동 시 자동 연장, 15분 단위 디스크 쓰기)
 - 쿠키: `HttpOnly; SameSite=Lax; Path=/`
+- public/non-loopback에서는 `Secure`도 강제(HTTPS 필요)
 - 서버 재시작 후에도 유지 (파일 기반)
+- 삭제되거나 비활성화된 계정의 기존 세션은 다음 요청에서 즉시 거부
+- POSIX에서 데이터 디렉터리 `0700`, atomic JSON/세션 파일 `0600`
+- 초대 게이트 쿠키는 설치별 secret으로 HMAC 서명되고 만료 시각을 포함함.
+  `authorized=true` 리터럴은 신뢰하지 않으며, 공용 기본 invite code도 없음
 
 ### SSO (선택적)
 
 - Entra ID / Okta OIDC (`OIDC_DISCOVERY_URL`, `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET`)
 - 콜백 후 내부 세션 토큰으로 변환
+- 초대 게이트 활성화 시 신규 SSO JIT 계정은 서명 초대 권한이 필요하며,
+  해당 권한은 서버 측 일회용 state/nonce/PKCE 트랜잭션에 바인딩됨
 - 어드민 핸드오프: `sessionStorage` 1회 읽기 (URL 파라미터 노출 방지)
 
 ## API 키 보안
@@ -83,15 +91,27 @@ MAGIC_NUMBERS = {
 - **수집 라이프사이클**: 모든 수집은 `IngestionPipeline.ingest` → `dispatch_tool`
   를 거쳐 `pre_tool`/`post_tool` 훅이 발화됩니다. `pre_tool`이 차단하면 수집은
   정직하게 `status="blocked"`로 거부됩니다(권한 게이트·민감정보 가드 적용).
-- **웹 URL 읽기**(`/api/browser/read-url`): `http(s)` 스킴만 허용(파일/기타 스킴
-  거부), 12초 타임아웃, 4MB 응답 상한, HTML/text 컨텐츠 타입만 처리. 차단/로그인
-  필요 페이지는 5xx가 아닌 **422로 우아하게 실패**합니다. 로컬 런타임이 사용자가
-  명시한 URL만 가져옵니다(자동 크롤링 없음).
+- **웹 URL 읽기**(`/api/browser/read-url`): `http(s)`만 허용하고 DNS의 모든 결과에서
+  loopback/private/link-local/multicast/reserved 주소를 거부합니다. 검증한 IP에 연결을
+  고정해 DNS rebinding을 막고, redirect마다 재검증하며 환경 proxy를 사용하지
+  않습니다. 12초 타임아웃, 스트리밍된 4MB 응답 상한, textual content type만
+  처리합니다. 차단/로그인 필요 페이지는 5xx가 아닌 **422로 실패**합니다.
 - **브라우저 탭 수집**(`/api/browser/ingest-current-tab`): payload 정화(스크립트/
   스타일 제거) + 페이로드 크기 상한(413). Manifest V3 확장은 **`127.0.0.1`로만**
   전송하며 클라우드 엔드포인트가 없습니다.
-- **포터빌리티 권한**: 그래프 export/status 읽기는 로그인 사용자, **import /
-  backup / restore 는 admin 전용**(`require_admin`). 그래프는 머신-전역 자원입니다.
+- **포터빌리티 권한**: 상태 읽기는 로그인 사용자, 전체 그래프 export/provenance와
+  **import / backup / restore는 admin 전용**(`require_admin`)입니다. 그래프는
+  머신-전역 자원입니다.
+- **워크스페이스 컨텍스트**: MCP 그래프 호출, 메모리 recall, hybrid search,
+  garden-note 컨텍스트, realtime presence는 인증된 사용자와 활성/허용 workspace에
+  바인딩됩니다. 에이전트·플러그인 registry 및 graph curation 변경은 admin
+  전용이며, MCP 환경 변수 값은 API 응답에 포함되지 않습니다. MCP/플러그인
+  실행은 local file/document 도구를 호출할 수 없고 전용 승인 토큰 경로를
+  사용해야 합니다. Document RAG와 answer trace도 동일한 workspace 범위로
+  검색·저장됩니다.
+- **fail-closed KG 범위**: workspace projection 조회 실패 또는 scope를 알 수 없는
+  v2 node는 반환하지 않습니다. legacy-global 데이터는
+  `include_legacy_global=True`를 명시한 호환 경로에서만 읽습니다.
 - **복원 무결성**: 백업 아카이브는 `manifest.json`의 sha256과 대조 검증 후에만
   복원되며, 불일치 시 거부됩니다.
 
@@ -99,9 +119,10 @@ MAGIC_NUMBERS = {
 
 ### `run_command()` 위험 플래그 차단
 
-다음 패턴이 포함된 명령 실행 거부:
-- `rm -rf`, `sudo`, `chmod 777`, `curl | bash`, `wget | sh`
-- `> /dev/sda`, `dd if=`, `mkfs`
+고정 allowlist(`pwd`, `ls`, `find`, `cat`, `head`, `tail`, `wc`, `rg`)와 정화된
+환경만 사용합니다. Python/Node/npm/npx/sed 같은 일반 인터프리터, 실행 파일 경로,
+절대 경로·`..` traversal·workspace 밖 symlink, `rg --pre`, `find -exec/-delete`
+등은 실행 전에 거부합니다.
 
 ### `edit_file()` 유일성 검증
 
@@ -119,6 +140,17 @@ MAGIC_NUMBERS = {
 - 평문 비밀번호 마이그레이션 이벤트: `password_migrated_from_plaintext`
 - `server.log` 파일에 모든 요청 기록
 
+## Telegram 및 권한 알림
+
+- Telegram은 `LATTICEAI_TELEGRAM_ALLOWED_CHAT_IDS`에 지정된 chat의 메시지와
+  callback query만 처리하며, 허용 전에 chat을 등록하지 않습니다.
+- 봇의 로컬 API 호출에는 `LATTICEAI_SERVER_SESSION_TOKEN` 전용 bearer가
+  필요합니다. 봇은 `sessions.json`을 스캔하지 않습니다.
+- 권한 요청 알림은 전체 승인 토큰 대신 8자 hint만 포함합니다. 선택적인
+  `LATTICEAI_PERMISSION_UI_URL`은 사람의 검토 페이지로 연결하지만 토큰을 URL에
+  넣지 않습니다.
+- permission queue는 atomic write와 POSIX `0600`을 사용합니다.
+
 ## 텔레메트리
 
 **없음.** 모든 데이터는 로컬에만 저장됩니다. 외부 서버로 어떠한 사용 데이터도 전송되지 않습니다.
@@ -128,11 +160,14 @@ MAGIC_NUMBERS = {
 ## 퍼블릭 배포 체크리스트
 
 - [ ] `LATTICEAI_MODE=public`
-- [ ] `LATTICEAI_INVITE_CODE` 비공개 값 설정
+- [ ] 초대 온보딩을 사용할 때만 `LATTICEAI_INVITE_GATE_ENABLED=true`와 비공개
+  `LATTICEAI_INVITE_CODE` 설정(미설정 시 생성되는 설치별 secret 영구 보관)
 - [ ] HTTPS 리버스 프록시 (nginx/Caddy)
 - [ ] `LATTICEAI_ENABLE_GRAPH=false` (필요 시)
 - [ ] `/data` 영구 볼륨 마운트
 - [ ] `LATTICEAI_ALLOW_LOCAL_MODELS=false`
 - [ ] 방화벽에서 4825 포트 직접 노출 차단 (리버스 프록시 통해서만)
+- [ ] Telegram 활성화 시 `LATTICEAI_TELEGRAM_ALLOWED_CHAT_IDS`와
+  `LATTICEAI_SERVER_SESSION_TOKEN` 설정
 
 자세한 내용: [public-deploy.md](public-deploy.md)

package/lattice_brain/__init__.py

@@ -26,7 +26,7 @@ from .storage import (
     storage_from_env,
 )
 
-__version__ = "8.9.0"
+__version__ = "9.1.0"
 
 __all__ = [
     "AgentRuntime",

package/lattice_brain/archive.py

@@ -9,7 +9,6 @@ restore on another machine without contacting a service.
 from __future__ import annotations
 
 import base64
-import hashlib
 import io
 import json
 import os
@@ -18,7 +17,6 @@ import sqlite3
 import tempfile
 import zipfile
 from dataclasses import dataclass
-from datetime import datetime, timezone
 from pathlib import Path, PurePosixPath
 from typing import Any, Dict, Iterable, List, Optional
 
@@ -27,6 +25,8 @@ from cryptography.hazmat.primitives.ciphers.aead import AESGCM
 from cryptography.exceptions import InvalidTag
 from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC
 
+from .utils import sha256_file as _sha256_file, utc_now_iso as _now
+
 
 ARCHIVE_FORMAT = "latticebrain.encrypted"
 ARCHIVE_VERSION = 2
@@ -47,10 +47,6 @@ PORTABLE_DATA_FILES = (
 PORTABLE_EXPORT_SUFFIXES = (".json", ".zip")
 
 
-def _now() -> str:
-    return datetime.now(timezone.utc).isoformat()
-
-
 def _stamp() -> str:
     return _now().replace(":", "").replace("-", "").replace(".", "")[:15]
 
@@ -68,15 +64,9 @@ def _derive_key(passphrase: str, salt: bytes) -> bytes:
 
 
 def _sha256_bytes(data: bytes) -> str:
-    return hashlib.sha256(data).hexdigest()
-
+    import hashlib
 
-def _sha256_file(path: Path) -> str:
-    h = hashlib.sha256()
-    with open(path, "rb") as fh:
-        for block in iter(lambda: fh.read(65536), b""):
-            h.update(block)
-    return h.hexdigest()
+    return hashlib.sha256(data).hexdigest()
 
 
 def _safe_json(value: Any) -> Any:

package/lattice_brain/context.py

@@ -13,6 +13,7 @@ design-review amendment T5).
 
 from __future__ import annotations
 
+import inspect
 import logging
 from dataclasses import dataclass, field
 from typing import Any, Callable, Dict, List, Optional
@@ -23,6 +24,46 @@ def approx_tokens(text: str) -> int:
     return max(0, (len(text or "") + 3) // 4)
 
 
+def _call_context_seam(callback: Callable[..., Any], query: str, **context: Any) -> Any:
+    """Pass identity/scope only when a legacy seam declares support for it.
+
+    Signature inspection preserves old one-argument adapters without catching
+    a callback's own ``TypeError`` and retrying it with less restrictive scope.
+    If a callable cannot be inspected, the secure behavior is to pass every
+    context field and let the caller's failure isolation omit that section.
+    """
+    try:
+        parameters = inspect.signature(callback).parameters
+    except (TypeError, ValueError):
+        return callback(query, **context)
+    accepts_kwargs = any(
+        item.kind is inspect.Parameter.VAR_KEYWORD
+        for item in parameters.values()
+    )
+    supported = context if accepts_kwargs else {
+        key: value for key, value in context.items()
+        if key in parameters
+    }
+    return callback(query, **supported)
+
+
+def _call_keyword_seam(callback: Callable[..., Any], **context: Any) -> Any:
+    """Invoke a keyword-only seam while preserving legacy narrow signatures."""
+    try:
+        parameters = inspect.signature(callback).parameters
+    except (TypeError, ValueError):
+        return callback(**context)
+    accepts_kwargs = any(
+        item.kind is inspect.Parameter.VAR_KEYWORD
+        for item in parameters.values()
+    )
+    supported = context if accepts_kwargs else {
+        key: value for key, value in context.items()
+        if key in parameters
+    }
+    return callback(**supported)
+
+
 @dataclass
 class ContextSection:
     name: str
@@ -112,11 +153,11 @@ class ContextAssembler:
         if self._memory_recall is not None:
             sections.append(self._memories_section(query, user_email, workspace_id, memory_limit))
         if self._hybrid_search is not None:
-            sections.append(self._knowledge_section(query, knowledge_limit, user_email))
+            sections.append(self._knowledge_section(query, knowledge_limit, user_email, workspace_id))
         if self._notes_context is not None:
-            sections.append(self._notes_section(query))
+            sections.append(self._notes_section(query, user_email, workspace_id))
         if self._recent_chat is not None:
-            sections.append(self._recent_section(user_email, conversation_id))
+            sections.append(self._recent_section(user_email, conversation_id, workspace_id))
 
         sections = [s for s in sections if s.content.strip()]
         self._apply_budget(sections, budget)
@@ -141,9 +182,15 @@ class ContextAssembler:
             ],
         )
 
-    def _knowledge_section(self, query, limit, user_email=None) -> ContextSection:
+    def _knowledge_section(self, query, limit, user_email=None, workspace_id=None) -> ContextSection:
         try:
-            hybrid = self._hybrid_search(query, limit=limit, user_email=user_email)
+            hybrid = _call_context_seam(
+                self._hybrid_search,
+                query,
+                limit=limit,
+                user_email=user_email,
+                workspace_id=workspace_id,
+            )
             matches = hybrid.get("matches", [])[:limit]
         except Exception as exc:
             logging.debug("context: hybrid search failed: %s", exc)
@@ -166,9 +213,14 @@ class ContextAssembler:
             provenance=provenance,
         )
 
-    def _notes_section(self, query) -> ContextSection:
+    def _notes_section(self, query, user_email=None, workspace_id=None) -> ContextSection:
         try:
-            content = self._notes_context(query) or ""
+            content = _call_context_seam(
+                self._notes_context,
+                query,
+                user_email=user_email,
+                workspace_id=workspace_id,
+            ) or ""
         except Exception as exc:
             logging.debug("context: notes context failed: %s", exc)
             content = ""
@@ -179,9 +231,14 @@ class ContextAssembler:
             provenance=[{"source": "garden", "included": bool(content)}],
         )
 
-    def _recent_section(self, user_email, conversation_id) -> ContextSection:
+    def _recent_section(self, user_email, conversation_id, workspace_id=None) -> ContextSection:
         try:
-            content = self._recent_chat(user_email=user_email, conversation_id=conversation_id) or ""
+            content = _call_keyword_seam(
+                self._recent_chat,
+                user_email=user_email,
+                conversation_id=conversation_id,
+                workspace_id=workspace_id,
+            ) or ""
         except Exception as exc:
             logging.debug("context: recent chat failed: %s", exc)
             content = ""

package/lattice_brain/embeddings.py

@@ -8,7 +8,7 @@ import os
 import re
 import struct
 from dataclasses import dataclass
-from typing import Iterable, List
+from typing import Any, Dict, Iterable, List, Optional
 
 
 DEFAULT_EMBEDDING_DIM = int(os.getenv("LATTICEAI_VECTOR_DIM", "384"))
@@ -87,4 +87,40 @@ class LocalEmbeddingModel:
         return list(struct.unpack(f"<{count}f", payload[: count * 4]))
 
 
-__all__ = ["DEFAULT_EMBEDDING_DIM", "EMBEDDING_MODEL_ID", "LocalEmbeddingModel", "embedding_model_id"]
+# --- Large candidate #2 slice: multimodal (vision) stubs ---
+# Schema already defines IMAGE / IMAGE_TEXT / CONTAINS_IMAGE.
+# These stubs allow ingestion + retrieval paths to carry image signals without
+# requiring heavy deps at core. Real impl can swap in local vision (e.g. via
+# ollama vision or onnx CLIP) behind the same interface.
+@dataclass(frozen=True)
+class VisionStub:
+    """Offline vision describe + embed stubs for multimodal Brain.
+
+    describe: returns a short textual caption derived from metadata/filename.
+    embed: produces a vector from image meta (size+format) + optional caption hash.
+    Later: replace with real embedding model that accepts image bytes/path.
+    """
+    dim: int = DEFAULT_EMBEDDING_DIM
+
+    def describe(self, path: str | None = None, meta: Optional[Dict[str, Any]] = None) -> str:
+        meta = meta or {}
+        w = meta.get("width") or meta.get("w") or "?"
+        h = meta.get("height") or meta.get("h") or "?"
+        fmt = meta.get("format") or meta.get("ext") or "img"
+        name = (path or "").split("/")[-1] or "image"
+        # deterministic caption stub (no external call)
+        return f"Image {name} ({fmt} {w}x{h})"
+
+    def embed_image(self, path: str | None = None, meta: Optional[Dict[str, Any]] = None, caption: str = "") -> List[float]:
+        meta = meta or {}
+        basis = f"{path or ''}|{meta.get('width',0)}x{meta.get('height',0)}|{meta.get('format','')}|{caption[:120]}"
+        # reuse text embedder for determinism (image content hash would be better with real vision)
+        model = LocalEmbeddingModel(dim=self.dim)
+        return model.embed(basis)
+
+
+def get_vision_embedder(dim: int | None = None) -> VisionStub:
+    return VisionStub(dim=dim or DEFAULT_EMBEDDING_DIM)
+
+
+__all__ = ["DEFAULT_EMBEDDING_DIM", "EMBEDDING_MODEL_ID", "LocalEmbeddingModel", "embedding_model_id", "VisionStub", "get_vision_embedder"]