@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/dist/index.d.mts CHANGED
@@ -1,7 +1,97 @@
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
+ /**
6
+ * `private_key_jwt` client assertions (RFC 7523 §2.2, OpenID Connect Core §9).
7
+ *
8
+ * A LumoAuth agent registered with the **Private key JWT** identity type has
9
+ * no client secret. Whenever it needs a token, it signs a short-lived JWT with
10
+ * its private key and sends that instead:
11
+ *
12
+ * ```ts
13
+ * const agent = new LumoAgent({
14
+ * clientId: 'agt_0123456789abcdef',
15
+ * privateKey: ClientAssertionSigner.fromPem(process.env.AGENT_PRIVATE_KEY!, { keyId: 'agent-2026-11' }),
16
+ * });
17
+ * ```
18
+ *
19
+ * Register `signer.jwks` (the public key only) on the agent.
20
+ *
21
+ * What the server checks, and what `create()` produces:
22
+ * - header `alg` (ES256, ES384, ES512, EdDSA, RS256–RS512 or PS256–PS512),
23
+ * `kid` and `typ: client-authentication+jwt`;
24
+ * - `iss` = `sub` = the agent ID, `aud` = the organization's issuer
25
+ * identifier alone (not the token endpoint URL);
26
+ * - `iat` now, `exp` at most 10 minutes later (60 s by default) and a random
27
+ * `jti`: every assertion is single-use, so sign a new one per request.
28
+ */
29
+ /** `client_assertion_type` for a JWT client assertion. */
30
+ declare const CLIENT_ASSERTION_TYPE = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer";
31
+ /** The `typ` header of a client-authentication JWT. */
32
+ declare const CLIENT_ASSERTION_TYP = "client-authentication+jwt";
33
+ /** The longest validity LumoAuth accepts for an assertion, in seconds. */
34
+ declare const MAX_ASSERTION_LIFETIME_SECONDS = 600;
35
+ type ClientAssertionAlgorithm = 'ES256' | 'ES384' | 'ES512' | 'EdDSA' | 'RS256' | 'RS384' | 'RS512' | 'PS256' | 'PS384' | 'PS512';
36
+ interface ClientAssertionSignerOptions {
37
+ /** PEM private key (PKCS#8, SEC 1 or PKCS#1): EC P-256/P-384/P-521, Ed25519 or RSA ≥ 2048 bits. */
38
+ privateKeyPem?: string;
39
+ /** A Node `KeyObject` private key, as an alternative to `privateKeyPem`. */
40
+ privateKey?: KeyObject;
41
+ /** `kid` of the registered public key. Required by the server when the agent has several keys. */
42
+ keyId?: string;
43
+ /** JWS algorithm. Defaults to the key's natural one (ES256/ES384/ES512, EdDSA, RS256); RSA keys may also use RS384/RS512/PS256/PS384/PS512. */
44
+ algorithm?: ClientAssertionAlgorithm;
45
+ /** Seconds until `exp`, 1–600. Default 60. */
46
+ lifetimeSeconds?: number;
47
+ /** Clock override in epoch seconds (tests only). */
48
+ now?: () => number;
49
+ }
50
+ /** A public JWK as registered on the agent. */
51
+ interface ClientAssertionJwk {
52
+ kty: string;
53
+ kid?: string;
54
+ alg: ClientAssertionAlgorithm;
55
+ use: 'sig';
56
+ crv?: string;
57
+ x?: string;
58
+ y?: string;
59
+ n?: string;
60
+ e?: string;
61
+ }
62
+ declare class ClientAssertionSigner {
63
+ /** The JWS algorithm the assertions are signed with. */
64
+ readonly algorithm: ClientAssertionAlgorithm;
65
+ /** `kid` put in every assertion header, if set. */
66
+ readonly keyId: string | undefined;
67
+ /** Seconds until `exp`. */
68
+ readonly lifetimeSeconds: number;
69
+ private readonly key;
70
+ private readonly now;
71
+ /** Generate a new key: ES256 (default), ES384, ES512, EdDSA, or an RSA algorithm (2048-bit key). */
72
+ static generate(algorithm?: ClientAssertionAlgorithm, keyId?: string): ClientAssertionSigner;
73
+ /** Load a PEM private key. */
74
+ static fromPem(pem: string, options?: Omit<ClientAssertionSignerOptions, 'privateKeyPem' | 'privateKey'>): ClientAssertionSigner;
75
+ constructor(options: ClientAssertionSignerOptions);
76
+ /** Sign one assertion for `clientId` (the agent ID) and `audience` (the organization's issuer). */
77
+ create(clientId: string, audience: string): string;
78
+ /** The public key as a JWK with `kid` (when set), `alg` and `use: "sig"`. */
79
+ get jwk(): ClientAssertionJwk;
80
+ /** `{ keys: [jwk] }`: what to register on the agent. */
81
+ get jwks(): {
82
+ keys: ClientAssertionJwk[];
83
+ };
84
+ /** The private key as PKCS#8 PEM, for your secret store. */
85
+ get privateKeyPem(): string;
86
+ }
87
+ /**
88
+ * The issuer identifier of an organization on `baseUrl`: the `issuer` of
89
+ * `/orgs/{orgId}/api/v1/.well-known/openid-configuration`, and the `aud` a
90
+ * client assertion must carry. On a custom domain the issuer differs; pass it
91
+ * explicitly there.
92
+ */
93
+ declare function issuerFor(baseUrl: string, orgId: string): string;
94
+
5
95
  interface LumoAgentOptions {
6
96
  /**
7
97
  * LumoAuth instance URL. Defaults to `process.env.LUMOAUTH_URL` or
@@ -14,6 +104,20 @@ interface LumoAgentOptions {
14
104
  clientId?: string;
15
105
  /** OAuth client secret. Defaults to `process.env.AGENT_CLIENT_SECRET`. */
16
106
  clientSecret?: string;
107
+ /**
108
+ * For an agent registered with the **Private key JWT** identity type: a
109
+ * `ClientAssertionSigner`, or the PEM private key. The agent then signs a
110
+ * client assertion (RFC 7523) for every token request and needs no
111
+ * `clientSecret`. Defaults to `process.env.AGENT_PRIVATE_KEY` (PEM).
112
+ */
113
+ privateKey?: ClientAssertionSigner | string;
114
+ /** `kid` of the registered public key, used with a PEM `privateKey`. Defaults to `process.env.AGENT_KEY_ID`. */
115
+ keyId?: string;
116
+ /**
117
+ * The organization's issuer identifier, the assertion's `aud`. Defaults to
118
+ * `{baseUrl}/orgs/{orgId}/api/v1`; set it on a custom domain.
119
+ */
120
+ issuer?: string;
17
121
  /** Scopes to request. When omitted the server grants the agent's defaults. */
18
122
  scopes?: string[];
19
123
  /** OAuth callback URL for the delegation consent flow. */
@@ -22,6 +126,14 @@ interface LumoAgentOptions {
22
126
  fetch?: typeof globalThis.fetch;
23
127
  /** Request timeout in milliseconds. Default: 30 000 ms. */
24
128
  timeout?: number;
129
+ /**
130
+ * DPoP proof signer (RFC 9449), e.g. `DpopProofSigner.generate()`. When
131
+ * set, the client-credentials token and every exchanged token (MCP,
132
+ * delegation) are sender-constrained to its key, and every request
133
+ * carries `Authorization: DPoP <token>` plus a proof. Needed for MCP
134
+ * servers registered with "Require DPoP".
135
+ */
136
+ dpop?: DpopProofProvider;
25
137
  }
26
138
  /**
27
139
  * High-level agent client — the Node.js counterpart of the Python SDK's
@@ -66,11 +178,14 @@ declare class LumoAgent {
66
178
  readonly delegation: DelegationModule;
67
179
  /** Push-approval-for-agent-actions. */
68
180
  readonly approvals: ApprovalsModule;
69
- /** Token exchange for secured MCP servers. */
181
+ /** MCP servers: token exchange and per-tool checks (`authorizeTool`). */
70
182
  readonly mcp: McpModule;
71
183
  private readonly clientSecret;
184
+ private readonly assertionSigner;
185
+ private readonly issuer;
72
186
  private readonly scopes;
73
187
  private readonly fetchFn;
188
+ private readonly dpop;
74
189
  private token;
75
190
  private refreshPromise;
76
191
  constructor(options?: LumoAgentOptions);
@@ -80,6 +195,21 @@ declare class LumoAgent {
80
195
  * startup or to request non-default scopes.
81
196
  */
82
197
  authenticate(scopes?: string[]): Promise<string>;
198
+ /**
199
+ * `token_type` of the last successful authentication: `DPoP` when the
200
+ * token is sender-constrained, otherwise `Bearer`; `null` before the
201
+ * first sign-in. Present the token with that `Authorization` scheme.
202
+ */
203
+ get tokenType(): string | null;
204
+ /**
205
+ * A new `private_key_jwt` client assertion for this agent (single-use),
206
+ * addressed to `issuer` or `{baseUrl}/orgs/{orgId}/api/v1`.
207
+ */
208
+ createClientAssertion(): string;
209
+ /** The client assertion signer this agent was configured with, if any. */
210
+ get clientAssertionSigner(): ClientAssertionSigner | undefined;
211
+ /** The DPoP proof signer this agent was configured with, if any. */
212
+ get dpopSigner(): DpopProofProvider | undefined;
83
213
  /**
84
214
  * The current access token, re-authenticating transparently when it is
85
215
  * missing or within 60 s of expiry. Concurrent callers share one
@@ -92,6 +222,11 @@ declare class LumoAgent {
92
222
  ask(action: string, context?: Record<string, unknown>): Promise<AgentAskResult>;
93
223
  /** Convenience wrapper: `true` when `action` is allowed. */
94
224
  isAllowed(action: string, context?: Record<string, unknown>): Promise<boolean>;
225
+ /**
226
+ * May this agent run `tool` on the registered MCP server `serverId`?
227
+ * A deny returns `{ allowed: false }` and does not throw.
228
+ */
229
+ authorizeMcpTool(serverId: string, tool: string): Promise<AgentMcpToolDecision>;
95
230
  /** The agent's own identity, capabilities, and workspace. */
96
231
  getCurrentAgent(): Promise<AgentIdentity>;
97
232
  /** The agent's declared capability slugs. */
@@ -521,6 +656,325 @@ declare class AAuthClient {
521
656
  private doFetch;
522
657
  }
523
658
 
659
+ /**
660
+ * RFC 9449 DPoP proof signing.
661
+ *
662
+ * A `DpopProofSigner` holds the agent's DPoP key and mints proof JWTs for
663
+ * the token endpoint, the attestation endpoint and resource requests. The
664
+ * LumoAuth server (`DPoPService`) accepts ES256/ES384/ES512, RS256/RS384/
665
+ * RS512, PS256/PS384/PS512 and EdDSA; this signer produces ES256 (P-256,
666
+ * the default), EdDSA (Ed25519, so the AAuth key can double as the DPoP
667
+ * key) and RS256.
668
+ *
669
+ * Proof contents, as the server checks them:
670
+ * - header `typ: "dpop+jwt"`, `alg`, `jwk` (public members only);
671
+ * - `jti` 32 random characters, `htm` upper-case method, `htu` the URL
672
+ * without query or fragment, `iat` now (the server allows 60 s ahead and
673
+ * 300 s behind);
674
+ * - `ath` = base64url(SHA-256(access token)) on resource requests;
675
+ * - `nonce` when the server handed one out (`DPoP-Nonce`). The signer
676
+ * remembers the latest nonce per origin, so `fetchWithDpop` only has to
677
+ * retry once after a `use_dpop_nonce` answer.
678
+ */
679
+ type DpopAlgorithm = 'ES256' | 'EdDSA' | 'RS256';
680
+ interface DpopProofSignerOptions {
681
+ /** PEM (PKCS#8) private key: EC P-256, Ed25519 or RSA. */
682
+ privateKeyPem?: string;
683
+ /** A Node `KeyObject` private key, as an alternative to `privateKeyPem`. */
684
+ privateKey?: KeyObject;
685
+ /** Clock override in epoch seconds (tests only). */
686
+ now?: () => number;
687
+ }
688
+ /** The public JWK carried in a DPoP proof header. */
689
+ type DpopJwk = AAuthJwk;
690
+ declare class DpopProofSigner implements DpopProofProvider {
691
+ /** The JWS algorithm the proofs are signed with. */
692
+ readonly algorithm: DpopAlgorithm;
693
+ /** The public key as a JWK, with public members only. */
694
+ readonly jwk: DpopJwk;
695
+ /** RFC 7638 thumbprint of `jwk`: the `cnf.jkt` value of bound tokens. */
696
+ readonly thumbprint: string;
697
+ private readonly key;
698
+ private readonly now;
699
+ private readonly nonces;
700
+ /**
701
+ * Generate a fresh key. ES256 (P-256) by default; pass `'EdDSA'` for an
702
+ * Ed25519 key or `'RS256'` for a 2048-bit RSA key.
703
+ */
704
+ static generate(algorithm?: DpopAlgorithm): DpopProofSigner;
705
+ constructor(options: DpopProofSignerOptions);
706
+ /** The private key as PKCS#8 PEM, for your secret store. */
707
+ get privateKeyPem(): string;
708
+ /** Create one proof JWT. See the file comment for the claims. */
709
+ createProof(input: DpopProofRequest): string;
710
+ /** Remember the latest server nonce for the origin of `url`. */
711
+ setNonce(url: string, nonce: string): void;
712
+ /** The remembered nonce for the origin of `url`, if any. */
713
+ getNonce(url: string): string | undefined;
714
+ /** Forget every remembered nonce. */
715
+ clearNonces(): void;
716
+ }
717
+ /** `ath` for an access token: base64url(SHA-256(token)). */
718
+ declare function dpopAth(accessToken: string): string;
719
+
720
+ /**
721
+ * Workload attestation: `POST {issuer}/agents/{agentId}/attest`.
722
+ *
723
+ * The agent's runtime presents a cloud-issued OIDC token (GitHub Actions,
724
+ * GCP, AWS, Kubernetes, Azure, SPIFFE, …) and gets a short-lived LumoAuth
725
+ * access token for the agent, with no client secret in the environment.
726
+ * With a `dpop` signer the request carries an RFC 9449 proof and the token
727
+ * comes back sender-constrained (`tokenType: "DPoP"`).
728
+ *
729
+ * NOTE: this endpoint is not yet in sdk-contract/routes.json, so the path
730
+ * is built here rather than taken from the shared route registry.
731
+ */
732
+ interface AttestWorkloadOptions {
733
+ /** LumoAuth instance URL. Defaults to `LUMOAUTH_URL` or `https://app.lumoauth.dev`. */
734
+ baseUrl?: string;
735
+ /** Organization slug. Defaults to `LUMOAUTH_ORG_ID`. */
736
+ orgId?: string;
737
+ /** The agent id (`agt_…`). */
738
+ agentId: string;
739
+ /** The workload's OIDC token. */
740
+ attestationToken: string;
741
+ /** DPoP proof signer; the returned token is bound to its key. */
742
+ dpop?: DpopProofProvider;
743
+ /** Custom fetch implementation. */
744
+ fetch?: typeof globalThis.fetch;
745
+ }
746
+ interface AttestWorkloadResult {
747
+ accessToken: string;
748
+ /** `DPoP` when bound to the signer's key, otherwise `Bearer`. */
749
+ tokenType: string;
750
+ expiresIn: number | null;
751
+ /** Space-separated agent capabilities. */
752
+ scope: string | null;
753
+ /** The verified workload identity (`provider`, `subject`, `issuer`, …). */
754
+ identity: Record<string, unknown>;
755
+ }
756
+ declare function attestWorkload(options: AttestWorkloadOptions): Promise<AttestWorkloadResult>;
757
+
758
+ /**
759
+ * Local verification of LumoAuth core access tokens (`at+jwt`, RFC 9068).
760
+ *
761
+ * This is the token an MCP server or any other resource server receives
762
+ * from an agent or a delegated user: a token-exchange result with `aud` set
763
+ * to the resource URI, or an agent's client-credentials token. (AAuth
764
+ * `auth+jwt` tokens are a different format; see `verifyAuthToken`.)
765
+ *
766
+ * Checks, in order: compact JWS shape; `typ` is `at+jwt` or
767
+ * `application/at+jwt`; `alg` is an asymmetric JWS algorithm (`none` and
768
+ * HMAC are refused); `kid` resolves in the issuer's JWKS, which is read from
769
+ * `{issuer}/.well-known/openid-configuration` → `jwks_uri` and cached, with
770
+ * one refetch on an unknown `kid`; signature; `iss`; `aud` contains the
771
+ * resource; `exp` / `nbf` with a clock skew (default 60 s); `token_use` is
772
+ * not `test`; and, when the token carries `cnf.jkt`, the RFC 9449 proof
773
+ * binding of the incoming request.
774
+ */
775
+ /** OAuth Actor Profile actor object (`act` claim), nested for chains. */
776
+ interface ActorClaim {
777
+ /** `agent_agt_…` for an agent, a user id for a user. */
778
+ sub: string;
779
+ iss?: string;
780
+ /** Entity classification, e.g. `ai_agent` or `user`. */
781
+ sub_profile?: string;
782
+ name?: string;
783
+ act?: ActorClaim;
784
+ [claim: string]: unknown;
785
+ }
786
+ interface AccessTokenClaims {
787
+ iss: string;
788
+ /** `agent_agt_…` for an agent, the user id for a delegated token. */
789
+ sub: string;
790
+ aud: string | string[];
791
+ exp: number;
792
+ iat: number;
793
+ nbf?: number;
794
+ jti: string;
795
+ /** Space-separated scopes. */
796
+ scope?: string;
797
+ is_agent?: boolean;
798
+ capabilities?: string[];
799
+ act?: ActorClaim;
800
+ cnf?: {
801
+ jkt?: string;
802
+ [member: string]: unknown;
803
+ };
804
+ token_use?: string;
805
+ client_id?: string;
806
+ name?: string;
807
+ [claim: string]: unknown;
808
+ }
809
+ /** Pluggable replay cache for DPoP `jti` values. */
810
+ interface DpopReplayCache {
811
+ /**
812
+ * Record `key` for `ttlSeconds`. Return `true` when it was not seen
813
+ * before, `false` when it was (a replay).
814
+ */
815
+ add(key: string, ttlSeconds: number): boolean | Promise<boolean>;
816
+ }
817
+ /** The DPoP proof of an incoming request, for the binding check. */
818
+ interface IncomingDpopProof {
819
+ /** HTTP method of the incoming request. */
820
+ method: string;
821
+ /** Full URL of the incoming request (the public one, behind any proxy). */
822
+ url: string;
823
+ /** The `DPoP` request header. */
824
+ proof?: string | null;
825
+ /**
826
+ * The scheme of the `Authorization` header (`DPoP` or `Bearer`). A
827
+ * DPoP-bound token must arrive with the `DPoP` scheme.
828
+ */
829
+ authorizationScheme?: string | null;
830
+ /** The nonce this resource server expects in the proof, if it issues any. */
831
+ nonce?: string;
832
+ }
833
+ interface VerifyAccessTokenOptions {
834
+ /** The trusted issuer, e.g. `https://app.lumoauth.dev/orgs/acme-corp/api/v1`. */
835
+ issuer: string;
836
+ /** This resource server's URI. The token's `aud` must contain it. */
837
+ resource: string;
838
+ /** Pre-fetched issuer JWKS (no network). */
839
+ jwks?: {
840
+ keys: AAuthJwk[];
841
+ };
842
+ /** Custom fetch implementation. */
843
+ fetch?: typeof globalThis.fetch;
844
+ /** Allowed clock skew in seconds for `exp` and `nbf`. Default 60. */
845
+ clockSkew?: number;
846
+ /** Refuse tokens that are not DPoP-bound (no `cnf.jkt`). Default false. */
847
+ requireDpop?: boolean;
848
+ /** The incoming request's proof. Required when the token has `cnf.jkt`. */
849
+ dpop?: IncomingDpopProof;
850
+ /** Replay cache for proof `jti`s. Default: in-memory, 300 s. */
851
+ replayCache?: DpopReplayCache;
852
+ /** JWKS cache. Default: one shared per process, keyed by issuer. */
853
+ jwksCache?: JwksCache;
854
+ }
855
+ /** Thrown when an access token or its DPoP binding is refused. */
856
+ declare class AccessTokenError extends LumoAuthError {
857
+ constructor(message: string,
858
+ /** `invalid_token`, `invalid_dpop_proof` or `jwks_fetch_failed`. */
859
+ code: 'invalid_token' | 'invalid_dpop_proof' | 'jwks_fetch_failed', statusCode?: number);
860
+ }
861
+ /** Per-issuer JWKS cache with discovery and a throttled refetch on unknown `kid`. */
862
+ declare class JwksCache {
863
+ private readonly fetchFn?;
864
+ private readonly entries;
865
+ constructor(fetchFn?: typeof globalThis.fetch | undefined);
866
+ /**
867
+ * Find `kid` in the issuer's JWKS. An unknown `kid` triggers one refetch
868
+ * (a key rotation); repeated misses refetch at most every 30 s, so a
869
+ * stream of bogus tokens cannot hammer the JWKS endpoint.
870
+ */
871
+ find(issuer: string, kid: string, fetchFn?: typeof globalThis.fetch): Promise<AAuthJwk | undefined>;
872
+ /** Drop the cached keys of one issuer, or of all when omitted. */
873
+ clear(issuer?: string): void;
874
+ }
875
+ /** In-memory `jti` replay cache. One process only; use a shared store across replicas. */
876
+ declare class InMemoryDpopReplayCache implements DpopReplayCache {
877
+ private readonly now;
878
+ private readonly seen;
879
+ constructor(now?: () => number);
880
+ add(key: string, ttlSeconds: number): boolean;
881
+ private prune;
882
+ }
883
+ /** Split an `Authorization` header into scheme and credential. */
884
+ declare function parseAuthorizationHeader(header: string | null | undefined): {
885
+ scheme: string;
886
+ token: string;
887
+ } | null;
888
+ /** The scopes of a verified token, as an array. */
889
+ declare function accessTokenScopes(claims: AccessTokenClaims): string[];
890
+ /**
891
+ * Verify a LumoAuth `at+jwt` access token. Returns the claims or throws
892
+ * `AccessTokenError`.
893
+ *
894
+ * @example
895
+ * ```ts
896
+ * const claims = await verifyAccessToken(token, {
897
+ * issuer: 'https://app.lumoauth.dev/orgs/acme-corp/api/v1',
898
+ * resource: 'https://mcp.example.com/mcp',
899
+ * dpop: { method: req.method, url, proof: req.headers.dpop, authorizationScheme: 'DPoP' },
900
+ * });
901
+ * ```
902
+ */
903
+ declare function verifyAccessToken(token: string, options: VerifyAccessTokenOptions): Promise<AccessTokenClaims>;
904
+ interface VerifyDpopProofOptions {
905
+ /** Method of the incoming request. */
906
+ method: string;
907
+ /** Full URL of the incoming request. */
908
+ url: string;
909
+ /** The presented access token, when the proof must carry `ath`. */
910
+ accessToken?: string;
911
+ /** Expected `nonce`, when this server issues nonces. */
912
+ nonce?: string;
913
+ /** Replay cache for `jti`. Default: in-memory, 300 s. */
914
+ replayCache?: DpopReplayCache;
915
+ /** Clock override in epoch seconds (tests only). */
916
+ now?: () => number;
917
+ }
918
+ interface VerifiedDpopProof {
919
+ /** The proof's public key. */
920
+ jwk: AAuthJwk;
921
+ /** RFC 7638 thumbprint of `jwk`. Compare with the token's `cnf.jkt`. */
922
+ thumbprint: string;
923
+ claims: {
924
+ jti: string;
925
+ htm: string;
926
+ htu: string;
927
+ iat: number;
928
+ ath?: string;
929
+ nonce?: string;
930
+ [claim: string]: unknown;
931
+ };
932
+ }
933
+ /**
934
+ * Verify a DPoP proof JWT against the incoming request, the same way the
935
+ * LumoAuth server does: header (`typ`, allow-listed `alg`, public `jwk`
936
+ * matching the algorithm), signature, `htm`, `htu` (scheme, host, port,
937
+ * path; query and fragment ignored), `iat` window, `jti` replay, `ath` when
938
+ * an access token is given, `nonce` when one is expected.
939
+ */
940
+ declare function verifyDpopProof(proof: string, options: VerifyDpopProofOptions): Promise<VerifiedDpopProof>;
941
+ interface AccessTokenVerifierOptions extends Omit<VerifyAccessTokenOptions, 'dpop' | 'jwksCache' | 'replayCache'> {
942
+ /** Replay cache for proof `jti`s. Default: one in-memory cache per verifier. */
943
+ replayCache?: DpopReplayCache;
944
+ }
945
+ /** A request as a resource server sees it, for `verifyRequest`. */
946
+ interface IncomingRequest {
947
+ method: string;
948
+ /** The full public URL of the request. */
949
+ url: string;
950
+ /** `Authorization` and `DPoP` headers, any case; or a `Headers` object. */
951
+ headers: Headers | Record<string, string | string[] | undefined>;
952
+ /** Expected nonce, when this server issues nonces. */
953
+ nonce?: string;
954
+ }
955
+ interface AccessTokenVerifier {
956
+ /** Verify a token; `dpop` is the incoming request when the token may be bound. */
957
+ verify(token: string, dpop?: IncomingDpopProof): Promise<AccessTokenClaims>;
958
+ /** Read `Authorization` (+ `DPoP`) from a request and verify. */
959
+ verifyRequest(request: IncomingRequest): Promise<AccessTokenClaims>;
960
+ /** Drop the cached JWKS. */
961
+ clearCache(): void;
962
+ }
963
+ /**
964
+ * A verifier with its own JWKS and replay caches, for a long-running
965
+ * resource server.
966
+ *
967
+ * @example
968
+ * ```ts
969
+ * const verifier = createAccessTokenVerifier({
970
+ * issuer: 'https://app.lumoauth.dev/orgs/acme-corp/api/v1',
971
+ * resource: 'https://mcp.example.com/mcp',
972
+ * });
973
+ * const claims = await verifier.verifyRequest({ method: req.method, url, headers: req.headers });
974
+ * ```
975
+ */
976
+ declare function createAccessTokenVerifier(options: AccessTokenVerifierOptions): AccessTokenVerifier;
977
+
524
978
  /**
525
979
  * Thrown for AAuth protocol failures — OAuth-style `{error,
526
980
  * error_description}` bodies from the agent token endpoint, signature
@@ -536,4 +990,4 @@ declare class AAuthError extends LumoAuthError {
536
990
  body?: unknown | undefined);
537
991
  }
538
992
 
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 };
993
+ 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, CLIENT_ASSERTION_TYP, CLIENT_ASSERTION_TYPE, type ClientAssertionAlgorithm, type ClientAssertionJwk, ClientAssertionSigner, type ClientAssertionSignerOptions, type DpopAlgorithm, type DpopJwk, DpopProofSigner, type DpopProofSignerOptions, type DpopReplayCache, InMemoryDpopReplayCache, type IncomingDpopProof, type IncomingRequest, JwksCache, LumoAgent, type LumoAgentOptions, MAX_ASSERTION_LIFETIME_SECONDS, type SignRequestOptions, type VerifiedDpopProof, type VerifyAccessTokenOptions, type VerifyAuthTokenOptions, type VerifyDpopProofOptions, accessTokenScopes, attestWorkload, buildSignatureBase, contentDigestSha256, createAccessTokenVerifier, decodeJwt, dpopAth, generateKeypair, generateNonce, issuerFor, jwkThumbprint, parseAuthorizationHeader, publicJwkFromPrivateKey, signRequest, signSignatureBase, signatureParams, verifyAccessToken, verifyAuthToken, verifyDpopProof, verifySignatureBase };