@id-wispera/core

Core governance engine for ID Wispera - the Identity Whisperer for AI Agents.

Installation

npm install @id-wispera/core

Features

• Type Definitions: Complete TypeScript types for passports, visas, and policies
• Encrypted Vault: AES-256-GCM encrypted local storage with Argon2id key derivation
• Passport Management: CRUD operations for credential passports
• Credential Detection: Regex + heuristic patterns for detecting exposed credentials
• Audit Trail: Append-only audit log for compliance
• Policy Engine: Cedar-inspired declarative policy evaluation
• Secure Sharing: Zero-knowledge credential sharing

Quick Start

import { initVault, createPassport, detectCredentials } from '@id-wispera/core';

// Initialize encrypted vault
const vault = await initVault('your-master-passphrase');

// Create a passport for a credential
const passport = await createPassport(vault, {
  name: 'OpenAI Production',
  credentialType: 'api-key',
  credentialValue: 'sk-...',
  visaType: 'access',
  platforms: ['openai'],
  scope: ['chat', 'completions'],
  humanOwner: '[email protected]',
});

// Detect exposed credentials in text
const results = detectCredentials(`
  API_KEY=sk-proj-abc123...
  AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
`);
// Returns array of detected credentials with type and position

API Reference

Auth

The auth module provides the zero-plaintext credential architecture. No credential material is ever exposed in environment variables, CLI arguments, or logs.

import {
  PassphraseProvider,
  SessionTokenManager,
  KeychainProvider,
} from '@id-wispera/core/auth';

// PassphraseProvider — interactive login, derives vault key from passphrase
const pp = new PassphraseProvider();
const vaultKey = await pp.deriveKey(passphrase);

// KeychainProvider — caches derived key in the OS keychain (macOS Keychain, libsecret, Windows Credential Manager)
const kc = new KeychainProvider();
await kc.store(vaultKey);
const cached = await kc.retrieve();

// SessionTokenManager — create, validate, and revoke scoped session tokens for headless/CI use
const stm = new SessionTokenManager(vault);
const token = await stm.create({ name: 'ci-deploy', scope: ['read', 'list'], ttl: '24h' });
const session = await stm.validate(token);
await stm.revoke(token.id);
const tokens = await stm.list();

| Export | Purpose | |--------|---------| | PassphraseProvider | Derive vault key from passphrase (interactive login) | | SessionTokenManager | Create / validate / revoke / list scoped session tokens | | KeychainProvider | Cache vault key in the OS keychain for session persistence |

Vault

import { initVault, unlockVault, lockVault } from '@id-wispera/core/vault';

// Initialize a new vault
const vault = await initVault(passphrase, storagePath?);

// Unlock existing vault
const vault = await unlockVault(passphrase);

// Lock vault (clears keys from memory)
lockVault(vault);

Passport Management

import { createPassport, getPassport, listPassports, revokePassport } from '@id-wispera/core/passport';

// Create passport
const passport = await createPassport(vault, input);

// Get by ID
const passport = await getPassport(vault, id);

// List with filters
const passports = await listPassports(vault, { status: 'active', platform: 'openai' });

// Revoke
const revoked = await revokePassport(vault, id, 'Security concern', '[email protected]');

Credential Detection

import { detectCredentials, classifyCredential } from '@id-wispera/core/detection';

// Detect credentials in text
const results = detectCredentials(text);
// Returns: { type, value, position, confidence }[]

// Classify a known credential
const type = classifyCredential('sk-proj-abc123...');
// Returns: 'api-key'

Policy Engine

import { evaluatePolicy, validatePassport } from '@id-wispera/core/policy';

const rules = [
  {
    id: 'max-validity',
    name: 'Maximum Validity Period',
    condition: { maxValidityDays: 90 },
    effect: 'deny',
  },
];

// Evaluate a specific action
const decision = evaluatePolicy(passport, 'access', rules);

// Validate passport against all rules
const violations = validatePassport(passport, rules);

Audit Trail

import { logAction, getAuditLog } from '@id-wispera/core/audit';

// Log an action
await logAction(vault, {
  passportId: passport.id,
  action: 'accessed',
  actor: 'claude-agent',
  platform: 'mcp',
});

// Get audit log
const entries = await getAuditLog(vault, passportId?, filters?);

Secure Sharing

import { createShareLink, resolveShareLink } from '@id-wispera/core/sharing';

// Create encrypted share payload
const { payload, key } = createShareLink(passport, {
  scope: 'read-only',
  expiresAt: '2024-12-31',
  maxViews: 1,
});

// Resolve (decrypt) shared passport
const passport = resolveShareLink(payload, key);

Credential Provisioning

Programmatically create API keys at vendor APIs and wrap them as governed passports.

import { provisionAndCreatePassport, listProviders } from '@id-wispera/core/provisioning';

// List all 8 supported providers
const providers = listProviders();
// → openai, aws, google-cloud, azure-entra, github, twilio, sendgrid, anthropic

// Provision and govern in one step
const { credential, passport } = await provisionAndCreatePassport(vault, {
  provider: 'openai',
  name: 'Agent Key',
  humanOwner: '[email protected]',
  config: { provider: 'openai', organizationId: 'org-xxx', projectId: 'proj-xxx', keyType: 'service-account' },
}, { type: 'api-key', key: 'sk-admin-...' });

AdminPassport

AdminPassport is a special passport type used to authenticate provisioning operations. Instead of passing raw admin credentials, wrap them in an AdminPassport for audit-trail coverage and policy enforcement:

import { AdminPassport } from '@id-wispera/core/provisioning';

// Create an admin passport for provider operations
const adminPassport = new AdminPassport(vault, {
  provider: 'openai',
  credentialName: 'openai-admin-key',
});

// Use it for provisioning — the admin credential is never exposed as plaintext
const { credential, passport } = await provisionAndCreatePassport(vault, request, adminPassport);

| Provider | Create | Rotate | Revoke | List | Scoped | Expiry | |---|---|---|---|---|---|---| | OpenAI | Yes | Yes | Yes | Yes | Yes | No | | AWS | Yes | Yes | Yes | Yes | Yes | Yes | | Google Cloud | Yes | Yes | Yes | Yes | Yes | Yes | | Azure Entra | Yes | Yes | Yes | Yes | Yes | Yes | | GitHub | Yes | Yes | No | No | Yes | Yes | | Twilio | Yes | Yes | Yes | Yes | Yes | No | | SendGrid | Yes | Yes | Yes | Yes | Yes | No | | Anthropic | No | No | Yes | Yes | No | No |

See Provisioning docs for full provider examples and authentication details.

Framework Integrations

Governed credential access for AI agent frameworks. Every access is cached, audited, and policy-enforced.

import { WisperaCredentialProvider, WisperaOpenAIAgentProvider } from '@id-wispera/core';

// Base provider -- works with any framework
const provider = new WisperaCredentialProvider({ vault });
const key = await provider.getOpenAIKey('openai-prod');

// OpenAI Agents SDK -- agent keys, tool auth, handoffs
const agents = new WisperaOpenAIAgentProvider({ vault });
const agentKey = await agents.getAgentKey('openai-prod');
const toolAuth = await agents.getToolAuth('serper-key');

| Integration | Class | What It Does | |---|---|---| | Base | WisperaCredentialProvider | Get, cache, and audit any credential | | LangChain.js | WisperaLangChainProvider | API keys for LangChain LLM constructors | | OpenAI Agents | WisperaOpenAIAgentProvider | Agent keys, tool auth, handoff scoping | | Google A2A | WisperaA2AProvider | Agent Card credentials, auth validation | | Slack | WisperaSlackProvider | Bot tokens, webhooks, Socket Mode |

See Integrations docs for full examples in TypeScript, Python, and Go.

Types

See types.ts for complete type definitions.

License

MIT