@lumoauth/agent 1.1.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
@@ -21,6 +21,8 @@ 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
+ - [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)
24
26
  - [AAuth: cryptographic agent identity](#aauth-cryptographic-agent-identity)
25
27
  - [Errors](#errors)
26
28
  - [Troubleshooting](#troubleshooting)
@@ -34,7 +36,9 @@ sure that it is the package that you need? See
34
36
  |---|---|
35
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` |
36
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` |
37
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` |
38
42
  | Starting a new agent app | [`npx create-lumo-agent`](../create-lumo-agent/README.md) |
39
43
  | Writing an ordinary backend that acts for a user, not as an agent | [`@lumoauth/backend`](../backend/README.md) |
40
44
 
@@ -100,6 +104,7 @@ grant. The SDK refreshes the token 60 seconds before it expires.
100
104
  | `redirectUri` | none | none | The callback URL of the delegation consent flow |
101
105
  | `timeout` | none | 30 000 ms | Request timeout |
102
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) |
103
108
 
104
109
  The constructor throws `LumoAuthConfigError` when the client ID or the client
105
110
  secret is missing. It does not call the server.
@@ -214,6 +219,8 @@ consent steps. The token types and the `resource` option are explained in the
214
219
  | `authenticate(scopes?)` | `Promise<string>` | Runs the client credentials grant now. You rarely need it, because every call signs in when needed |
215
220
  | `getAccessToken()` | `Promise<string>` | The current access token, refreshed when it is about to expire |
216
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` |
217
224
  | `ask(action, context?)` | `Promise<AgentAskResult>` | The full decision for an action |
218
225
  | `isAllowed(action, context?)` | `Promise<boolean>` | `ask()` reduced to a boolean |
219
226
  | `getCurrentAgent()` | `Promise<AgentIdentity>` | The agent's identity, capabilities and workspace |
@@ -225,15 +232,113 @@ consent steps. The token types and the `resource` option are explained in the
225
232
 
226
233
  | Namespace | What it does | Methods |
227
234
  |---|---|---|
228
- | `agents` | Agent identity | `ask`, `isAllowed`, `me`, `getCurrentAgent`, `capabilities`, `budget`, `register` |
235
+ | `agents` | Agent identity | `ask`, `isAllowed`, `me`, `getCurrentAgent`, `capabilities`, `budget`, `register`, `authorizeMcpTool(serverId, tool)` |
229
236
  | `approvals` | Push approval for agent actions | `require`, `create`, `getStatus`, `wait` |
230
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 |
231
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` |
232
- | `mcp` | Token exchange for 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` |
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` |
233
240
 
234
241
  The parameters of each method are in the
235
242
  [workspace API reference](../../README.md#api-reference).
236
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';
298
+
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 });
304
+ ```
305
+
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
+
237
342
  ## AAuth: cryptographic agent identity
238
343
 
239
344
  AAuth gives an agent an identity that a resource server can verify without a
@@ -333,6 +438,8 @@ no clock skew on `exp` unless you set `clockSkew` in seconds. It throws
333
438
  | Signing primitives (RFC 9421) | `signRequest`, `buildSignatureBase`, `signatureParams`, `signSignatureBase`, `verifySignatureBase`, `contentDigestSha256`, `generateNonce`, `AAUTH_COVERED_COMPONENTS` |
334
439
  | Verification | `verifyAuthToken`, `decodeJwt` |
335
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` |
336
443
 
337
444
  The signing code is tested byte for byte against the shared test vector in
338
445
  [`sdk-contract`](https://github.com/LumoAuth/sdk-contract). Signatures made
@@ -356,6 +463,7 @@ most often are:
356
463
  | `LumoAuthApprovalNotDeliveredError` | The approval prompt reached no device. `reason` is `email_fallback_sent` or `no_enrolled_device`, and `taskId` names the task |
357
464
  | `LumoAuthBudgetExceededError` | The agent ran out of budget |
358
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` |
359
467
 
360
468
  ## Troubleshooting
361
469
 
@@ -369,6 +477,8 @@ most often are:
369
477
  | 401 from an API with a delegated token | The token's `aud` is the agent ID | Pass `resource` to `exchange()` |
370
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 |
371
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 |
372
482
 
373
483
  ## Related packages
374
484
 
package/dist/index.d.mts CHANGED
@@ -1,5 +1,5 @@
1
- import { AgentsModule, JitModule, DelegationModule, ApprovalsModule, McpModule, AgentAskResult, AgentIdentity, AgentBudget, LumoAuthError } from '@lumoauth/shared';
2
- export { ApprovalNotDeliveredReason, ApprovalRequestResult, ApprovalResult, CreateApprovalRequest, LumoAuthApiError, LumoAuthApprovalDeniedError, LumoAuthApprovalNotDeliveredError, LumoAuthApprovalTimeoutError, LumoAuthAuthenticationError, LumoAuthBudgetExceededError, LumoAuthConfigError, LumoAuthError, LumoAuthNetworkError, LumoAuthNotFoundError, LumoAuthPermissionDeniedError, LumoAuthRateLimitError, LumoAuthValidationError, RequireApprovalRequest } from '@lumoauth/shared';
1
+ import { AgentsModule, JitModule, DelegationModule, ApprovalsModule, McpModule, DpopProofProvider, AgentAskResult, AgentMcpToolDecision, AgentIdentity, AgentBudget, DpopProofRequest, LumoAuthError } from '@lumoauth/shared';
2
+ export { AgentMcpToolDecision, ApprovalNotDeliveredReason, ApprovalRequestResult, ApprovalResult, CreateApprovalRequest, DPOP_NONCE_HEADER, DPOP_SCHEME, DpopHeadersInput, DpopProofProvider, DpopProofRequest, FetchWithDpopOptions, LumoAuthApiError, LumoAuthApprovalDeniedError, LumoAuthApprovalNotDeliveredError, LumoAuthApprovalTimeoutError, LumoAuthAuthenticationError, LumoAuthBudgetExceededError, LumoAuthConfigError, LumoAuthError, LumoAuthNetworkError, LumoAuthNotFoundError, LumoAuthPermissionDeniedError, LumoAuthRateLimitError, LumoAuthValidationError, McpAuthorizeToolOptions, McpSubject, McpSubjectType, McpToolDecision, McpToolResource, RequireApprovalRequest, USE_DPOP_NONCE, buildDpopHeaders, dpopHtu, fetchWithDpop } from '@lumoauth/shared';
3
3
  import { KeyObject } from 'node:crypto';
4
4
 
5
5
  interface LumoAgentOptions {
@@ -22,6 +22,14 @@ interface LumoAgentOptions {
22
22
  fetch?: typeof globalThis.fetch;
23
23
  /** Request timeout in milliseconds. Default: 30 000 ms. */
24
24
  timeout?: number;
25
+ /**
26
+ * DPoP proof signer (RFC 9449), e.g. `DpopProofSigner.generate()`. When
27
+ * set, the client-credentials token and every exchanged token (MCP,
28
+ * delegation) are sender-constrained to its key, and every request
29
+ * carries `Authorization: DPoP <token>` plus a proof. Needed for MCP
30
+ * servers registered with "Require DPoP".
31
+ */
32
+ dpop?: DpopProofProvider;
25
33
  }
26
34
  /**
27
35
  * High-level agent client — the Node.js counterpart of the Python SDK's
@@ -66,11 +74,12 @@ declare class LumoAgent {
66
74
  readonly delegation: DelegationModule;
67
75
  /** Push-approval-for-agent-actions. */
68
76
  readonly approvals: ApprovalsModule;
69
- /** Token exchange for secured MCP servers. */
77
+ /** MCP servers: token exchange and per-tool checks (`authorizeTool`). */
70
78
  readonly mcp: McpModule;
71
79
  private readonly clientSecret;
72
80
  private readonly scopes;
73
81
  private readonly fetchFn;
82
+ private readonly dpop;
74
83
  private token;
75
84
  private refreshPromise;
76
85
  constructor(options?: LumoAgentOptions);
@@ -80,6 +89,14 @@ declare class LumoAgent {
80
89
  * startup or to request non-default scopes.
81
90
  */
82
91
  authenticate(scopes?: string[]): Promise<string>;
92
+ /**
93
+ * `token_type` of the last successful authentication: `DPoP` when the
94
+ * token is sender-constrained, otherwise `Bearer`; `null` before the
95
+ * first sign-in. Present the token with that `Authorization` scheme.
96
+ */
97
+ get tokenType(): string | null;
98
+ /** The DPoP proof signer this agent was configured with, if any. */
99
+ get dpopSigner(): DpopProofProvider | undefined;
83
100
  /**
84
101
  * The current access token, re-authenticating transparently when it is
85
102
  * missing or within 60 s of expiry. Concurrent callers share one
@@ -92,6 +109,11 @@ declare class LumoAgent {
92
109
  ask(action: string, context?: Record<string, unknown>): Promise<AgentAskResult>;
93
110
  /** Convenience wrapper: `true` when `action` is allowed. */
94
111
  isAllowed(action: string, context?: Record<string, unknown>): Promise<boolean>;
112
+ /**
113
+ * May this agent run `tool` on the registered MCP server `serverId`?
114
+ * A deny returns `{ allowed: false }` and does not throw.
115
+ */
116
+ authorizeMcpTool(serverId: string, tool: string): Promise<AgentMcpToolDecision>;
95
117
  /** The agent's own identity, capabilities, and workspace. */
96
118
  getCurrentAgent(): Promise<AgentIdentity>;
97
119
  /** The agent's declared capability slugs. */
@@ -521,6 +543,325 @@ declare class AAuthClient {
521
543
  private doFetch;
522
544
  }
523
545
 
546
+ /**
547
+ * RFC 9449 DPoP proof signing.
548
+ *
549
+ * A `DpopProofSigner` holds the agent's DPoP key and mints proof JWTs for
550
+ * the token endpoint, the attestation endpoint and resource requests. The
551
+ * LumoAuth server (`DPoPService`) accepts ES256/ES384/ES512, RS256/RS384/
552
+ * RS512, PS256/PS384/PS512 and EdDSA; this signer produces ES256 (P-256,
553
+ * the default), EdDSA (Ed25519, so the AAuth key can double as the DPoP
554
+ * key) and RS256.
555
+ *
556
+ * Proof contents, as the server checks them:
557
+ * - header `typ: "dpop+jwt"`, `alg`, `jwk` (public members only);
558
+ * - `jti` 32 random characters, `htm` upper-case method, `htu` the URL
559
+ * without query or fragment, `iat` now (the server allows 60 s ahead and
560
+ * 300 s behind);
561
+ * - `ath` = base64url(SHA-256(access token)) on resource requests;
562
+ * - `nonce` when the server handed one out (`DPoP-Nonce`). The signer
563
+ * remembers the latest nonce per origin, so `fetchWithDpop` only has to
564
+ * retry once after a `use_dpop_nonce` answer.
565
+ */
566
+ type DpopAlgorithm = 'ES256' | 'EdDSA' | 'RS256';
567
+ interface DpopProofSignerOptions {
568
+ /** PEM (PKCS#8) private key: EC P-256, Ed25519 or RSA. */
569
+ privateKeyPem?: string;
570
+ /** A Node `KeyObject` private key, as an alternative to `privateKeyPem`. */
571
+ privateKey?: KeyObject;
572
+ /** Clock override in epoch seconds (tests only). */
573
+ now?: () => number;
574
+ }
575
+ /** The public JWK carried in a DPoP proof header. */
576
+ type DpopJwk = AAuthJwk;
577
+ declare class DpopProofSigner implements DpopProofProvider {
578
+ /** The JWS algorithm the proofs are signed with. */
579
+ readonly algorithm: DpopAlgorithm;
580
+ /** The public key as a JWK, with public members only. */
581
+ readonly jwk: DpopJwk;
582
+ /** RFC 7638 thumbprint of `jwk`: the `cnf.jkt` value of bound tokens. */
583
+ readonly thumbprint: string;
584
+ private readonly key;
585
+ private readonly now;
586
+ private readonly nonces;
587
+ /**
588
+ * Generate a fresh key. ES256 (P-256) by default; pass `'EdDSA'` for an
589
+ * Ed25519 key or `'RS256'` for a 2048-bit RSA key.
590
+ */
591
+ static generate(algorithm?: DpopAlgorithm): DpopProofSigner;
592
+ constructor(options: DpopProofSignerOptions);
593
+ /** The private key as PKCS#8 PEM, for your secret store. */
594
+ get privateKeyPem(): string;
595
+ /** Create one proof JWT. See the file comment for the claims. */
596
+ createProof(input: DpopProofRequest): string;
597
+ /** Remember the latest server nonce for the origin of `url`. */
598
+ setNonce(url: string, nonce: string): void;
599
+ /** The remembered nonce for the origin of `url`, if any. */
600
+ getNonce(url: string): string | undefined;
601
+ /** Forget every remembered nonce. */
602
+ clearNonces(): void;
603
+ }
604
+ /** `ath` for an access token: base64url(SHA-256(token)). */
605
+ declare function dpopAth(accessToken: string): string;
606
+
607
+ /**
608
+ * Workload attestation: `POST {issuer}/agents/{agentId}/attest`.
609
+ *
610
+ * The agent's runtime presents a cloud-issued OIDC token (GitHub Actions,
611
+ * GCP, AWS, Kubernetes, Azure, SPIFFE, …) and gets a short-lived LumoAuth
612
+ * access token for the agent, with no client secret in the environment.
613
+ * With a `dpop` signer the request carries an RFC 9449 proof and the token
614
+ * comes back sender-constrained (`tokenType: "DPoP"`).
615
+ *
616
+ * NOTE: this endpoint is not yet in sdk-contract/routes.json, so the path
617
+ * is built here rather than taken from the shared route registry.
618
+ */
619
+ interface AttestWorkloadOptions {
620
+ /** LumoAuth instance URL. Defaults to `LUMOAUTH_URL` or `https://app.lumoauth.dev`. */
621
+ baseUrl?: string;
622
+ /** Organization slug. Defaults to `LUMOAUTH_ORG_ID`. */
623
+ orgId?: string;
624
+ /** The agent id (`agt_…`). */
625
+ agentId: string;
626
+ /** The workload's OIDC token. */
627
+ attestationToken: string;
628
+ /** DPoP proof signer; the returned token is bound to its key. */
629
+ dpop?: DpopProofProvider;
630
+ /** Custom fetch implementation. */
631
+ fetch?: typeof globalThis.fetch;
632
+ }
633
+ interface AttestWorkloadResult {
634
+ accessToken: string;
635
+ /** `DPoP` when bound to the signer's key, otherwise `Bearer`. */
636
+ tokenType: string;
637
+ expiresIn: number | null;
638
+ /** Space-separated agent capabilities. */
639
+ scope: string | null;
640
+ /** The verified workload identity (`provider`, `subject`, `issuer`, …). */
641
+ identity: Record<string, unknown>;
642
+ }
643
+ declare function attestWorkload(options: AttestWorkloadOptions): Promise<AttestWorkloadResult>;
644
+
645
+ /**
646
+ * Local verification of LumoAuth core access tokens (`at+jwt`, RFC 9068).
647
+ *
648
+ * This is the token an MCP server or any other resource server receives
649
+ * from an agent or a delegated user: a token-exchange result with `aud` set
650
+ * to the resource URI, or an agent's client-credentials token. (AAuth
651
+ * `auth+jwt` tokens are a different format; see `verifyAuthToken`.)
652
+ *
653
+ * Checks, in order: compact JWS shape; `typ` is `at+jwt` or
654
+ * `application/at+jwt`; `alg` is an asymmetric JWS algorithm (`none` and
655
+ * HMAC are refused); `kid` resolves in the issuer's JWKS, which is read from
656
+ * `{issuer}/.well-known/openid-configuration` → `jwks_uri` and cached, with
657
+ * one refetch on an unknown `kid`; signature; `iss`; `aud` contains the
658
+ * resource; `exp` / `nbf` with a clock skew (default 60 s); `token_use` is
659
+ * not `test`; and, when the token carries `cnf.jkt`, the RFC 9449 proof
660
+ * binding of the incoming request.
661
+ */
662
+ /** OAuth Actor Profile actor object (`act` claim), nested for chains. */
663
+ interface ActorClaim {
664
+ /** `agent_agt_…` for an agent, a user id for a user. */
665
+ sub: string;
666
+ iss?: string;
667
+ /** Entity classification, e.g. `ai_agent` or `user`. */
668
+ sub_profile?: string;
669
+ name?: string;
670
+ act?: ActorClaim;
671
+ [claim: string]: unknown;
672
+ }
673
+ interface AccessTokenClaims {
674
+ iss: string;
675
+ /** `agent_agt_…` for an agent, the user id for a delegated token. */
676
+ sub: string;
677
+ aud: string | string[];
678
+ exp: number;
679
+ iat: number;
680
+ nbf?: number;
681
+ jti: string;
682
+ /** Space-separated scopes. */
683
+ scope?: string;
684
+ is_agent?: boolean;
685
+ capabilities?: string[];
686
+ act?: ActorClaim;
687
+ cnf?: {
688
+ jkt?: string;
689
+ [member: string]: unknown;
690
+ };
691
+ token_use?: string;
692
+ client_id?: string;
693
+ name?: string;
694
+ [claim: string]: unknown;
695
+ }
696
+ /** Pluggable replay cache for DPoP `jti` values. */
697
+ interface DpopReplayCache {
698
+ /**
699
+ * Record `key` for `ttlSeconds`. Return `true` when it was not seen
700
+ * before, `false` when it was (a replay).
701
+ */
702
+ add(key: string, ttlSeconds: number): boolean | Promise<boolean>;
703
+ }
704
+ /** The DPoP proof of an incoming request, for the binding check. */
705
+ interface IncomingDpopProof {
706
+ /** HTTP method of the incoming request. */
707
+ method: string;
708
+ /** Full URL of the incoming request (the public one, behind any proxy). */
709
+ url: string;
710
+ /** The `DPoP` request header. */
711
+ proof?: string | null;
712
+ /**
713
+ * The scheme of the `Authorization` header (`DPoP` or `Bearer`). A
714
+ * DPoP-bound token must arrive with the `DPoP` scheme.
715
+ */
716
+ authorizationScheme?: string | null;
717
+ /** The nonce this resource server expects in the proof, if it issues any. */
718
+ nonce?: string;
719
+ }
720
+ interface VerifyAccessTokenOptions {
721
+ /** The trusted issuer, e.g. `https://app.lumoauth.dev/orgs/acme-corp/api/v1`. */
722
+ issuer: string;
723
+ /** This resource server's URI. The token's `aud` must contain it. */
724
+ resource: string;
725
+ /** Pre-fetched issuer JWKS (no network). */
726
+ jwks?: {
727
+ keys: AAuthJwk[];
728
+ };
729
+ /** Custom fetch implementation. */
730
+ fetch?: typeof globalThis.fetch;
731
+ /** Allowed clock skew in seconds for `exp` and `nbf`. Default 60. */
732
+ clockSkew?: number;
733
+ /** Refuse tokens that are not DPoP-bound (no `cnf.jkt`). Default false. */
734
+ requireDpop?: boolean;
735
+ /** The incoming request's proof. Required when the token has `cnf.jkt`. */
736
+ dpop?: IncomingDpopProof;
737
+ /** Replay cache for proof `jti`s. Default: in-memory, 300 s. */
738
+ replayCache?: DpopReplayCache;
739
+ /** JWKS cache. Default: one shared per process, keyed by issuer. */
740
+ jwksCache?: JwksCache;
741
+ }
742
+ /** Thrown when an access token or its DPoP binding is refused. */
743
+ declare class AccessTokenError extends LumoAuthError {
744
+ constructor(message: string,
745
+ /** `invalid_token`, `invalid_dpop_proof` or `jwks_fetch_failed`. */
746
+ code: 'invalid_token' | 'invalid_dpop_proof' | 'jwks_fetch_failed', statusCode?: number);
747
+ }
748
+ /** Per-issuer JWKS cache with discovery and a throttled refetch on unknown `kid`. */
749
+ declare class JwksCache {
750
+ private readonly fetchFn?;
751
+ private readonly entries;
752
+ constructor(fetchFn?: typeof globalThis.fetch | undefined);
753
+ /**
754
+ * Find `kid` in the issuer's JWKS. An unknown `kid` triggers one refetch
755
+ * (a key rotation); repeated misses refetch at most every 30 s, so a
756
+ * stream of bogus tokens cannot hammer the JWKS endpoint.
757
+ */
758
+ find(issuer: string, kid: string, fetchFn?: typeof globalThis.fetch): Promise<AAuthJwk | undefined>;
759
+ /** Drop the cached keys of one issuer, or of all when omitted. */
760
+ clear(issuer?: string): void;
761
+ }
762
+ /** In-memory `jti` replay cache. One process only; use a shared store across replicas. */
763
+ declare class InMemoryDpopReplayCache implements DpopReplayCache {
764
+ private readonly now;
765
+ private readonly seen;
766
+ constructor(now?: () => number);
767
+ add(key: string, ttlSeconds: number): boolean;
768
+ private prune;
769
+ }
770
+ /** Split an `Authorization` header into scheme and credential. */
771
+ declare function parseAuthorizationHeader(header: string | null | undefined): {
772
+ scheme: string;
773
+ token: string;
774
+ } | null;
775
+ /** The scopes of a verified token, as an array. */
776
+ declare function accessTokenScopes(claims: AccessTokenClaims): string[];
777
+ /**
778
+ * Verify a LumoAuth `at+jwt` access token. Returns the claims or throws
779
+ * `AccessTokenError`.
780
+ *
781
+ * @example
782
+ * ```ts
783
+ * const claims = await verifyAccessToken(token, {
784
+ * issuer: 'https://app.lumoauth.dev/orgs/acme-corp/api/v1',
785
+ * resource: 'https://mcp.example.com/mcp',
786
+ * dpop: { method: req.method, url, proof: req.headers.dpop, authorizationScheme: 'DPoP' },
787
+ * });
788
+ * ```
789
+ */
790
+ declare function verifyAccessToken(token: string, options: VerifyAccessTokenOptions): Promise<AccessTokenClaims>;
791
+ interface VerifyDpopProofOptions {
792
+ /** Method of the incoming request. */
793
+ method: string;
794
+ /** Full URL of the incoming request. */
795
+ url: string;
796
+ /** The presented access token, when the proof must carry `ath`. */
797
+ accessToken?: string;
798
+ /** Expected `nonce`, when this server issues nonces. */
799
+ nonce?: string;
800
+ /** Replay cache for `jti`. Default: in-memory, 300 s. */
801
+ replayCache?: DpopReplayCache;
802
+ /** Clock override in epoch seconds (tests only). */
803
+ now?: () => number;
804
+ }
805
+ interface VerifiedDpopProof {
806
+ /** The proof's public key. */
807
+ jwk: AAuthJwk;
808
+ /** RFC 7638 thumbprint of `jwk`. Compare with the token's `cnf.jkt`. */
809
+ thumbprint: string;
810
+ claims: {
811
+ jti: string;
812
+ htm: string;
813
+ htu: string;
814
+ iat: number;
815
+ ath?: string;
816
+ nonce?: string;
817
+ [claim: string]: unknown;
818
+ };
819
+ }
820
+ /**
821
+ * Verify a DPoP proof JWT against the incoming request, the same way the
822
+ * LumoAuth server does: header (`typ`, allow-listed `alg`, public `jwk`
823
+ * matching the algorithm), signature, `htm`, `htu` (scheme, host, port,
824
+ * path; query and fragment ignored), `iat` window, `jti` replay, `ath` when
825
+ * an access token is given, `nonce` when one is expected.
826
+ */
827
+ declare function verifyDpopProof(proof: string, options: VerifyDpopProofOptions): Promise<VerifiedDpopProof>;
828
+ interface AccessTokenVerifierOptions extends Omit<VerifyAccessTokenOptions, 'dpop' | 'jwksCache' | 'replayCache'> {
829
+ /** Replay cache for proof `jti`s. Default: one in-memory cache per verifier. */
830
+ replayCache?: DpopReplayCache;
831
+ }
832
+ /** A request as a resource server sees it, for `verifyRequest`. */
833
+ interface IncomingRequest {
834
+ method: string;
835
+ /** The full public URL of the request. */
836
+ url: string;
837
+ /** `Authorization` and `DPoP` headers, any case; or a `Headers` object. */
838
+ headers: Headers | Record<string, string | string[] | undefined>;
839
+ /** Expected nonce, when this server issues nonces. */
840
+ nonce?: string;
841
+ }
842
+ interface AccessTokenVerifier {
843
+ /** Verify a token; `dpop` is the incoming request when the token may be bound. */
844
+ verify(token: string, dpop?: IncomingDpopProof): Promise<AccessTokenClaims>;
845
+ /** Read `Authorization` (+ `DPoP`) from a request and verify. */
846
+ verifyRequest(request: IncomingRequest): Promise<AccessTokenClaims>;
847
+ /** Drop the cached JWKS. */
848
+ clearCache(): void;
849
+ }
850
+ /**
851
+ * A verifier with its own JWKS and replay caches, for a long-running
852
+ * resource server.
853
+ *
854
+ * @example
855
+ * ```ts
856
+ * const verifier = createAccessTokenVerifier({
857
+ * issuer: 'https://app.lumoauth.dev/orgs/acme-corp/api/v1',
858
+ * resource: 'https://mcp.example.com/mcp',
859
+ * });
860
+ * const claims = await verifier.verifyRequest({ method: req.method, url, headers: req.headers });
861
+ * ```
862
+ */
863
+ declare function createAccessTokenVerifier(options: AccessTokenVerifierOptions): AccessTokenVerifier;
864
+
524
865
  /**
525
866
  * Thrown for AAuth protocol failures — OAuth-style `{error,
526
867
  * error_description}` bodies from the agent token endpoint, signature
@@ -536,4 +877,4 @@ declare class AAuthError extends LumoAuthError {
536
877
  body?: unknown | undefined);
537
878
  }
538
879
 
539
- export { AAUTH_COVERED_COMPONENTS, type AAuthAgentMetadata, type AAuthAuthorizationRequired, AAuthClient, type AAuthClientOptions, AAuthError, type AAuthIssuerMetadata, type AAuthJwk, type AAuthKeypair, type AAuthResourceMetadata, type AAuthTokenClaims, type AAuthTokenResponse, LumoAgent, type LumoAgentOptions, type SignRequestOptions, type VerifyAuthTokenOptions, buildSignatureBase, contentDigestSha256, decodeJwt, generateKeypair, generateNonce, jwkThumbprint, publicJwkFromPrivateKey, signRequest, signSignatureBase, signatureParams, verifyAuthToken, verifySignatureBase };
880
+ export { AAUTH_COVERED_COMPONENTS, type AAuthAgentMetadata, type AAuthAuthorizationRequired, AAuthClient, type AAuthClientOptions, AAuthError, type AAuthIssuerMetadata, type AAuthJwk, type AAuthKeypair, type AAuthResourceMetadata, type AAuthTokenClaims, type AAuthTokenResponse, type AccessTokenClaims, AccessTokenError, type AccessTokenVerifier, type AccessTokenVerifierOptions, type ActorClaim, type AttestWorkloadOptions, type AttestWorkloadResult, type DpopAlgorithm, type DpopJwk, DpopProofSigner, type DpopProofSignerOptions, type DpopReplayCache, InMemoryDpopReplayCache, type IncomingDpopProof, type IncomingRequest, JwksCache, LumoAgent, type LumoAgentOptions, type SignRequestOptions, type VerifiedDpopProof, type VerifyAccessTokenOptions, type VerifyAuthTokenOptions, type VerifyDpopProofOptions, accessTokenScopes, attestWorkload, buildSignatureBase, contentDigestSha256, createAccessTokenVerifier, decodeJwt, dpopAth, generateKeypair, generateNonce, jwkThumbprint, parseAuthorizationHeader, publicJwkFromPrivateKey, signRequest, signSignatureBase, signatureParams, verifyAccessToken, verifyAuthToken, verifyDpopProof, verifySignatureBase };