Credential Vault and Auth Framework for AI Agents

Common errors

• Error: DATABASE_URL environment variable is required.

  cause 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.

  cause 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

  cause 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]

  cause 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.

Warnings

• breaking 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.
  Fix: Consult the GitHub release notes and commit history for specific changes between minor versions. Update your API calls and configurations accordingly.
• gotcha 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.
  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.
• gotcha 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.
  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.
• breaking 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.
  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.
• gotcha 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.
  Fix: Carefully verify and synchronize the `redirectUri` used in your `startOAuth` call with the settings in the third-party OAuth provider's application configuration.

Install

• npm install agent.pw npm
• yarn add agent.pw yarn
• pnpm add agent.pw pnpm

Imports

• createAgentPw
  wrong:

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

  correct:

  import { createAgentPw } from '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
  wrong:

  import { createInMemoryFlowStore } from 'agent.pw';

  correct:

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

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

  import { createDb } from 'agent.pw';

  correct:

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

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

  import { unwrap } from 'agent.pw';

  correct:

  import { unwrap } from 'okay-error';

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

Quickstart

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);