@lumoauth/agent 1.0.0 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,51 +1,500 @@
1
1
  # @lumoauth/agent
2
2
 
3
- The LumoAuth SDK for AI agents (Node 18+). Two layers:
3
+ [![npm](https://img.shields.io/npm/v/@lumoauth/agent.svg)](https://www.npmjs.com/package/@lumoauth/agent)
4
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
4
5
 
5
- - **`LumoAgent`** — high-level client: OAuth 2.0 client-credentials auth with
6
- transparent refresh, preflight checks (`ask` / `isAllowed`), self-inspection
7
- (`capabilities`, `budget`), and the `jit`, `delegation`, `approvals`, and
8
- `mcp` namespaces.
9
- - **`AAuthClient`** + signing primitives — the AAuth protocol: cryptographic
10
- agent identity, proof-of-possession tokens, and RFC 9421 HTTP message
11
- signing (`node:crypto`, hence Node-only).
6
+ > The LumoAuth SDK for AI agents that run on Node 18 or newer. `LumoAgent`
7
+ > signs the agent in, checks permissions before it acts, asks people for
8
+ > approval, requests just-in-time permissions and gets MCP tokens.
9
+ > `AAuthClient` implements the AAuth protocol: a cryptographic agent identity
10
+ > with RFC 9421 HTTP message signatures.
11
+
12
+ This package is part of the [LumoAuth JavaScript SDK](../../README.md). Not
13
+ sure that it is the package that you need? See
14
+ [Which package do I need?](../../README.md#which-package-do-i-need).
15
+
16
+ ## Contents
17
+
18
+ - [Is this the right package?](#is-this-the-right-package)
19
+ - [Install](#install)
20
+ - [Quick start](#quick-start)
21
+ - [Configuration](#configuration)
22
+ - [Guides](#guides)
23
+ - [`LumoAgent` reference](#lumoagent-reference)
24
+ - [DPoP: sender-constrained tokens](#dpop-sender-constrained-tokens)
25
+ - [Verify LumoAuth access tokens on an MCP server](#verify-lumoauth-access-tokens-on-an-mcp-server)
26
+ - [AAuth: cryptographic agent identity](#aauth-cryptographic-agent-identity)
27
+ - [Errors](#errors)
28
+ - [Troubleshooting](#troubleshooting)
29
+ - [Related packages](#related-packages)
30
+ - [Learn more](#learn-more)
31
+ - [License](#license)
32
+
33
+ ## Is this the right package?
34
+
35
+ | You are… | Use |
36
+ |---|---|
37
+ | Writing an agent (LangChain.js, Vercel AI SDK, your own loop) that signs in **as itself**, asks before acting, and gets a person's approval for risky actions | **This package**, `LumoAgent` |
38
+ | Building or calling an agent that needs a verifiable cryptographic identity, signed requests, or delegation between agents | **This package**, `AAuthClient` |
39
+ | Building an MCP server or another resource server that must verify LumoAuth access tokens, with or without DPoP | **This package**, `verifyAccessToken` |
40
+ | Building a resource server that must verify incoming AAuth tokens | **This package**, `verifyAuthToken` |
41
+ | Calling an MCP server that requires DPoP-bound tokens | **This package**, `DpopProofSigner` |
42
+ | Starting a new agent app | [`npx create-lumo-agent`](../create-lumo-agent/README.md) |
43
+ | Writing an ordinary backend that acts for a user, not as an agent | [`@lumoauth/backend`](../backend/README.md) |
12
44
 
13
45
  ## Install
14
46
 
15
- ```sh
47
+ ```bash
16
48
  npm install @lumoauth/agent
17
49
  ```
18
50
 
19
- ## Example
51
+ **This package needs Node 18 or newer.** The AAuth part uses `node:crypto`, so
52
+ the package never runs in a browser.
53
+
54
+ ## Quick start
55
+
56
+ Create the agent in the LumoAuth portal first. You need its client ID, its
57
+ client secret and your organization slug.
58
+
59
+ ```bash
60
+ export LUMOAUTH_ORG_ID=acme-corp
61
+ export AGENT_CLIENT_ID=…
62
+ export AGENT_CLIENT_SECRET=…
63
+ ```
20
64
 
21
65
  ```ts
22
66
  import { LumoAgent } from '@lumoauth/agent';
23
67
 
24
- // Reads LUMOAUTH_URL / LUMOAUTH_ORG_ID / AGENT_CLIENT_ID / AGENT_CLIENT_SECRET
25
- const agent = new LumoAgent();
68
+ const agent = new LumoAgent(); // reads the variables above
26
69
 
27
- // Preflight before running a tool
70
+ // 1. Check first: may this agent do this, in this context?
28
71
  if (!(await agent.isAllowed('document.read', { id: 'doc_99' }))) {
29
72
  throw new Error('not allowed');
30
73
  }
31
74
 
32
- // Human approval for an irreversible action — push lands on the user's phone
75
+ // 2. Ask a person before an action that cannot be undone. A push arrives on
76
+ // the user's phone, and the promise resolves when they answer or time runs out.
33
77
  const approval = await agent.approvals.require({
34
78
  taskId: 'wire-001',
35
79
  reason: 'Wire $4,500 to vendor INV-7741',
36
80
  impact: 'high',
37
81
  onBehalfOf: 'ada@acme.com',
38
82
  });
39
- if (approval.status !== 'approved') throw new Error(`denied: ${approval.status}`);
83
+ if (approval.status !== 'approved') throw new Error(`not approved: ${approval.status}`);
84
+
85
+ // 3. Get a short-lived token for a secured MCP server.
86
+ // The server ID is the MCP server's https URL. It becomes the token's `aud`.
87
+ const mcpToken = await agent.mcp.getToken('https://mcp.example.com/mcp');
88
+ ```
89
+
90
+ Sign-in is automatic. The first call runs the OAuth 2.0 client credentials
91
+ grant. The SDK refreshes the token 60 seconds before it expires.
92
+
93
+ ## Configuration
94
+
95
+ `new LumoAgent(options?)`. Every option falls back to an environment variable.
96
+
97
+ | Option | Environment variable | Default | Description |
98
+ |---|---|---|---|
99
+ | `baseUrl` | `LUMOAUTH_URL` | `https://app.lumoauth.dev` | The LumoAuth host. Use `https://eu.app.lumoauth.dev` for the EU region |
100
+ | `orgId` | `LUMOAUTH_ORG_ID` | none | The organization slug. Every namespace needs it |
101
+ | `clientId` | `AGENT_CLIENT_ID` | required | The agent's OAuth client ID |
102
+ | `clientSecret` | `AGENT_CLIENT_SECRET` | required | The agent's OAuth client secret |
103
+ | `scopes` | none | the agent's defaults | Scopes to request |
104
+ | `redirectUri` | none | none | The callback URL of the delegation consent flow |
105
+ | `timeout` | none | 30 000 ms | Request timeout |
106
+ | `fetch` | none | global `fetch` | A custom `fetch` |
107
+ | `dpop` | none | none | A `DpopProofSigner`. Every token the agent obtains is then bound to its key, and every request carries a DPoP proof. See [DPoP](#dpop-sender-constrained-tokens) |
108
+
109
+ The constructor throws `LumoAuthConfigError` when the client ID or the client
110
+ secret is missing. It does not call the server.
111
+
112
+ ## Guides
113
+
114
+ ### Check before acting
115
+
116
+ `ask()` returns the decision and the reason. `isAllowed()` returns only the
117
+ boolean.
118
+
119
+ ```ts
120
+ const decision = await agent.ask('tickets.write', { ticket: 'T-42' });
121
+ // decision.allowed, decision.action, decision.reason, decision.audit_id
122
+ ```
123
+
124
+ The decision comes from the agent's capabilities and the organization's
125
+ policies. The server always sets `ip`, `userAgent`, `requestMethod` and
126
+ `requestPath` in the context from the real request. Values that you send under
127
+ those names move to `pep`.
128
+
129
+ ### Ask a person for approval
130
+
131
+ ```ts
132
+ const approval = await agent.approvals.require({
133
+ taskId: 'delete-42',
134
+ reason: 'Delete 1,204 archived invoices',
135
+ impact: 'critical', // 'low' | 'medium' | 'high' | 'critical'; default 'medium'
136
+ onBehalfOf: 'ada@acme.com', // email or user ID
137
+ meta: { count: 1204 }, // shown to the user
138
+ timeoutMs: 120_000, // default 90 000
139
+ });
140
+ ```
141
+
142
+ `approval.status` is `approved`, `denied`, `expired` or `pending`. `pending`
143
+ means that the wait ended before the user answered. `approval.token` lets you
144
+ check again later with `agent.approvals.getStatus(token)` or
145
+ `agent.approvals.wait(token)`.
146
+
147
+ When the user has no enrolled push device, no prompt is sent. `require()`
148
+ then throws `LumoAuthApprovalNotDeliveredError`. It never returns
149
+ `approved` in this case. Check `err.reason`:
150
+
151
+ - `email_fallback_sent`: the server emailed the user a notice with no
152
+ approval link. There is no token, so the SDK does not poll. An unknown
153
+ user gets the same answer.
154
+ - `no_enrolled_device`: the email could not be sent either.
155
+
156
+ ```ts
157
+ import { LumoAuthApprovalNotDeliveredError } from '@lumoauth/agent';
158
+
159
+ try {
160
+ await agent.approvals.require({ taskId: 'delete-42', reason: 'Delete invoices', onBehalfOf: 'ada@acme.com' });
161
+ } catch (err) {
162
+ if (err instanceof LumoAuthApprovalNotDeliveredError) {
163
+ // Ask the user to check their email, or to enrol the LumoAuth app.
164
+ } else throw err;
165
+ }
166
+ ```
167
+
168
+ `agent.approvals.create()` sends the request without waiting. It returns
169
+ `status: 'pending'` and a `token` when a prompt was sent. Otherwise it
170
+ returns `status: 'email_fallback_sent'` and `token: null`, without throwing.
171
+
172
+ ### Request just-in-time permissions
173
+
174
+ ```ts
175
+ await agent.jit.createTask({ name: 'Analyse the Q4 report', onBehalfOf: 'ada@acme.com' });
176
+
177
+ const result = await agent.jit.requestPermission(
178
+ { type: 'file_access', actions: ['read'], identifier: 'report_q4.pdf' },
179
+ { justification: 'The user asked for Q4 revenue', ttl: 300 },
180
+ );
181
+
182
+ if (result.status === 'approved') {
183
+ const token = await agent.jit.getToken(result.request_id);
184
+ // Call the resource with `Authorization: Bearer ${token}`.
185
+ }
186
+
187
+ await agent.jit.completeTask(); // ends the task and revokes its tokens
188
+ ```
189
+
190
+ When a request needs approval, `requestPermission()` keeps polling until a
191
+ person answers. It polls every 5 seconds for up to 5 minutes; pass `waitForApproval: false` to
192
+ return at once. A JIT token lasts at most 900 seconds.
193
+
194
+ ### Act for a user
195
+
196
+ ```ts
197
+ const agent = new LumoAgent({ redirectUri: 'https://agent.example.com/callback' });
198
+
199
+ const url = agent.delegation.getConsentUrl('session-1', ['read:documents']);
200
+ // …the user consents and returns with ?code=…
201
+ await agent.delegation.handleConsentCallback('session-1', code);
202
+
203
+ const delegated = await agent.delegation.exchange('session-1', ['read:documents'], {
204
+ resource: 'https://api.example.com', // becomes the token's aud
205
+ });
206
+ ```
207
+
208
+ When you already hold the user's access token, call
209
+ `agent.delegation.setUserToken('session-1', accessToken)` instead of the
210
+ consent steps. The token types and the `resource` option are explained in the
211
+ [workspace guide](../../README.md#act-on-a-users-behalf-delegation).
212
+
213
+ ## `LumoAgent` reference
214
+
215
+ ### Properties and methods
216
+
217
+ | Member | Returns | Description |
218
+ |---|---|---|
219
+ | `authenticate(scopes?)` | `Promise<string>` | Runs the client credentials grant now. You rarely need it, because every call signs in when needed |
220
+ | `getAccessToken()` | `Promise<string>` | The current access token, refreshed when it is about to expire |
221
+ | `tokenScopes` | `string[]` | The scopes that the server granted to the current token |
222
+ | `tokenType` | `string \| null` | `DPoP` when the current token is sender-constrained, otherwise `Bearer`; `null` before the first sign-in |
223
+ | `dpopSigner` | `DpopProofProvider \| undefined` | The signer passed as `dpop` |
224
+ | `ask(action, context?)` | `Promise<AgentAskResult>` | The full decision for an action |
225
+ | `isAllowed(action, context?)` | `Promise<boolean>` | `ask()` reduced to a boolean |
226
+ | `getCurrentAgent()` | `Promise<AgentIdentity>` | The agent's identity, capabilities and workspace |
227
+ | `capabilities()` | `Promise<string[]>` | The agent's capabilities |
228
+ | `budget()` | `Promise<AgentBudget>` | The agent's budget policy, or `{}` when none is set |
229
+ | `baseUrl`, `orgId`, `clientId` | `string` | The resolved configuration |
230
+
231
+ ### Namespaces
232
+
233
+ | Namespace | What it does | Methods |
234
+ |---|---|---|
235
+ | `agents` | Agent identity | `ask`, `isAllowed`, `me`, `getCurrentAgent`, `capabilities`, `budget`, `register`, `authorizeMcpTool(serverId, tool)` |
236
+ | `approvals` | Push approval for agent actions | `require`, `create`, `getStatus`, `wait` |
237
+ | `jit` | Just-in-time permissions | `createTask`, `requestPermission`, `getRequestStatus`, `getToken`, `evaluateTask`, `completeTask`. `listPendingRequests` is the human reviewer's view. It needs a user token with `jit:approve`, so the server rejects an agent's own token |
238
+ | `delegation` | Act for a user, or hand work to a sub-agent, with RFC 8693 token exchange | `getConsentUrl`, `handleConsentCallback`, `setUserToken`, `exchange`, `request`, `delegateToSubAgent`, `revoke`, `revokeAll`, `hasDelegation`, `activeSessions` |
239
+ | `mcp` | Secured MCP servers | `getToken`, `getTokenDetailed`. Pass the MCP server's https URL, such as `https://mcp.example.com/mcp`. The SDK sends it as the RFC 8707 `resource`, so the token's `aud` is that URL. Any other ID throws `LumoAuthValidationError`. The token works only at that MCP server. With a `dpop` signer the token is DPoP-bound (`tokenType: 'DPoP'`). `authorizeTool({ serverId, subject, tool })` lets an MCP server check one tool call with its own `mcp:authorize` token. A deny returns `allowed: false` |
240
+
241
+ The parameters of each method are in the
242
+ [workspace API reference](../../README.md#api-reference).
243
+
244
+ ## DPoP: sender-constrained tokens
245
+
246
+ An MCP server registered with "Require DPoP" accepts only tokens that are
247
+ bound to the caller's key (RFC 9449). Give the agent a `DpopProofSigner`.
248
+ The client-credentials token, every MCP token exchange, every delegation
249
+ exchange and every API call then carry a DPoP proof, and the tokens come
250
+ back with `token_type: "DPoP"`. The server's `use_dpop_nonce` answer is
251
+ retried once, and the latest `DPoP-Nonce` is remembered per origin.
252
+
253
+ ```ts
254
+ import { LumoAgent, DpopProofSigner, buildDpopHeaders } from '@lumoauth/agent';
255
+
256
+ // One key per agent instance. ES256 (P-256) by default; 'EdDSA' reuses an
257
+ // Ed25519 key, so the AAuth key can double as the DPoP key.
258
+ const dpop = DpopProofSigner.generate();
259
+ // Or load one: new DpopProofSigner({ privateKeyPem: process.env.AGENT_DPOP_KEY! })
260
+
261
+ const agent = new LumoAgent({ dpop });
262
+
263
+ const mcp = await agent.mcp.getTokenDetailed('https://mcp.example.com/mcp');
264
+ // mcp.tokenType === 'DPoP'
265
+
266
+ // Each MCP request needs a fresh proof that names the token (ath).
267
+ const headers = await buildDpopHeaders(dpop, {
268
+ method: 'POST',
269
+ url: 'https://mcp.example.com/mcp',
270
+ accessToken: mcp.accessToken,
271
+ tokenType: mcp.tokenType, // 'Bearer' here falls back to a plain Bearer header
272
+ });
273
+ await fetch('https://mcp.example.com/mcp', { method: 'POST', headers, body });
274
+ ```
275
+
276
+ `fetchWithDpop(fetch, url, init, dpop, { accessToken })` does the same and
277
+ also retries a `use_dpop_nonce` challenge from the MCP server.
278
+
279
+ | Export | What it does |
280
+ |---|---|
281
+ | `DpopProofSigner.generate(alg?)` | A new key: `'ES256'` (default), `'EdDSA'` or `'RS256'` |
282
+ | `new DpopProofSigner({ privateKeyPem })` | Loads an EC P-256, Ed25519 or RSA PEM key. `privateKeyPem` reads it back |
283
+ | `signer.createProof({ method, url, accessToken?, nonce? })` | One proof JWT: `typ dpop+jwt`, `jwk`, `jti`, `htm`, `htu` (no query), `iat`, `ath` when a token is given, `nonce` when given or remembered |
284
+ | `signer.jwk`, `signer.thumbprint` | The public key and its RFC 7638 thumbprint (the `cnf.jkt` of bound tokens) |
285
+ | `signer.setNonce(url, nonce)`, `getNonce(url)`, `clearNonces()` | Nonce memory per origin |
286
+ | `buildDpopHeaders(signer, { method, url, accessToken, tokenType? })` | `{ Authorization: 'DPoP …', DPoP }`, or `{ Authorization: 'Bearer …' }` for an unbound token |
287
+ | `fetchWithDpop(fetch, url, init, signer, { accessToken? })` | `fetch` with the proof and the one-time nonce retry |
288
+ | `attestWorkload({ orgId, agentId, attestationToken, dpop? })` | Workload attestation (`POST …/agents/{agentId}/attest`) with an optional proof; returns `{ accessToken, tokenType, expiresIn, scope, identity }` |
289
+
290
+ ## Verify LumoAuth access tokens on an MCP server
291
+
292
+ The token an MCP server receives is a LumoAuth `at+jwt` access token whose
293
+ `aud` is the server's resource URI. Verify it locally, without a call to
294
+ LumoAuth per request:
295
+
296
+ ```ts
297
+ import { createAccessTokenVerifier } from '@lumoauth/agent';
40
298
 
41
- // Short-lived token for a secured MCP server
42
- const mcpToken = await agent.mcp.getToken('urn:mcp:financial-data');
299
+ const verifier = createAccessTokenVerifier({
300
+ issuer: 'https://app.lumoauth.dev/orgs/acme-corp/api/v1',
301
+ resource: 'https://mcp.example.com/mcp', // must be in the token's aud
302
+ });
303
+ const claims = await verifier.verifyRequest({ method: req.method, url: publicUrl, headers: req.headers });
43
304
  ```
44
305
 
45
- ## Docs
306
+ `verifyRequest` reads `Authorization` (scheme `Bearer` or `DPoP`) and the
307
+ `DPoP` header. `verifier.verify(token, dpop?)` takes the token directly, and
308
+ the plain function `verifyAccessToken(token, { issuer, resource, … })` does
309
+ the same with a process-wide key cache.
310
+
311
+ The verifier fetches the organization's keys from
312
+ `{issuer}/.well-known/openid-configuration` (`jwks_uri`), caches them and
313
+ fetches them again once when a token names an unknown `kid`. Pass `jwks` to
314
+ skip the network. It checks:
315
+
316
+ - `typ` is `at+jwt` or `application/at+jwt`; `alg` is asymmetric (`none`
317
+ and `HS*` are refused); `kid` resolves;
318
+ - the signature, `iss`, `aud` (string or array) contains `resource`, `exp`
319
+ and `nbf` with `clockSkew` seconds of tolerance (default 60), `sub`;
320
+ - `token_use` is not `test`: a portal test token is never accepted;
321
+ - when the token carries `cnf.jkt`, the request used the `DPoP` scheme and
322
+ its proof is signed by that key, names the request (`htm`, `htu`), the
323
+ token (`ath`) and a fresh `jti` (replay window 300 s), within the `iat`
324
+ window. `requireDpop: true` refuses tokens without `cnf.jkt`.
325
+
326
+ The result is the typed claims: `sub` (`agent_agt_…` or a user id),
327
+ `scope` (`accessTokenScopes(claims)` splits it), `is_agent`,
328
+ `capabilities`, `act` (the actor chain) and `cnf`. A failed check throws
329
+ `AccessTokenError` with `statusCode` 401 and `code` `invalid_token`,
330
+ `invalid_dpop_proof` or `jwks_fetch_failed`. Answer a failure with
331
+ `WWW-Authenticate: DPoP error="<code>"` (or `Bearer …`).
332
+
333
+ The in-memory `jti` replay cache covers one process. Pass `replayCache`
334
+ (`{ add(key, ttlSeconds) }`) backed by a shared store when the MCP server
335
+ has several replicas. `verifyDpopProof(proof, { method, url, accessToken?,
336
+ nonce? })` is exported on its own for servers that bind tokens differently.
337
+
338
+ Then ask LumoAuth whether the caller may run the tool with
339
+ [`mcp.authorizeTool`](../../README.md#check-mcp-tool-calls), using
340
+ `claims.sub` as the subject.
341
+
342
+ ## AAuth: cryptographic agent identity
343
+
344
+ AAuth gives an agent an identity that a resource server can verify without a
345
+ shared secret. The agent holds an Ed25519 or RSA key pair. It signs each
346
+ request with RFC 9421 HTTP message signatures and presents
347
+ proof-of-possession tokens. The protocol has four token requests (`auth`,
348
+ `code`, `exchange` and `refresh`), which support user consent and delegation
349
+ across several agents.
350
+
351
+ ### Set up the key
352
+
353
+ ```ts
354
+ import { generateKeypair } from '@lumoauth/agent';
355
+
356
+ const { privateKeyPem, jwks } = generateKeypair(); // Ed25519, kid "key-1"
357
+ // Store privateKeyPem in your secret manager. Register jwks with your organization.
358
+ ```
359
+
360
+ ### Agent side
361
+
362
+ ```ts
363
+ import { AAuthClient } from '@lumoauth/agent';
364
+
365
+ const aauth = new AAuthClient({
366
+ agentIdentifier: 'https://my-agent.example.com', // an HTTPS URL that names the agent
367
+ privateKeyPem: process.env.AGENT_PRIVATE_KEY!,
368
+ orgId: 'acme-corp',
369
+ });
370
+
371
+ const result = await aauth.requestAuthToken({ resourceToken, agentToken, scope: 'read write' });
372
+
373
+ if ('authorizationRequired' in result) {
374
+ // The user has to consent first. Send them to result.authorizationUri,
375
+ // then call aauth.exchangeCode({ code, redirectUri, agentToken }).
376
+ } else {
377
+ const res = await aauth.signedRequest('GET', 'https://api.example.com/v1/data', {
378
+ authToken: result.authToken,
379
+ });
380
+ }
381
+ ```
382
+
383
+ `resourceToken` is the resource token that the target resource issued to the
384
+ agent. `agentToken` is the agent's own `agent+jwt`, sent in the `Agent-Auth`
385
+ header.
386
+
387
+ ### `AAuthClient` options
388
+
389
+ | Option | Default | Description |
390
+ |---|---|---|
391
+ | `agentIdentifier` | required | The HTTPS URL that names the agent |
392
+ | `privateKeyPem` | required | A PEM Ed25519 (PKCS#8) or RSA private key |
393
+ | `baseUrl` | `LUMOAUTH_URL`, then `https://app.lumoauth.dev` | The LumoAuth host |
394
+ | `orgId` | `LUMOAUTH_ORG_ID` | The organization slug |
395
+ | `kid` | `key-1` | The key ID. It must match the registered JWKS entry |
396
+ | `fetch` | global `fetch` | A custom `fetch` |
397
+ | `timeout` | 30 000 ms | Request timeout |
398
+
399
+ ### `AAuthClient` methods
400
+
401
+ | Method | What it does |
402
+ |---|---|
403
+ | `requestAuthToken({ resourceToken, agentToken, scope?, redirectUri? })` | Requests an auth token. Returns the token, or `{ authorizationRequired: true, requestToken, authorizationUri }` when the user must consent |
404
+ | `buildConsentUrl(requestToken)` | Builds the consent URL for a pending request token |
405
+ | `exchangeCode({ code, redirectUri, agentToken })` | Exchanges the consent code for an auth token |
406
+ | `exchangeToken({ authToken, resourceToken, agentToken })` | Exchanges an upstream auth token for a downstream one, which adds to the `act` chain |
407
+ | `refresh({ refreshToken, resourceToken, scope?, agentToken })` | Refreshes an auth token. It needs a fresh resource token |
408
+ | `revoke({ token, tokenType?, agentToken })` | Revokes an auth token by its `jti`, or a refresh token by value |
409
+ | `signRequest(method, url, options?)` | Returns RFC 9421 signature headers for a request |
410
+ | `signedRequest(method, url, { authToken, data?, headers? })` | Sends a signed request with the auth token, and returns the `fetch` `Response` |
411
+ | `verifyAuthToken(token, { resource, jwks?, clockSkew?, issuer? })` | Verifies a token. The issuer defaults to this organization's issuer |
412
+ | `discoverIssuer()`, `discoverAgents()`, `discoverResource(url)` | Read the AAuth metadata documents |
413
+ | `issuer`, `publicJwk`, `publicJwkThumbprint` | The issuer URL and the agent's public key |
414
+
415
+ ### Resource-server side
416
+
417
+ ```ts
418
+ import { verifyAuthToken } from '@lumoauth/agent';
419
+
420
+ const claims = await verifyAuthToken(bearer, {
421
+ issuer: 'https://app.lumoauth.dev/orgs/acme-corp/api/v1',
422
+ resource: 'https://api.example.com', // must equal the token's aud
423
+ });
424
+ // Then check the request signature against claims.cnf.jwk.
425
+ ```
426
+
427
+ `verifyAuthToken()` fetches the issuer's keys unless you pass `jwks`. It
428
+ accepts only asymmetric algorithms, so `HS*` and `none` always fail. It allows
429
+ no clock skew on `exp` unless you set `clockSkew` in seconds. It throws
430
+ `AAuthError` when a check fails.
431
+
432
+ ### Exports
433
+
434
+ | Group | Exports |
435
+ |---|---|
436
+ | Client | `AAuthClient` |
437
+ | Keys | `generateKeypair`, `publicJwkFromPrivateKey`, `jwkThumbprint` |
438
+ | Signing primitives (RFC 9421) | `signRequest`, `buildSignatureBase`, `signatureParams`, `signSignatureBase`, `verifySignatureBase`, `contentDigestSha256`, `generateNonce`, `AAUTH_COVERED_COMPONENTS` |
439
+ | Verification | `verifyAuthToken`, `decodeJwt` |
440
+ | Errors | `AAuthError` |
441
+ | DPoP (RFC 9449) | `DpopProofSigner`, `dpopAth`, `dpopHtu`, `buildDpopHeaders`, `fetchWithDpop`, `DPOP_SCHEME`, `DPOP_NONCE_HEADER`, `USE_DPOP_NONCE`, `attestWorkload` |
442
+ | Access token verification | `verifyAccessToken`, `createAccessTokenVerifier`, `verifyDpopProof`, `parseAuthorizationHeader`, `accessTokenScopes`, `AccessTokenError`, `JwksCache`, `InMemoryDpopReplayCache` |
443
+
444
+ The signing code is tested byte for byte against the shared test vector in
445
+ [`sdk-contract`](https://github.com/LumoAuth/sdk-contract). Signatures made
446
+ here therefore verify in the Python, Go, PHP, Java and .NET SDKs, and the
447
+ other way round.
448
+
449
+ ## Errors
450
+
451
+ This package re-exports the error classes of
452
+ [`@lumoauth/shared`](../shared/README.md#errors). The ones that agents meet
453
+ most often are:
454
+
455
+ | Class | When |
456
+ |---|---|
457
+ | `LumoAuthConfigError` | The client ID, client secret or `orgId` is missing |
458
+ | `LumoAuthApiError` | Sign-in failed: the server rejected the client credentials. `statusCode` holds the HTTP status |
459
+ | `LumoAuthAuthenticationError` | A later call got 401, for example because the agent was suspended |
460
+ | `LumoAuthPermissionDeniedError` | The server rejected the call. `requiredScopes` names a missing scope, when there is one |
461
+ | `LumoAuthRateLimitError` | Too many requests. `retryAfter` holds the wait in seconds |
462
+ | `LumoAuthApprovalDeniedError`, `LumoAuthApprovalTimeoutError` | A person declined, or nobody answered in time |
463
+ | `LumoAuthApprovalNotDeliveredError` | The approval prompt reached no device. `reason` is `email_fallback_sent` or `no_enrolled_device`, and `taskId` names the task |
464
+ | `LumoAuthBudgetExceededError` | The agent ran out of budget |
465
+ | `AAuthError` | An AAuth request or a token check failed |
466
+ | `AccessTokenError` | `verifyAccessToken` refused a token or its DPoP proof. `code` is `invalid_token`, `invalid_dpop_proof` or `jwks_fetch_failed` |
467
+
468
+ ## Troubleshooting
469
+
470
+ | Symptom | Cause | Fix |
471
+ |---|---|---|
472
+ | `LumoAuthConfigError` at construction | `AGENT_CLIENT_ID` or `AGENT_CLIENT_SECRET` is not set | Set both, or pass `clientId` and `clientSecret` |
473
+ | `LumoAuthConfigError` that mentions `orgId` | `LUMOAUTH_ORG_ID` is not set | Set it, or pass `orgId` |
474
+ | 403 `test_token_not_accepted` from approvals, or 401 on a JIT route | The call used a portal test token | Use the agent's real credentials |
475
+ | 403 on `jit.listPendingRequests()` | It is the reviewer's view and needs a user token with `jit:approve` | Call it from the reviewer's app |
476
+ | `invalid_grant` from `delegation.exchange()` | The declared token type does not match, the user is no longer active, or the subject is a JIT token | Fix `subjectTokenType`, and use an active user token |
477
+ | 401 from an API with a delegated token | The token's `aud` is the agent ID | Pass `resource` to `exchange()` |
478
+ | `approvals.require()` throws `LumoAuthApprovalNotDeliveredError` | The user has no enrolled push device. With `reason` `email_fallback_sent`, the server emailed them a notice | Ask the user to enrol the LumoAuth app, then ask again |
479
+ | `mcp.getToken()` throws `LumoAuthValidationError` | The server ID is not an https URL, for example `urn:mcp:…` | Pass the MCP server's URL |
480
+ | 401 `invalid_dpop_proof` from an MCP server | The MCP server requires DPoP and the token is not bound, or the request has no proof | Pass `dpop: DpopProofSigner.generate()` to `LumoAgent`, and send each request with `buildDpopHeaders()` |
481
+ | `invalid_dpop_proof` on the token endpoint | The proof's `htu` or `iat` is off | Check the clock, and build the proof from the exact request URL |
482
+
483
+ ## Related packages
484
+
485
+ | Package | How it relates |
486
+ |---|---|
487
+ | [`create-lumo-agent`](../create-lumo-agent/README.md) | Creates a complete agent app with one command |
488
+ | [`@lumoauth/backend`](../backend/README.md) | The same namespaces for a server that holds a user's token instead of agent credentials |
489
+ | [`@lumoauth/shared`](../shared/README.md) | The core that this package re-exports |
490
+ | [Workspace README](../../README.md) | How all of the packages fit together, with guides and the full API reference |
491
+
492
+ ## Learn more
46
493
 
47
- https://docs.lumoauth.dev
494
+ - [Enable security for AI agents](https://docs.lumoauth.dev/quickstarts/ai-agent-security/)
495
+ - [AAuth quickstart](https://docs.lumoauth.dev/agents/aauth-quickstart/)
496
+ - [SDK overview](https://docs.lumoauth.dev/developer/sdks/)
48
497
 
49
498
  ## License
50
499
 
51
- MIT
500
+ [MIT](./LICENSE)