Provider Authentication
Relevant source files
The following files were used as context for generating this wiki page:
Provider Authentication in Noesis manages the secure acquisition, storage, and lifecycle of credentials required to interact with various LLM providers (e.g., Anthropic, OpenAI, OpenRouter). It acts as a bridge between the Noesis runtime and the Pi execution substrate, ensuring that sensitive secrets are handled within protected boundaries and never leaked into activity history or general workspace files.
The system supports multiple authentication methods including API keys and OAuth flows. It enforces strict filesystem permissions (0700 for directories, 0600 for files) and utilizes a file-based locking mechanism to prevent concurrent write corruption during credential updates. Authentication status is continuously monitored to detect expired OAuth tokens or missing environment variables.
Core Architecture
The authentication architecture is divided into a high-level manager and a low-level secure store. The PiAuthManager handles the interactive login logic and provider-specific flows, while the SecurePiCredentialStore manages the atomic, locked, and permission-hardened filesystem operations.
Component Relationship
The following diagram illustrates the relationship between the Auth Manager, the Credential Store, and the underlying filesystem.
Key Data Structures
Authentication relies on typed credentials and status objects to communicate between the TUI and the runtime.
| Structure | Description | Key Fields |
|---|---|---|
Credential | Union type for API keys or OAuth tokens. | type, key, access, refresh, expires |
PiAuthStatus | Represents the current state of a provider. | configured, source, expired |
NoesisAuthEvent | Events emitted during interactive login. | auth_url, device_code, progress |
FileIdentity | Used to verify filesystem integrity. | dev (device ID), ino (inode number) |
Sources: packages/runtime-pi/src/auth.ts:24-42, 252-273
Secure Storage and I/O
The system implements a hardened storage layer for auth.json. It refuses to interact with symbolic links or files with unsafe permissions to prevent privilege escalation or data theft.
Storage Constraints
- Directory Permissions: Parent directories for credentials must be
0700(user read/write/execute only). - File Permissions: The
auth.jsonfile must be0600(user read/write only). - Atomic Writes: Updates are written to a temporary file and renamed to the destination only after a successful
fsync. - Identity Verification: The system verifies
devandinobefore and after operations to detect race conditions or directory swapping.
Sources: packages/runtime-pi/src/auth.ts:133-162, 222-243, AGENTS.md
Concurrency Control
Noesis uses a file-based lock (auth.json.lock) containing the process ID (PID) and a unique UUID token to manage concurrent access.
Interactive Login Flow
Authentication typically occurs during first-launch onboarding or via explicit TUI commands. The PiAuthManager orchestrates the flow by calling provider-specific login methods provided by the Pi substrate.
Authentication Lifecycle
- Status Check: The system determines if a provider is configured via environment variables, existing stored keys, or OAuth.
- Interactive Prompt: If required, the system emits a
NoesisAuthPrompt(Text, Secret, or Select) to the TUI. - External Verification: For OAuth, a URL or device code is provided to the user.
- Credential Materialization: Once authorized, credentials are saved to the secure store.
Sources: packages/runtime-pi/src/auth.ts:286-319, apps/noesis/test/onboarding.test.ts:70-89
Onboarding and Auto-Configuration
Noesis attempts to "auto-onboard" interactive TUI sessions if no configuration exists. It prefers environment variables (e.g., OPENROUTER_API_KEY) to minimize explicit credential storage.
| Source | Priority | Description |
|---|---|---|
environment | High | Provider-specific ENV variables detected by the Pi substrate. |
stored-api-key | Medium | API keys manually entered and saved to auth.json. |
oauth | Low | Dynamic tokens acquired via device flows. |
Sources: apps/noesis/test/onboarding.test.ts:91-103, packages/runtime-pi/src/auth.ts:321-340
Summary
Provider Authentication in Noesis provides a secure, audited gateway for LLM provider credentials. By combining strict filesystem enforcement, atomic transactional writes, and clear isolation from the general workspace and activity ledgers, the system ensures that the agent's core capabilities do not compromise user secrets. The implementation prioritizes environment-based authentication but provides robust interactive flows for professional OAuth and multi-provider management.
Sources: plans/noesis-autonomous-compounding-implementation-plan.html, AGENTS.md, plans/noesis-high-leverage-correction-plan.html