API reference
Every public export, by entry point. All keys accept JWK, PEM, or CryptoKey (KeyInput). Requires Node 20+ (WebCrypto Ed25519).
corri/server
| Export | Signature | Description |
|---|---|---|
createAgentAccess | (options: CreateAgentAccessOptions) => AgentAccess | The server-side orchestrator: verifies identity, evaluates policy, checks entitlements, gates the handler, issues receipts. The handler is never invoked before authorization fully succeeds. |
access.protect | (config: ProtectConfig, handler: ProtectedHandler) => (request: Request) => Promise<Response> | Wrap a handler. config.resource is a Resource or a (request) => Resource resolver; the handler receives { request, principal, resource, authorization, receipt, signature? }. |
access.authorize | (request: Request, config: ProtectConfig) => Promise<{ ok: true, context } | { ok: false, response }> | Run the authorization pipeline without a handler, for building adapters. |
definePolicy | (definition: PolicyDefinition) => Policy | Validate a definition into an evaluatable policy. Throws PolicyValidationError when malformed. |
memoryReplayStore | (options?: { maxEntries? }) => ReplayStore | In-memory nonce store for development / single instances. Default cap 100k entries. |
redisReplayStore | (client, options?: { keyPrefix?, style? }) => ReplayStore | Shared store via Redis SET NX PX. Works with ioredis and node-redis v4 (style selects the call convention). |
apiKeyEntitlement | (options: { resolve, header?, name? }) => EntitlementProvider | Publisher-issued API keys; resolve(key) returns an ApiKeyGrant or null. Reads Authorization: Bearer by default. |
staticEntitlement | (options: { keys, header?, name? }) => EntitlementProvider | Fixed key → grant table. Tests and local examples only. |
x402Entitlement | (options: X402EntitlementOptions) => EntitlementProvider | x402 micro-payments settled to payTo. See Payments. |
httpFacilitator | ({ url, createAuthHeaders?, fetchImpl? }) => X402FacilitatorClient | HTTP client for hosted facilitators (x402.org, Coinbase CDP, or any compatible endpoint). |
testFacilitator | (options?: { network? }) => X402FacilitatorClient & { settledReferences: string[] } | In-process facilitator for tests/demos. No chain interaction; never use in production. |
usdToAtomicUsdc | (amount: string) => string | Convert decimal USD ("0.01") to USDC atomic units ("10000"). |
generateAgentKeyPair | (options?: { keyId? }) => Promise<AgentKeyPair> | Fresh Ed25519 pair as { keyId, publicKeyJwk, privateKeyJwk, publicKeyPem, privateKeyPem, thumbprint }. Also exported from /client. |
webBotAuthIdentity | (options: WebBotAuthIdentityOptions) => RequestIdentityAdapter | The identity adapter used internally; exported for custom pipelines. |
signReceipt | (payload: AccessReceiptPayload, { issuerKey }) => Promise<string> | Sign a receipt payload into a compact JWS. |
createRslDocument | (policy: PolicyDefinition, options?: CreateRslDocumentOptions) => string | Render a policy as RSL 1.0 XML. See RSL licensing. |
corri/client
| Export | Signature | Description |
|---|---|---|
createAgentClient | (options: AgentClientOptions) => AgentClient | Agent-side client: signs requests (RFC 9421, web-bot-auth tag), declares action/purpose, presents an API key, and auto-answers x402 402 challenges via a PaymentHandler. |
agent.fetch | (url: string, options?: AgentFetchOptions) => Promise<Response> | Options: method, action, purpose, accept, headers, body, autoPay (disable auto-payment per call). |
x402TestPayer | (options?: { payerAddress? }) => PaymentHandler | Demo payment handler compatible with testFacilitator. Fabricates an EIP-3009-shaped authorization; never use in production. |
signRequest | (options: SignRequestOptions) => Promise<{ headers, coveredComponents, signatureBase }> | Low-level request signing for custom agent stacks. |
encodePaymentHeader | (payload: unknown) => string | Base64-encode an x402 v2 payment payload for the PAYMENT-SIGNATURE header. |
generateAgentKeyPair | (options?: { keyId? }) => Promise<AgentKeyPair> | Same helper as in /server. |
corri (core)
Framework-neutral primitives, also re-exported from /server.
| Export | Signature | Description |
|---|---|---|
definePolicy / evaluatePolicy | (definition, request?) => Policy | AccessDecision | The pure policy engine. evaluatePolicy validates and evaluates a raw definition in one call. |
matchesResourcePattern | (pattern: string, resourceId: string) => boolean | "report:*" matches "report:grid"; exact strings match exactly. |
verifyReceipt | (receipt: string, { resolveIssuerKey, now? }) => Promise<VerifiedReceipt> | Verify signature, structure, and validity window. Returns { valid: true, payload } | { valid: false, reason }. |
decodeReceipt | (receipt: string) => AccessReceiptPayload | Decode without verifying. Never trust the result alone. |
createRslDocument / parseRslDocument | (policy | xml) => string | ParsedRslDocument | RSL 1.0 rendering and safe parsing (DOCTYPE rejected, entities never resolved). |
rslHeaders | (policyUrl: string) => Record<string, string> | HTTP headers advertising an RSL license document. |
PURPOSE_TO_RSL_USAGE / RSL_USAGE_TO_PURPOSES | Record<string, string> / Record<string, string[]> | Purpose ↔ RSL usage token maps. |
corri/next
| Export | Signature | Description |
|---|---|---|
protectRoute | (access, config: ProtectRouteConfig, handler) => (request, context) => Promise<Response> | App Router adapter. config.resolveResource receives { params, request }; the handler additionally gets params. Uses only web-standard Request/Response, so it works in Node and edge runtimes. |
ACCESS_RECEIPT_HEADER | "access-receipt" | The response header carrying the receipt JWS. Also exported from /server. |
Key types
| Export | Signature | Description |
|---|---|---|
AccessEffect | "allow" | "deny" | "challenge" | "charge" | The four decisions. |
Principal | { id, kind, operatorId?, trust, keyId?, attributes? } | kind: verified_agent | api_client | unknown; trust: verified | unknown | revoked. |
Resource | { id, version, attributes? } | The protected thing being requested. |
AccessDecision | { effect, policyId, policyVersion, ruleId?, reason?, obligations?, entitlementRequirement?, payment? } | Output of policy evaluation; embedded in receipts and error bodies. |
AccessReceiptPayload | { receiptId, issuer, issuerKeyId, principalId, resourceId, resourceVersion, action, purpose?, policyId, policyVersion, ruleId?, obligations, entitlement?, contentDigest?, issuedAt, expiresAt?, … } | Receipt claims, see Access receipts. |
KeyInput | AgentJwk | string | CryptoKey | Accepted everywhere a key is needed: JWK object, JWK JSON string, PEM (PKCS8/SPKI), or CryptoKey. |
EntitlementProvider | { name, inspect(input), describeRequirement?(input) } | Pluggable entitlement/payment boundary, implement it to accept custom credentials. |
ReplayStore | { consume({ principalId, nonce, expiresAt }): Promise<"accepted" | "replayed"> } | Replay protection boundary. |
Constants
| Constant | Value |
|---|---|
ACCESS_RECEIPT_HEADER | "access-receipt" |
RECEIPT_TYP | "corri-receipt+jws" |
WEB_BOT_AUTH_TAG | "web-bot-auth" |
HEADER_SIGNATURE_AGENT | "signature-agent" |
HEADER_ACTION / HEADER_PURPOSE | "corri-action" / "corri-purpose" |
X402_PAYMENT_SIGNATURE_HEADER | "payment-signature" |
RSL_MEDIA_TYPE / RSL_NAMESPACE | "application/rsl+xml" / "https://rslstandard.org/rsl" |