Access

“这是一个相当精巧的小工具。” — 我

偶尔，需要提醒一下代理这个工具的存在。

以下所有内容均由机器人起草。

一个 Bearer 令牌，管理所有服务。

Access 为代理和脚本提供对 OAuth 和 API 密钥支持服务的安全访问，无需直接处理凭据。存储您的密钥、自动刷新令牌、代理请求、审计一切——通过 HTTP 和 MCP 上的一个稳定接口。

flowchart LR
    A[Any MCP client\nor HTTP caller] -->|Bearer token| B["Access\n(Next.js + Postgres)"]
    B -->|OAuth 2.0| C[Google · GitHub · Sentry · Oura]
    B -->|API key| D[HubSpot · Linear · Jira · Stripe\nNotion · Apollo · Cal · Porkbun]
    B -->|Token| E[Slack · Cloudflare · Vercel\nGitLab · AWS]

它能做什么

您可以将所有凭据放入其中——API 密钥、OAuth 令牌、机器人令牌、代理凭据、服务密钥，以及您的代理和脚本所需的任何内容。然后由您决定谁能获得什么。

• 按代理和按集群分配权限 — 每个代理或组都有自己的令牌，具有作用域访问权限。编码代理可以访问 GitHub 和 Linear。通信代理可以访问 Gmail 和 Slack。运维代理可以访问 AWS。通过管理 UI 进行管理——无需配置文件，无需摆弄 CLI。

• 加密存储一切 — API 密钥、OAuth 令牌、机器人令牌、代理间凭据、服务密钥。静态存储采用 AES-256-GCM，访问令牌采用 HMAC 哈希。

• 处理 OAuth — 令牌刷新、授权流程、多账户 Google — 您的代理无需参与。

• 代理 API 调用 — 对于带有适配器的服务，代理访问 Access 并获取 JSON 返回，而无需看到底层的密钥。

• 直接提供凭据 — 对于其他所有内容，代理通过 /bootstrap 或 /secrets/by-env/WHATEVER 获取密钥。

• 记录一切 — 每次密钥访问、每次 API 调用、每次身份验证尝试，都会记录操作者和 IP。

• 引导会话 — 一次 /bootstrap 调用仅向代理提供其被授权查看的内容——环境变量、文档和上下文。

理想路径： 代理发送 Bearer 令牌 → Access 处理身份验证、刷新和代理 → 代理获取 JSON 或引导包。就是这样。

它看起来是什么样

仪表板 — 一目了然地查看服务、密钥、代理和审计历史：

代理权限分配 — 每个代理都有自己的令牌，具有作用域访问授权：

代理详情 — 信任级别、令牌前缀、最后使用时间和授权计数：

30 秒示例

# Set once per session (don't paste tokens directly in commands)
export TOKEN="your-token"
export ACCESS="https://your-access-instance"

# Your agent searches Gmail through Access
curl -H "Authorization: Bearer $TOKEN" "$ACCESS/api/v1/google/gmail?action=search&q=from:alice&account=work"

# Or bootstraps an entire session in one call
curl -H "Authorization: Bearer $TOKEN" "$ACCESS/api/v1/bootstrap"

通过 MCP，您的代理可以获得诸如 gmail_search、calendar_list、drive_list 等工具——无需针对每个服务进行配置，没有过期的令牌，无需凭据管理。

适用人群

适用场景：

• 在多个会话或机器上运行 AI 代理（Claude Code、Cursor、Gemini CLI、Codex）

• 多代理设置，其中代理需要其他代理、机器人和内部服务的凭据

• 自托管的个人或小型团队设置

• 多服务工作流，其中代理需要 Gmail、Slack、GitHub 等

• 厌倦了用分散的 .env 文件引导代理会话的任何人

不适用场景：

• 有合规性要求的企业级密钥管理（请使用 HashiCorp Vault）

• 有 KMS/HSM 要求的高合规性基础设施

• 大型团队 IAM 或多租户访问控制

它与密码管理器的区别： 1Password 存储凭据供人类复制粘贴。Access 存储凭据并使用它们——代理 API 调用、刷新 OAuth 令牌、引导代理会话。您的代理永远看不到代理服务的原始密钥。

安全态势

Access 防御的内容：

• 代理查看或存储原始凭据

• 过期的 OAuth 令牌导致代理会话中断

• 跨机器未经审计的凭据访问

• 数据库中的明文密钥（静态存储采用 AES-256-GCM 加密）

• 暴力破解令牌猜测（HMAC-SHA256 哈希，恒定时间比较）

Access 不防御的内容：

• 被入侵的 Access 实例（如果有人获得了您的服务器，他们就获得了一切）

• 云级密钥管理（尚无 KMS/HSM 集成——请参阅路线图）

• 多租户隔离（这是一个单所有者系统）

• 网络级攻击（部署在 HTTPS 之后，使用防火墙）

为什么不直接使用 .env 文件？

• OAuth 令牌会过期。 Google 访问令牌有效期为 60 分钟。您的代理无法刷新它们——但 Access 可以。

• 凭据分散。 每个代理会话都需要自己的副本。轮换一个密钥，您就得在 6 个地方更新它。

• 没有审计追踪。 哪个代理访问了哪个服务？什么时候？从哪里？完全不知道。

• 引导很痛苦。 每个新会话都从加载环境变量开始，并祈祷没有东西过期。

现有解决方案（以及 Access 的定位）

针对此问题的部分内容已有成熟工具。大多数只解决其中一小部分：

• 密钥管理器 (1Password CLI, Doppler, Infisical) — 通过 op run / doppler run 在运行时注入静态密钥。非常适合 API 密钥。不处理 OAuth 刷新或 API 代理。

• 工作负载身份 / OIDC (GitHub Actions OIDC) — 通过证明身份来获取短期凭据，从而完全避免长期密钥。非常适合 CI/CD。对本地代理会话没有帮助。

• 动态密钥 (Vault dynamic secrets) — 按需生成有时限的凭据。严肃的基础设施。对于大多数代理设置来说过于复杂。

• OAuth 代理 (Nango, Composio) — 处理 OAuth 授权、令牌存储和刷新。具有自己的仪表板和计费的云原生平台。

成熟的组织将问题拆分到 Vault + OIDC + OAuth 代理 + 内部平台工具中。小型团队使用 1Password/Doppler 处理静态密钥，但在 OAuth 上仍然很痛苦。

Access 将这些层合并为一个自托管应用程序：存储凭据、刷新 OAuth、代理 API 调用、引导代理会话、审计一切。它不如 Vault + KMS 安全，但它是一个整体而不是四个——而且它确实能用。

快速入门

先决条件

• Node.js 20+

• PostgreSQL（或使用随附的 Docker Compose）

• Google Cloud OAuth 应用（如果您需要 Google API 代理）

1. 克隆并安装

git clone https://github.com/Scottpedia0/access.git
cd access
npm install

2. 设置数据库

# Option A: Use Docker Compose
docker compose up -d

# Option B: Use your own Postgres
# Set DATABASE_URL and DIRECT_DATABASE_URL in .env

3. 配置环境变量

cp .env.example .env

# Generate required secrets
openssl rand -base64 32  # -> SECRET_ENCRYPTION_KEY
openssl rand -base64 32  # -> NEXTAUTH_SECRET
openssl rand -base64 32  # -> CONSUMER_TOKEN_HASH_SECRET

使用您的值编辑 .env。至少需要：

• DATABASE_URL / DIRECT_DATABASE_URL

• SECRET_ENCRYPTION_KEY

• NEXTAUTH_SECRET

• OWNER_EMAILS（允许登录的电子邮件列表，以逗号分隔）

• 一个身份验证提供程序（Google OAuth、电子邮件魔法链接或所有者密码）

4. 运行迁移和种子数据

npx prisma migrate deploy
npm run db:seed  # Creates example services and a consumer token

5. 启动应用

npm run dev

访问 http://localhost:3000 并使用 OWNER_EMAILS 列表中的电子邮件登录。

6. 安装代理技能 + MCP 配置

bash scripts/install.sh

这将检测您安装的代理工具（Claude Code、Cursor、Gemini CLI、Windsurf、VS Code、Codex），安装健康检查技能，并为您显示每个工具的 MCP 配置。您可以接受或拒绝每一步。

支持的服务

/api/v1/* 下有 27 个服务端点。每个适配器处理身份验证并将请求代理到上游。

Google Workspace (OAuth 2.0, 多账户) — Gmail, Calendar, Drive, Sheets, Docs, Contacts, Analytics, Search Console, Tag Manager, Admin Reports, Profile

开发者工具 — GitHub, GitLab, Linear, Jira, Notion, Sentry, Vercel

商业 — HubSpot, Slack, Stripe (只读), Apollo.io, Cal.com

基础设施 — AWS (S3, EC2, Lambda, CloudWatch — 可选 SDK 依赖), Cloudflare

其他 — Oura Ring, Porkbun

Google 服务支持多账户——通过 GOOGLE_ACCOUNTS 环境变量配置（例如 work:me@company.com,personal:me@gmail.com）。添加新适配器大约需要 100 行代码——请参阅 添加新服务。

核心端点

这些不是服务代理——它们是 Access 本身：

身份验证

Access 支持三种用于代理身份验证的令牌类型：

按代理或集群分配权限

消费者令牌允许您按角色细分访问权限。每个消费者都有自己的身份、令牌和作用域授权：

Coding agents (Claude Code, Cursor)  →  GitHub, Linear, Sentry
Comms agents                         →  Gmail, Slack, Calendar
Ops agents                           →  AWS, Cloudflare, Vercel
Intake-only (team members)           →  Write keys, can't read anything

授权在两个级别上工作——整个服务（代理可以看到该服务中的所有内容）或单个密钥（代理只能看到特定密钥）。当代理调用 /bootstrap 时，它只会收到它被授权查看的内容。

# Search Gmail with a global token
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "http://localhost:3000/api/v1/google/gmail?action=search&q=from:alice&account=work"

# Bootstrap an agent session — pull only what this token is authorized for
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "http://localhost:3000/api/v1/bootstrap"

管理 UI 的人类身份验证使用 Google OAuth、电子邮件魔法链接或简单的密码——通过环境变量配置。只有 OWNER_EMAILS 中的电子邮件才能登录。

添加新服务

每个代理适配器都是 src/app/api/v1/<service>/route.ts 下的一个 Next.js 路由处理程序。要添加一个：

1. 创建 src/app/api/v1/your-service/route.ts

2. 使用 @/lib/access 中的 authenticateRequestActor() 进行身份验证

3. 从加密存储（通过 Prisma）或环境变量中读取 API 密钥

4. 将请求代理到上游 API

5. 返回结果

大多数适配器不到 100 行。请参阅 src/app/api/v1/hubspot/route.ts 获取清晰示例。

代理指令

此仓库中的 AGENTS.md 有两个部分：

1. 针对在 Access 上开发的代理 — 架构、模式、数据模型、命令

2. 针对使用 Access 的代理 — 一个可直接粘贴到您的 CLAUDE.md 或代理指令中的块，告诉您的代理如何引导、拉取凭据以及使用代理端点

将“针对使用 Access 的代理”部分复制到您的代理指令文件中，并在您的环境中设置 ACCESS_BASE_URL 和 ACCESS_TOKEN。

MCP 服务器

Access 包含一个 MCP 服务器 (mcp-server.mjs)，通过 stdio 传输公开 Google Workspace 工具。适用于任何兼容 MCP 的客户端。

将以下配置添加到您的客户端。JSON 是相同的——只有文件路径因客户端而异：

{
  "mcpServers": {
    "access": {
      "command": "node",
      "args": ["/path/to/access/mcp-server.mjs"],
      "env": {
        "ACCESS_BASE_URL": "http://localhost:3000",
        "GLOBAL_AGENT_TOKEN": "your-token-here"
      }
    }
  }
}

VS Code 注意： 使用 "servers" 作为顶级键，而不是 "mcpServers"。

连接后，您的代理将获得诸如 gmail_search、calendar_list、drive_list、contacts_search 等工具——所有这些都通过 Access 进行身份验证。

直接 API (无 MCP)

您不需要 MCP。任何 HTTP 客户端都可以工作：

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:3000/api/v1/google/gmail?action=search&q=is:unread"

架构

请求流程

1. Agent sends:     GET /api/v1/google/gmail?action=search&q=from:alice&account=work
                    Authorization: Bearer amb_live_xxxx

2. Middleware:       Rate limit check → Body size check → Pass

3. Auth:            Validate Bearer token (HMAC comparison)
                    Look up consumer permissions or verify global token

4. Proxy:           Load OAuth credentials from Postgres (encrypted)
                    Refresh access token if expired
                    Forward request to Gmail API

5. Response:        Return Gmail results as JSON to agent
                    Log access in audit_events table

设计原则

• 代理永远看不到凭据。 它们发送 Bearer 令牌，获取 API 结果。

• OAuth 在服务器端处理。 令牌刷新、授权流程、多账户管理——都在 Access 内部。

• 一切皆可审计。 每次密钥访问、每次 API 代理调用、每次登录尝试都会记录操作者、时间戳和 IP。

• 密钥静态加密。 AES-256-GCM，带有版本化负载 (v2.iv.authTag.ciphertext)，支持密钥轮换。

• 消费者令牌使用 HMAC。 恒定时间比较，仅存储前缀——从不存储原始令牌。

• 无状态代理。 Access 不缓存或存储 API 响应。它是一个直通代理。

安全性

• 所有存储的密钥均采用 AES-256-GCM 加密

• HMAC-SHA256 消费者令牌哈希，具有恒定时间比较

• 所有 API 端点上的 Zod 输入验证

• 所有访问事件和身份验证失败的审计日志

• 管理 UI 访问的所有者电子邮件白名单

• 生产环境中的错误消息绝不会泄露上游详细信息

• 健康检查端点需要身份验证才能公开库存计数

• 身份验证和 API 端点上的速率限制（可配置，默认在内存中）

• 所有变异端点上的请求体大小限制

密钥轮换

Access 支持零停机加密密钥轮换：

# 1. Generate a new key
openssl rand -base64 32

# 2. Set the new key and keep the old one
SECRET_ENCRYPTION_KEY="<new key>"
SECRET_ENCRYPTION_KEY_PREVIOUS="<old key>"

# 3. Re-encrypt all secrets
npx tsx scripts/rotate-keys.ts

# 4. After success, remove the old key
# unset SECRET_ENCRYPTION_KEY_PREVIOUS

该脚本是幂等的——当前密钥上已有的密钥会被跳过。它使用任何有效的密钥（当前或上一个）进行解密，并使用当前密钥重新加密。

安全路线图

• [ ] 按服务作用域令牌（