Skip to content
Nexus

Security

Understand Nexus credential planes, tenant isolation, secret handling, logging boundaries, and rotation policy.

Updated View as Markdown
Audience: operatorPlane: operationsAuth: noneStatus: beta

Outcome

为每个 Nexus 凭证选择正确的持有者、存储位置和轮换动作，并验证一次请求不会跨 Workspace 解析连接或把上游 Secret 暴露给最终用户。

Credential and request boundary

Provider boundary

  1. Developer Provider Secret

    Written by the platform developer; never delivered to the application user.

  2. Encrypted ProviderConnection

    Stores one explicit upstream capability inside a Workspace.

Admin Plane

  1. Application Backend

    Uses a Management Key to configure resources and provision users.

  2. Nexus Admin API

    Creates User, WorkspaceAccess and QuotaPeriod.

  3. Inference Key

    Returned once and delivered to the trusted user client.

Data Plane

  1. User SDK or Agent

    Sends the Inference Key and an explicit connection UUID.

  2. Nexus Gateway

    Resolves Access and commits a Quota Reservation in PostgreSQL.

  3. Workspace ProviderConnection

    Supplies the selected Base URL and decrypted short-lived credential.

  4. Model Provider

    Receives the original provider path, model and payload.

Provider Secret 不到达最终用户；Admin Plane 管理配置与生命周期；Data Plane 只有在 PostgreSQL 中的 Access、Quota 和 Workspace-scoped ProviderConnection 校验全部成功后才调用 Provider。

Credential model

Credential Plane Authentication Audience Stored by Never send to
Provider Secret Provider boundary Upstream-specific Nexus server only Encrypted ProviderConnection secret store User SDK、Console bundle、日志
Management Key Admin Bearer Management Key Application backend Server Secret Manager Browser/mobile、Gateway
Inference Key Data Bearer Inference Key User agent / server SDK Better Auth hash + ApiKeyBinding Admin API、Provider
Console Session Admin Better Auth Session Human operator Browser secure session Provider、Gateway Authorization

Management 与 Inference Key 使用不同的 configId、Scope、前缀和验证入口。Management Key 不能调用 /providers/*，Inference Key 不能调用 /admin/v1/*。

Provider secret storage

Provider Secret 写入后只保留加密值和安全预览。服务端仅在 Provider 调用边界短时解密，用它替换客户端的 Nexus Authorization；创建、读取、Usage、Audit 和错误响应都不返回明文。

.env.example 的本地加密 Key 是一次性开发值。共享、预发布和生产环境必须使用独立的高熵 Better Auth Secret、Provider Secret 加密 Key/外部 Resolver 和数据库凭证；不得复制本地默认值。

Workspace isolation

一个推理请求按以下顺序解析：

Inference Key
→ ApiKeyBinding
→ WorkspaceAccess
→ Workspace
→ (workspaceId, providerConnectionId)
→ ACTIVE ProviderConnection

providerConnectionId 是服务生成、创建后不可变的 UUID。即使另一个 Workspace 的 UUID 真实存在，也必须返回不暴露跨租户存在性的 provider_connection_not_found；客户端不能在 URL、Header 或 Body 提交任意上游 Host。

SSRF and transport boundary

  • 保存的 Provider Base URL 必须是安全的 HTTP(S) URL，不能包含凭证、Query 或 Fragment。
  • Gateway 路径必须匹配 /providers/{providerConnectionId}/{providerPath...}；包含绝对 URL 或不安全引用的后缀返回 unsafe_provider_path。
  • Gateway 消费 Nexus Authorization，并为上游重新建立 Provider 认证；客户端认证 Header 不透明转发。
  • Provider Response Header 仍受代理安全策略约束；不要把 Provider Cookie 当作 Nexus Session。

Logging and request bodies

默认诊断键是 x-nexus-request-id、Invocation ID、WorkspaceAccess ID 和 ProviderConnection ID。不要记录以下内容：

  • Provider Secret、Management Key、Inference Key 或完整 Authorization Header。
  • Secret 解密结果、Webhook Signing Secret 或数据库连接密码。
  • 未经产品数据政策允许的完整 Prompt、Completion、Tool Arguments 和文件内容。

Usage/Audit 应记录模型名、Token、Quota Units、状态、延迟和资源归因等必要事实，不应成为敏感正文的旁路存储。

Rotation

Event Safe action Preserved state
Provider Key scheduled rotation 在同一 ProviderConnection 上 Rotate，验证后撤销旧上游 Key UUID、Base URL、用户 Key、Usage
Inference Key scheduled rotation 先签发新 Key、切流、验证，再撤销旧 Key Access、Plan、QuotaPeriod、历史 Usage
Management Key compromise 从后端 Secret Store 移除并撤销，审计 Admin 操作 用户 Access/Quota 不应被重建
Provider Secret compromise 轮换上游与 Nexus 保存值，审查相关 Provider Attempts 不向用户分发 Provider Secret

使用 Provider Secret rotation 和 Inference Key rotation 的可执行流程。

Browser and mobile restrictions

MVP 长期 Inference Key 适合受控服务端 SDK，不适合公开 Browser Bundle、localStorage 或可逆向的移动应用。短期 Data Token 是未来的单独凭证类型；在该能力可用前，让你的应用后端持有长期 Key 并代理受权请求。任何 VITE_* 环境变量都会进入公开 Console Bundle，不能存放 Secret。

Security FAQ

Can an inference key choose an arbitrary provider host?

不能。Key 先确定 Workspace，URL UUID 只能选择该 Workspace 中已经保存且 ACTIVE 的 ProviderConnection。

Does rotating a key reset quota?

不能。Quota 属于 WorkspaceAccess 的当前 QuotaPeriod，不属于 Better Auth API Key。

Is Quota a wallet or money balance?

不是。Quota Unit 只表达 AI 使用权；Nexus MVP 不提供 Wallet、Ledger 或模型定价。

What should I attach to an incident?

提供时间范围、部署 Adapter、x-nexus-request-id、Workspace/Access/Connection 资源 ID 和已脱敏的错误码。不要附任何 Key 或 Secret。

Check your work

  • Secret scan 不发现真实凭证，生产配置没有复用 .env.example 默认值。
  • Management 与 Inference Key 交叉调用均被拒绝。
  • 跨 Workspace ProviderConnection UUID 不会解析成功。
  • 错误、Usage、Audit 和应用日志中没有 Provider Secret 或 Authorization 明文。
Navigation

Type to search…

↑↓ navigate↵ selectEsc close