Code sync, security fixes

.env.example

@@ -0,0 +1,224 @@
+# Relata configuration.
+#
+# Copy to .env and adjust. Every value here has a working default; the file
+# exists so the available settings are discoverable in one place.
+#
+#   cp .env.example .env
+#
+# .env must never be committed. It is listed in .gitignore.
+
+# --- General ---------------------------------------------------------------
+
+RELATA_ENV=development
+# debug | info | warn | error
+RELATA_LOG_LEVEL=info
+# Structured JSON logs. Leave false for readable local output.
+RELATA_LOG_JSON=false
+
+# --- HTTP ------------------------------------------------------------------
+
+# Relata binds to loopback by default. Listening on any other interface
+# requires RELATA_ALLOW_EXTERNAL_BIND=true, so exposure is always deliberate.
+RELATA_HTTP_ADDR=127.0.0.1:8080
+RELATA_ALLOW_EXTERNAL_BIND=false
+
+# Used for CSRF origin checks and for links printed by the CLI.
+# Setting an https:// URL automatically enables Secure cookies.
+RELATA_BASE_URL=http://127.0.0.1:8080
+
+# Only enable when Relata genuinely sits behind a trusted reverse proxy:
+# otherwise a forged X-Forwarded-For would defeat login rate limiting.
+RELATA_TRUST_PROXY_HEADERS=false
+RELATA_SECURE_COOKIES=false
+
+RELATA_HTTP_READ_TIMEOUT=30s
+# Must exceed RELATA_ANALYSIS_TIMEOUT: an answer is generated inside a request,
+# and a shorter write timeout cuts the connection while the model is still working.
+RELATA_HTTP_WRITE_TIMEOUT=360s
+RELATA_HTTP_IDLE_TIMEOUT=90s
+RELATA_HTTP_SHUTDOWN_TIMEOUT=20s
+RELATA_MAX_REQUEST_BYTES=1048576
+RELATA_METRICS_ENABLED=true
+
+# --- MongoDB ---------------------------------------------------------------
+
+RELATA_MONGO_URI=mongodb://127.0.0.1:27017
+RELATA_MONGO_DATABASE=relata
+RELATA_MONGO_TIMEOUT=10s
+
+# In production, use a least-privilege account with readWrite on this database
+# only, and put the credentials in the URI:
+#   RELATA_MONGO_URI=mongodb://relata_app:PASSWORD@127.0.0.1:27017/relata?authSource=relata
+
+# --- Qdrant ----------------------------------------------------------------
+
+RELATA_QDRANT_URL=http://127.0.0.1:6333
+RELATA_QDRANT_COLLECTION=relata_chunks
+RELATA_QDRANT_TIMEOUT=15s
+# Set when Qdrant requires an API key. Never commit a real value.
+RELATA_QDRANT_API_KEY=
+
+# --- AI providers ----------------------------------------------------------
+
+RELATA_OLLAMA_BASE_URL=http://127.0.0.1:11434
+
+# Pull these before first use:
+#   ollama pull nomic-embed-text
+#   ollama pull llama3.1:8b
+RELATA_EMBEDDING_MODEL=nomic-embed-text
+RELATA_ANALYSIS_MODEL=llama3.1:8b
+
+# Must match the embedding model's output width. nomic-embed-text is 768.
+# Changing this requires re-embedding the workspace.
+RELATA_EMBEDDING_DIMENSIONS=768
+
+# Set false to run without a language model. Ingestion, chunking, embedding,
+# deterministic entity and claim extraction, relationship scoring and search
+# all continue to work; only model-assisted analysis and generated answers stop.
+RELATA_ANALYSIS_ENABLED=true
+
+RELATA_EMBED_TIMEOUT=60s
+# Generous because an 8B model on CPU takes tens of seconds per answer.
+RELATA_ANALYSIS_TIMEOUT=300s
+RELATA_EMBED_BATCH_SIZE=16
+RELATA_AI_MAX_RETRIES=3
+RELATA_AI_RETRY_BASE_DELAY=500ms
+RELATA_AI_RETRY_MAX_DELAY=8s
+RELATA_AI_MAX_OUTPUT_TOKENS=2048
+
+# --- Uploads and limits ----------------------------------------------------
+
+RELATA_UPLOAD_DIR=./data/uploads
+RELATA_MAX_UPLOAD_BYTES=26214400
+RELATA_MAX_EXTRACTED_TEXT_BYTES=2097152
+RELATA_MAX_JSON_DEPTH=20
+RELATA_MAX_METADATA_KEYS=40
+RELATA_MAX_METADATA_VALUE_LEN=2000
+RELATA_MAX_TITLE_LEN=300
+RELATA_PROCESSING_TIMEOUT=10m
+RELATA_MAX_CONCURRENT_INGEST=4
+
+# --- Chunking --------------------------------------------------------------
+
+RELATA_CHUNK_MAX_CHARS=1800
+RELATA_CHUNK_TARGET_CHARS=1100
+RELATA_CHUNK_MIN_CHARS=200
+RELATA_CHUNK_OVERLAP_CHARS=120
+RELATA_MAX_CHUNKS_PER_ITEM=400
+# Documents smaller than this are never split.
+RELATA_CHUNK_MIN_SPLIT_CHARS=900
+
+# --- Background workers ----------------------------------------------------
+
+RELATA_WORKERS_ENABLED=true
+RELATA_WORKER_COUNT=3
+# Concurrent AI calls, independent of worker count. Raise only if the model
+# host can take it.
+RELATA_AI_CONCURRENCY=2
+RELATA_WORKER_POLL_INTERVAL=1s
+RELATA_JOB_LEASE_DURATION=2m
+# Must be shorter than the lease, or a running job would lose it.
+RELATA_JOB_HEARTBEAT=30s
+RELATA_JOB_MAX_ATTEMPTS=4
+RELATA_JOB_TIMEOUT=8m
+
+# --- Search ----------------------------------------------------------------
+
+RELATA_SEARCH_VECTOR_CANDIDATES=60
+RELATA_SEARCH_LEXICAL_CANDIDATES=60
+RELATA_SEARCH_DEFAULT_LIMIT=20
+RELATA_SEARCH_MAX_RESULTS=100
+# Relationship strength below which a link will not pull an item into results.
+RELATA_SEARCH_EXPANSION_MIN_SCORE=0.45
+RELATA_SEARCH_MAX_EXPANDED_ITEMS=20
+RELATA_ANSWER_ENABLED=true
+# Passages given to the model per answer. Each one costs model time; six
+# completes comfortably with llama3.1:8b on CPU, twelve does not.
+RELATA_ANSWER_MAX_CHUNKS=6
+RELATA_ANSWER_MAX_CHARS_PER_CHUNK=1200
+
+# --- Relationship discovery and scoring ------------------------------------
+
+# Candidates considered per newly-ingested item. Discovery never compares an
+# item with every other item.
+RELATA_REL_MAX_CANDIDATES=40
+# Below this strength a candidate is discarded entirely.
+RELATA_REL_MIN_SCORE=0.18
+# At or above this strength a candidate is stored, pending human review.
+# Nothing is ever auto-confirmed.
+RELATA_REL_STORE_SCORE=0.25
+# Language-model classification calls per discovery run.
+RELATA_REL_MAX_MODEL_CALLS=8
+# Cosine similarity at which two items are flagged as likely near-duplicates.
+# They are flagged, never merged.
+RELATA_NEAR_DUPLICATE_SIMILARITY=0.94
+RELATA_REL_TEMPORAL_WINDOW=168h
+RELATA_REL_MAX_NEIGHBOURS_PER_CHUNK=10
+
+# --- Sessions and authentication -------------------------------------------
+
+RELATA_SESSION_COOKIE=relata_session
+RELATA_SESSION_IDLE_TIMEOUT=12h
+RELATA_SESSION_ABSOLUTE_TIMEOUT=168h
+RELATA_LOGIN_RATE_BURST=8
+RELATA_LOGIN_RATE_WINDOW=5m
+
+# --- Federated sign-in (OAuth 2.0 / OpenID Connect) -------------------------
+#
+# The redirect URI to register with your provider is derived from RELATA_BASE_URL
+# and a fixed path:
+#
+#     <RELATA_BASE_URL>/auth/oauth/callback
+#
+# The path is not configurable, so what you register and what Relata serves
+# cannot drift apart.
+
+RELATA_OAUTH_ENABLED=false
+RELATA_OAUTH_PROVIDER_NAME=Blackwall
+
+# Supply EITHER an issuer (OIDC discovery fills in the rest, and enables ID
+# token signature validation) OR the endpoints directly.
+RELATA_OAUTH_ISSUER=
+RELATA_OAUTH_AUTHORIZE_URL=
+RELATA_OAUTH_TOKEN_URL=
+RELATA_OAUTH_USERINFO_URL=
+RELATA_OAUTH_JWKS_URL=
+
+# NEVER commit real values. This file is an example; .env is gitignored.
+RELATA_OAUTH_CLIENT_ID=
+RELATA_OAUTH_CLIENT_SECRET=
+
+RELATA_OAUTH_SCOPES=openid profile email
+
+# Optional allowlist. Empty means any identity the provider vouches for is
+# accepted. Subdomains are NOT matched: "example.com" does not admit
+# "sub.example.com".
+RELATA_OAUTH_ALLOWED_EMAIL_DOMAINS=
+
+RELATA_OAUTH_TIMEOUT=15s
+
+# --- Local (break-glass) sign-in -------------------------------------------
+#
+# Unset, this defaults to the opposite of RELATA_OAUTH_ENABLED: on while there
+# is no identity provider, off once there is one. Set it explicitly to keep a
+# password login available alongside OAuth — useful for recovering from a
+# broken provider configuration, since `relata createadmin` still works.
+#
+# A federated account has no password hash and can never sign in locally,
+# whatever is submitted.
+#RELATA_LOCAL_LOGIN_ENABLED=true
+
+# --- API tokens ------------------------------------------------------------
+#
+# Bearer credentials people create for themselves in Settings -> API tokens.
+# Only a SHA-256 hash is stored, so these bounds are the whole of the lifetime
+# control: a token cannot be looked up, extended or re-shown.
+
+RELATA_API_TOKEN_DEFAULT_TTL=2160h   # 90 days
+RELATA_API_TOKEN_MAX_TTL=8760h       # 365 days
+
+# --- Administrator creation ------------------------------------------------
+
+# Only for unattended setup. Prefer the interactive prompt, which does not
+# place the password in the environment or in shell history.
+# RELATA_ADMIN_PASSWORD=