@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/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
|
-
/**
|
|
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 };
|