npm package: @id-wispera/core
Description: Core governance engine for ID Wispera - types, vault, detection, policies
Author: Wispera AI Inc.
Latest version: 0.1.0

# @id-wispera/core

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

## Installation

```bash
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

```typescript
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: 'alice@company.com',
});

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

```typescript
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

```typescript
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

```typescript
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', 'admin@company.com');
```

### Credential Detection

```typescript
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

```typescript
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

```typescript
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

```typescript
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.

```typescript
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: 'alice@company.com',
  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:

```typescript
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](../../docs/provisioning.md) for full provider examples and authentication details.

### Framework Integrations

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

```typescript
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](../../docs/integrations.md) for full examples in TypeScript, Python, and Go.

## Types

See [types.ts](./src/types.ts) for complete type definitions.

## License

MIT