agent.pw

library0.8.2jsnpmunverified

agent.pw is a robust credential vault and authentication framework specifically designed for AI agents. It provides secure storage for encrypted credentials, including OAuth tokens and API keys, utilizing AES-GCM for data at rest. The library manages the entire OAuth lifecycle, supporting PKCE, token refresh, revocation, and RFC 9728 discovery. Currently at version 0.8.2, the project exhibits a rapid release cadence with frequent patch and minor updates (multiple in April 2026 alone), indicating active development and continuous improvement. Key differentiators include its agent-centric design, comprehensive OAuth handling, support for admin-configurable credential profiles, path-based organization (`ltree` paths like `acme.connections.github`), and scoped access control. It is designed to be embeddable, working seamlessly with any PostgreSQL-compatible database without requiring a separate server component.

auth-security llm-agents database

npm install agent.pw

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · AGENT.PW

agent.pw

auth-securityjavascriptv0.8.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

createAgentPw

✓ import { createAgentPw } from 'agent.pw';

✗ const { createAgentPw } = require('agent.pw');

agent.pw is primarily an ESM module, though CJS usage might be possible via transpilation or specific Node.js settings, ESM is recommended.

createInMemoryFlowStore

✓ import { createInMemoryFlowStore } from 'agent.pw/oauth';

✗ import { createInMemoryFlowStore } from 'agent.pw';

OAuth-related utilities are located in the 'agent.pw/oauth' subpath. Ensure correct subpath import for specific features.

createDb

✓ import { createDb } from 'agent.pw/sql';

✗ import { createDb } from 'agent.pw';

Database connection utilities are located in the 'agent.pw/sql' subpath. This is a common mistake to import from the root.

unwrap

✓ import { unwrap } from 'okay-error';

✗ import { unwrap } from 'agent.pw';

The `unwrap` utility is an external dependency from the `okay-error` package, not an internal export of `agent.pw`.

This quickstart demonstrates how to initialize `agent.pw` with a PostgreSQL database, an encryption key, and an in-memory OAuth flow store, then resolves headers for a resource.

import { createAgentPw } from "agent.pw"; import { createInMemoryFlowStore } from "agent.pw/oauth"; import { createDb } from "agent.pw/sql"; import { unwrap } from "okay-error"; async function initializeAgentPw() { const databaseUrl = process.env.DATABASE_URL ?? ''; if (!databaseUrl) { throw new Error("DATABASE_URL environment variable is required."); } const encryptionKey = process.env.AGENTPW_ENCRYPTION_KEY ?? ''; if (!encryptionKey) { throw new Error("AGENTPW_ENCRYPTION_KEY environment variable is required."); } const db = unwrap(createDb(databaseUrl)); const agentPw = await unwrap( createAgentPw({ db, encryptionKey, flowStore: createInMemoryFlowStore(), }), ); console.log('agent.pw initialized successfully.'); // Example: Resolve headers for a previously connected resource const path = "acme.connections.docs"; // Replace with your resource path try { const headers = await unwrap(agentPw.connect.resolveHeaders({ path })); console.log(`Resolved headers for ${path}:`, headers); } catch (error) { console.error(`Failed to resolve headers for ${path}:`, error); } return agentPw; } initializeAgentPw().catch(console.error);

Debug

Known issues

breakingAs `agent.pw` is in active `0.x.x` development, minor version increments (e.g., `0.6.0` to `0.7.0`) may introduce breaking API changes not explicitly detailed as such. Always review release notes carefully when upgrading.

fix

Consult the GitHub release notes and commit history for specific changes between minor versions. Update your API calls and configurations accordingly.

affects: >=0.1.0

gotchaThe `encryptionKey` is critical for credential security. Losing this key will result in irreversible loss of access to all encrypted credentials stored by `agent.pw`. It must be a strong, securely generated secret.

fix

Ensure the `AGENTPW_ENCRYPTION_KEY` environment variable is set with a robust, persistent secret, ideally managed by a dedicated secrets management system. Never hardcode or expose it directly in source control.

affects: >=0.1.0

gotchaMany `agent.pw` operations return `Result` types (an `Ok` or `Err` wrapper) requiring the use of `unwrap` from `okay-error`. Failing to handle potential errors from `unwrap` can lead to uncaught exceptions and application crashes.

fix

Always wrap `unwrap` calls in `try...catch` blocks or use explicit error handling patterns like `if (result.isErr()) { ... }` when dealing with `Result` types to gracefully manage failures.

affects: >=0.1.0

breakingVersion `0.8.0` introduced the ability to initialize with a profile-only configuration without an encryption key, but the core `createAgentPw` function still mandates an `encryptionKey` if you intend to store secrets. This feature primarily applies to specific `connect.prepare` flows.

fix

For full credential management capabilities, always provide a valid `encryptionKey` to `createAgentPw`. If you're leveraging profile-only initialization, ensure your use case aligns with the specific capabilities enabled by this feature.

affects: >=0.8.0

gotchaThe OAuth redirect URIs (`redirectUri`) specified in `agentPw.connect.startOAuth` must exactly match the redirect URIs configured with the OAuth provider. Mismatches will result in authorization failures.

fix

Carefully verify and synchronize the `redirectUri` used in your `startOAuth` call with the settings in the third-party OAuth provider's application configuration.

affects: >=0.1.0

Errors

Common errors & fixes

Error: DATABASE_URL environment variable is required.

The `DATABASE_URL` environment variable was not set or was empty when `createDb` was called.

fix

Set the `DATABASE_URL` environment variable in your environment (e.g., `.env` file, shell export) to a valid PostgreSQL connection string before running your application.

Error: AGENTPW_ENCRYPTION_KEY environment variable is required.

The `AGENTPW_ENCRYPTION_KEY` environment variable was not set or was empty during `createAgentPw` initialization.

fix

Provide a secure, randomly generated string for the `AGENTPW_ENCRYPTION_KEY` environment variable. This key is used to encrypt all stored credentials.

OAuthError: Invalid redirect_uri

The `redirectUri` passed to `agentPw.connect.startOAuth` does not match the URI registered with the OAuth provider.

fix

Double-check the `redirectUri` parameter against your OAuth application's configuration on the provider's side and ensure they are an exact match, including protocol, hostname, port, and path.

Error: Unwrapped an Err value. Original error: [Some specific database error]

An operation on the database (e.g., connection, query) failed, and the `unwrap` call on the `Result` type threw an error.

fix

Inspect the 'Original error' message for specifics. This usually indicates an issue with the `DATABASE_URL`, network connectivity to the database, or database permissions. Ensure your database is running and accessible.

Upgrade

Version history

0.8.2latest on npm

Audit

Dependencies

okay-errorrequiredUsed for error handling and result unwrapping, requiring explicit checks for success or failure.

pgrequiredPostgreSQL-compatible database is required for persistent storage. While `agent.pw` abstracts the database connection via `createDb`, a Postgres client library is implicitly needed.

Agent activity

59 hits · last 30 days

node

Perplexity

OpenAI (training)

Resources

githubhttps://github.com/smithery-ai/agent.pw ↗

packagehttps://www.npmjs.com/package/agent.pw ↗

homepagehttps://agent.pw ↗