Access

"꽤 괜찮은 작은 유틸리티입니다." — me

가끔씩 에이전트에게 이 도구의 존재를 상기시켜 줄 필요가 있습니다.

이 줄 아래의 모든 내용은 봇이 작성했습니다.

하나의 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을 봅니다. 관리자 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 프록시는 처리하지 않습니다.

• 워크로드 ID / OIDC (GitHub Actions OIDC) — 단기 자격 증명에 대한 ID를 증명하여 장기 비밀 정보를 피합니다. CI/CD에는 좋지만 로컬 에이전트 세션에는 도움이 되지 않습니다.

• 동적 비밀 정보 (Vault dynamic secrets) — 필요할 때 시간 제한 자격 증명을 생성합니다. 본격적인 인프라 도구이며 대부분의 에이전트 설정에는 과합니다.

• OAuth 브로커 (Nango, Composio) — OAuth 인증, 토큰 저장 및 갱신을 처리합니다. 자체 대시보드와 과금 체계를 가진 클라우드 우선 플랫폼입니다.

성숙한 조직은 Vault + OIDC + OAuth 브로커 + 내부 플랫폼 도구로 문제를 분할합니다. 소규모 팀은 정적 비밀 정보에 1Password/Doppler를 사용하면서 OAuth 문제로 고통받습니다.

Access는 이러한 계층을 하나의 자체 호스팅 앱으로 통합합니다. 자격 증명 저장, OAuth 갱신, API 호출 프록시, 에이전트 세션 부트스트랩, 모든 활동 감사를 수행합니다. Vault + KMS보다는 덜 안전할 수 있지만, 4개의 도구 대신 하나만 사용하면 되며 실제로 작동합니다.

빠른 시작

사전 요구 사항

• 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는 에이전트 인증을 위해 세 가지 토큰 유형을 지원합니다:

에이전트 또는 플릿별 권한 부여

소비자 토큰을 사용하면 역할별로 액세스를 분할할 수 있습니다. 각 소비자는 고유한 ID, 토큰 및 범위가 지정된 권한을 가집니다:

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는 stdio 전송을 통해