@lumoauth/agent 0.0.0-stage → 1.1.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/LICENSE +21 -0
- package/README.md +389 -2
- package/dist/index.d.mts +539 -0
- package/dist/index.d.ts +539 -0
- package/dist/index.js +770 -0
- package/dist/index.js.map +1 -0
- package/dist/index.mjs +747 -0
- package/dist/index.mjs.map +1 -0
- package/package.json +50 -5
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,539 @@
|
|
|
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';
|
|
3
|
+
import { KeyObject } from 'node:crypto';
|
|
4
|
+
|
|
5
|
+
interface LumoAgentOptions {
|
|
6
|
+
/**
|
|
7
|
+
* LumoAuth instance URL. Defaults to `process.env.LUMOAUTH_URL` or
|
|
8
|
+
* `https://app.lumoauth.dev`.
|
|
9
|
+
*/
|
|
10
|
+
baseUrl?: string;
|
|
11
|
+
/** Organization slug. Defaults to `process.env.LUMOAUTH_ORG_ID`. */
|
|
12
|
+
orgId?: string;
|
|
13
|
+
/** OAuth client ID. Defaults to `process.env.AGENT_CLIENT_ID`. */
|
|
14
|
+
clientId?: string;
|
|
15
|
+
/** OAuth client secret. Defaults to `process.env.AGENT_CLIENT_SECRET`. */
|
|
16
|
+
clientSecret?: string;
|
|
17
|
+
/** Scopes to request. When omitted the server grants the agent's defaults. */
|
|
18
|
+
scopes?: string[];
|
|
19
|
+
/** OAuth callback URL for the delegation consent flow. */
|
|
20
|
+
redirectUri?: string;
|
|
21
|
+
/** Custom fetch implementation. */
|
|
22
|
+
fetch?: typeof globalThis.fetch;
|
|
23
|
+
/** Request timeout in milliseconds. Default: 30 000 ms. */
|
|
24
|
+
timeout?: number;
|
|
25
|
+
}
|
|
26
|
+
/**
|
|
27
|
+
* High-level agent client — the Node.js counterpart of the Python SDK's
|
|
28
|
+
* `LumoAuthAgent`.
|
|
29
|
+
*
|
|
30
|
+
* Handles the full agent lifecycle:
|
|
31
|
+
* - OAuth 2.0 client-credentials authentication with transparent refresh
|
|
32
|
+
* (60 s safety buffer)
|
|
33
|
+
* - Preflight capability checks (`ask` / `isAllowed`)
|
|
34
|
+
* - Self-inspection (`getCurrentAgent`, `capabilities`, `budget`)
|
|
35
|
+
* - `jit`, `delegation`, `approvals`, and `mcp` namespaces
|
|
36
|
+
*
|
|
37
|
+
* For the AAuth protocol (cryptographic agent identity, RFC 9421 message
|
|
38
|
+
* signing) use {@link AAuthClient} from this same package.
|
|
39
|
+
*
|
|
40
|
+
* @example
|
|
41
|
+
* ```ts
|
|
42
|
+
* import { LumoAgent } from '@lumoauth/agent';
|
|
43
|
+
*
|
|
44
|
+
* const agent = new LumoAgent(); // reads env vars by default
|
|
45
|
+
* if (await agent.isAllowed('document.read', { id: 'doc_99' })) {
|
|
46
|
+
* // ... do the thing
|
|
47
|
+
* }
|
|
48
|
+
*
|
|
49
|
+
* const approval = await agent.approvals.require({
|
|
50
|
+
* taskId: 'wire-001',
|
|
51
|
+
* reason: 'Wire $4,500 to vendor INV-7741',
|
|
52
|
+
* impact: 'high',
|
|
53
|
+
* onBehalfOf: 'ada@acme.com',
|
|
54
|
+
* });
|
|
55
|
+
* ```
|
|
56
|
+
*/
|
|
57
|
+
declare class LumoAgent {
|
|
58
|
+
readonly baseUrl: string;
|
|
59
|
+
readonly orgId: string;
|
|
60
|
+
readonly clientId: string;
|
|
61
|
+
/** Agent identity — ask/isAllowed, self-inspection, registration. */
|
|
62
|
+
readonly agents: AgentsModule;
|
|
63
|
+
/** Just-in-Time permissions — ephemeral tasks and scoped tokens. */
|
|
64
|
+
readonly jit: JitModule;
|
|
65
|
+
/** Chain of Agency — RFC 8693 delegation and nested agent chains. */
|
|
66
|
+
readonly delegation: DelegationModule;
|
|
67
|
+
/** Push-approval-for-agent-actions. */
|
|
68
|
+
readonly approvals: ApprovalsModule;
|
|
69
|
+
/** Token exchange for secured MCP servers. */
|
|
70
|
+
readonly mcp: McpModule;
|
|
71
|
+
private readonly clientSecret;
|
|
72
|
+
private readonly scopes;
|
|
73
|
+
private readonly fetchFn;
|
|
74
|
+
private token;
|
|
75
|
+
private refreshPromise;
|
|
76
|
+
constructor(options?: LumoAgentOptions);
|
|
77
|
+
/**
|
|
78
|
+
* Authenticate with the client-credentials flow. Called automatically
|
|
79
|
+
* by every API method — invoke it directly only to fail fast at
|
|
80
|
+
* startup or to request non-default scopes.
|
|
81
|
+
*/
|
|
82
|
+
authenticate(scopes?: string[]): Promise<string>;
|
|
83
|
+
/**
|
|
84
|
+
* The current access token, re-authenticating transparently when it is
|
|
85
|
+
* missing or within 60 s of expiry. Concurrent callers share one
|
|
86
|
+
* in-flight token request.
|
|
87
|
+
*/
|
|
88
|
+
getAccessToken(): Promise<string>;
|
|
89
|
+
/** Scopes granted by the last successful authentication. */
|
|
90
|
+
get tokenScopes(): string[];
|
|
91
|
+
/** Preflight check: is the agent authorised to perform `action`? */
|
|
92
|
+
ask(action: string, context?: Record<string, unknown>): Promise<AgentAskResult>;
|
|
93
|
+
/** Convenience wrapper: `true` when `action` is allowed. */
|
|
94
|
+
isAllowed(action: string, context?: Record<string, unknown>): Promise<boolean>;
|
|
95
|
+
/** The agent's own identity, capabilities, and workspace. */
|
|
96
|
+
getCurrentAgent(): Promise<AgentIdentity>;
|
|
97
|
+
/** The agent's declared capability slugs. */
|
|
98
|
+
capabilities(): Promise<string[]>;
|
|
99
|
+
/** The agent's budget policy (empty object when no policy is set). */
|
|
100
|
+
budget(): Promise<AgentBudget>;
|
|
101
|
+
private requireOrgId;
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
/** A public JSON Web Key as published in a JWKS. */
|
|
105
|
+
interface AAuthJwk {
|
|
106
|
+
kty: string;
|
|
107
|
+
crv?: string;
|
|
108
|
+
x?: string;
|
|
109
|
+
y?: string;
|
|
110
|
+
n?: string;
|
|
111
|
+
e?: string;
|
|
112
|
+
use?: string;
|
|
113
|
+
kid?: string;
|
|
114
|
+
alg?: string;
|
|
115
|
+
[key: string]: unknown;
|
|
116
|
+
}
|
|
117
|
+
interface AAuthKeypair {
|
|
118
|
+
/** PKCS#8 PEM-encoded Ed25519 private key. Store in your secret manager. */
|
|
119
|
+
privateKeyPem: string;
|
|
120
|
+
/** SPKI PEM-encoded public key. */
|
|
121
|
+
publicKeyPem: string;
|
|
122
|
+
/** The public key as a JWK (with `use: "sig"` and the given `kid`). */
|
|
123
|
+
jwk: AAuthJwk;
|
|
124
|
+
/** A JWKS document ready to publish at `/.well-known/jwks.json`. */
|
|
125
|
+
jwks: {
|
|
126
|
+
keys: AAuthJwk[];
|
|
127
|
+
};
|
|
128
|
+
}
|
|
129
|
+
/**
|
|
130
|
+
* Generate an Ed25519 key pair suitable for AAuth.
|
|
131
|
+
*
|
|
132
|
+
* Mirrors the Python SDK's `AAuthClient.generate_keypair()`: returns the
|
|
133
|
+
* PKCS#8 private key PEM plus a JWKS document ready to be published at
|
|
134
|
+
* `/.well-known/jwks.json` (or registered inline with LumoAuth).
|
|
135
|
+
*
|
|
136
|
+
* @example
|
|
137
|
+
* ```ts
|
|
138
|
+
* import { generateKeypair } from '@lumoauth/agent';
|
|
139
|
+
*
|
|
140
|
+
* const { privateKeyPem, jwks } = generateKeypair();
|
|
141
|
+
* console.log(JSON.stringify(jwks, null, 2));
|
|
142
|
+
* ```
|
|
143
|
+
*/
|
|
144
|
+
declare function generateKeypair(kid?: string): AAuthKeypair;
|
|
145
|
+
/**
|
|
146
|
+
* Compute the RFC 7638 JWK thumbprint (base64url-encoded SHA-256) of a
|
|
147
|
+
* public JWK. This is the `jkt` value AAuth uses to bind tokens to keys.
|
|
148
|
+
*/
|
|
149
|
+
declare function jwkThumbprint(jwk: AAuthJwk): string;
|
|
150
|
+
/** Derive the public JWK for a loaded private key. */
|
|
151
|
+
declare function publicJwkFromPrivateKey(pem: string, kid?: string): AAuthJwk;
|
|
152
|
+
|
|
153
|
+
/**
|
|
154
|
+
* RFC 9421 HTTP Message Signing, profiled for AAuth.
|
|
155
|
+
*
|
|
156
|
+
* The LumoAuth agent token endpoint enforces a strict profile (AAuth 1.0 §4):
|
|
157
|
+
*
|
|
158
|
+
* - Covered components: `@method @authority @path signature-key
|
|
159
|
+
* content-digest content-type authorization` (plus `@query` if and only if
|
|
160
|
+
* the target URI has a query string).
|
|
161
|
+
* - `Signature-Input` parameters: exactly `created` (within ±60 s) and a
|
|
162
|
+
* fresh `nonce` (≥ 12 bytes / 96 bits of entropy, base64url).
|
|
163
|
+
* - `Content-Digest` per RFC 9530 with **standard** base64 (`sha-256=:…:`).
|
|
164
|
+
* - The `Signature` value is **base64url** encoded (`label=:…:`).
|
|
165
|
+
* - Algorithms: Ed25519 or RSA-PSS-SHA512 (MGF1-SHA512, 64-byte salt),
|
|
166
|
+
* dispatched by key type — do NOT declare an `alg` parameter.
|
|
167
|
+
*/
|
|
168
|
+
/** Covered components required by the AAuth agent token endpoint, in order. */
|
|
169
|
+
declare const AAUTH_COVERED_COMPONENTS: readonly ["@method", "@authority", "@path", "signature-key", "content-digest", "content-type", "authorization"];
|
|
170
|
+
/**
|
|
171
|
+
* Compute an RFC 9530 `Content-Digest` header value over the exact body
|
|
172
|
+
* bytes. Uses sha-256 with STANDARD base64 (the server base64-decodes it).
|
|
173
|
+
*/
|
|
174
|
+
declare function contentDigestSha256(body: Buffer | Uint8Array | string): string;
|
|
175
|
+
/** Generate a fresh signature nonce: base64url of 16 random bytes (128 bits). */
|
|
176
|
+
declare function generateNonce(): string;
|
|
177
|
+
/**
|
|
178
|
+
* Build the RFC 9421 signature base: one `"<component>": <value>` line per
|
|
179
|
+
* covered component in declared order, then the `"@signature-params"` line
|
|
180
|
+
* carrying ONLY `created` and `nonce`.
|
|
181
|
+
*/
|
|
182
|
+
declare function buildSignatureBase(components: readonly string[], values: Record<string, string>, created: number, nonce: string): string;
|
|
183
|
+
/** The `(…);created=…;nonce="…"` parameter string shared by the base and header. */
|
|
184
|
+
declare function signatureParams(components: readonly string[], created: number, nonce: string): string;
|
|
185
|
+
/**
|
|
186
|
+
* Sign a signature base with the agent's private key.
|
|
187
|
+
* Ed25519 keys produce `ed25519` signatures; RSA keys produce
|
|
188
|
+
* `rsa-pss-sha512` signatures (MGF1-SHA512, salt length = digest length).
|
|
189
|
+
* Returns the base64url-encoded signature (RFC 9421 profile).
|
|
190
|
+
*/
|
|
191
|
+
declare function signSignatureBase(signatureBase: string, privateKey: KeyObject): string;
|
|
192
|
+
/**
|
|
193
|
+
* Verify a base64url signature over a signature base (resource-server side).
|
|
194
|
+
* Dispatches on key type like the LumoAuth server does.
|
|
195
|
+
*/
|
|
196
|
+
declare function verifySignatureBase(signatureBase: string, signatureB64url: string, publicKey: KeyObject): boolean;
|
|
197
|
+
interface SignRequestOptions {
|
|
198
|
+
/** Raw request body. Defaults to the empty body. */
|
|
199
|
+
body?: Buffer | Uint8Array | string;
|
|
200
|
+
/** Media type of the body. Default: `application/json`. */
|
|
201
|
+
contentType?: string;
|
|
202
|
+
/** The `agent+jwt` to present in the `Agent-Auth` header. */
|
|
203
|
+
agentToken?: string;
|
|
204
|
+
/** Value of a covered `Authorization` header, if any (e.g. `Bearer …`). */
|
|
205
|
+
authorization?: string;
|
|
206
|
+
/** Value of a covered `Signature-Key` header, if any. */
|
|
207
|
+
signatureKey?: string;
|
|
208
|
+
/**
|
|
209
|
+
* Override the `created` timestamp (seconds). Testing only — the server
|
|
210
|
+
* rejects timestamps more than 60 s from its clock.
|
|
211
|
+
*/
|
|
212
|
+
created?: number;
|
|
213
|
+
/** Override the nonce. Testing only — nonces are single-use server-side. */
|
|
214
|
+
nonce?: string;
|
|
215
|
+
}
|
|
216
|
+
/**
|
|
217
|
+
* Create RFC 9421 signature headers for a request to the AAuth agent token
|
|
218
|
+
* endpoint (or any endpoint enforcing the AAuth profile).
|
|
219
|
+
*
|
|
220
|
+
* Byte-compatible with the Python SDK's `AAuthClient.sign_request()`.
|
|
221
|
+
*/
|
|
222
|
+
declare function signRequest(privateKeyPem: string, method: string, url: string, options?: SignRequestOptions): Record<string, string>;
|
|
223
|
+
|
|
224
|
+
/**
|
|
225
|
+
* Auth-token (`auth+jwt`) verification for resource servers.
|
|
226
|
+
*
|
|
227
|
+
* Verifies the JWS signature against the organization's AAuth issuer JWKS
|
|
228
|
+
* (`{issuer}/aauth/jwks.json`), plus `typ`, `iss`, `aud`, and `exp` — the
|
|
229
|
+
* same checks LumoAuth's own `validateAuthToken()` performs (revocation
|
|
230
|
+
* excepted: use `POST {issuer}/aauth/auth/token/verify` for live
|
|
231
|
+
* revocation-aware introspection).
|
|
232
|
+
*
|
|
233
|
+
* NOTE: AAuth auth tokens are proof-of-possession tokens. After verifying
|
|
234
|
+
* the JWT, the resource MUST also verify the request's RFC 9421 signature
|
|
235
|
+
* against the key in `cnf.jwk` (see `verifySignatureBase` and
|
|
236
|
+
* `jwkThumbprint`).
|
|
237
|
+
*/
|
|
238
|
+
interface AAuthTokenClaims {
|
|
239
|
+
iss: string;
|
|
240
|
+
aud: string;
|
|
241
|
+
exp: number;
|
|
242
|
+
iat: number;
|
|
243
|
+
jti: string;
|
|
244
|
+
cnf: {
|
|
245
|
+
jwk: AAuthJwk;
|
|
246
|
+
};
|
|
247
|
+
agent?: string;
|
|
248
|
+
agent_delegate?: string;
|
|
249
|
+
scope?: string;
|
|
250
|
+
sub?: string;
|
|
251
|
+
act?: Record<string, unknown>;
|
|
252
|
+
[claim: string]: unknown;
|
|
253
|
+
}
|
|
254
|
+
interface VerifyAuthTokenOptions {
|
|
255
|
+
/** The trusted issuer URL, e.g. `https://app.lumoauth.dev/orgs/acme-corp/api/v1`. */
|
|
256
|
+
issuer: string;
|
|
257
|
+
/** Your resource identifier — must equal the token's `aud`. */
|
|
258
|
+
resource: string;
|
|
259
|
+
/** Pre-fetched issuer JWKS (skips the network fetch). */
|
|
260
|
+
jwks?: {
|
|
261
|
+
keys: AAuthJwk[];
|
|
262
|
+
};
|
|
263
|
+
/** Custom fetch implementation. */
|
|
264
|
+
fetch?: typeof globalThis.fetch;
|
|
265
|
+
/** Allowed clock skew in seconds for `exp`. Default 0 (like the server). */
|
|
266
|
+
clockSkew?: number;
|
|
267
|
+
}
|
|
268
|
+
/** Decode a JWT without verifying it. Useful for reading `aud`/`cnf` first. */
|
|
269
|
+
declare function decodeJwt(token: string): {
|
|
270
|
+
header: Record<string, unknown>;
|
|
271
|
+
claims: Record<string, unknown>;
|
|
272
|
+
};
|
|
273
|
+
/**
|
|
274
|
+
* Verify an AAuth auth token (`auth+jwt`) against the issuing
|
|
275
|
+
* organization's JWKS. Returns the verified claims or throws `AAuthError`.
|
|
276
|
+
*
|
|
277
|
+
* @example
|
|
278
|
+
* ```ts
|
|
279
|
+
* import { verifyAuthToken } from '@lumoauth/agent';
|
|
280
|
+
*
|
|
281
|
+
* const claims = await verifyAuthToken(bearer, {
|
|
282
|
+
* issuer: 'https://app.lumoauth.dev/orgs/acme-corp/api/v1',
|
|
283
|
+
* resource: 'https://api.example.com',
|
|
284
|
+
* });
|
|
285
|
+
* // Then enforce PoP: verify the request signature against claims.cnf.jwk.
|
|
286
|
+
* ```
|
|
287
|
+
*/
|
|
288
|
+
declare function verifyAuthToken(token: string, options: VerifyAuthTokenOptions): Promise<AAuthTokenClaims>;
|
|
289
|
+
|
|
290
|
+
interface AAuthClientOptions {
|
|
291
|
+
/** HTTPS URL uniquely identifying the agent (e.g. `https://my-agent.example.com`). */
|
|
292
|
+
agentIdentifier: string;
|
|
293
|
+
/** PEM-encoded Ed25519 (PKCS#8) or RSA private key. */
|
|
294
|
+
privateKeyPem: string;
|
|
295
|
+
/**
|
|
296
|
+
* LumoAuth instance URL. Defaults to `process.env.LUMOAUTH_URL` or
|
|
297
|
+
* `https://app.lumoauth.dev`.
|
|
298
|
+
*/
|
|
299
|
+
baseUrl?: string;
|
|
300
|
+
/** Organization ID (slug). Defaults to `process.env.LUMOAUTH_ORG_ID`. */
|
|
301
|
+
orgId?: string;
|
|
302
|
+
/** Key ID matching the JWKS entry registered with LumoAuth. Default `key-1`. */
|
|
303
|
+
kid?: string;
|
|
304
|
+
/** Custom fetch implementation (defaults to the global `fetch`). */
|
|
305
|
+
fetch?: typeof globalThis.fetch;
|
|
306
|
+
/** Request timeout in milliseconds. Default: 30 000 ms. */
|
|
307
|
+
timeout?: number;
|
|
308
|
+
}
|
|
309
|
+
/** Successful response from the agent token endpoint. */
|
|
310
|
+
interface AAuthTokenResponse {
|
|
311
|
+
requestType: 'auth' | 'code' | 'exchange' | 'refresh';
|
|
312
|
+
/** The `auth+jwt` access token to present to the resource. */
|
|
313
|
+
authToken: string;
|
|
314
|
+
expiresIn: number;
|
|
315
|
+
tokenType: string;
|
|
316
|
+
refreshToken?: string;
|
|
317
|
+
}
|
|
318
|
+
/** Returned by `requestAuthToken()` when the user must consent first. */
|
|
319
|
+
interface AAuthAuthorizationRequired {
|
|
320
|
+
authorizationRequired: true;
|
|
321
|
+
/** Opaque token identifying the pending request (600 s TTL). */
|
|
322
|
+
requestToken: string;
|
|
323
|
+
/** Consent page URL — redirect the user here. */
|
|
324
|
+
authorizationUri: string;
|
|
325
|
+
expiresIn?: number;
|
|
326
|
+
}
|
|
327
|
+
interface AAuthIssuerMetadata {
|
|
328
|
+
issuer: string;
|
|
329
|
+
aauth_version: string;
|
|
330
|
+
jwks_uri: string;
|
|
331
|
+
agent_token_endpoint: string;
|
|
332
|
+
agent_auth_endpoint: string;
|
|
333
|
+
agent_signing_algs_supported: string[];
|
|
334
|
+
token_signing_algs_supported: string[];
|
|
335
|
+
request_types_supported: string[];
|
|
336
|
+
scopes_supported: string[];
|
|
337
|
+
[key: string]: unknown;
|
|
338
|
+
}
|
|
339
|
+
interface AAuthAgentMetadata {
|
|
340
|
+
agent: string;
|
|
341
|
+
jwks_uri: string;
|
|
342
|
+
redirect_uris?: string[];
|
|
343
|
+
name?: string;
|
|
344
|
+
[key: string]: unknown;
|
|
345
|
+
}
|
|
346
|
+
interface AAuthResourceMetadata {
|
|
347
|
+
resource: string;
|
|
348
|
+
jwks_uri: string;
|
|
349
|
+
resource_token_endpoint?: string;
|
|
350
|
+
supported_scopes?: string[];
|
|
351
|
+
[key: string]: unknown;
|
|
352
|
+
}
|
|
353
|
+
/**
|
|
354
|
+
* Client for the AAuth (Agent Auth) protocol — the Node.js counterpart of
|
|
355
|
+
* the Python SDK's `lumoauth.AAuthClient`.
|
|
356
|
+
*
|
|
357
|
+
* AAuth extends OAuth 2.1 with cryptographic agent identity,
|
|
358
|
+
* proof-of-possession tokens, and RFC 9421 HTTP message signing.
|
|
359
|
+
*
|
|
360
|
+
* @example
|
|
361
|
+
* ```ts
|
|
362
|
+
* import { AAuthClient } from '@lumoauth/agent';
|
|
363
|
+
*
|
|
364
|
+
* const client = new AAuthClient({
|
|
365
|
+
* agentIdentifier: 'https://my-agent.example.com',
|
|
366
|
+
* privateKeyPem: process.env.AGENT_PRIVATE_KEY!,
|
|
367
|
+
* baseUrl: 'https://app.lumoauth.dev',
|
|
368
|
+
* orgId: 'acme-corp',
|
|
369
|
+
* });
|
|
370
|
+
*
|
|
371
|
+
* const result = await client.requestAuthToken({
|
|
372
|
+
* resourceToken,
|
|
373
|
+
* scope: 'read write',
|
|
374
|
+
* agentToken,
|
|
375
|
+
* });
|
|
376
|
+
* if ('authorizationRequired' in result) {
|
|
377
|
+
* // redirect the user to result.authorizationUri, then exchangeCode()
|
|
378
|
+
* } else {
|
|
379
|
+
* const resp = await client.signedRequest('GET', 'https://api.example.com/v1/data', {
|
|
380
|
+
* authToken: result.authToken,
|
|
381
|
+
* });
|
|
382
|
+
* }
|
|
383
|
+
* ```
|
|
384
|
+
*/
|
|
385
|
+
declare class AAuthClient {
|
|
386
|
+
/** Generate an Ed25519 key pair suitable for AAuth (parity with Python). */
|
|
387
|
+
static generateKeypair: typeof generateKeypair;
|
|
388
|
+
readonly agentIdentifier: string;
|
|
389
|
+
readonly baseUrl: string;
|
|
390
|
+
readonly orgId: string;
|
|
391
|
+
readonly kid: string;
|
|
392
|
+
private readonly privateKeyPem;
|
|
393
|
+
private readonly fetchFn;
|
|
394
|
+
private readonly timeout;
|
|
395
|
+
constructor(options: AAuthClientOptions);
|
|
396
|
+
/** The organization's AAuth issuer URL: `{baseUrl}/orgs/{orgId}/api/v1`. */
|
|
397
|
+
get issuer(): string;
|
|
398
|
+
/** The agent's public JWK derived from its private key. */
|
|
399
|
+
get publicJwk(): AAuthJwk;
|
|
400
|
+
/** RFC 7638 thumbprint of the agent's public key (the `jkt` binding value). */
|
|
401
|
+
get publicJwkThumbprint(): string;
|
|
402
|
+
/**
|
|
403
|
+
* Create RFC 9421 signature headers for a request per the AAuth profile.
|
|
404
|
+
* See `signRequest()` in `signing.ts` for the exact contract.
|
|
405
|
+
*/
|
|
406
|
+
signRequest(method: string, url: string, options?: SignRequestOptions): Record<string, string>;
|
|
407
|
+
/**
|
|
408
|
+
* Request an auth token (`request_type=auth` — direct authorization).
|
|
409
|
+
*
|
|
410
|
+
* Presents the resource token in the body and the agent token in the
|
|
411
|
+
* `Agent-Auth` header, signed with the agent's key. If the server
|
|
412
|
+
* requires user consent it returns `{ authorizationRequired: true,
|
|
413
|
+
* requestToken, authorizationUri }` — redirect the user, then call
|
|
414
|
+
* `exchangeCode()` with the code delivered to your `redirectUri`.
|
|
415
|
+
*/
|
|
416
|
+
requestAuthToken(params: {
|
|
417
|
+
/** Resource token (`resource+jwt`) obtained from the target resource. */
|
|
418
|
+
resourceToken: string;
|
|
419
|
+
/** Space-separated scopes (informational; scopes bind via the resource token). */
|
|
420
|
+
scope?: string;
|
|
421
|
+
/** The `agent+jwt` presented in `Agent-Auth`. */
|
|
422
|
+
agentToken: string;
|
|
423
|
+
/** Redirect URI for user-consent flows (must be registered). */
|
|
424
|
+
redirectUri?: string;
|
|
425
|
+
}): Promise<AAuthTokenResponse | AAuthAuthorizationRequired>;
|
|
426
|
+
/**
|
|
427
|
+
* Build the user-consent URL for a pending request token
|
|
428
|
+
* (`GET {issuer}/aauth/agent/auth?request_token=…`). Prefer the
|
|
429
|
+
* `authorizationUri` returned by `requestAuthToken()` when present.
|
|
430
|
+
*/
|
|
431
|
+
buildConsentUrl(requestToken: string): string;
|
|
432
|
+
/**
|
|
433
|
+
* Exchange an authorization code for tokens (`request_type=code`) after
|
|
434
|
+
* user consent. `redirectUri` must be the exact URI the code was
|
|
435
|
+
* delivered to.
|
|
436
|
+
*/
|
|
437
|
+
exchangeCode(params: {
|
|
438
|
+
code: string;
|
|
439
|
+
redirectUri: string;
|
|
440
|
+
agentToken: string;
|
|
441
|
+
}): Promise<AAuthTokenResponse>;
|
|
442
|
+
/**
|
|
443
|
+
* Multi-hop token exchange (`request_type=exchange`): trade an upstream
|
|
444
|
+
* auth token plus a downstream resource token for a new auth token with
|
|
445
|
+
* an `act` actor chain. Requires token exchange to be enabled for the
|
|
446
|
+
* agent.
|
|
447
|
+
*/
|
|
448
|
+
exchangeToken(params: {
|
|
449
|
+
/** The upstream `auth+jwt` addressed to this agent. */
|
|
450
|
+
authToken: string;
|
|
451
|
+
/** Resource token issued by the downstream resource to this agent. */
|
|
452
|
+
resourceToken: string;
|
|
453
|
+
agentToken: string;
|
|
454
|
+
}): Promise<AAuthTokenResponse>;
|
|
455
|
+
/**
|
|
456
|
+
* Refresh an auth token (`request_type=refresh`). A fresh resource token
|
|
457
|
+
* for the target resource is required; scopes requested via the resource
|
|
458
|
+
* token must be a subset of the original grant. Refresh tokens are not
|
|
459
|
+
* rotated.
|
|
460
|
+
*/
|
|
461
|
+
refresh(params: {
|
|
462
|
+
refreshToken: string;
|
|
463
|
+
/** Fresh resource token for the target resource. */
|
|
464
|
+
resourceToken: string;
|
|
465
|
+
/** Optional scope narrowing. */
|
|
466
|
+
scope?: string;
|
|
467
|
+
agentToken: string;
|
|
468
|
+
}): Promise<AAuthTokenResponse>;
|
|
469
|
+
/**
|
|
470
|
+
* Revoke an auth token (by its `jti`) or a refresh token (by value).
|
|
471
|
+
* Always resolves `{ revoked: true }` — the server does not reveal
|
|
472
|
+
* whether the token existed.
|
|
473
|
+
*/
|
|
474
|
+
revoke(params: {
|
|
475
|
+
/** A refresh-token value, or an auth token's `jti`. */
|
|
476
|
+
token: string;
|
|
477
|
+
tokenType?: 'auth_token' | 'refresh_token';
|
|
478
|
+
agentToken: string;
|
|
479
|
+
}): Promise<{
|
|
480
|
+
revoked: boolean;
|
|
481
|
+
}>;
|
|
482
|
+
/**
|
|
483
|
+
* Make a signed, authenticated request to a protected resource.
|
|
484
|
+
*
|
|
485
|
+
* Carries the auth token as `Authorization: Bearer …` **and** an RFC
|
|
486
|
+
* 9421 signature proving possession of the key bound in the token's
|
|
487
|
+
* `cnf.jwk`. The signature covers the `authorization` component, so the
|
|
488
|
+
* resource can verify both together.
|
|
489
|
+
*
|
|
490
|
+
* Returns the raw `fetch` Response.
|
|
491
|
+
*/
|
|
492
|
+
signedRequest(method: string, url: string, options: {
|
|
493
|
+
/** The AAuth `auth+jwt` access token. */
|
|
494
|
+
authToken: string;
|
|
495
|
+
/** JSON body (for POST/PUT). */
|
|
496
|
+
data?: unknown;
|
|
497
|
+
/** Extra headers (not covered by the signature). */
|
|
498
|
+
headers?: Record<string, string>;
|
|
499
|
+
}): Promise<Response>;
|
|
500
|
+
/**
|
|
501
|
+
* Verify an `auth+jwt` against this organization's issuer JWKS.
|
|
502
|
+
* See `verifyAuthToken()` for details (PoP still required!).
|
|
503
|
+
*/
|
|
504
|
+
verifyAuthToken(token: string, options: Omit<VerifyAuthTokenOptions, 'issuer' | 'fetch'> & {
|
|
505
|
+
issuer?: string;
|
|
506
|
+
}): Promise<AAuthTokenClaims>;
|
|
507
|
+
/** Fetch `{issuer}/.well-known/aauth-issuer`. */
|
|
508
|
+
discoverIssuer(): Promise<AAuthIssuerMetadata>;
|
|
509
|
+
/** Fetch `{issuer}/.well-known/aauth-agent` — metadata for all active agents. */
|
|
510
|
+
discoverAgents(): Promise<AAuthAgentMetadata[]>;
|
|
511
|
+
/** Fetch `{resourceUrl}/.well-known/aauth-resource` from a resource server. */
|
|
512
|
+
discoverResource(resourceUrl: string): Promise<AAuthResourceMetadata | AAuthResourceMetadata[]>;
|
|
513
|
+
private requireAgentToken;
|
|
514
|
+
private tokenUrl;
|
|
515
|
+
/** Absolute URL for an org-scoped route from the shared registry. */
|
|
516
|
+
private routeUrl;
|
|
517
|
+
private tokenRequest;
|
|
518
|
+
private signedPost;
|
|
519
|
+
private mapTokenResponse;
|
|
520
|
+
private getJson;
|
|
521
|
+
private doFetch;
|
|
522
|
+
}
|
|
523
|
+
|
|
524
|
+
/**
|
|
525
|
+
* Thrown for AAuth protocol failures — OAuth-style `{error,
|
|
526
|
+
* error_description}` bodies from the agent token endpoint, signature
|
|
527
|
+
* problems, and token-verification failures.
|
|
528
|
+
*/
|
|
529
|
+
declare class AAuthError extends LumoAuthError {
|
|
530
|
+
/** The parsed response body, when the error came from the server. */
|
|
531
|
+
readonly body?: unknown | undefined;
|
|
532
|
+
constructor(message: string,
|
|
533
|
+
/** OAuth-style error code, e.g. `invalid_grant`, `authentication_required`. */
|
|
534
|
+
code: string, statusCode?: number,
|
|
535
|
+
/** The parsed response body, when the error came from the server. */
|
|
536
|
+
body?: unknown | undefined);
|
|
537
|
+
}
|
|
538
|
+
|
|
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 };
|