@lumoauth/agent 1.2.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 +33 -3
- package/dist/index.d.mts +114 -1
- package/dist/index.d.ts +114 -1
- package/dist/index.js +253 -63
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +228 -36
- package/dist/index.mjs.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -21,6 +21,7 @@ sure that it is the package that you need? See
|
|
|
21
21
|
- [Configuration](#configuration)
|
|
22
22
|
- [Guides](#guides)
|
|
23
23
|
- [`LumoAgent` reference](#lumoagent-reference)
|
|
24
|
+
- [Private key JWT: sign in without a secret](#private-key-jwt-sign-in-without-a-secret)
|
|
24
25
|
- [DPoP: sender-constrained tokens](#dpop-sender-constrained-tokens)
|
|
25
26
|
- [Verify LumoAuth access tokens on an MCP server](#verify-lumoauth-access-tokens-on-an-mcp-server)
|
|
26
27
|
- [AAuth: cryptographic agent identity](#aauth-cryptographic-agent-identity)
|
|
@@ -99,15 +100,19 @@ grant. The SDK refreshes the token 60 seconds before it expires.
|
|
|
99
100
|
| `baseUrl` | `LUMOAUTH_URL` | `https://app.lumoauth.dev` | The LumoAuth host. Use `https://eu.app.lumoauth.dev` for the EU region |
|
|
100
101
|
| `orgId` | `LUMOAUTH_ORG_ID` | none | The organization slug. Every namespace needs it |
|
|
101
102
|
| `clientId` | `AGENT_CLIENT_ID` | required | The agent's OAuth client ID |
|
|
102
|
-
| `clientSecret` | `AGENT_CLIENT_SECRET` | required | The agent's OAuth client secret |
|
|
103
|
+
| `clientSecret` | `AGENT_CLIENT_SECRET` | required unless `privateKey` | The agent's OAuth client secret |
|
|
104
|
+
| `privateKey` | `AGENT_PRIVATE_KEY` (PEM) | none | For a **Private key JWT** agent: a `ClientAssertionSigner` or the PEM private key. The agent then signs a client assertion instead of sending a secret. See [Private key JWT](#private-key-jwt-sign-in-without-a-secret) |
|
|
105
|
+
| `keyId` | `AGENT_KEY_ID` | none | The `kid` of the registered public key, used with a PEM `privateKey` |
|
|
106
|
+
| `issuer` | none | `{baseUrl}/orgs/{orgId}/api/v1` | The organization's issuer identifier, the assertion's `aud`. Set it on a custom domain |
|
|
103
107
|
| `scopes` | none | the agent's defaults | Scopes to request |
|
|
104
108
|
| `redirectUri` | none | none | The callback URL of the delegation consent flow |
|
|
105
109
|
| `timeout` | none | 30 000 ms | Request timeout |
|
|
106
110
|
| `fetch` | none | global `fetch` | A custom `fetch` |
|
|
107
111
|
| `dpop` | none | none | A `DpopProofSigner`. Every token the agent obtains is then bound to its key, and every request carries a DPoP proof. See [DPoP](#dpop-sender-constrained-tokens) |
|
|
108
112
|
|
|
109
|
-
The constructor throws `LumoAuthConfigError` when the client ID
|
|
110
|
-
secret is
|
|
113
|
+
The constructor throws `LumoAuthConfigError` when the client ID is missing, when
|
|
114
|
+
neither a client secret nor a private key is given, or when both are. It does not
|
|
115
|
+
call the server.
|
|
111
116
|
|
|
112
117
|
## Guides
|
|
113
118
|
|
|
@@ -241,6 +246,31 @@ consent steps. The token types and the `resource` option are explained in the
|
|
|
241
246
|
The parameters of each method are in the
|
|
242
247
|
[workspace API reference](../../README.md#api-reference).
|
|
243
248
|
|
|
249
|
+
## Private key JWT: sign in without a secret
|
|
250
|
+
|
|
251
|
+
An agent registered with the **Private key JWT** identity type has no client
|
|
252
|
+
secret. Whenever it needs a token, it signs a short-lived JWT (a client
|
|
253
|
+
assertion, RFC 7523) with its private key. Only the public key is registered.
|
|
254
|
+
|
|
255
|
+
```ts
|
|
256
|
+
import { ClientAssertionSigner, LumoAgent } from '@lumoauth/agent';
|
|
257
|
+
|
|
258
|
+
const signer = ClientAssertionSigner.generate('ES256', 'agent-2026-11');
|
|
259
|
+
// Store signer.privateKeyPem in your secret store; paste signer.jwks into the agent's public keys.
|
|
260
|
+
|
|
261
|
+
const agent = new LumoAgent({
|
|
262
|
+
clientId: 'agt_0123456789abcdef',
|
|
263
|
+
privateKey: ClientAssertionSigner.fromPem(process.env.AGENT_PRIVATE_KEY!, { keyId: 'agent-2026-11' }),
|
|
264
|
+
});
|
|
265
|
+
await agent.authenticate();
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
Every token request carries a new assertion: `iss` and `sub` are the agent ID,
|
|
269
|
+
`aud` is the organization's issuer identifier, `exp` is 60 seconds ahead and
|
|
270
|
+
`jti` is random. `ClientAssertionSigner` signs with ES256, ES384, ES512,
|
|
271
|
+
EdDSA, RS256 to RS512 or PS256 to PS512; `agent.createClientAssertion()` gives
|
|
272
|
+
you one for another call. Combine it with `dpop` to also bind the tokens to a key.
|
|
273
|
+
|
|
244
274
|
## DPoP: sender-constrained tokens
|
|
245
275
|
|
|
246
276
|
An MCP server registered with "Require DPoP" accepts only tokens that are
|
package/dist/index.d.mts
CHANGED
|
@@ -2,6 +2,96 @@ import { AgentsModule, JitModule, DelegationModule, ApprovalsModule, McpModule,
|
|
|
2
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. */
|
|
@@ -77,6 +181,8 @@ declare class LumoAgent {
|
|
|
77
181
|
/** MCP servers: token exchange and per-tool checks (`authorizeTool`). */
|
|
78
182
|
readonly mcp: McpModule;
|
|
79
183
|
private readonly clientSecret;
|
|
184
|
+
private readonly assertionSigner;
|
|
185
|
+
private readonly issuer;
|
|
80
186
|
private readonly scopes;
|
|
81
187
|
private readonly fetchFn;
|
|
82
188
|
private readonly dpop;
|
|
@@ -95,6 +201,13 @@ declare class LumoAgent {
|
|
|
95
201
|
* first sign-in. Present the token with that `Authorization` scheme.
|
|
96
202
|
*/
|
|
97
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;
|
|
98
211
|
/** The DPoP proof signer this agent was configured with, if any. */
|
|
99
212
|
get dpopSigner(): DpopProofProvider | undefined;
|
|
100
213
|
/**
|
|
@@ -877,4 +990,4 @@ declare class AAuthError extends LumoAuthError {
|
|
|
877
990
|
body?: unknown | undefined);
|
|
878
991
|
}
|
|
879
992
|
|
|
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 };
|
|
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 };
|
package/dist/index.d.ts
CHANGED
|
@@ -2,6 +2,96 @@ import { AgentsModule, JitModule, DelegationModule, ApprovalsModule, McpModule,
|
|
|
2
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. */
|
|
@@ -77,6 +181,8 @@ declare class LumoAgent {
|
|
|
77
181
|
/** MCP servers: token exchange and per-tool checks (`authorizeTool`). */
|
|
78
182
|
readonly mcp: McpModule;
|
|
79
183
|
private readonly clientSecret;
|
|
184
|
+
private readonly assertionSigner;
|
|
185
|
+
private readonly issuer;
|
|
80
186
|
private readonly scopes;
|
|
81
187
|
private readonly fetchFn;
|
|
82
188
|
private readonly dpop;
|
|
@@ -95,6 +201,13 @@ declare class LumoAgent {
|
|
|
95
201
|
* first sign-in. Present the token with that `Authorization` scheme.
|
|
96
202
|
*/
|
|
97
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;
|
|
98
211
|
/** The DPoP proof signer this agent was configured with, if any. */
|
|
99
212
|
get dpopSigner(): DpopProofProvider | undefined;
|
|
100
213
|
/**
|
|
@@ -877,4 +990,4 @@ declare class AAuthError extends LumoAuthError {
|
|
|
877
990
|
body?: unknown | undefined);
|
|
878
991
|
}
|
|
879
992
|
|
|
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 };
|
|
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 };
|