@keychains/server-sdk

@keychains/server-sdk

BETA — This SDK is under active development. APIs may change.

Server SDK for Keychains.dev — give your server-side app secure access to user credentials (OAuth tokens, API keys) through the Keychains proxy.

Setup

npm install @keychains/server-sdk
npx @keychains/server-sdk register myapp.com

The register script will:

• Generate an RSA keypair and write jwks.json to the right location for your project
• Walk you through DNS verification
• Add KEYCHAINS_* env vars to your .env

Quickstart

import { KeychainsApp } from '@keychains/server-sdk';

const keychains = KeychainsApp.fromEnv();

Option 1: Approval at request time (recommended)

Everything is transparent until the proxy request — identical to how keychains curl works. A wildcard permission is created automatically, and the auth URL only surfaces when the user actually needs to connect a service.

// One-liner — fetch through the proxy:
try {
  const res = await keychains.forUser(userId).withTask('Project Albatros').fetch('https://api.github.com/user');
  const data = await res.json();
} catch (err) {
  if (err instanceof KeychainsAppError && err.approvalUrl) {
    // User hasn't connected GitHub yet — show them this URL
    console.log(`Please authorize: ${err.approvalUrl}`);
  }
}

Or step by step:

// Get a token (creates a wildcard permission if needed)
const { token } = await keychains.forUser(userId).withTask('Project Albatros').getToken();

// Use the token for one or more proxy requests
const res = await keychains.fetch('https://api.github.com/user', { permissionToken: token });

When to use: Quick prototyping, AI agents, cases where you don't know upfront which services the user will need.

Option 2: Pre-approving requests

Create a scoped permission with specific scopes. The user approves upfront, then all subsequent requests go through without interruption.

const scopes = ['gmail.com::oauth2::read', 'linear.app::oauth2::read'];
const permission = await keychains.forUser(userId).withTask('Project Albatros').getPermission(scopes);

// Show approval URL to the user
console.log('Please approve at: ' + permission.approvalUrl());

// Check if approved (poll or after redirect)
if (await permission.isApproved()) {
  const res = await permission.fetch('https://gmail.googleapis.com/gmail/v1/users/me/messages');
  // or: const { token } = await permission.getToken();
}

When to use: Apps with explicit user consent UIs, when you know exactly which services are needed.

API Reference

KeychainsApp

// From environment variables (recommended)
const keychains = KeychainsApp.fromEnv();

// Manual configuration
const keychains = new KeychainsApp({
  domain: 'myapp.com',
  privateKey: process.env.KEYCHAINS_PRIVATE_KEY!,
  keyId: 'key-1',
  serverUrl: 'https://keychains.dev', // optional
});
keychains.setAppId(process.env.KEYCHAINS_APP_ID!);

Fluent API

Method	Returns	Description
.forUser(userId)	UserContext	Scope operations to a user
.forUser(id).withTask(name)	TaskContext	Scope to a user + task
.forUser(id).withTask(name).fetch(url, opts?)	Response	Wildcard token + proxied fetch
.forUser(id).withTask(name).getToken()	TokenResult	Wildcard token for manual fetch
.forUser(id).withTask(name).getPermission(scopes?)	Permission	Scoped permission for pre-approval
.forUser(id).getTokenForTask(name)	TokenResult	Shortcut for .withTask(name).getToken()
.forUser(id).getPermissionForTask(name, scopes)	Permission	Shortcut for .withTask(name).getPermission(scopes)

Lower-level methods

Method	Description
.createPermission(opts)	Create a permission request
.listPermissions(appUserId)	List permissions for a user
.getPermissionStatus(id, appUserId)	Check permission status
.mintToken(permissionId, appUserId, ttl?)	Mint a short-lived token
.fetch(url, { permissionToken })	Proxied fetch with a token
.register({ verify? })	DNS registration flow
.delegate(permissionId, appUserId, opts)	Delegate access to VMs

Permission

Method	Returns	Description
.approvalUrl()	string | undefined	URL for user to approve
.isApproved()	boolean	Poll if permission is active
.getToken(ttl?)	TokenResult	Mint a token
.fetch(url, opts?)	Response	Mint token + proxied fetch

Error Handling

import { KeychainsAppError } from '@keychains/server-sdk';

try {
  const res = await keychains.forUser(userId).withTask('My Task').fetch(url);
} catch (err) {
  if (err instanceof KeychainsAppError) {
    if (err.approvalUrl) {
      // User needs to authorize — redirect or show the URL
      console.log(`Authorize: ${err.approvalUrl}`);
    } else {
      console.error(`${err.code}: ${err.message}`);
    }
  }
}

Code	Description
authorization_required	Proxy request needs user approval (has approvalUrl)
missing_env	Required environment variables not set
not_registered	App ID not set — run register or call setAppId()
unauthorized	Invalid or expired JWT
not_found	Permission or app not found
forbidden	Permission revoked or app revoked

Registration Flow

1. Run the register script

npx @keychains/server-sdk register myapp.com

This generates a keypair, writes jwks.json, and walks you through DNS verification.

2. Serve the JWKS endpoint

Your domain must serve the JWKS file at:

https://myapp.com/.well-known/keychains.dev/jwks.json

For Next.js / static sites, the register script places it in public/ by default.

3. DNS verification

Add a TXT record as instructed by the script. Once verified, your app is registered and the env vars are written to .env.

Delegation

Delegate access to VMs or sub-agents:

const delegate = await keychains.delegate(permissionId, userId, {
  publicKey: vmPublicKey,
  scopes: ['github.com::oauth2::repo'],
});

// Or use bootstrap token for self-registration
const delegate = await keychains.delegate(permissionId, userId, {
  useBootstrapToken: true,
  scopes: ['github.com::oauth2::repo'],
});
// delegate.bootstrapToken → send to VM

Security Model

• JWKS Authentication: Your app signs JWTs with a private key; Keychains verifies via your published JWKS
• Domain Verification: DNS TXT record proves domain ownership
• User Sovereignty: Users authenticate on keychains.dev and explicitly authorize access. Compromising your signing key does NOT grant access to user credentials.
• Key Rotation: Add new keys to JWKS before removing old ones. 24-hour grace period on key disappearance.

Environment Variables

Variable	Required	Description
KEYCHAINS_DOMAIN	Yes	Your registered domain
KEYCHAINS_PRIVATE_KEY	Yes	PEM-encoded private key
KEYCHAINS_KEY_ID	Yes	Key ID (kid) from your JWKS
KEYCHAINS_APP_ID	No	App ID (auto-set by register script)
KEYCHAINS_SERVER_URL	No	Override server URL (default: https://keychains.dev)

License

Proprietary — Interagentic Inc.