Package Exports
- @getparafe/sdk
Readme
@getparafe/sdk
Node.js client SDK for the Parafe Trust Broker — the neutral trust infrastructure for agent-to-agent interactions.
Install
npm install @getparafe/sdkRequires Node.js 18+.
Quickstart
import { ParafeClient } from '@getparafe/sdk';
// 1. Initialize the client
const parafe = new ParafeClient({
brokerUrl: 'https://parafe-production-9bc9.up.railway.app',
apiKey: 'prf_key_live_...', // From the Parafe Developer Portal
});
// 2. Register your agent (once — generates Ed25519 key pair internally)
const agent = await parafe.register({
name: 'my-travel-agent', // lowercase alphanumeric + hyphens, 3–100 chars
type: 'enterprise', // 'personal' or 'enterprise'
owner: 'Acme Corp',
scopePolicies: { // Optional: declare what scopes this agent accepts
'flight-rebooking': {
permissions: ['read_bookings', 'search_alternatives', 'request_rebooking'],
exclusions: ['cancel_booking', 'charge_payment'],
minimum_authorization_modality: 'attested',
minimum_verification_tier: 'email_verified',
},
},
});
// agent.agentId, agent.credential, agent.publicKey, agent.privateKey, ...
// 3. Save credentials to an encrypted file (AES-256-GCM + scrypt)
await parafe.saveCredentials('./parafe-credentials.enc', 'your-passphrase');
// 4. On subsequent runs, load them back
await parafe.loadCredentials('./parafe-credentials.enc', 'your-passphrase');
// 5. Check credential state
const status = parafe.credentialStatus();
// { loaded: true, agentId: 'prf_agent_...', expiresAt: '...', expired: false }Handshake Flow
Initiator side
const { handshakeId, challengeForTarget } = await parafe.handshake({
targetAgentId: 'prf_agent_target01',
scope: 'flight-rebooking',
permissions: ['read_bookings', 'search_alternatives'],
authorization: ParafeClient.authorization.attested({
instruction: 'User requested flight rebooking via chat',
platform: 'acme-travel-app',
}),
context: { userId: 'alex-mercer' }, // Optional
});
// Send handshakeId + challengeForTarget to the target agent via your transportTarget side
const { sessionId, consentToken } = await parafe.completeHandshake({
handshakeId, // Received from initiator
challengeNonce, // The challengeForTarget value
// SDK signs the nonce internally with your stored private key
});Verify consent and record actions
// Verify an action is permitted
const check = await parafe.verifyConsent({
consentToken: consentToken.token,
action: 'read_bookings',
sessionId,
});
// { valid: true, permitted: true, action: 'read_bookings' }
// Record an action
await parafe.recordAction({
sessionId,
agentId: agent.agentId,
action: 'read_bookings',
details: { bookingRef: 'BK-001' },
consentToken: consentToken.token,
});
// Close the session — returns a signed receipt
const receipt = await parafe.closeSession(sessionId);
// Independently verify the receipt
const verification = await parafe.verifyReceipt(receipt);
// { valid: true, tamperDetected: false, signedBy: 'parafe-broker' }Scope Escalation
Request additional scope within an existing session without re-handshaking:
const escalated = await parafe.escalateScope({
sessionId,
targetAgentId: 'prf_agent_target01',
scope: 'payment-processing',
permissions: ['charge_card'],
authorization: ParafeClient.authorization.verified({
instruction: 'User confirmed payment of $247',
platform: 'acme-payments',
userSignature: '<cryptographic proof>',
}),
});Authorization Helpers
// Autonomous — agent acting alone
ParafeClient.authorization.autonomous()
// Attested — agent claims a human issued this instruction
ParafeClient.authorization.attested({
instruction: 'User clicked "Rebook"',
platform: 'acme-app',
timestamp: new Date().toISOString(), // Optional, defaults to now
})
// Verified — cryptographic proof of human approval
ParafeClient.authorization.verified({
instruction: 'User confirmed $247 charge',
platform: 'acme-payments',
userSignature: '<base64 signature>',
timestamp: new Date().toISOString(), // Optional, defaults to now
})Agent Lifecycle
// Revoke an agent
await parafe.revokeAgent('prf_agent_...');
// Renew credential to pick up org's current verification tier
await parafe.renewCredential('prf_agent_...');
// Update scope policies
await parafe.updateScopePolicies('prf_agent_...', {
'new-scope': { permissions: ['read'], exclusions: ['delete'] },
});Error Handling
The SDK throws typed errors matching the broker's error codes:
import {
ParafeError,
ValidationError,
AuthError,
ForbiddenError,
NotFoundError,
ConflictError,
ExpiredError,
RateLimitError,
InternalError,
} from '@getparafe/sdk';
try {
await parafe.handshake({ ... });
} catch (err) {
if (err instanceof AuthError) {
// err.code — broker error string (e.g. 'invalid_credential')
// err.statusCode — HTTP status (401)
// err.message — human-readable description
}
if (err instanceof RateLimitError) {
// Back off and retry
}
}Running Tests
cd sdk/
npm install
# Unit tests only (no broker needed)
npm run test:unit
# Integration tests (requires a running broker)
PARAFE_TEST_API_KEY=prf_key_live_... npm run test:integration
# Or point at a specific broker URL
PARAFE_TEST_BROKER_URL=http://localhost:3000 PARAFE_TEST_API_KEY=prf_key_live_... npm run test:integrationBuilding
npm run build
# Outputs:
# dist/esm/ — ES modules (Node ESM)
# dist/cjs/ — CommonJS
# dist/types/ — TypeScript declarationsLicense
MIT — see LICENSE.