mirror of https://github.com/lfnovo/open-notebook.git synced 2026-05-02 21:30:38 +00:00

feat: credential-based API key management (#477 ) (#540 )

* feat: replace provider config with credential-based system (#477)

Introduce a new credential management system replacing the old
ProviderConfig singleton and standalone Models page. Each credential
stores encrypted API keys and provider-specific configuration with
full CRUD support via a unified settings UI.

Backend:
- Add Credential domain model with encrypted API key storage
- Add credentials API router (CRUD, discovery, registration, testing)
- Add encryption utilities for secure key storage
- Add key_provider for DB-first env-var fallback provisioning
- Add connection tester and model discovery services
- Integrate ModelManager with credential-based config
- Add provider name normalization for Esperanto compatibility
- Add database migrations 11-12 for credential schema

Frontend:
- Rewrite settings/api-keys page with credential management UI
- Add model discovery dialog with search and custom model support
- Add compact default model assignments (primary/advanced layout)
- Add inline model testing and credential connection testing
- Add env-var migration banner
- Update navigation to unified settings page
- Remove standalone models page and old settings components

i18n:
- Update all 7 locale files with credential and model management keys

Closes #477

Co-Authored-By: JFMD <git@jfmd.us>
Co-Authored-By: OraCatQAQ <570768706@qq.com>

* fix: address PR #540 review comments

- Fix docs referencing removed Models page
- Fix error-handler returning raw messages instead of i18n keys
- Fix auth.py misleading docstring and missing no-password guard
- Fix connection_tester using wrong env var for openai_compatible
- Add provision_provider_keys before model discovery/sync
- Update CLAUDE.md to reflect credential-based system
- Fix missing closing brace in api-keys page useEffect

* fix: add logging to credential migration and surface errors in UI

- Add comprehensive logging to migrate-from-env and
  migrate-from-provider-config endpoints (start, per-provider
  progress, success/failure with stack traces, final summary)
- Fix frontend migration hooks ignoring errors array from response
- Show error toast when migration fails instead of "nothing to migrate"
- Invalidate status/envStatus queries after migration so banner updates

* docs: update CLAUDE.md files for credential system

Replace stale ProviderConfig and /api-keys/ references across 8 CLAUDE.md
files to reflect the new Credential-based system from PR #540.

* docs: update user documentation for credential-based system

Replace env var API key instructions with Settings UI credential
workflow across all user-facing documentation. The new flow is:
set OPEN_NOTEBOOK_ENCRYPTION_KEY → start services → add credential
in Settings UI → test → discover models → register.

- Rewrite ai-providers.md, api-configuration.md, environment-reference.md
- Update all quick-start guides and installation docs
- Update ollama.md, openai-compatible.md, local-tts/stt networking sections
- Update reverse-proxy.md, development-setup.md, security.md
- Fix broken links to non-existent docs/deployment/ paths
- Add credentials endpoints to api-reference.md
- Move all API key env vars to deprecated/legacy sections

* chore: bump version to 1.7.0-rc1

Release candidate for credential-based provider management system.

* fix: initialize provider before try block in test_credential

Prevents UnboundLocalError when Credential.get() throws (e.g.,
invalid credential_id) before provider is assigned.

* fix: reorder down migration to drop index before table

Removes duplicate REMOVE FIELD statement and reorders so the index
is dropped before the table, preventing rollback failures.

* refactor: simplify encryption key to always derive via SHA-256

Remove the dual code path in _ensure_fernet_key() that detected native
Fernet keys. Since the credential system is new, always deriving via
SHA-256 removes unnecessary complexity. Also removes the generate_key()
function and Fernet.generate_key() references from docs.

* fix: correct mock patch targets in embedding tests and URL validation

Fix embedding tests patching wrong module path for model_manager
(was targeting open_notebook.utils.embedding.model_manager but it's
imported locally from open_notebook.ai.models). Also fix URL validation
to allow unresolvable hostnames since they may be valid in the
deployment environment (e.g., Azure endpoints, internal DNS).

* feat: add global setup banner for encryption and migration status

Show a persistent banner in AppShell when encryption key is missing
(red) or env var API keys can be migrated (amber), so users see
these prompts on every page instead of only on Settings > API Keys.

Includes a docs link for the encryption banner and i18n support
across all 7 locales.

* docs: several improvements to docker-compose e env examples

* Update README.md

Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>

* docs: fix env var format in README and update model setup instructions

Align the encryption key snippet in README Step 2 with the list
format used in the compose file. Replace deprecated "Settings →
Models" instructions with credential-based Discover Models flow.

* fix: address credential system review issues

- Fix SSRF bypass via IPv4-mapped IPv6 addresses (::ffff:169.254.x.x)
- Fix TTS connection test missing config parameter
- Add Azure-specific model discovery using api-key auth header
- Add Vertex static model list for credential-based discovery
- Fix PROVIDER_DISCOVERY_FUNCTIONS incorrect azure/vertex mapping
- Extract business logic to api/credentials_service.py (service layer)
- Move credential Pydantic schemas to api/models.py
- Update tests to use new service imports and ValueError assertions

* fix: sanitize error responses and migrate key_provider to Credential

- Replace raw exception messages in all credential router 500 responses
  with generic error strings (internal details logged server-side only)
- Refactor key_provider.py to use Credential.get_by_provider() instead
  of deprecated ProviderConfig.get_instance()
- Remove unused functions (get_provider_configs, get_default_api_key,
  get_provider_config) that were dead code

---------

Co-authored-by: JFMD <git@jfmd.us>
Co-authored-by: OraCatQAQ <570768706@qq.com>

2026-02-10 08:30:22 -03:00

8.1 KiB

Raw Blame History

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

[1.7.0-rc1] - 2026-02-07

Added

Credential-Based Provider Management (#477)
- New Settings → API Keys page for managing AI provider credentials via the UI
- Support for 14 providers: OpenAI, Anthropic, Google, Groq, Mistral, DeepSeek, xAI, OpenRouter, Voyage AI, ElevenLabs, Ollama, Azure OpenAI, OpenAI-Compatible, and Vertex AI
- Secure storage of API keys in SurrealDB with field-level encryption (Fernet AES-128-CBC + HMAC-SHA256)
- One-click connection testing, model discovery, and model registration per credential
- Migration tool to import existing environment variable keys into the credential system
- Azure OpenAI support with service-specific endpoints (LLM, Embedding, STT, TTS)
- OpenAI-Compatible support with per-service URL configurations
- Vertex AI support with project, location, and credentials path
- Environment variable API keys deprecated in favor of Settings UI
Security Enhancements
- Docker secrets support via _FILE suffix pattern (e.g., OPEN_NOTEBOOK_PASSWORD_FILE)
- Default encryption key derived from "0p3n-N0t3b0ok" for easy setup (change in production!)
- Default password "open-notebook-change-me" for out-of-box experience (change in production!)
- URL validation for SSRF protection - blocks private IPs and localhost (except for Ollama which runs locally)
- Security warnings logged when using default credentials
HTML clipboard detection for text sources (#426)
- When pasting content, automatically detects HTML format (e.g., from Word, web pages)
- Shows info message when HTML is detected, informing user it will be converted to Markdown
- Preserves formatting that would be lost with plain text paste
- Bump content-core to 0.11.0 for HTML to Markdown conversion support

Fixed

Azure form race condition: all configuration now saved in single atomic request
Migration API "error error" display: added proper MigrationResult model with message field
Connection tester for Ollama providers: improved error handling and URL validation

Security

API keys are encrypted at rest using Fernet symmetric encryption
Keys are never returned to the frontend, only configuration status
SSRF protection prevents internal network access via URL validation

Docs

Complete documentation update for credential-based system across 25 files
All quick-start, installation, and configuration guides now use Settings UI workflow
Environment variable API key instructions moved to deprecated/legacy sections
Fixed broken links in installation docs

[1.6.2] - 2026-01-24

Fixed

Connection error with llama.cpp and OpenAI-compatible providers (#465)
- Bump Esperanto to 2.17.2 which fixes LangChain connection errors caused by garbage collection

[1.6.1] - 2026-01-22

Fixed

"Failed to send message" error with unhelpful logs when chat model is not configured (#358)
- Added detailed error logging with model selection context and full traceback
- Improved error messages to guide users to Settings → Models
- Added warnings when default models are not configured

Docs

Ollama troubleshooting: Added "Model Name Configuration" section emphasizing exact model names from ollama list
Added troubleshooting entry for "Failed to send message" error with step-by-step solutions
Updated AI Chat Issues documentation with model configuration guidance

[1.6.0] - 2026-01-21

Added

Content-type aware text chunking with automatic HTML, Markdown, and plain text detection (#350, #142)
Unified embedding generation with mean pooling for large content that exceeds model context limits
Dedicated embedding commands: embed_note, embed_insight, embed_source
New utility modules: chunking.py and embedding.py in open_notebook/utils/
Japanese (ja-JP) language support (#450)

Changed

Embedding is now fire-and-forget: domain models submit embedding commands asynchronously after save
rebuild_embeddings_command now delegates to individual embed_* commands instead of inline processing
Chunk size reduced to 1500 characters for better compatibility with Ollama embedding models
Bump Esperanto to 2.16 for increased Ollama context window support

Removed

Legacy embedding commands: embed_single_item_command, embed_chunk_command, vectorize_source_command
needs_embedding() and get_embedding_content() methods from domain models
split_text() function from text_utils (replaced by chunk_text() in chunking module)

Fixed

Embedding failures when content exceeds model context limits (#350, #142)
Empty note titles when saving from chat (clean thinking tags from prompt graph output)
Orphaned embedding/insight records when deleting sources (cascade delete)
Search results crash with null parent_id (defensive frontend check)
Database migration 10 cleans up existing orphaned records

[1.5.2] - 2026-01-15

Performance

Improved source listing speed by 20-30x (#436, closes #351)
- Added database indexes on source field for source_insight and source_embedding tables
- Use SurrealDB FETCH clause for command status instead of N async calls

[1.5.1] - 2026-01-15

Fixed

Podcast dialog infinite loop error caused by excessive translation Proxy accesses in loops
Podcast dialog UI freezing when typing episode name or additional instructions
Removed incorrect translation keys for user-defined episode profiles (user content should not be translated)

[1.5.0] - 2026-01-15

Added

Internationalization (i18n) support with Chinese (Simplified and Traditional) translations (#371, closes #344, #349, #360)
Frontend test infrastructure with Vitest (#371)
Language toggle component for switching UI language (#371)
Date localization using date-fns locales (#371)
Error message translation system (#371)

Fixed

Accessibility improvements: added missing id, name, and autoComplete attributes to form inputs (#371)
Added DialogDescription to dialogs for Radix UI accessibility compliance (#371)
Fixed "Collapsible is changing from uncontrolled to controlled" warning in SettingsForm (#371)
Fixed lint command for Next.js 16 compatibility (eslint instead of next lint)

Changed

Dockerfile optimizations: better layer caching, --no-install-recommends for smaller images (#371)
Dockerfile.single refactored into 3 separate build stages for better caching (#371)

[1.4.0] - 2026-01-14

Added

CTA button to empty state notebook list for better onboarding (#408)
Offline deployment support for Docker containers (#414)

Fixed

Large file uploads (>10MB) by upgrading to Next.js 16 (#423)
Orphaned uploaded files when sources are removed (#421)
Broken documentation links to ai-providers.md (#419)
ZIP support indication removed from UI (#418)
Duplicate Claude Code workflow runs on PRs (#417)
Claude Code review workflow now runs on PRs from forks (#416)

Changed

Upgraded Next.js from 15.4.10 to 16.1.1 (#423)
Upgraded React from 19.1.0 to 19.2.3 (#423)
Renamed middleware.ts to proxy.ts for Next.js 16 compatibility (#423)

Dependencies

next: 15.4.10 → 16.1.1
react: 19.1.0 → 19.2.3
react-dom: 19.1.0 → 19.2.3

[1.2.4] - 2025-12-14

Added

Infinite scroll for notebook sources - no more 50 source limit (#325)
Markdown table rendering in chat responses, search results, and insights (#325)

Fixed

Timeout errors with Ollama and local LLMs - increased to 10 minutes (#325)
"Unable to Connect to API Server" on Docker startup - frontend now waits for API health check (#325, #315)
SSL issues with langchain (#274)
Query key consistency for source mutations to properly refresh infinite scroll (#325)
Docker compose start-all flow (#323)

Changed

Timeout configuration now uses granular httpx.Timeout (short connect, long read) (#325)

Dependencies

Updated next.js to 15.4.10
Updated httpx to >=0.27.0 for SSL fix

8.1 KiB Raw Blame History

Changelog

[Unreleased]

[1.7.0-rc1] - 2026-02-07

Added

Fixed

Security

Docs

[1.6.2] - 2026-01-24

Fixed

[1.6.1] - 2026-01-22

Fixed

Docs

[1.6.0] - 2026-01-21

Added

Changed

Removed

Fixed

[1.5.2] - 2026-01-15

Performance

[1.5.1] - 2026-01-15

Fixed

[1.5.0] - 2026-01-15

Added

Fixed

Changed

[1.4.0] - 2026-01-14

Added

Fixed

Changed

Dependencies

[1.2.4] - 2025-12-14

Added

Fixed

Changed

Dependencies

8.1 KiB

Raw Blame History