Acceso

"Es una pequeña utilidad bastante ingeniosa." — yo

De vez en cuando, hay que recordarle a un agente que esto existe.

Todo lo que hay debajo de esta línea fue redactado por los bots.

Un token Bearer, todos tus servicios.

Acceso proporciona a los agentes y scripts un acceso seguro a servicios respaldados por OAuth y claves de API sin manejar las credenciales directamente. Almacena tus secretos, renueva tokens automáticamente, realiza peticiones proxy, audita todo — a través de una interfaz estable sobre HTTP y 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]

Qué hace

Colocas cada credencial en él: claves de API, tokens de OAuth, tokens de bot, credenciales de agente, secretos de servicio, lo que sea que tus agentes y scripts necesiten. Luego decides quién obtiene qué.

• Permisos por agente y por flota — cada agente o grupo obtiene su propio token con acceso limitado. Los agentes de programación ven GitHub y Linear. Los agentes de comunicaciones ven Gmail y Slack. Los agentes de operaciones ven AWS. Gestionado desde la interfaz de administración: sin archivos de configuración, sin malabares con la CLI.

• Almacena todo cifrado — claves de API, tokens de OAuth, tokens de bot, credenciales de agente a agente, secretos de servicio. AES-256-GCM en reposo, tokens de acceso con hash HMAC.

• Gestiona OAuth — renovación de tokens, flujos de consentimiento, Google multi-cuenta: tu agente nunca participa.

• Realiza llamadas a la API como proxy — para servicios con adaptadores, los agentes acceden a Acceso y reciben JSON de vuelta sin ver nunca la clave subyacente.

• Sirve credenciales directamente — para todo lo demás, los agentes obtienen las claves a través de /bootstrap o /secrets/by-env/LO_QUE_SEA.

• Registra todo — cada acceso a secretos, cada llamada a la API, cada intento de autenticación, con actor e IP.

• Inicia sesiones (Bootstraps) — una llamada a /bootstrap le da a un agente solo lo que está autorizado a ver: variables de entorno, documentos y contexto.

El camino feliz: El agente envía el token Bearer → Acceso gestiona la autenticación, renovación y proxy → El agente recibe JSON o un paquete de inicio. Eso es todo.

Cómo se ve

Panel de control — servicios, claves, agentes e historial de auditoría de un vistazo:

Permisos de agente — cada agente obtiene su propio token con concesiones de acceso limitadas:

Detalle del agente — nivel de confianza, prefijo del token, última vez utilizado y recuento de concesiones:

Ejemplo de 30 segundos

# 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"

Con MCP, tu agente obtiene herramientas como gmail_search, calendar_list, drive_list: sin configuración por servicio, sin tokens caducados, sin gestión de credenciales.

Para quién es esto

Buen ajuste:

• Ejecutar agentes de IA (Claude Code, Cursor, Gemini CLI, Codex) en múltiples sesiones o máquinas.

• Configuraciones multi-agente donde los agentes necesitan credenciales para otros agentes, bots y servicios internos.

• Configuraciones autohospedadas para uso personal o de equipos pequeños.

• Flujos de trabajo multi-servicio donde los agentes necesitan Gmail, Slack, GitHub, etc.

• Cualquiera que esté cansado de iniciar sesiones de agentes con archivos .env dispersos.

No es un buen ajuste:

• Gestión de secretos empresarial con requisitos de cumplimiento (usa HashiCorp Vault).

• Infraestructura de alto cumplimiento con requisitos de KMS/HSM.

• Control de acceso para equipos grandes o multi-inquilino (multi-tenant).

En qué se diferencia de un gestor de contraseñas: 1Password almacena credenciales para que los humanos las copien y peguen. Acceso almacena credenciales y las utiliza: realizando llamadas a la API como proxy, renovando tokens de OAuth, iniciando sesiones de agentes. Tu agente nunca ve la clave sin procesar para los servicios proxy.

Postura de seguridad

Contra qué protege Acceso:

• Agentes que ven o almacenan credenciales sin procesar.

• Tokens de OAuth caducados que interrumpen las sesiones de los agentes.

• Acceso a credenciales no auditado entre máquinas.

• Secretos en texto plano en bases de datos (cifrado AES-256-GCM en reposo).

• Adivinación de tokens por fuerza bruta (hash HMAC-SHA256, comparación de tiempo constante).

Contra qué no protege Acceso:

• Una instancia de Acceso comprometida (si alguien obtiene tu servidor, obtiene todo).

• Gestión de claves de grado en la nube (aún no hay integración con KMS/HSM: ver hoja de ruta).

• Aislamiento multi-inquilino (este es un sistema de un solo propietario).

• Ataques a nivel de red (despliega detrás de HTTPS, usa un firewall).

¿Por qué no usar simplemente archivos .env?

• Los tokens de OAuth caducan. Los tokens de acceso de Google duran 60 minutos. Tu agente no puede renovarlos; Acceso sí puede.

• Las credenciales se dispersan. Cada sesión de agente necesita su propia copia. Rotas una clave y tienes que actualizarla en 6 lugares.

• Sin rastro de auditoría. ¿Qué agente accedió a qué servicio? ¿Cuándo? ¿Desde dónde? Ni idea.

• El inicio de sesión es doloroso. Cada sesión nueva comienza cargando variables de entorno y esperando que nada haya caducado.

Soluciones existentes (y dónde encaja Acceso)

Existen herramientas reales para partes de este problema. La mayoría resuelve una parte:

• Gestores de secretos (1Password CLI, Doppler, Infisical) — inyectan secretos estáticos en tiempo de ejecución mediante op run / doppler run. Geniales para claves de API. No gestionan la renovación de OAuth ni el proxy de API.

• Identidad de carga de trabajo / OIDC (GitHub Actions OIDC) — evitan secretos de larga duración por completo al probar la identidad para credenciales de corta duración. Genial para CI/CD. No ayuda con las sesiones de agentes locales.

• Secretos dinámicos (Vault dynamic secrets) — crean credenciales con límite de tiempo bajo demanda. Infraestructura seria. Excesivo para la mayoría de las configuraciones de agentes.

• Brokers de OAuth (Nango, Composio) — gestionan la autorización de OAuth, el almacenamiento de tokens y la renovación. Plataformas centradas en la nube con sus propios paneles y facturación.

Las organizaciones maduras dividen el problema entre Vault + OIDC + brokers de OAuth + herramientas de plataforma interna. Los equipos más pequeños usan 1Password/Doppler para secretos estáticos y siguen sufriendo con OAuth.

Acceso colapsa estas capas en una sola aplicación autohospedada: almacena credenciales, renueva OAuth, realiza llamadas a la API como proxy, inicia sesiones de agentes, audita todo. Es menos seguro que Vault + KMS, pero es una sola cosa en lugar de cuatro, y realmente funciona.

Inicio rápido

Requisitos previos

• Node.js 20+

• PostgreSQL (o usa el Docker Compose incluido)

• Una aplicación OAuth de Google Cloud (si deseas proxy de API de Google)

1. Clonar e instalar

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

2. Configurar la base de datos

# 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. Configurar el entorno

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

Edita .env con tus valores. Como mínimo necesitas:

• DATABASE_URL / DIRECT_DATABASE_URL

• SECRET_ENCRYPTION_KEY

• NEXTAUTH_SECRET

• OWNER_EMAILS (lista separada por comas de correos electrónicos permitidos para iniciar sesión)

• Un proveedor de autenticación (Google OAuth, enlace mágico por correo electrónico o contraseña de propietario)

4. Ejecutar migraciones y seed

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

5. Iniciar la aplicación

npm run dev

Visita http://localhost:3000 e inicia sesión con un correo electrónico de tu lista OWNER_EMAILS.

6. Instalar habilidad de agente + configuración MCP

bash scripts/install.sh

Esto detecta tus arneses de agente instalados (Claude Code, Cursor, Gemini CLI, Windsurf, VS Code, Codex), instala la habilidad de verificación de estado y te muestra la configuración MCP para cada uno. Puedes aceptar o rechazar cada paso.

Servicios compatibles

27 puntos finales de servicio a través de /api/v1/*. Cada adaptador gestiona la autenticación y realiza peticiones proxy al upstream.

Google Workspace (OAuth 2.0, multi-cuenta) — Gmail, Calendar, Drive, Sheets, Docs, Contacts, Analytics, Search Console, Tag Manager, Admin Reports, Profile

Herramientas de desarrollador — GitHub, GitLab, Linear, Jira, Notion, Sentry, Vercel

Negocios — HubSpot, Slack, Stripe (solo lectura), Apollo.io, Cal.com

Infraestructura — AWS (S3, EC2, Lambda, CloudWatch — dependencias SDK opcionales), Cloudflare

Otros — Oura Ring, Porkbun

Los servicios de Google admiten múltiples cuentas: configúralas a través de la variable de entorno GOOGLE_ACCOUNTS (ej. work:me@company.com,personal:me@gmail.com). Agregar un nuevo adaptador toma unas 100 líneas: ver Agregar un nuevo servicio.

Puntos finales principales

Estos no son proxies de servicio, son el propio Acceso:

Autenticación

Acceso admite tres tipos de tokens para la autenticación de agentes:

Permisos por agente o flota

Los tokens de consumidor te permiten segmentar el acceso por rol. Cada consumidor obtiene su propia identidad, token y concesiones limitadas:

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

Las concesiones funcionan en dos niveles: servicio completo (el agente ve todo en ese servicio) o secretos individuales (el agente ve solo claves específicas). Cuando un agente llama a /bootstrap, solo recibe lo que está autorizado a ver.

# 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"

La autenticación humana para la interfaz de administración utiliza Google OAuth, enlaces mágicos por correo electrónico o una contraseña simple, configurada a través de variables de entorno. Solo los correos electrónicos en OWNER_EMAILS pueden iniciar sesión.

Agregar un nuevo servicio

Cada adaptador de proxy es un manejador de ruta de Next.js en src/app/api/v1/<servicio>/route.ts. Para agregar uno:

1. Crea src/app/api/v1/tu-servicio/route.ts

2. Usa authenticateRequestActor() de @/lib/access para la autenticación

3. Lee la clave de API del almacén cifrado (a través de Prisma) o variables de entorno

4. Realiza la petición proxy a la API upstream

5. Devuelve el resultado

La mayoría de los adaptadores tienen menos de 100 líneas. Mira src/app/api/v1/hubspot/route.ts para un ejemplo limpio.

Instrucciones para agentes

AGENTS.md en este repositorio tiene dos secciones:

1. Para agentes que desarrollan en Acceso — arquitectura, patrones, modelo de datos, comandos

2. Para agentes que usan Acceso — un bloque listo para copiar para tu CLAUDE.md o instrucciones de agente que le dice a tus agentes cómo iniciar sesión, extraer credenciales y usar puntos finales proxy

Copia la sección "Para agentes que USAN Acceso" en el archivo de instrucciones de tu agente y establece ACCESS_BASE_URL y ACCESS_TOKEN en tu entorno.

Servidor MCP

Acceso incluye un servidor MCP (mcp-server.mjs) que expone herramientas de Google Workspace a través del transporte stdio. Funciona con cualquier cliente compatible con MCP.

Agrega la siguiente configuración a tu cliente. El JSON es el mismo, solo cambia la ruta del archivo por cliente:

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

Nota de VS Code: Usa "servers" como clave de nivel superior en lugar de "mcpServers".

Una vez conectado, tu agente obtiene herramientas como gmail_search, calendar_list, drive_list, contacts_search y más, todo autenticado a través de Acceso.

API directa (Sin MCP)

No necesitas MCP. Cualquier cliente HTTP funciona:

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

Arquitectura

Cómo fluye una solicitud

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

Principios de diseño

• Los agentes nunca ven las credenciales. Envían un token Bearer, obtienen resultados de la API.

• OAuth se maneja en el lado del servidor. Renovación de tokens, flujos de consentimiento, gestión multi-cuenta: todo dentro de Acceso