@lumoauth/agent 1.2.0 → 1.4.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 +35 -4
- package/dist/index.d.mts +130 -3
- package/dist/index.d.ts +130 -3
- package/dist/index.js +269 -63
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +244 -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
|
|
|
@@ -226,13 +231,14 @@ consent steps. The token types and the `resource` option are explained in the
|
|
|
226
231
|
| `getCurrentAgent()` | `Promise<AgentIdentity>` | The agent's identity, capabilities and workspace |
|
|
227
232
|
| `capabilities()` | `Promise<string[]>` | The agent's capabilities |
|
|
228
233
|
| `budget()` | `Promise<AgentBudget>` | The agent's budget policy, or `{}` when none is set |
|
|
234
|
+
| `reportUsage({ tokens, costUsd })` | `Promise<UsageReportResult>` | Report model tokens and cost; token and cost limits count only reported usage |
|
|
229
235
|
| `baseUrl`, `orgId`, `clientId` | `string` | The resolved configuration |
|
|
230
236
|
|
|
231
237
|
### Namespaces
|
|
232
238
|
|
|
233
239
|
| Namespace | What it does | Methods |
|
|
234
240
|
|---|---|---|
|
|
235
|
-
| `agents` | Agent identity | `ask`, `isAllowed`, `me`, `getCurrentAgent`, `capabilities`, `budget`, `register`, `authorizeMcpTool(serverId, tool)` |
|
|
241
|
+
| `agents` | Agent identity | `ask`, `isAllowed`, `me`, `getCurrentAgent`, `capabilities`, `budget`, `reportUsage`, `register`, `authorizeMcpTool(serverId, tool)` |
|
|
236
242
|
| `approvals` | Push approval for agent actions | `require`, `create`, `getStatus`, `wait` |
|
|
237
243
|
| `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 |
|
|
238
244
|
| `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` |
|
|
@@ -241,6 +247,31 @@ consent steps. The token types and the `resource` option are explained in the
|
|
|
241
247
|
The parameters of each method are in the
|
|
242
248
|
[workspace API reference](../../README.md#api-reference).
|
|
243
249
|
|
|
250
|
+
## Private key JWT: sign in without a secret
|
|
251
|
+
|
|
252
|
+
An agent registered with the **Private key JWT** identity type has no client
|
|
253
|
+
secret. Whenever it needs a token, it signs a short-lived JWT (a client
|
|
254
|
+
assertion, RFC 7523) with its private key. Only the public key is registered.
|
|
255
|
+
|
|
256
|
+
```ts
|
|
257
|
+
import { ClientAssertionSigner, LumoAgent } from '@lumoauth/agent';
|
|
258
|
+
|
|
259
|
+
const signer = ClientAssertionSigner.generate('ES256', 'agent-2026-11');
|
|
260
|
+
// Store signer.privateKeyPem in your secret store; paste signer.jwks into the agent's public keys.
|
|
261
|
+
|
|
262
|
+
const agent = new LumoAgent({
|
|
263
|
+
clientId: 'agt_0123456789abcdef',
|
|
264
|
+
privateKey: ClientAssertionSigner.fromPem(process.env.AGENT_PRIVATE_KEY!, { keyId: 'agent-2026-11' }),
|
|
265
|
+
});
|
|
266
|
+
await agent.authenticate();
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
Every token request carries a new assertion: `iss` and `sub` are the agent ID,
|
|
270
|
+
`aud` is the organization's issuer identifier, `exp` is 60 seconds ahead and
|
|
271
|
+
`jti` is random. `ClientAssertionSigner` signs with ES256, ES384, ES512,
|
|
272
|
+
EdDSA, RS256 to RS512 or PS256 to PS512; `agent.createClientAssertion()` gives
|
|
273
|
+
you one for another call. Combine it with `dpop` to also bind the tokens to a key.
|
|
274
|
+
|
|
244
275
|
## DPoP: sender-constrained tokens
|
|
245
276
|
|
|
246
277
|
An MCP server registered with "Require DPoP" accepts only tokens that are
|
package/dist/index.d.mts
CHANGED
|
@@ -1,7 +1,97 @@
|
|
|
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';
|
|
1
|
+
import { AgentsModule, JitModule, DelegationModule, ApprovalsModule, McpModule, DpopProofProvider, AgentAskResult, AgentMcpToolDecision, AgentIdentity, AgentBudget, UsageReport, UsageReportResult, DpopProofRequest, LumoAuthError } from '@lumoauth/shared';
|
|
2
|
+
export { AgentBudget, 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, UsageReport, UsageReportResult, 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
|
/**
|
|
@@ -120,6 +233,20 @@ declare class LumoAgent {
|
|
|
120
233
|
capabilities(): Promise<string[]>;
|
|
121
234
|
/** The agent's budget policy (empty object when no policy is set). */
|
|
122
235
|
budget(): Promise<AgentBudget>;
|
|
236
|
+
/**
|
|
237
|
+
* Report the model tokens and cost that the agent just used, for example
|
|
238
|
+
* the `usage` that the model provider returned. LumoAuth does not see
|
|
239
|
+
* model calls, so token and cost limits count only reported usage. The
|
|
240
|
+
* result's `budget.exhausted` says whether the next metered call (Ask,
|
|
241
|
+
* token or JIT request) will get 429.
|
|
242
|
+
*
|
|
243
|
+
* ```ts
|
|
244
|
+
* const resp = await llm.chat(...);
|
|
245
|
+
* const { budget } = await agent.reportUsage({ tokens: resp.usage.total_tokens, costUsd: 0.0042 });
|
|
246
|
+
* if (budget.exhausted) throw new Error('budget spent');
|
|
247
|
+
* ```
|
|
248
|
+
*/
|
|
249
|
+
reportUsage(report: UsageReport): Promise<UsageReportResult>;
|
|
123
250
|
private requireOrgId;
|
|
124
251
|
}
|
|
125
252
|
|
|
@@ -877,4 +1004,4 @@ declare class AAuthError extends LumoAuthError {
|
|
|
877
1004
|
body?: unknown | undefined);
|
|
878
1005
|
}
|
|
879
1006
|
|
|
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 };
|
|
1007
|
+
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
|
@@ -1,7 +1,97 @@
|
|
|
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';
|
|
1
|
+
import { AgentsModule, JitModule, DelegationModule, ApprovalsModule, McpModule, DpopProofProvider, AgentAskResult, AgentMcpToolDecision, AgentIdentity, AgentBudget, UsageReport, UsageReportResult, DpopProofRequest, LumoAuthError } from '@lumoauth/shared';
|
|
2
|
+
export { AgentBudget, 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, UsageReport, UsageReportResult, 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
|
/**
|
|
@@ -120,6 +233,20 @@ declare class LumoAgent {
|
|
|
120
233
|
capabilities(): Promise<string[]>;
|
|
121
234
|
/** The agent's budget policy (empty object when no policy is set). */
|
|
122
235
|
budget(): Promise<AgentBudget>;
|
|
236
|
+
/**
|
|
237
|
+
* Report the model tokens and cost that the agent just used, for example
|
|
238
|
+
* the `usage` that the model provider returned. LumoAuth does not see
|
|
239
|
+
* model calls, so token and cost limits count only reported usage. The
|
|
240
|
+
* result's `budget.exhausted` says whether the next metered call (Ask,
|
|
241
|
+
* token or JIT request) will get 429.
|
|
242
|
+
*
|
|
243
|
+
* ```ts
|
|
244
|
+
* const resp = await llm.chat(...);
|
|
245
|
+
* const { budget } = await agent.reportUsage({ tokens: resp.usage.total_tokens, costUsd: 0.0042 });
|
|
246
|
+
* if (budget.exhausted) throw new Error('budget spent');
|
|
247
|
+
* ```
|
|
248
|
+
*/
|
|
249
|
+
reportUsage(report: UsageReport): Promise<UsageReportResult>;
|
|
123
250
|
private requireOrgId;
|
|
124
251
|
}
|
|
125
252
|
|
|
@@ -877,4 +1004,4 @@ declare class AAuthError extends LumoAuthError {
|
|
|
877
1004
|
body?: unknown | undefined);
|
|
878
1005
|
}
|
|
879
1006
|
|
|
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 };
|
|
1007
|
+
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 };
|