@agentpki/scopes

Pre-built capability scope templates for AgentPKI passports. Use these instead of inventing your own scope strings — every site verifying AgentPKI tokens will recognize them.

Install

npm i @agentpki/scopes

Quick start

import { AgentPKI } from '@agentpki/sdk';
import { Scopes } from '@agentpki/scopes';

const client = new AgentPKI({ passportProvider });

// Mint a passport with a pre-built scope pack:
const token = await client.mint({
  sub: 'agent:mybot/v1',
  scope: Scopes.commerce.checkout({ maxUsd: 100 }),
});
// scope: ['read:catalog', 'read:availability', 'read:pricing', 'read:reviews',
//         'request:quote', 'accept:quote', 'purchase:<=100usd',
//         'read:receipt', 'read:order-status', 'request:refund']

Built-in scope packs

Commerce

Pack	Description
Scopes.commerce.readOnly	Browse-only: catalog, availability, pricing, reviews.
Scopes.commerce.checkout({ maxUsd })	Full checkout up to N USD per transaction.
Scopes.commerce.subscriptionManagement({ maxUsdPerPeriod })	Manage recurring billing.

Scheduling

Pack	Description
Scopes.scheduling.readOnly	Read calendar + availability.
Scopes.scheduling.fullAccess	Book, reschedule, cancel, invite.
Scopes.scheduling.windowed({ from, to })	Scheduling constrained to a time window.

News / Content

Pack	Description
Scopes.news.researchBot	Articles + headlines + metadata + public data.
Scopes.news.aggregator	Headlines + RSS + sitemap.

Medical (requires Tier-2 issuer)

Pack	Description
Scopes.medical.triage	Public health info + drug DB. No PHI.
Scopes.medical.telehealthScheduling	Schedule / reschedule / cancel visits.
Scopes.medical.patientRecordsReadonly	Read own records + lab results.

Financial (requires Tier-2 issuer)

Pack	Description
Scopes.financial.research	Market data + filings + rates.
Scopes.financial.accountReadonly	Read balance + transactions + statements.
Scopes.financial.payBills({ maxPerTransactionUsd, maxDailyUsd })	Pay bills with daily and per-tx caps.

Helpers

import { union, satisfies, parse } from '@agentpki/scopes';

// Combine multiple packs:
const combined = union(
  Scopes.commerce.readOnly,
  Scopes.scheduling.fullAccess,
);

// Check if a passport satisfies required scopes:
const ok = satisfies(passportToken.scope, [Scopes.commerce.READ_CATALOG]);

// Parse a parameterized scope:
const parsed = parse('purchase:<=100usd');
// { raw: 'purchase:<=100usd', action: 'purchase', resource: null,
//   constraints: { usd: '<=100' } }

Why standardize?

Every AgentPKI verifier needs to enforce scope semantics consistently. If Anthropic's agent says purchase:limit_100_usd and DataDome expects purchase:<=100usd, both sides have to maintain mapping tables forever.

By using @agentpki/scopes, you guarantee:

• Your scope strings match every other AgentPKI integration's
• Verifiers don't need vendor-specific shims to enforce limits
• The protocol stays one source of truth

If a pack is missing for your industry, open an issue. We add scopes in batches as the ecosystem coalesces.

Adding a new vertical

PRs welcome. New verticals live in src/<vertical>.ts and are added to the top-level Scopes export in src/index.ts. Each vertical should:

1. Export individual scope strings as named constants (UPPER_SNAKE_CASE)
2. Export common packs as readonly arrays
3. Export parameterized scope generators as functions
4. Document any Tier-2 / Tier-3 issuer requirements in comments

License

MIT.

See also

• AgentPKI v0.2 spec — protocol details
• @agentpki/sdk — core SDK
• agentpki CLI — terminal interface