@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