@lumoauth/agent 1.1.0 → 1.3.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 +145 -5
- package/dist/index.d.mts +458 -4
- package/dist/index.d.ts +458 -4
- package/dist/index.js +858 -57
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +839 -33
- package/dist/index.mjs.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -21,6 +21,9 @@ sure that it is the package that you need? See
|
|
|
21
21
|
- [Configuration](#configuration)
|
|
22
22
|
- [Guides](#guides)
|
|
23
23
|
- [`LumoAgent` reference](#lumoagent-reference)
|
|
24
|
+
- [Private key JWT: sign in without a secret](#private-key-jwt-sign-in-without-a-secret)
|
|
25
|
+
- [DPoP: sender-constrained tokens](#dpop-sender-constrained-tokens)
|
|
26
|
+
- [Verify LumoAuth access tokens on an MCP server](#verify-lumoauth-access-tokens-on-an-mcp-server)
|
|
24
27
|
- [AAuth: cryptographic agent identity](#aauth-cryptographic-agent-identity)
|
|
25
28
|
- [Errors](#errors)
|
|
26
29
|
- [Troubleshooting](#troubleshooting)
|
|
@@ -34,7 +37,9 @@ sure that it is the package that you need? See
|
|
|
34
37
|
|---|---|
|
|
35
38
|
| 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` |
|
|
36
39
|
| Building or calling an agent that needs a verifiable cryptographic identity, signed requests, or delegation between agents | **This package**, `AAuthClient` |
|
|
40
|
+
| Building an MCP server or another resource server that must verify LumoAuth access tokens, with or without DPoP | **This package**, `verifyAccessToken` |
|
|
37
41
|
| Building a resource server that must verify incoming AAuth tokens | **This package**, `verifyAuthToken` |
|
|
42
|
+
| Calling an MCP server that requires DPoP-bound tokens | **This package**, `DpopProofSigner` |
|
|
38
43
|
| Starting a new agent app | [`npx create-lumo-agent`](../create-lumo-agent/README.md) |
|
|
39
44
|
| Writing an ordinary backend that acts for a user, not as an agent | [`@lumoauth/backend`](../backend/README.md) |
|
|
40
45
|
|
|
@@ -95,14 +100,19 @@ grant. The SDK refreshes the token 60 seconds before it expires.
|
|
|
95
100
|
| `baseUrl` | `LUMOAUTH_URL` | `https://app.lumoauth.dev` | The LumoAuth host. Use `https://eu.app.lumoauth.dev` for the EU region |
|
|
96
101
|
| `orgId` | `LUMOAUTH_ORG_ID` | none | The organization slug. Every namespace needs it |
|
|
97
102
|
| `clientId` | `AGENT_CLIENT_ID` | required | The agent's OAuth client ID |
|
|
98
|
-
| `clientSecret` | `AGENT_CLIENT_SECRET` | required | The agent's OAuth client secret |
|
|
103
|
+
| `clientSecret` | `AGENT_CLIENT_SECRET` | required unless `privateKey` | The agent's OAuth client secret |
|
|
104
|
+
| `privateKey` | `AGENT_PRIVATE_KEY` (PEM) | none | For a **Private key JWT** agent: a `ClientAssertionSigner` or the PEM private key. The agent then signs a client assertion instead of sending a secret. See [Private key JWT](#private-key-jwt-sign-in-without-a-secret) |
|
|
105
|
+
| `keyId` | `AGENT_KEY_ID` | none | The `kid` of the registered public key, used with a PEM `privateKey` |
|
|
106
|
+
| `issuer` | none | `{baseUrl}/orgs/{orgId}/api/v1` | The organization's issuer identifier, the assertion's `aud`. Set it on a custom domain |
|
|
99
107
|
| `scopes` | none | the agent's defaults | Scopes to request |
|
|
100
108
|
| `redirectUri` | none | none | The callback URL of the delegation consent flow |
|
|
101
109
|
| `timeout` | none | 30 000 ms | Request timeout |
|
|
102
110
|
| `fetch` | none | global `fetch` | A custom `fetch` |
|
|
111
|
+
| `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) |
|
|
103
112
|
|
|
104
|
-
The constructor throws `LumoAuthConfigError` when the client ID
|
|
105
|
-
secret is
|
|
113
|
+
The constructor throws `LumoAuthConfigError` when the client ID is missing, when
|
|
114
|
+
neither a client secret nor a private key is given, or when both are. It does not
|
|
115
|
+
call the server.
|
|
106
116
|
|
|
107
117
|
## Guides
|
|
108
118
|
|
|
@@ -214,6 +224,8 @@ consent steps. The token types and the `resource` option are explained in the
|
|
|
214
224
|
| `authenticate(scopes?)` | `Promise<string>` | Runs the client credentials grant now. You rarely need it, because every call signs in when needed |
|
|
215
225
|
| `getAccessToken()` | `Promise<string>` | The current access token, refreshed when it is about to expire |
|
|
216
226
|
| `tokenScopes` | `string[]` | The scopes that the server granted to the current token |
|
|
227
|
+
| `tokenType` | `string \| null` | `DPoP` when the current token is sender-constrained, otherwise `Bearer`; `null` before the first sign-in |
|
|
228
|
+
| `dpopSigner` | `DpopProofProvider \| undefined` | The signer passed as `dpop` |
|
|
217
229
|
| `ask(action, context?)` | `Promise<AgentAskResult>` | The full decision for an action |
|
|
218
230
|
| `isAllowed(action, context?)` | `Promise<boolean>` | `ask()` reduced to a boolean |
|
|
219
231
|
| `getCurrentAgent()` | `Promise<AgentIdentity>` | The agent's identity, capabilities and workspace |
|
|
@@ -225,15 +237,138 @@ consent steps. The token types and the `resource` option are explained in the
|
|
|
225
237
|
|
|
226
238
|
| Namespace | What it does | Methods |
|
|
227
239
|
|---|---|---|
|
|
228
|
-
| `agents` | Agent identity | `ask`, `isAllowed`, `me`, `getCurrentAgent`, `capabilities`, `budget`, `register` |
|
|
240
|
+
| `agents` | Agent identity | `ask`, `isAllowed`, `me`, `getCurrentAgent`, `capabilities`, `budget`, `register`, `authorizeMcpTool(serverId, tool)` |
|
|
229
241
|
| `approvals` | Push approval for agent actions | `require`, `create`, `getStatus`, `wait` |
|
|
230
242
|
| `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 |
|
|
231
243
|
| `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` |
|
|
232
|
-
| `mcp` |
|
|
244
|
+
| `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` |
|
|
233
245
|
|
|
234
246
|
The parameters of each method are in the
|
|
235
247
|
[workspace API reference](../../README.md#api-reference).
|
|
236
248
|
|
|
249
|
+
## Private key JWT: sign in without a secret
|
|
250
|
+
|
|
251
|
+
An agent registered with the **Private key JWT** identity type has no client
|
|
252
|
+
secret. Whenever it needs a token, it signs a short-lived JWT (a client
|
|
253
|
+
assertion, RFC 7523) with its private key. Only the public key is registered.
|
|
254
|
+
|
|
255
|
+
```ts
|
|
256
|
+
import { ClientAssertionSigner, LumoAgent } from '@lumoauth/agent';
|
|
257
|
+
|
|
258
|
+
const signer = ClientAssertionSigner.generate('ES256', 'agent-2026-11');
|
|
259
|
+
// Store signer.privateKeyPem in your secret store; paste signer.jwks into the agent's public keys.
|
|
260
|
+
|
|
261
|
+
const agent = new LumoAgent({
|
|
262
|
+
clientId: 'agt_0123456789abcdef',
|
|
263
|
+
privateKey: ClientAssertionSigner.fromPem(process.env.AGENT_PRIVATE_KEY!, { keyId: 'agent-2026-11' }),
|
|
264
|
+
});
|
|
265
|
+
await agent.authenticate();
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
Every token request carries a new assertion: `iss` and `sub` are the agent ID,
|
|
269
|
+
`aud` is the organization's issuer identifier, `exp` is 60 seconds ahead and
|
|
270
|
+
`jti` is random. `ClientAssertionSigner` signs with ES256, ES384, ES512,
|
|
271
|
+
EdDSA, RS256 to RS512 or PS256 to PS512; `agent.createClientAssertion()` gives
|
|
272
|
+
you one for another call. Combine it with `dpop` to also bind the tokens to a key.
|
|
273
|
+
|
|
274
|
+
## DPoP: sender-constrained tokens
|
|
275
|
+
|
|
276
|
+
An MCP server registered with "Require DPoP" accepts only tokens that are
|
|
277
|
+
bound to the caller's key (RFC 9449). Give the agent a `DpopProofSigner`.
|
|
278
|
+
The client-credentials token, every MCP token exchange, every delegation
|
|
279
|
+
exchange and every API call then carry a DPoP proof, and the tokens come
|
|
280
|
+
back with `token_type: "DPoP"`. The server's `use_dpop_nonce` answer is
|
|
281
|
+
retried once, and the latest `DPoP-Nonce` is remembered per origin.
|
|
282
|
+
|
|
283
|
+
```ts
|
|
284
|
+
import { LumoAgent, DpopProofSigner, buildDpopHeaders } from '@lumoauth/agent';
|
|
285
|
+
|
|
286
|
+
// One key per agent instance. ES256 (P-256) by default; 'EdDSA' reuses an
|
|
287
|
+
// Ed25519 key, so the AAuth key can double as the DPoP key.
|
|
288
|
+
const dpop = DpopProofSigner.generate();
|
|
289
|
+
// Or load one: new DpopProofSigner({ privateKeyPem: process.env.AGENT_DPOP_KEY! })
|
|
290
|
+
|
|
291
|
+
const agent = new LumoAgent({ dpop });
|
|
292
|
+
|
|
293
|
+
const mcp = await agent.mcp.getTokenDetailed('https://mcp.example.com/mcp');
|
|
294
|
+
// mcp.tokenType === 'DPoP'
|
|
295
|
+
|
|
296
|
+
// Each MCP request needs a fresh proof that names the token (ath).
|
|
297
|
+
const headers = await buildDpopHeaders(dpop, {
|
|
298
|
+
method: 'POST',
|
|
299
|
+
url: 'https://mcp.example.com/mcp',
|
|
300
|
+
accessToken: mcp.accessToken,
|
|
301
|
+
tokenType: mcp.tokenType, // 'Bearer' here falls back to a plain Bearer header
|
|
302
|
+
});
|
|
303
|
+
await fetch('https://mcp.example.com/mcp', { method: 'POST', headers, body });
|
|
304
|
+
```
|
|
305
|
+
|
|
306
|
+
`fetchWithDpop(fetch, url, init, dpop, { accessToken })` does the same and
|
|
307
|
+
also retries a `use_dpop_nonce` challenge from the MCP server.
|
|
308
|
+
|
|
309
|
+
| Export | What it does |
|
|
310
|
+
|---|---|
|
|
311
|
+
| `DpopProofSigner.generate(alg?)` | A new key: `'ES256'` (default), `'EdDSA'` or `'RS256'` |
|
|
312
|
+
| `new DpopProofSigner({ privateKeyPem })` | Loads an EC P-256, Ed25519 or RSA PEM key. `privateKeyPem` reads it back |
|
|
313
|
+
| `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 |
|
|
314
|
+
| `signer.jwk`, `signer.thumbprint` | The public key and its RFC 7638 thumbprint (the `cnf.jkt` of bound tokens) |
|
|
315
|
+
| `signer.setNonce(url, nonce)`, `getNonce(url)`, `clearNonces()` | Nonce memory per origin |
|
|
316
|
+
| `buildDpopHeaders(signer, { method, url, accessToken, tokenType? })` | `{ Authorization: 'DPoP …', DPoP }`, or `{ Authorization: 'Bearer …' }` for an unbound token |
|
|
317
|
+
| `fetchWithDpop(fetch, url, init, signer, { accessToken? })` | `fetch` with the proof and the one-time nonce retry |
|
|
318
|
+
| `attestWorkload({ orgId, agentId, attestationToken, dpop? })` | Workload attestation (`POST …/agents/{agentId}/attest`) with an optional proof; returns `{ accessToken, tokenType, expiresIn, scope, identity }` |
|
|
319
|
+
|
|
320
|
+
## Verify LumoAuth access tokens on an MCP server
|
|
321
|
+
|
|
322
|
+
The token an MCP server receives is a LumoAuth `at+jwt` access token whose
|
|
323
|
+
`aud` is the server's resource URI. Verify it locally, without a call to
|
|
324
|
+
LumoAuth per request:
|
|
325
|
+
|
|
326
|
+
```ts
|
|
327
|
+
import { createAccessTokenVerifier } from '@lumoauth/agent';
|
|
328
|
+
|
|
329
|
+
const verifier = createAccessTokenVerifier({
|
|
330
|
+
issuer: 'https://app.lumoauth.dev/orgs/acme-corp/api/v1',
|
|
331
|
+
resource: 'https://mcp.example.com/mcp', // must be in the token's aud
|
|
332
|
+
});
|
|
333
|
+
const claims = await verifier.verifyRequest({ method: req.method, url: publicUrl, headers: req.headers });
|
|
334
|
+
```
|
|
335
|
+
|
|
336
|
+
`verifyRequest` reads `Authorization` (scheme `Bearer` or `DPoP`) and the
|
|
337
|
+
`DPoP` header. `verifier.verify(token, dpop?)` takes the token directly, and
|
|
338
|
+
the plain function `verifyAccessToken(token, { issuer, resource, … })` does
|
|
339
|
+
the same with a process-wide key cache.
|
|
340
|
+
|
|
341
|
+
The verifier fetches the organization's keys from
|
|
342
|
+
`{issuer}/.well-known/openid-configuration` (`jwks_uri`), caches them and
|
|
343
|
+
fetches them again once when a token names an unknown `kid`. Pass `jwks` to
|
|
344
|
+
skip the network. It checks:
|
|
345
|
+
|
|
346
|
+
- `typ` is `at+jwt` or `application/at+jwt`; `alg` is asymmetric (`none`
|
|
347
|
+
and `HS*` are refused); `kid` resolves;
|
|
348
|
+
- the signature, `iss`, `aud` (string or array) contains `resource`, `exp`
|
|
349
|
+
and `nbf` with `clockSkew` seconds of tolerance (default 60), `sub`;
|
|
350
|
+
- `token_use` is not `test`: a portal test token is never accepted;
|
|
351
|
+
- when the token carries `cnf.jkt`, the request used the `DPoP` scheme and
|
|
352
|
+
its proof is signed by that key, names the request (`htm`, `htu`), the
|
|
353
|
+
token (`ath`) and a fresh `jti` (replay window 300 s), within the `iat`
|
|
354
|
+
window. `requireDpop: true` refuses tokens without `cnf.jkt`.
|
|
355
|
+
|
|
356
|
+
The result is the typed claims: `sub` (`agent_agt_…` or a user id),
|
|
357
|
+
`scope` (`accessTokenScopes(claims)` splits it), `is_agent`,
|
|
358
|
+
`capabilities`, `act` (the actor chain) and `cnf`. A failed check throws
|
|
359
|
+
`AccessTokenError` with `statusCode` 401 and `code` `invalid_token`,
|
|
360
|
+
`invalid_dpop_proof` or `jwks_fetch_failed`. Answer a failure with
|
|
361
|
+
`WWW-Authenticate: DPoP error="<code>"` (or `Bearer …`).
|
|
362
|
+
|
|
363
|
+
The in-memory `jti` replay cache covers one process. Pass `replayCache`
|
|
364
|
+
(`{ add(key, ttlSeconds) }`) backed by a shared store when the MCP server
|
|
365
|
+
has several replicas. `verifyDpopProof(proof, { method, url, accessToken?,
|
|
366
|
+
nonce? })` is exported on its own for servers that bind tokens differently.
|
|
367
|
+
|
|
368
|
+
Then ask LumoAuth whether the caller may run the tool with
|
|
369
|
+
[`mcp.authorizeTool`](../../README.md#check-mcp-tool-calls), using
|
|
370
|
+
`claims.sub` as the subject.
|
|
371
|
+
|
|
237
372
|
## AAuth: cryptographic agent identity
|
|
238
373
|
|
|
239
374
|
AAuth gives an agent an identity that a resource server can verify without a
|
|
@@ -333,6 +468,8 @@ no clock skew on `exp` unless you set `clockSkew` in seconds. It throws
|
|
|
333
468
|
| Signing primitives (RFC 9421) | `signRequest`, `buildSignatureBase`, `signatureParams`, `signSignatureBase`, `verifySignatureBase`, `contentDigestSha256`, `generateNonce`, `AAUTH_COVERED_COMPONENTS` |
|
|
334
469
|
| Verification | `verifyAuthToken`, `decodeJwt` |
|
|
335
470
|
| Errors | `AAuthError` |
|
|
471
|
+
| DPoP (RFC 9449) | `DpopProofSigner`, `dpopAth`, `dpopHtu`, `buildDpopHeaders`, `fetchWithDpop`, `DPOP_SCHEME`, `DPOP_NONCE_HEADER`, `USE_DPOP_NONCE`, `attestWorkload` |
|
|
472
|
+
| Access token verification | `verifyAccessToken`, `createAccessTokenVerifier`, `verifyDpopProof`, `parseAuthorizationHeader`, `accessTokenScopes`, `AccessTokenError`, `JwksCache`, `InMemoryDpopReplayCache` |
|
|
336
473
|
|
|
337
474
|
The signing code is tested byte for byte against the shared test vector in
|
|
338
475
|
[`sdk-contract`](https://github.com/LumoAuth/sdk-contract). Signatures made
|
|
@@ -356,6 +493,7 @@ most often are:
|
|
|
356
493
|
| `LumoAuthApprovalNotDeliveredError` | The approval prompt reached no device. `reason` is `email_fallback_sent` or `no_enrolled_device`, and `taskId` names the task |
|
|
357
494
|
| `LumoAuthBudgetExceededError` | The agent ran out of budget |
|
|
358
495
|
| `AAuthError` | An AAuth request or a token check failed |
|
|
496
|
+
| `AccessTokenError` | `verifyAccessToken` refused a token or its DPoP proof. `code` is `invalid_token`, `invalid_dpop_proof` or `jwks_fetch_failed` |
|
|
359
497
|
|
|
360
498
|
## Troubleshooting
|
|
361
499
|
|
|
@@ -369,6 +507,8 @@ most often are:
|
|
|
369
507
|
| 401 from an API with a delegated token | The token's `aud` is the agent ID | Pass `resource` to `exchange()` |
|
|
370
508
|
| `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 |
|
|
371
509
|
| `mcp.getToken()` throws `LumoAuthValidationError` | The server ID is not an https URL, for example `urn:mcp:…` | Pass the MCP server's URL |
|
|
510
|
+
| 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()` |
|
|
511
|
+
| `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 |
|
|
372
512
|
|
|
373
513
|
## Related packages
|
|
374
514
|
|