{"id":16757,"library":"agent.pw","title":"Credential Vault and Auth Framework for AI Agents","description":"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.","status":"active","version":"0.8.2","language":"javascript","source_language":"en","source_url":"https://github.com/smithery-ai/agent.pw","tags":["javascript"],"install":[{"cmd":"npm install agent.pw","lang":"bash","label":"npm"},{"cmd":"yarn add agent.pw","lang":"bash","label":"yarn"},{"cmd":"pnpm add agent.pw","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used for error handling and result unwrapping, requiring explicit checks for success or failure.","package":"okay-error","optional":false},{"reason":"PostgreSQL-compatible database is required for persistent storage. While `agent.pw` abstracts the database connection via `createDb`, a Postgres client library is implicitly needed.","package":"pg","optional":false}],"imports":[{"note":"agent.pw is primarily an ESM module, though CJS usage might be possible via transpilation or specific Node.js settings, ESM is recommended.","wrong":"const { createAgentPw } = require('agent.pw');","symbol":"createAgentPw","correct":"import { createAgentPw } from 'agent.pw';"},{"note":"OAuth-related utilities are located in the 'agent.pw/oauth' subpath. Ensure correct subpath import for specific features.","wrong":"import { createInMemoryFlowStore } from 'agent.pw';","symbol":"createInMemoryFlowStore","correct":"import { createInMemoryFlowStore } from 'agent.pw/oauth';"},{"note":"Database connection utilities are located in the 'agent.pw/sql' subpath. This is a common mistake to import from the root.","wrong":"import { createDb } from 'agent.pw';","symbol":"createDb","correct":"import { createDb } from 'agent.pw/sql';"},{"note":"The `unwrap` utility is an external dependency from the `okay-error` package, not an internal export of `agent.pw`.","wrong":"import { unwrap } from 'agent.pw';","symbol":"unwrap","correct":"import { unwrap } from 'okay-error';"}],"quickstart":{"code":"import { createAgentPw } from \"agent.pw\";\nimport { createInMemoryFlowStore } from \"agent.pw/oauth\";\nimport { createDb } from \"agent.pw/sql\";\nimport { unwrap } from \"okay-error\";\n\nasync function initializeAgentPw() {\n  const databaseUrl = process.env.DATABASE_URL ?? '';\n  if (!databaseUrl) {\n    throw new Error(\"DATABASE_URL environment variable is required.\");\n  }\n  const encryptionKey = process.env.AGENTPW_ENCRYPTION_KEY ?? '';\n  if (!encryptionKey) {\n    throw new Error(\"AGENTPW_ENCRYPTION_KEY environment variable is required.\");\n  }\n\n  const db = unwrap(createDb(databaseUrl));\n  const agentPw = await unwrap(\n    createAgentPw({\n      db,\n      encryptionKey,\n      flowStore: createInMemoryFlowStore(),\n    }),\n  );\n\n  console.log('agent.pw initialized successfully.');\n  \n  // Example: Resolve headers for a previously connected resource\n  const path = \"acme.connections.docs\"; // Replace with your resource path\n  try {\n    const headers = await unwrap(agentPw.connect.resolveHeaders({ path }));\n    console.log(`Resolved headers for ${path}:`, headers);\n  } catch (error) {\n    console.error(`Failed to resolve headers for ${path}:`, error);\n  }\n  \n  return agentPw;\n}\n\ninitializeAgentPw().catch(console.error);","lang":"typescript","description":"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."},"warnings":[{"fix":"Consult the GitHub release notes and commit history for specific changes between minor versions. Update your API calls and configurations accordingly.","message":"As `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.","severity":"breaking","affected_versions":">=0.1.0"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"Many `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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"Version `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.","severity":"breaking","affected_versions":">=0.8.0"},{"fix":"Carefully verify and synchronize the `redirectUri` used in your `startOAuth` call with the settings in the third-party OAuth provider's application configuration.","message":"The 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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","cause":"The `DATABASE_URL` environment variable was not set or was empty when `createDb` was called.","error":"Error: DATABASE_URL environment variable is required."},{"fix":"Provide a secure, randomly generated string for the `AGENTPW_ENCRYPTION_KEY` environment variable. This key is used to encrypt all stored credentials.","cause":"The `AGENTPW_ENCRYPTION_KEY` environment variable was not set or was empty during `createAgentPw` initialization.","error":"Error: AGENTPW_ENCRYPTION_KEY environment variable is required."},{"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.","cause":"The `redirectUri` passed to `agentPw.connect.startOAuth` does not match the URI registered with the OAuth provider.","error":"OAuthError: Invalid redirect_uri"},{"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.","cause":"An operation on the database (e.g., connection, query) failed, and the `unwrap` call on the `Result` type threw an error.","error":"Error: Unwrapped an Err value. Original error: [Some specific database error]"}],"ecosystem":"npm","meta_description":null}