lambda-erp 0.8.29__tar.gz → 0.8.31__tar.gz

{lambda_erp-0.8.29 → lambda_erp-0.8.31}/PKG-INFO

@@ -1,12 +1,11 @@
 Metadata-Version: 2.5
 Name: lambda-erp
-Version: 0.8.29
+Version: 0.8.31
 Summary: Core ERP logic - accounting, sales, purchasing, inventory
 Author: TORUS INVESTMENTS AG
 License-Expression: Apache-2.0
 License-File: LICENSE
 Requires-Python: >=3.10
-Requires-Dist: anthropic>=0.40
 Requires-Dist: bcrypt>=5
 Requires-Dist: defusedxml>=0.7
 Requires-Dist: fastapi>=0.115
@@ -87,8 +86,8 @@ Each of those is hours of skilled work today. With a capable LLM in the loop, th
 │  - Document forms          │    │  - Document CRUD API       │
 │  - Reports / Analytics     │    │  - Report endpoints        │
 │  - Chat (WebSocket)        │    │  - Auth (JWT cookie)       │
-│  - Client-side JS runtime  │    │  - WebSocket chat gateway  │
-│    (Web Worker) for charts │    └────────────┬───────────────┘
+│  - Declarative report      │    │  - WebSocket chat gateway  │
+│    interpreter for charts  │    └────────────┬───────────────┘
 └────────────────────────────┘                 │
                                                ▼
                            ┌──────────────────────────────────────────┐
@@ -96,8 +95,8 @@ Each of those is hours of skilled work today. With a capable LLM in the loop, th
                            │  - GPT-5.6 drives the reasoning loop     │
                            │  - Tool-use: document CRUD, search,      │
                            │    reports, aggregations, analytics      │
-                           │  - Delegates JS generation to Anthropic  │
-                           │    code-specialist sub-agent             │
+                           │  - Delegates report specs to a separate │
+                           │    GPT-5.6 Terra specialist call         │
                            └──────────────────┬───────────────────────┘
                                               │
                                               ▼
@@ -117,9 +116,9 @@ Each of those is hours of skilled work today. With a capable LLM in the loop, th
 - **Extensions are first-class to the AI.** A customer deployment registers its own doctypes and master types through plugin seams (`register_doctype`, `register_master`) and the chat discovers them automatically - tool schemas and the system prompt are built per request from the live registries, and fields are introspected from the live table, so there is nothing to teach per type. A CRM lead added by a plugin is searchable in chat from day one, with zero prompt or tool edits.
 - **One shape for every document.** Invoices, sales orders, stock entries, payments - all share a single `Document` base class and the same three-state lifecycle (Draft → Submitted → Cancelled) with `on_submit`/`on_cancel` hooks. The LLM learns the pattern once and drives every doctype the same way. Leading open-source and commercial ERPs have per-model action verbs spread across 150+ core models; each one is a separate tool the model has to get right.
 - **Metadata-driven UI, shared with the LLM.** A single React form component renders every doctype from `frontend/src/lib/doctypes.ts`. The schema the model reasons over and the schema the user sees are literally the same file. Adding a field is two lines - one in the Python class, one in the config - not a new module with hand-written views and inheritance overlays.
-- **Two-model orchestration.** A planner model handles reasoning and tool-use. When it needs to generate code for a custom report, it delegates to a code-specialist sub-agent. This keeps each model doing what it's best at and keeps latency down on simple turns.
+- **Two-model orchestration.** A planner model handles reasoning and tool-use. When it needs a custom report, it delegates a bounded declarative report specification to a report-specialist model. No generated report JavaScript is executed in the browser.
 - **Semantic datasets, not free SQL.** The LLM can't write raw SQL; it calls whitelisted semantic datasets (`sales_invoices`, `purchase_invoices`, `ar_open_items`, `stock_balances`, etc.) with whitelisted filters and group-bys. This makes the system auditable without sacrificing flexibility.
-- **Client-side analytics runtime.** Custom report JS executes in a sandboxed Web Worker in the user's browser. The server never runs untrusted JS. Charts are persisted as portable specs, not screenshots.
+- **Client-side analytics runtime.** A bounded declarative interpreter groups, aggregates, sorts, and charts whitelisted semantic datasets. Report drafts contain portable JSON specifications, never executable code.
 - **Double-entry invariant enforced.** Every submitted document that touches the GL must balance to zero. The engine adds round-off entries for rounding gaps and refuses to post imbalanced vouchers.
 - **One deployment per customer, simple to operate.** Lambda ERP is built to be self-hosted by a single company for its own books - not as a multi-tenant SaaS. One FastAPI process, one database, one VPS is enough. If you want a hosted offering, we'll ship a dedicated instance per customer.
 
@@ -133,7 +132,7 @@ Each of those is hours of skilled work today. With a capable LLM in the loop, th
 | Frontend | React + Vite + TypeScript + Tailwind + Recharts |
 | Chat transport | WebSocket |
 | LLM orchestrator | OpenAI (configurable) |
-| Code specialist | Anthropic (configurable) |
+| Report specialist | OpenAI GPT-5.6 Terra (configurable) |
 | Auth | JWT httponly cookie, three roles + demo |
 
 ---
@@ -186,7 +185,7 @@ The result is booked in one step — chart of accounts, sensible default account
 Four things had to be true for this to work, and they all became true in the last ~18 months:
 
 1. **LLMs can reliably call tools.** A year ago, models would hallucinate tool calls, mangle JSON, or drift after 2–3 steps. Today's frontier models can run an 8-step reasoning loop over a real tool inventory without falling off.
-2. **Costs collapsed.** Generating a custom report via a code-specialist sub-agent is cents of compute. Even keeping a human reviewer fully in the loop, the marginal cost of "one more report" or "one more dashboard" drops by orders of magnitude — which means companies actually ask for them, instead of living with the defaults.
+2. **Costs collapsed.** Generating a custom report via a report-specialist model is cents of compute. Even keeping a human reviewer fully in the loop, the marginal cost of "one more report" or "one more dashboard" drops by orders of magnitude — which means companies actually ask for them, instead of living with the defaults.
 3. **Structured output + function calling are first-class.** We can constrain the LLM's outputs to valid tool-call schemas, safe SQL parameters, and typed JSON - which is what makes an AI-native ERP even conceivable as a safe thing to run.
 4. **Greenfield is finally cheaper than retrofit.** Twenty-year ERP codebases have hundreds of bespoke models and thousands of hand-written forms - teaching an LLM to drive that reliably means curating a custom tool layer over every quirk. Starting from scratch around one Document lifecycle and a metadata-driven UI is now cheaper than retrofitting an existing platform.
 
@@ -217,7 +216,7 @@ You need Docker and Compose v2. The canonical installs:
 Then, from the repo root:
 
 ```bash
-cp .env.example .env          # add your OPENAI_API_KEY and ANTHROPIC_API_KEY (for custom analytics)
+cp .env.example .env          # add your OPENAI_API_KEY
 docker compose up --build
 ```
 
@@ -262,14 +261,15 @@ Open `http://localhost:5173`. Vite proxies `/api/*` to the backend.
 
 ```
 OPENAI_API_KEY=sk-...
-ANTHROPIC_API_KEY=sk-ant-...    # optional, used for the code-specialist sub-agent
-ANTHROPIC_CODE_MODEL=claude-opus-4-7   # optional, default shown
+LAMBDA_ERP_REPORT_MODEL=gpt-5.6-terra  # optional specialist override; default shown
 LAMBDA_ERP_ADMIN_EMAIL=admin@example.com   # optional, seeds the admin at boot
 LAMBDA_ERP_ADMIN_PASSWORD=...              # optional, required with the line above
 LAMBDA_ERP_ADMIN_NAME=Administrator        # optional, display name for the seeded admin
 ```
 
-Chat needs `OPENAI_API_KEY`. Custom-report code generation uses `ANTHROPIC_API_KEY` when set; otherwise it falls back and the chat will tell you it can't generate reports.
+Chat and custom-report specification generation share `OPENAI_API_KEY`. Both
+the orchestrator and report specialist default to GPT-5.6 Terra; the specialist
+can be overridden with `LAMBDA_ERP_REPORT_MODEL`.
 
 **Seeded admin.** By default the first person to register becomes the admin. Set `LAMBDA_ERP_ADMIN_EMAIL` + `LAMBDA_ERP_ADMIN_PASSWORD` to instead provision that admin automatically at startup — useful when the database is recreated on every deploy, so a redeployed instance can't be claimed by whoever visits first. It's create-if-missing and idempotent (an existing account with that email is promoted to an enabled admin; its password is left untouched), and the password is only ever read from the environment.
 
@@ -487,4 +487,4 @@ Release notes live in [CHANGELOG.md](./CHANGELOG.md). Releases are tagged
 
 ## Trademarks and affiliations
 
-Lambda ERP and [lambda.dev](https://lambda.dev/) are product and trade names of **TORUS INVESTMENTS AG**. It is not affiliated with, endorsed by, or sponsored by OpenAI, Anthropic, SAP, Oracle, Microsoft, or any other company named in this repository. SAP, Business One, S/4HANA, Oracle, NetSuite, Microsoft, Dynamics, OpenAI, GPT, Anthropic, and Claude are trademarks of their respective owners and are referenced here only for descriptive and comparative purposes (nominative fair use). We interoperate with OpenAI and Anthropic APIs as a customer like anyone else; you supply your own API keys.
+Lambda ERP and [lambda.dev](https://lambda.dev/) are product and trade names of **TORUS INVESTMENTS AG**. It is not affiliated with, endorsed by, or sponsored by OpenAI, Anthropic, SAP, Oracle, Microsoft, or any other company named in this repository. SAP, Business One, S/4HANA, Oracle, NetSuite, Microsoft, Dynamics, OpenAI, GPT, Anthropic, and Claude are trademarks of their respective owners and are referenced here only for descriptive and comparative purposes (nominative fair use). The ERP uses the OpenAI API as a customer; you supply your own API key.

{lambda_erp-0.8.29 → lambda_erp-0.8.31}/README.md

@@ -58,8 +58,8 @@ Each of those is hours of skilled work today. With a capable LLM in the loop, th
 │  - Document forms          │    │  - Document CRUD API       │
 │  - Reports / Analytics     │    │  - Report endpoints        │
 │  - Chat (WebSocket)        │    │  - Auth (JWT cookie)       │
-│  - Client-side JS runtime  │    │  - WebSocket chat gateway  │
-│    (Web Worker) for charts │    └────────────┬───────────────┘
+│  - Declarative report      │    │  - WebSocket chat gateway  │
+│    interpreter for charts  │    └────────────┬───────────────┘
 └────────────────────────────┘                 │
                                                ▼
                            ┌──────────────────────────────────────────┐
@@ -67,8 +67,8 @@ Each of those is hours of skilled work today. With a capable LLM in the loop, th
                            │  - GPT-5.6 drives the reasoning loop     │
                            │  - Tool-use: document CRUD, search,      │
                            │    reports, aggregations, analytics      │
-                           │  - Delegates JS generation to Anthropic  │
-                           │    code-specialist sub-agent             │
+                           │  - Delegates report specs to a separate │
+                           │    GPT-5.6 Terra specialist call         │
                            └──────────────────┬───────────────────────┘
                                               │
                                               ▼
@@ -88,9 +88,9 @@ Each of those is hours of skilled work today. With a capable LLM in the loop, th
 - **Extensions are first-class to the AI.** A customer deployment registers its own doctypes and master types through plugin seams (`register_doctype`, `register_master`) and the chat discovers them automatically - tool schemas and the system prompt are built per request from the live registries, and fields are introspected from the live table, so there is nothing to teach per type. A CRM lead added by a plugin is searchable in chat from day one, with zero prompt or tool edits.
 - **One shape for every document.** Invoices, sales orders, stock entries, payments - all share a single `Document` base class and the same three-state lifecycle (Draft → Submitted → Cancelled) with `on_submit`/`on_cancel` hooks. The LLM learns the pattern once and drives every doctype the same way. Leading open-source and commercial ERPs have per-model action verbs spread across 150+ core models; each one is a separate tool the model has to get right.
 - **Metadata-driven UI, shared with the LLM.** A single React form component renders every doctype from `frontend/src/lib/doctypes.ts`. The schema the model reasons over and the schema the user sees are literally the same file. Adding a field is two lines - one in the Python class, one in the config - not a new module with hand-written views and inheritance overlays.
-- **Two-model orchestration.** A planner model handles reasoning and tool-use. When it needs to generate code for a custom report, it delegates to a code-specialist sub-agent. This keeps each model doing what it's best at and keeps latency down on simple turns.
+- **Two-model orchestration.** A planner model handles reasoning and tool-use. When it needs a custom report, it delegates a bounded declarative report specification to a report-specialist model. No generated report JavaScript is executed in the browser.
 - **Semantic datasets, not free SQL.** The LLM can't write raw SQL; it calls whitelisted semantic datasets (`sales_invoices`, `purchase_invoices`, `ar_open_items`, `stock_balances`, etc.) with whitelisted filters and group-bys. This makes the system auditable without sacrificing flexibility.
-- **Client-side analytics runtime.** Custom report JS executes in a sandboxed Web Worker in the user's browser. The server never runs untrusted JS. Charts are persisted as portable specs, not screenshots.
+- **Client-side analytics runtime.** A bounded declarative interpreter groups, aggregates, sorts, and charts whitelisted semantic datasets. Report drafts contain portable JSON specifications, never executable code.
 - **Double-entry invariant enforced.** Every submitted document that touches the GL must balance to zero. The engine adds round-off entries for rounding gaps and refuses to post imbalanced vouchers.
 - **One deployment per customer, simple to operate.** Lambda ERP is built to be self-hosted by a single company for its own books - not as a multi-tenant SaaS. One FastAPI process, one database, one VPS is enough. If you want a hosted offering, we'll ship a dedicated instance per customer.
 
@@ -104,7 +104,7 @@ Each of those is hours of skilled work today. With a capable LLM in the loop, th
 | Frontend | React + Vite + TypeScript + Tailwind + Recharts |
 | Chat transport | WebSocket |
 | LLM orchestrator | OpenAI (configurable) |
-| Code specialist | Anthropic (configurable) |
+| Report specialist | OpenAI GPT-5.6 Terra (configurable) |
 | Auth | JWT httponly cookie, three roles + demo |
 
 ---
@@ -157,7 +157,7 @@ The result is booked in one step — chart of accounts, sensible default account
 Four things had to be true for this to work, and they all became true in the last ~18 months:
 
 1. **LLMs can reliably call tools.** A year ago, models would hallucinate tool calls, mangle JSON, or drift after 2–3 steps. Today's frontier models can run an 8-step reasoning loop over a real tool inventory without falling off.
-2. **Costs collapsed.** Generating a custom report via a code-specialist sub-agent is cents of compute. Even keeping a human reviewer fully in the loop, the marginal cost of "one more report" or "one more dashboard" drops by orders of magnitude — which means companies actually ask for them, instead of living with the defaults.
+2. **Costs collapsed.** Generating a custom report via a report-specialist model is cents of compute. Even keeping a human reviewer fully in the loop, the marginal cost of "one more report" or "one more dashboard" drops by orders of magnitude — which means companies actually ask for them, instead of living with the defaults.
 3. **Structured output + function calling are first-class.** We can constrain the LLM's outputs to valid tool-call schemas, safe SQL parameters, and typed JSON - which is what makes an AI-native ERP even conceivable as a safe thing to run.
 4. **Greenfield is finally cheaper than retrofit.** Twenty-year ERP codebases have hundreds of bespoke models and thousands of hand-written forms - teaching an LLM to drive that reliably means curating a custom tool layer over every quirk. Starting from scratch around one Document lifecycle and a metadata-driven UI is now cheaper than retrofitting an existing platform.
 
@@ -188,7 +188,7 @@ You need Docker and Compose v2. The canonical installs:
 Then, from the repo root:
 
 ```bash
-cp .env.example .env          # add your OPENAI_API_KEY and ANTHROPIC_API_KEY (for custom analytics)
+cp .env.example .env          # add your OPENAI_API_KEY
 docker compose up --build
 ```
 
@@ -233,14 +233,15 @@ Open `http://localhost:5173`. Vite proxies `/api/*` to the backend.
 
 ```
 OPENAI_API_KEY=sk-...
-ANTHROPIC_API_KEY=sk-ant-...    # optional, used for the code-specialist sub-agent
-ANTHROPIC_CODE_MODEL=claude-opus-4-7   # optional, default shown
+LAMBDA_ERP_REPORT_MODEL=gpt-5.6-terra  # optional specialist override; default shown
 LAMBDA_ERP_ADMIN_EMAIL=admin@example.com   # optional, seeds the admin at boot
 LAMBDA_ERP_ADMIN_PASSWORD=...              # optional, required with the line above
 LAMBDA_ERP_ADMIN_NAME=Administrator        # optional, display name for the seeded admin
 ```
 
-Chat needs `OPENAI_API_KEY`. Custom-report code generation uses `ANTHROPIC_API_KEY` when set; otherwise it falls back and the chat will tell you it can't generate reports.
+Chat and custom-report specification generation share `OPENAI_API_KEY`. Both
+the orchestrator and report specialist default to GPT-5.6 Terra; the specialist
+can be overridden with `LAMBDA_ERP_REPORT_MODEL`.
 
 **Seeded admin.** By default the first person to register becomes the admin. Set `LAMBDA_ERP_ADMIN_EMAIL` + `LAMBDA_ERP_ADMIN_PASSWORD` to instead provision that admin automatically at startup — useful when the database is recreated on every deploy, so a redeployed instance can't be claimed by whoever visits first. It's create-if-missing and idempotent (an existing account with that email is promoted to an enabled admin; its password is left untouched), and the password is only ever read from the environment.
 
@@ -458,4 +459,4 @@ Release notes live in [CHANGELOG.md](./CHANGELOG.md). Releases are tagged
 
 ## Trademarks and affiliations
 
-Lambda ERP and [lambda.dev](https://lambda.dev/) are product and trade names of **TORUS INVESTMENTS AG**. It is not affiliated with, endorsed by, or sponsored by OpenAI, Anthropic, SAP, Oracle, Microsoft, or any other company named in this repository. SAP, Business One, S/4HANA, Oracle, NetSuite, Microsoft, Dynamics, OpenAI, GPT, Anthropic, and Claude are trademarks of their respective owners and are referenced here only for descriptive and comparative purposes (nominative fair use). We interoperate with OpenAI and Anthropic APIs as a customer like anyone else; you supply your own API keys.
+Lambda ERP and [lambda.dev](https://lambda.dev/) are product and trade names of **TORUS INVESTMENTS AG**. It is not affiliated with, endorsed by, or sponsored by OpenAI, Anthropic, SAP, Oracle, Microsoft, or any other company named in this repository. SAP, Business One, S/4HANA, Oracle, NetSuite, Microsoft, Dynamics, OpenAI, GPT, Anthropic, and Claude are trademarks of their respective owners and are referenced here only for descriptive and comparative purposes (nominative fair use). The ERP uses the OpenAI API as a customer; you supply your own API key.

{lambda_erp-0.8.29 → lambda_erp-0.8.31}/api/attachments.py

@@ -238,6 +238,12 @@ async def upload_attachment(
     user: dict = Depends(require_role("viewer")),
 ):
     """Upload a chat attachment. Returns metadata the client uses to attach it to a message."""
+    db = get_db()
+    sessions = db.sql('SELECT user_id FROM "Chat Session" WHERE id = ?', [session_id])
+    if not sessions or sessions[0].get("user_id") != user.get("name"):
+        # Keep foreign session IDs indistinguishable from nonexistent ones.
+        raise HTTPException(status_code=404, detail="Chat session not found")
+
     mime = (file.content_type or "application/octet-stream").lower()
     if mime not in ALLOWED_MIME_TYPES:
         # Browsers/OSes often mislabel Office files (e.g. octet-stream) — fall
@@ -253,9 +259,14 @@ async def upload_attachment(
                         "and structured bank files (XML/ZIP)."),
             )
 
-    data = await file.read()
-    if len(data) > MAX_ATTACHMENT_SIZE:
-        raise HTTPException(status_code=413, detail=f"File too large. Maximum {MAX_ATTACHMENT_SIZE // (1024 * 1024)} MB.")
+    chunks: list[bytes] = []
+    size = 0
+    while chunk := await file.read(1024 * 1024):
+        size += len(chunk)
+        if size > MAX_ATTACHMENT_SIZE:
+            raise HTTPException(status_code=413, detail=f"File too large. Maximum {MAX_ATTACHMENT_SIZE // (1024 * 1024)} MB.")
+        chunks.append(chunk)
+    data = b"".join(chunks)
     if not data:
         raise HTTPException(status_code=400, detail="Empty file.")
 
@@ -275,7 +286,6 @@ async def upload_attachment(
                 ),
             )
 
-    db = get_db()
     # Sanity-cap the number of attachments per session
     cnt = db.sql('SELECT COUNT(*) as c FROM "Chat Attachment" WHERE session_id = ?', [session_id])
     if cnt and cnt[0]["c"] >= MAX_ATTACHMENTS_PER_SESSION:

{lambda_erp-0.8.29 → lambda_erp-0.8.31}/api/auth.py

@@ -196,6 +196,87 @@ class SetPasswordRequest(BaseModel):
 ROLE_HIERARCHY = {"admin": 3, "manager": 2, "public_manager": 2, "viewer": 1}
 ASSIGNABLE_ROLES = {"admin", "manager", "viewer"}
 
+SESSION_CREDENTIAL = "session"
+API_KEY_CREDENTIAL = "api_key"
+PUBLIC_DEMO_CREDENTIAL = "public_demo"
+
+
+def make_auth_principal(
+    user: dict,
+    credential_type: str,
+    *,
+    name: str | None = None,
+    api_key_id: str | None = None,
+) -> dict:
+    """Return the request-scoped identity used by authorization checks.
+
+    ``User`` and ``Api Key`` rows remain the persistence model.  A principal is
+    deliberately ephemeral: it records both *who* the owner is and *how* this
+    request authenticated, so a role-capped API key cannot be mistaken for an
+    interactive browser session at credential-management endpoints.
+    """
+    principal = dict(user)
+    principal["user_id"] = user["name"]
+    principal["name"] = name or user["name"]
+    principal["credential_type"] = credential_type
+    if api_key_id:
+        principal["api_key_id"] = api_key_id
+    return principal
+
+
+def refresh_auth_principal(principal: dict | None) -> dict | None:
+    """Re-resolve an authenticated principal from live database state.
+
+    Used at long-lived boundaries (notably chat WebSockets and tool dispatch)
+    so disabling/demoting a user or revoking a key takes effect without waiting
+    for the connection to close.  Legacy in-process callers without an explicit
+    credential type are returned unchanged; every real HTTP/WS auth path sets it.
+    """
+    if not principal:
+        return None
+    credential_type = principal.get("credential_type")
+    if not credential_type:
+        return principal
+
+    db = get_db()
+    if credential_type == API_KEY_CREDENTIAL:
+        key_id = principal.get("api_key_id")
+        rows = db.sql(
+            'SELECT id, owner, role, session_owner, revoked FROM "Api Key" WHERE id = ?',
+            [key_id],
+        )
+        if not rows or rows[0].get("revoked"):
+            return None
+        key = dict(rows[0])
+        owner = db.get_value(
+            "User", key["owner"], ["name", "email", "full_name", "role", "enabled"]
+        )
+        if not owner or not owner.get("enabled"):
+            return None
+        owner = dict(owner)
+        effective_role = (
+            key["role"] if _role_rank(key["role"]) <= _role_rank(owner["role"])
+            else owner["role"]
+        )
+        owner["role"] = effective_role
+        return make_auth_principal(
+            owner,
+            API_KEY_CREDENTIAL,
+            name=principal.get("name") or key.get("session_owner") or owner["name"],
+            api_key_id=key["id"],
+        )
+
+    user_id = principal.get("user_id") or principal.get("name")
+    user = db.get_value(
+        "User", user_id, ["name", "email", "full_name", "role", "enabled"]
+    )
+    if not user or not user.get("enabled"):
+        return None
+    user = dict(user)
+    if credential_type == PUBLIC_DEMO_CREDENTIAL and user.get("role") != "public_manager":
+        return None
+    return make_auth_principal(user, credential_type)
+
 
 def get_current_user(request: Request) -> dict:
     """FastAPI dependency: resolve the caller for every cookie-gated REST route.
@@ -223,26 +304,23 @@ def get_current_user(request: Request) -> dict:
         if user_name:
             user = db.get_value("User", user_name, ["name", "email", "full_name", "role", "enabled"])
             if user and user.get("enabled"):
-                return dict(user)
+                return make_auth_principal(dict(user), SESSION_CREDENTIAL)
 
     bearer = _bearer_token(request)
     if bearer is not None:
         if not _setting_enabled(db, "rest_api_enabled"):
             raise HTTPException(status_code=401, detail="REST API key access is disabled")
         key, owner, effective_role = _lookup_api_key(db, bearer)
-        return {
-            "name": owner["name"],
-            "email": owner.get("email"),
-            "full_name": owner.get("full_name"),
-            "role": effective_role,
-            "enabled": owner.get("enabled"),
-            "api_key_id": key["id"],
-        }
+        owner = dict(owner)
+        owner["role"] = effective_role
+        return make_auth_principal(
+            owner, API_KEY_CREDENTIAL, api_key_id=key["id"]
+        )
 
     # Fall back to public manager (demo mode)
     pub = db.sql('SELECT name, email, full_name, role, enabled FROM "User" WHERE role = \'public_manager\' AND enabled = 1')
     if pub:
-        return dict(pub[0])
+        return make_auth_principal(dict(pub[0]), PUBLIC_DEMO_CREDENTIAL)
 
     raise HTTPException(status_code=401, detail="Not authenticated")
 
@@ -272,6 +350,34 @@ require_manager = require_role("manager")
 require_viewer = require_role("viewer")
 
 
+def require_interactive_user(user: dict = Depends(get_current_user)) -> dict:
+    """Require a real browser session for account/credential management."""
+    if user.get("credential_type") != SESSION_CREDENTIAL:
+        raise HTTPException(
+            status_code=403,
+            detail="This account-security operation requires an interactive sign-in.",
+        )
+    return user
+
+
+def require_interactive_role(minimum_role: str):
+    """Require both a browser session and the requested live account role."""
+    min_level = ROLE_HIERARCHY[minimum_role]
+
+    def checker(user: dict = Depends(require_interactive_user)) -> dict:
+        if ROLE_HIERARCHY.get(user.get("role"), 0) < min_level:
+            raise HTTPException(
+                status_code=403,
+                detail=f"Requires {minimum_role} role or higher",
+            )
+        return user
+
+    return checker
+
+
+require_interactive_admin = require_interactive_role("admin")
+
+
 def require_non_public_manager(user: dict = Depends(get_current_user)) -> dict:
     user_level = ROLE_HIERARCHY.get(user["role"], 0)
     if user_level < ROLE_HIERARCHY["manager"]:
@@ -404,7 +510,7 @@ def me(user: dict = Depends(get_current_user)):
 
 
 @router.post("/change-password")
-def change_password(data: ChangePasswordRequest, user: dict = Depends(get_current_user)):
+def change_password(data: ChangePasswordRequest, user: dict = Depends(require_interactive_user)):
     """Change the signed-in user's own password (verifies the current one)."""
     # The public_manager is a shared demo account — no real password to change.
     if user["role"] == "public_manager":
@@ -426,7 +532,7 @@ def change_password(data: ChangePasswordRequest, user: dict = Depends(get_curren
 
 
 @router.post("/set-password")
-def set_password(data: SetPasswordRequest, user: dict = Depends(get_current_user)):
+def set_password(data: SetPasswordRequest, user: dict = Depends(require_interactive_user)):
     """Set a first password for an account that has none — e.g. a user created
     via social login who wants an email+password fallback. Requires an
     authenticated session; refuses if a usable password already exists (that
@@ -451,7 +557,7 @@ def set_password(data: SetPasswordRequest, user: dict = Depends(get_current_user
 
 
 @router.post("/invite")
-def create_invite(data: InviteRequest, user: dict = Depends(require_admin)):
+def create_invite(data: InviteRequest, user: dict = Depends(require_interactive_admin)):
     db = get_db()
 
     validate_assignable_role(data.role)
@@ -474,14 +580,14 @@ def create_invite(data: InviteRequest, user: dict = Depends(require_admin)):
 
 
 @router.get("/users")
-def list_users(user: dict = Depends(require_admin)):
+def list_users(user: dict = Depends(require_interactive_admin)):
     db = get_db()
     rows = db.sql('SELECT name, email, full_name, role, enabled, creation FROM "User" ORDER BY creation')
     return [dict(r) for r in rows]
 
 
 @router.put("/users/{user_name}/role")
-def change_role(user_name: str, data: ChangeRoleRequest, user: dict = Depends(require_admin)):
+def change_role(user_name: str, data: ChangeRoleRequest, user: dict = Depends(require_interactive_admin)):
     validate_assignable_role(data.role)
 
     db = get_db()
@@ -498,7 +604,7 @@ def change_role(user_name: str, data: ChangeRoleRequest, user: dict = Depends(re
 
 
 @router.delete("/users/{user_name}")
-def disable_user(user_name: str, user: dict = Depends(require_admin)):
+def disable_user(user_name: str, user: dict = Depends(require_interactive_admin)):
     if user_name == user["name"]:
         raise HTTPException(status_code=409, detail="Cannot disable yourself")
 
@@ -511,14 +617,14 @@ def disable_user(user_name: str, user: dict = Depends(require_admin)):
 
 
 @router.get("/invites")
-def list_invites(user: dict = Depends(require_admin)):
+def list_invites(user: dict = Depends(require_interactive_admin)):
     db = get_db()
     rows = db.sql('SELECT token, email, role, used, creation FROM "Invite" ORDER BY creation DESC')
     return [dict(r) for r in rows]
 
 
 @router.delete("/invites/{token}")
-def revoke_invite(token: str, user: dict = Depends(require_admin)):
+def revoke_invite(token: str, user: dict = Depends(require_interactive_admin)):
     """Revoke a pending (unused) invite so its link no longer works."""
     db = get_db()
     rows = db.sql('SELECT token, used FROM "Invite" WHERE token = ?', [token])
@@ -532,7 +638,7 @@ def revoke_invite(token: str, user: dict = Depends(require_admin)):
 
 
 @router.post("/public-manager")
-def create_public_manager(user: dict = Depends(require_admin)):
+def create_public_manager(user: dict = Depends(require_interactive_admin)):
     """Create (or re-enable) the public manager account for demo mode.
 
     Also seeds the chat-replay artefacts the "Enter Live Demo" script
@@ -580,7 +686,7 @@ def create_public_manager(user: dict = Depends(require_admin)):
 
 
 @router.delete("/public-manager")
-def remove_public_manager(user: dict = Depends(require_admin)):
+def remove_public_manager(user: dict = Depends(require_interactive_admin)):
     """Disable the public manager account."""
     db = get_db()
     existing = db.sql('SELECT name FROM "User" WHERE role = \'public_manager\'')
@@ -690,7 +796,7 @@ def ensure_seed_admin() -> dict | None:
 
 
 @router.get("/settings")
-def get_settings(user: dict = Depends(get_current_user)):
+def get_settings(user: dict = Depends(require_interactive_user)):
     db = get_db()
     rows = db.sql('SELECT key, value FROM "Settings"')
     settings = {r["key"]: r["value"] for r in rows}
@@ -702,7 +808,7 @@ def get_settings(user: dict = Depends(get_current_user)):
 
 
 @router.put("/settings")
-def update_settings(data: dict, user: dict = Depends(require_admin)):
+def update_settings(data: dict, user: dict = Depends(require_interactive_admin)):
     db = get_db()
     for key, value in data.items():
         existing = db.sql('SELECT key FROM "Settings" WHERE key = ?', [key])
@@ -857,13 +963,17 @@ def get_api_caller(request: Request) -> dict:
         raise HTTPException(status_code=401, detail="Missing or malformed Authorization header")
     key, owner, effective_role = _lookup_api_key(db, token)
 
-    return {
-        "name": key["session_owner"],
-        "full_name": f"{owner.get('full_name') or key['owner']} (API)",
-        "role": effective_role,
-        "api_key_id": key["id"],
-        "api_key_user": key["owner"],
-    }
+    owner = dict(owner)
+    owner["role"] = effective_role
+    principal = make_auth_principal(
+        owner,
+        API_KEY_CREDENTIAL,
+        name=key["session_owner"],
+        api_key_id=key["id"],
+    )
+    principal["full_name"] = f"{owner.get('full_name') or key['owner']} (API)"
+    principal["api_key_user"] = key["owner"]
+    return principal
 
 
 class ApiKeyCreate(BaseModel):
@@ -904,7 +1014,7 @@ def _require_key_access(key: dict, user: dict) -> None:
 
 
 @router.get("/api-keys")
-def list_api_keys(user: dict = Depends(require_viewer)):
+def list_api_keys(user: dict = Depends(require_interactive_user)):
     """List API keys (metadata only — the token is never returned).
 
     Users see their own keys; admins see everyone's. Each key carries its
@@ -930,7 +1040,7 @@ def list_api_keys(user: dict = Depends(require_viewer)):
 
 
 @router.post("/api-keys")
-def create_api_key(data: ApiKeyCreate, user: dict = Depends(require_viewer)):
+def create_api_key(data: ApiKeyCreate, user: dict = Depends(require_interactive_user)):
     """Create an API key for YOURSELF. Returns the full token exactly once.
 
     Self-service: any logged-in (non-demo) user can mint keys, because a key
@@ -975,7 +1085,7 @@ def create_api_key(data: ApiKeyCreate, user: dict = Depends(require_viewer)):
 
 
 @router.post("/api-keys/{key_id}/revoke")
-def revoke_api_key(key_id: str, user: dict = Depends(require_viewer)):
+def revoke_api_key(key_id: str, user: dict = Depends(require_interactive_user)):
     """Revoke (soft-disable) an API key. Owner or admin."""
     db = get_db()
     key = _get_key_or_404(db, key_id)
@@ -986,7 +1096,7 @@ def revoke_api_key(key_id: str, user: dict = Depends(require_viewer)):
 
 
 @router.delete("/api-keys/{key_id}")
-def delete_api_key(key_id: str, user: dict = Depends(require_viewer)):
+def delete_api_key(key_id: str, user: dict = Depends(require_interactive_user)):
     """Hard-delete a REVOKED API key. Owner or admin.
 
     Two-step by design: a live key must be revoked first (409 otherwise), so a