Skills
skills/incept5/eve-skillpacks/eve-auth-and-secrets

eve-auth-and-secrets

SKILL.md

Eve Auth and Secrets

Use this workflow to log in to Eve and manage secrets for your app.

When to Use

  • Setting up a new project profile
  • Authentication failures
  • Adding or rotating secrets
  • Secret interpolation errors during deploys
  • Setting up identity providers or org invites
  • Adding SSO login to an Eve-deployed app
  • Setting up access groups and scoped data-plane authorization
  • Configuring group-aware RLS for environment databases

Authentication

eve auth login
eve auth login --ttl 30                # custom token TTL (1-90 days)
eve auth status

Challenge-Response Flow

Eve uses challenge-response authentication. The default provider is github_ssh:

  1. Client sends SSH public key fingerprint
  2. Server returns a challenge (random bytes)
  3. Client signs the challenge with the private key
  4. Server verifies the signature and issues a JWT

Token Types

Type Issued Via Use Case
User Token eve auth login Interactive CLI sessions
Job Token Worker auto-issued Agent execution within jobs
Minted Token eve auth mint Bot/service accounts

JWT payloads include sub (user ID), org_id, scope, and exp. Verify tokens via the JWKS endpoint: GET /auth/jwks.

Role and org membership changes take effect immediately -- the server resolves permissions from live DB memberships, not stale JWT claims. When a request includes a project_id but no org_id, the permission guard derives the org context from the project's owning org.

Permissions

Check what the current token can do:

eve auth permissions

Register additional identities for multi-provider access:

curl -X POST "$EVE_API_URL/auth/identities" -H "Authorization: Bearer $TOKEN" \
  -d '{"provider": "nostr", "external_id": "<pubkey>"}'

Identity Providers

Eve supports pluggable identity providers. The auth guard tries Bearer JWT first, then provider-specific request auth.

Provider Auth Method Use Case
github_ssh SSH challenge-response Default CLI login
nostr NIP-98 request auth + challenge-response Nostr-native users

Nostr Authentication

Two paths:

  • Challenge-response: Like SSH but signs with Nostr key. Use eve auth login --provider nostr.
  • NIP-98 request auth: Every API request signed with a Kind 27235 event. Stateless, no stored token.

Org Invites

Invite external users via the CLI or API:

# Invite with SSH key registration (registers key so the user can log in immediately)
eve admin invite --email user@example.com --ssh-key ~/.ssh/id_ed25519.pub --org org_xxx

# Invite with GitHub identity
eve admin invite --email user@example.com --github ghuser --org org_xxx

# Invite with web-based auth (Supabase)
eve admin invite --email user@example.com --web --org org_xxx

# API: invite targeting a Nostr pubkey
curl -X POST "$EVE_API_URL/auth/invites" -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"org_id": "org_xxx", "role": "member", "provider_hint": "nostr", "identity_hint": "<pubkey>"}'

If no auth method is specified (--github, --ssh-key, or --web), the CLI warns that the user will not be able to log in. The user can self-register later via eve auth request-access --org "Org Name" --ssh-key ~/.ssh/id_ed25519.pub --wait.

When the identity authenticates, Eve auto-provisions their account and org membership.

Token Minting (Admin)

Mint tokens for bot/service users without SSH login:

# Mint token for a bot user (creates user + membership if needed)
eve auth mint --email app-bot@example.com --org org_xxx

# With custom TTL (1-90 days, default: server configured)
eve auth mint --email app-bot@example.com --org org_xxx --ttl 90

# Scope to project with admin role
eve auth mint --email app-bot@example.com --project proj_xxx --role admin

Print the current access token (useful for scripts):

eve auth token

Self-Service Access Requests

Users without an invite can request access:

eve auth request-access --org "My Company" --email you@example.com
eve auth request-access --org "My Company" --ssh-key ~/.ssh/id_ed25519.pub
eve auth request-access --status <request_id>

Admins approve or reject via:

eve admin access-requests list
eve admin access-requests approve <request_id>
eve admin access-requests reject <request_id> --reason "..."

List responses use the canonical { "data": [...] } envelope.

Approval is atomic (single DB transaction) and idempotent -- re-approving a completed request returns the existing record. If the fingerprint is already registered, Eve reuses that identity owner. If a legacy partial org matches the requested slug and name, Eve reuses it during approval. Failed attempts never leave partial state.

Credential Check

Verify local AI tool credentials:

eve auth creds                # Show Claude + Codex cred status
eve auth creds --claude       # Only Claude
eve auth creds --codex        # Only Codex

Output includes token type (setup-token or oauth), preview, and expiry. Use this to confirm token health before syncing.

OAuth Token Sync

Sync local Claude/Codex OAuth tokens into Eve secrets so agents can use them. Scope precedence: project > org > user.

eve auth sync                       # Sync to user-level (default)
eve auth sync --org org_xxx         # Sync to org-level (shared across org projects)
eve auth sync --project proj_xxx    # Sync to project-level (scoped to one project)
eve auth sync --dry-run             # Preview without syncing

This sets CLAUDE_CODE_OAUTH_TOKEN / CLAUDE_OAUTH_REFRESH_TOKEN (Claude) and CODEX_AUTH_JSON_B64 (Codex/Code) at the requested scope.

Claude Token Types

Token Prefix Type Lifetime Recommendation
sk-ant-oat01-* setup-token (long-lived) Long-lived Preferred for jobs and automation
Other sk-ant-* oauth (short-lived) ~15 hours Use for interactive dev; regenerate with claude setup-token

eve auth sync warns when syncing a short-lived OAuth token. Run eve auth creds to inspect token type before syncing.

Automatic Codex/Code Token Write-Back

After each harness invocation, the worker checks if the Codex/Code CLI refreshed auth.json during the session. If the token changed, it is automatically written back to the originating secret scope (user/org/project) so the next job starts with a fresh token. This is transparent and non-fatal -- a write-back failure logs a warning but does not affect the job result.

For Codex/Code credentials, the sync picks the freshest token across ~/.codex/auth.json and ~/.code/auth.json by comparing tokens.expires_at.

Access Groups + Scoped Access

Groups are first-class authorization primitives that segment data-plane access (org filesystem, org docs, environment databases). Create groups, add members, and bind roles with scoped constraints:

# Create a group
eve access groups create --org org_xxx --slug eng-team --name "Engineering"

# Add members
eve access groups members add eng-team --org org_xxx --user user_abc
eve access groups members add eng-team --org org_xxx --service-principal sp_xxx

# Bind a role with scoped access
eve access bind --org org_xxx --group grp_xxx --role data-reader \
  --scope-json '{"orgfs":{"allow_prefixes":["/shared/"]},"envdb":{"schemas":["public"]}}'

# Check effective access
eve access memberships --org org_xxx --user user_abc

Scope Types

Resource Scope Fields Example
Org Filesystem orgfs.allow_prefixes, orgfs.read_only_prefixes "/shared/", "/reports/"
Org Documents orgdocs.allow_prefixes, orgdocs.read_only_prefixes "/pm/features/"
Environment DB envdb.schemas, envdb.tables "public", "analytics_*"

Group-Aware RLS

Scaffold RLS helper functions for group-based row-level security in environment databases:

eve db rls init --with-groups

This creates SQL helpers (app.current_user_id(), app.current_group_ids(), app.has_group()) that read session context set by Eve's runtime. Use them in RLS policies:

CREATE POLICY notes_group_read ON notes FOR SELECT
  USING (group_id = ANY(app.current_group_ids()));

Membership Introspection

Inspect a principal's full effective access -- base org/project roles, group memberships, resolved bindings, and merged scopes:

eve access memberships --org org_xxx --user user_abc
eve access memberships --org org_xxx --service-principal sp_xxx

The response includes effective_scopes (merged across all bindings), effective_permissions, and each binding's matched_via (direct or group).

Resource-Specific Access Checks

Check and explain access against a specific data-plane resource:

eve access can orgfs:read /shared/reports --org org_xxx
eve access explain orgfs:write /shared/reports --org org_xxx --user user_abc

The response includes scope_required, scope_matched, and per-grant scope_reason explaining why a binding did or did not match the requested resource path.

Policy-as-Code (v2)

Declare groups, roles, and scoped bindings in .eve/access.yaml. Use version: 2:

version: 2
access:
  groups:
    eng-team:
      name: Engineering Team
      description: Scoped access for engineering collaborators
      members:
        - type: user
          id: user_abc
  roles:
    app_editor:
      scope: org
      permissions:
        - orgdocs:read
        - orgdocs:write
        - orgfs:read
        - envdb:read
  bindings:
    - subject: { type: group, id: eng-team }
      roles: [app_editor]
      scope:
        orgdocs: { allow_prefixes: ["/groups/app/**"] }
        orgfs: { allow_prefixes: ["/groups/app/**"] }
        envdb: { schemas: ["app"] }

Validate, plan, and sync:

eve access validate --file .eve/access.yaml
eve access plan --file .eve/access.yaml --org org_xxx
eve access sync --file .eve/access.yaml --org org_xxx

Sync is declarative: it creates, updates, and prunes groups, members, roles, and bindings to match the YAML. Invalid scope configurations fail fast before any mutations are applied. Binding subjects can be user, service_principal, or group.

Key Rotation

Rotate the JWT signing key:

  1. Set EVE_AUTH_JWT_SECRET_NEW alongside the existing secret
  2. Server starts signing with the new key but accepts both during the grace period
  3. After grace period (EVE_AUTH_KEY_ROTATION_GRACE_HOURS), remove the old secret
  4. Emergency rotation: set only the new key (immediately invalidates all existing tokens)

App SSO Integration

Add Eve SSO login to any Eve-deployed app using two shared packages: @eve-horizon/auth (backend) and @eve-horizon/auth-react (frontend). The platform auto-injects EVE_SSO_URL, EVE_ORG_ID, and EVE_API_URL into deployed services.

Backend (@eve-horizon/auth)

Install: npm install @eve-horizon/auth

Three exports handle the full backend auth surface:

Export Behavior
eveUserAuth() Non-blocking middleware. Verifies RS256 token via JWKS, checks org membership, attaches req.eveUser: { id, email, orgId, role }. Passes through silently on missing/invalid tokens.
eveAuthGuard() Returns 401 if req.eveUser not set. Place on protected routes.
eveAuthConfig() Handler returning { sso_url, eve_api_url, ... } from auto-injected env vars. Frontend fetches this to discover SSO.

Additional exports for agent/service scenarios:

Export Behavior
eveAuthMiddleware() Blocking middleware for agent/job tokens. Attaches req.agent with full EveTokenClaims. Returns 401 on failure.
verifyEveToken(token) JWKS-based local verification (15-min cache). Returns EveTokenClaims.
verifyEveTokenRemote(token) HTTP verification via /auth/token/verify. Always current.

Express setup (~3 lines):

import { eveUserAuth, eveAuthGuard, eveAuthConfig, eveAuthMe } from '@eve-horizon/auth';

app.use(eveUserAuth());
app.get('/auth/config', eveAuthConfig());
app.get('/auth/me', eveAuthMe());               // Full response for React SDK
app.use('/api', eveAuthGuard());

NestJS setup -- apply eveUserAuth() globally in main.ts, then use a thin guard wrapper:

// main.ts
import { eveUserAuth } from '@eve-horizon/auth';
app.use(eveUserAuth());

// auth.guard.ts -- thin NestJS adapter
@Injectable()
export class EveGuard implements CanActivate {
  canActivate(ctx: ExecutionContext): boolean {
    const req = ctx.switchToHttp().getRequest();
    if (!req.eveUser) throw new UnauthorizedException();
    return true;
  }
}

// auth-config.controller.ts
@Controller()
export class AuthConfigController {
  private handler = eveAuthConfig();

  @Get('auth/config')
  getConfig(@Req() req, @Res() res) { this.handler(req, res); }
}

Verification strategies: eveUserAuth() defaults to 'local' (JWKS, cached 15 min). Use strategy: 'remote' for immediate membership freshness at ~50ms latency per request.

Custom role mapping: If your app needs roles beyond Eve's owner/admin/member, bridge after eveUserAuth():

app.use((req, _res, next) => {
  if (req.eveUser) {
    req.user = { ...req.eveUser, appRole: req.eveUser.role === 'member' ? 'viewer' : 'admin' };
  }
  next();
});

Frontend (@eve-horizon/auth-react)

Install: npm install @eve-horizon/auth-react

Export Purpose
EveAuthProvider Context provider. Bootstraps session: checks sessionStorage, probes SSO /session, caches tokens.
useEveAuth() Hook: { user, loading, error, config, loginWithSso, loginWithToken, logout }
EveLoginGate Renders children when authenticated, login form otherwise.
EveLoginForm Built-in SSO + token-paste login UI.
createEveClient(baseUrl?) Fetch wrapper with automatic Bearer injection.

Simple setup -- EveLoginGate handles the loading/login/authenticated states:

import { EveAuthProvider, EveLoginGate } from '@eve-horizon/auth-react';

<EveAuthProvider apiUrl="/api">
  <EveLoginGate>
    <ProtectedApp />
  </EveLoginGate>
</EveAuthProvider>

Custom auth gate -- use useEveAuth() for full control over loading, login, and error states:

import { EveAuthProvider, useEveAuth } from '@eve-horizon/auth-react';

function AuthGate() {
  const { user, loading, loginWithToken, loginWithSso, logout } = useEveAuth();
  if (loading) return <Spinner />;
  if (!user) return <LoginPage onSso={loginWithSso} onToken={loginWithToken} />;
  return <App user={user} onLogout={logout} />;
}

export default () => (
  <EveAuthProvider apiUrl="/api">
    <AuthGate />
  </EveAuthProvider>
);

API calls with auth: Use createEveClient() for automatic Bearer token injection:

import { createEveClient } from '@eve-horizon/auth-react';
const client = createEveClient('/api');
const res = await client.fetch('/data');

Migration from Custom Auth

The SDK replaces ~700-800 lines of hand-rolled auth with ~50 lines. Delete custom JWKS/token verification, Bearer extraction middleware, SSO URL discovery, session probe logic, token storage helpers, and login form. Keep app-specific role mapping and local password auth.

For the full migration checklist, types reference, token lifecycle, and advanced patterns (SSE auth, token paste mode, token staleness), see references/app-sso-integration.md.

Project Secrets

# Set a secret
eve secrets set API_KEY "your-api-key" --project proj_xxx

# List keys (no values)
eve secrets list --project proj_xxx

# Delete a secret
eve secrets delete API_KEY --project proj_xxx

# Import from file
eve secrets import .env --project proj_xxx

Secret Interpolation

Reference secrets in .eve/manifest.yaml using ${secret.KEY}:

services:
  api:
    environment:
      API_KEY: ${secret.API_KEY}

Manifest Validation

Validate that all required secrets are set before deploying:

eve manifest validate --validate-secrets    # check secret references
eve manifest validate --strict              # fail on missing secrets

Local Secrets File

For local development, create .eve/dev-secrets.yaml (gitignored):

secrets:
  default:
    API_KEY: local-dev-key
    DB_PASSWORD: local-password
  staging:
    DB_PASSWORD: staging-password

Worker Injection

At job execution time, resolved secrets are injected as environment variables into the worker container. File-type secrets are written to disk and referenced via EVE_SECRETS_FILE. The file is removed after the agent process reads it.

Git Auth

The worker uses secrets for repository access:

  • HTTPS: github_token secret → Authorization: Bearer header
  • SSH: ssh_key secret → written to ~/.ssh/ and used via GIT_SSH_COMMAND

Troubleshooting

Problem Fix
Not authenticated Run eve auth login
Token expired Re-run eve auth login (tokens auto-refresh if within 5 min of expiry)
Bootstrap already completed Use eve auth login (existing user) or eve admin invite (new users). On non-prod stacks, eve auth bootstrap auto-attempts server recovery. For wrong-email recovery: eve auth bootstrap --email correct@example.com
Secret missing Confirm with eve secrets list and set the key
Interpolation error Verify ${secret.KEY} spelling; run eve manifest validate --validate-secrets
Git clone failed Check github_token or ssh_key secret is set
Service can't reach API Verify EVE_API_URL is injected (check eve env show)
Scoped access denied Run eve access explain <permission> <resource> --org <org> to see scope match details. Check that the binding's scope constraints include the target path/schema
Wrong role shown Role is resolved from live DB memberships. Run eve auth permissions to see effective role. If multi-org, check eve auth status for per-org membership listing
Short-lived Claude token in jobs Run eve auth creds to check token type. If oauth (not setup-token), regenerate with claude setup-token then re-sync with eve auth sync
Codex token expired between jobs Automatic write-back should refresh it. If not, re-run eve auth sync. Check that ~/.codex/auth.json or ~/.code/auth.json has a fresh token
App SSO not working Verify EVE_SSO_URL is injected (eve env show). For local dev, set EVE_SSO_URL, EVE_ORG_ID, and EVE_API_URL manually
Stale org membership in app tokens Default 1-day TTL. Use strategy: 'remote' in eveUserAuth() for immediate membership checks

Incident Response (Secret Leak)

If a secret may be compromised:

  1. Contain: Rotate the secret immediately via eve secrets set
  2. Invalidate: Redeploy affected environments
  3. Audit: Check eve job list for recent jobs that used the secret
  4. Recover: Generate new credentials at the source (GitHub, AWS, etc.)
  5. Document: Record the incident and update rotation procedures
Weekly Installs
135
Repository
incept5/eve-skillpacks
First Seen
Feb 8, 2026
Security Audits
Gen Agent Trust HubPass
SocketPass
SnykPass
Installed on
gemini-cli135
codex135
claude-code131
pi37
opencode32
amp32