@lumoauth/agent 1.5.0 → 1.6.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 +11 -9
- package/dist/index.d.mts +83 -27
- package/dist/index.d.ts +83 -27
- package/dist/index.js +19 -11
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +19 -11
- package/dist/index.mjs.map +1 -1
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -69,7 +69,7 @@ import { LumoAgent } from '@lumoauth/agent';
|
|
|
69
69
|
const agent = new LumoAgent(); // reads the variables above
|
|
70
70
|
|
|
71
71
|
// 1. Check first: may this agent do this, in this context?
|
|
72
|
-
if (!(await agent.isAllowed('document
|
|
72
|
+
if (!(await agent.isAllowed('document:read', { id: 'doc_99' }))) {
|
|
73
73
|
throw new Error('not allowed');
|
|
74
74
|
}
|
|
75
75
|
|
|
@@ -122,7 +122,7 @@ call the server.
|
|
|
122
122
|
boolean.
|
|
123
123
|
|
|
124
124
|
```ts
|
|
125
|
-
const decision = await agent.ask('tickets
|
|
125
|
+
const decision = await agent.ask('tickets:write', { ticket: 'T-42' });
|
|
126
126
|
// decision.allowed, decision.action, decision.reason, decision.audit_id
|
|
127
127
|
```
|
|
128
128
|
|
|
@@ -201,11 +201,11 @@ return at once. A JIT token lasts at most 900 seconds.
|
|
|
201
201
|
```ts
|
|
202
202
|
const agent = new LumoAgent({ redirectUri: 'https://agent.example.com/callback' });
|
|
203
203
|
|
|
204
|
-
const url = agent.delegation.getConsentUrl('session-1', ['read
|
|
204
|
+
const url = agent.delegation.getConsentUrl('session-1', ['documents:read']);
|
|
205
205
|
// …the user consents and returns with ?code=…
|
|
206
206
|
await agent.delegation.handleConsentCallback('session-1', code);
|
|
207
207
|
|
|
208
|
-
const delegated = await agent.delegation.exchange('session-1', ['read
|
|
208
|
+
const delegated = await agent.delegation.exchange('session-1', ['documents:read'], {
|
|
209
209
|
resource: 'https://api.example.com', // becomes the token's aud
|
|
210
210
|
});
|
|
211
211
|
```
|
|
@@ -399,7 +399,7 @@ const aauth = new AAuthClient({
|
|
|
399
399
|
orgId: 'acme-corp',
|
|
400
400
|
});
|
|
401
401
|
|
|
402
|
-
const result = await aauth.requestAuthToken({ resourceToken, agentToken
|
|
402
|
+
const result = await aauth.requestAuthToken({ resourceToken, agentToken });
|
|
403
403
|
|
|
404
404
|
if ('authorizationRequired' in result) {
|
|
405
405
|
// The user has to consent first. Send them to result.authorizationUri,
|
|
@@ -412,8 +412,10 @@ if ('authorizationRequired' in result) {
|
|
|
412
412
|
```
|
|
413
413
|
|
|
414
414
|
`resourceToken` is the resource token that the target resource issued to the
|
|
415
|
-
agent. `
|
|
416
|
-
|
|
415
|
+
agent. Its `scope` claim names the scope of the auth token: LumoAuth ignores a
|
|
416
|
+
`scope` that is passed to `requestAuthToken`. `agentToken` is the agent's own
|
|
417
|
+
`agent+jwt`, sent in the `Agent-Auth` header. The key that signs the request
|
|
418
|
+
must be the key in the agent token's `cnf` claim.
|
|
417
419
|
|
|
418
420
|
### `AAuthClient` options
|
|
419
421
|
|
|
@@ -431,11 +433,11 @@ header.
|
|
|
431
433
|
|
|
432
434
|
| Method | What it does |
|
|
433
435
|
|---|---|
|
|
434
|
-
| `requestAuthToken({ resourceToken, agentToken, scope?, redirectUri? })` | Requests an auth token. Returns the token, or `{ authorizationRequired: true, requestToken, authorizationUri }` when the user must consent |
|
|
436
|
+
| `requestAuthToken({ resourceToken, agentToken, scope?, redirectUri? })` | Requests an auth token. Returns the token, or `{ authorizationRequired: true, requestToken, authorizationUri }` when the user must consent. Consent needs `redirectUri`. LumoAuth ignores `scope` here |
|
|
435
437
|
| `buildConsentUrl(requestToken)` | Builds the consent URL for a pending request token |
|
|
436
438
|
| `exchangeCode({ code, redirectUri, agentToken })` | Exchanges the consent code for an auth token |
|
|
437
439
|
| `exchangeToken({ authToken, resourceToken, agentToken })` | Exchanges an upstream auth token for a downstream one, which adds to the `act` chain |
|
|
438
|
-
| `refresh({ refreshToken, resourceToken, scope?, agentToken })` | Refreshes an auth token. It needs a
|
|
440
|
+
| `refresh({ refreshToken, resourceToken, scope?, agentToken })` | Refreshes an auth token. It needs a resource token from the same resource. `scope` only narrows: a scope outside the grant is refused with `invalid_scope` |
|
|
439
441
|
| `revoke({ token, tokenType?, agentToken })` | Revokes an auth token by its `jti`, or a refresh token by value |
|
|
440
442
|
| `signRequest(method, url, options?)` | Returns RFC 9421 signature headers for a request |
|
|
441
443
|
| `signedRequest(method, url, { authToken, data?, headers? })` | Sends a signed request with the auth token, and returns the `fetch` `Response` |
|
package/dist/index.d.mts
CHANGED
|
@@ -154,7 +154,7 @@ interface LumoAgentOptions {
|
|
|
154
154
|
* import { LumoAgent } from '@lumoauth/agent';
|
|
155
155
|
*
|
|
156
156
|
* const agent = new LumoAgent(); // reads env vars by default
|
|
157
|
-
* if (await agent.isAllowed('document
|
|
157
|
+
* if (await agent.isAllowed('document:read', { id: 'doc_99' })) {
|
|
158
158
|
* // ... do the thing
|
|
159
159
|
* }
|
|
160
160
|
*
|
|
@@ -293,7 +293,9 @@ interface AAuthKeypair {
|
|
|
293
293
|
declare function generateKeypair(kid?: string): AAuthKeypair;
|
|
294
294
|
/**
|
|
295
295
|
* Compute the RFC 7638 JWK thumbprint (base64url-encoded SHA-256) of a
|
|
296
|
-
* public JWK.
|
|
296
|
+
* public JWK. LumoAuth uses it as `agent_jkt` in resource tokens and as
|
|
297
|
+
* `cnf_jkt` in the answer of the token verify endpoint. Auth tokens carry
|
|
298
|
+
* the full key in `cnf.jwk`, not the thumbprint.
|
|
297
299
|
*/
|
|
298
300
|
declare function jwkThumbprint(jwk: AAuthJwk): string;
|
|
299
301
|
/** Derive the public JWK for a loaded private key. */
|
|
@@ -306,13 +308,24 @@ declare function publicJwkFromPrivateKey(pem: string, kid?: string): AAuthJwk;
|
|
|
306
308
|
*
|
|
307
309
|
* - Covered components: `@method @authority @path signature-key
|
|
308
310
|
* content-digest content-type authorization` (plus `@query` if and only if
|
|
309
|
-
* the target URI has a query string).
|
|
310
|
-
*
|
|
311
|
-
*
|
|
311
|
+
* the target URI has a query string). `signature-key` and `authorization`
|
|
312
|
+
* are the values of the `Signature-Key` and `Authorization` request
|
|
313
|
+
* headers, or the empty string when the header is not sent. `@target-uri`
|
|
314
|
+
* is not accepted in place of `@authority` and `@path`.
|
|
315
|
+
* - `Signature-Input` parameters: `created` (required, within ±60 s of the
|
|
316
|
+
* server clock) and a single-use `nonce` (required, base64url of at least
|
|
317
|
+
* 12 random bytes). The server also accepts `expires`, `alg`, `keyid` and
|
|
318
|
+
* `tag`, and refuses any other parameter. This signer sends only
|
|
319
|
+
* `created` and `nonce`.
|
|
312
320
|
* - `Content-Digest` per RFC 9530 with **standard** base64 (`sha-256=:…:`).
|
|
313
|
-
*
|
|
314
|
-
* -
|
|
315
|
-
*
|
|
321
|
+
* The header is mandatory and must match the body.
|
|
322
|
+
* - The `Signature` value (`label=:…:`) is sent **base64url** encoded. The
|
|
323
|
+
* server accepts base64url and standard base64.
|
|
324
|
+
* - The algorithm follows the key type: Ed25519 → `ed25519`, RSA →
|
|
325
|
+
* `rsa-pss-sha512` (MGF1-SHA512, 64-byte salt). The server also accepts
|
|
326
|
+
* EC P-256 keys (`ecdsa-p256-sha256`, raw r||s), which this signer does
|
|
327
|
+
* not support. An `alg` parameter is optional (it must then name the
|
|
328
|
+
* algorithm of the key); this signer declares none.
|
|
316
329
|
*/
|
|
317
330
|
/** Covered components required by the AAuth agent token endpoint, in order. */
|
|
318
331
|
declare const AAUTH_COVERED_COMPONENTS: readonly ["@method", "@authority", "@path", "signature-key", "content-digest", "content-type", "authorization"];
|
|
@@ -340,7 +353,10 @@ declare function signatureParams(components: readonly string[], created: number,
|
|
|
340
353
|
declare function signSignatureBase(signatureBase: string, privateKey: KeyObject): string;
|
|
341
354
|
/**
|
|
342
355
|
* Verify a base64url signature over a signature base (resource-server side).
|
|
343
|
-
* Dispatches on key type like the LumoAuth server does
|
|
356
|
+
* Dispatches on key type like the LumoAuth server does, for Ed25519 and RSA
|
|
357
|
+
* keys only: a signature made with an EC P-256 key, which the server also
|
|
358
|
+
* accepts from agents, does not verify here. The signature must be
|
|
359
|
+
* base64url (the form the LumoAuth SDKs send).
|
|
344
360
|
*/
|
|
345
361
|
declare function verifySignatureBase(signatureBase: string, signatureB64url: string, publicKey: KeyObject): boolean;
|
|
346
362
|
interface SignRequestOptions {
|
|
@@ -352,7 +368,13 @@ interface SignRequestOptions {
|
|
|
352
368
|
agentToken?: string;
|
|
353
369
|
/** Value of a covered `Authorization` header, if any (e.g. `Bearer …`). */
|
|
354
370
|
authorization?: string;
|
|
355
|
-
/**
|
|
371
|
+
/**
|
|
372
|
+
* Value of a covered `Signature-Key` header, if any. It is also sent as
|
|
373
|
+
* that header. Its label must be `sig1`, the label of `Signature-Input`
|
|
374
|
+
* and `Signature`. `POST /aauth/agent/issue` requires
|
|
375
|
+
* `sig1=jwks_uri;id="<agent identifier>";kid="<kid>"`; the agent token
|
|
376
|
+
* endpoint and `/aauth/token/revoke` need no `Signature-Key`.
|
|
377
|
+
*/
|
|
356
378
|
signatureKey?: string;
|
|
357
379
|
/**
|
|
358
380
|
* Override the `created` timestamp (seconds). Testing only — the server
|
|
@@ -390,13 +412,27 @@ interface AAuthTokenClaims {
|
|
|
390
412
|
exp: number;
|
|
391
413
|
iat: number;
|
|
392
414
|
jti: string;
|
|
415
|
+
/** The agent's full public JWK. Auth tokens carry no `cnf.jkt`. */
|
|
393
416
|
cnf: {
|
|
394
417
|
jwk: AAuthJwk;
|
|
395
418
|
};
|
|
419
|
+
/** The agent identifier. Present only when `aud` differs from it. */
|
|
396
420
|
agent?: string;
|
|
421
|
+
/** The delegate (the `sub` of the agent token) that made the request, if any. */
|
|
397
422
|
agent_delegate?: string;
|
|
423
|
+
/** Resource scopes only: openid, profile, email, phone and address are never listed. */
|
|
398
424
|
scope?: string;
|
|
425
|
+
/**
|
|
426
|
+
* The user. A pseudonym for this resource, not the user ID, when the
|
|
427
|
+
* resource's default auth level is `pseudonymous`, or `authorized`
|
|
428
|
+
* without a consent record.
|
|
429
|
+
*/
|
|
399
430
|
sub?: string;
|
|
431
|
+
/**
|
|
432
|
+
* Actor chain of an exchanged token: `{ agent, agent_delegate?, sub?,
|
|
433
|
+
* act? }`. `act.agent` names the upstream agent and `act.sub` the
|
|
434
|
+
* upstream user; a nested `act` holds the earlier hops (at most 5).
|
|
435
|
+
*/
|
|
400
436
|
act?: Record<string, unknown>;
|
|
401
437
|
[claim: string]: unknown;
|
|
402
438
|
}
|
|
@@ -518,8 +554,7 @@ interface AAuthResourceMetadata {
|
|
|
518
554
|
* });
|
|
519
555
|
*
|
|
520
556
|
* const result = await client.requestAuthToken({
|
|
521
|
-
* resourceToken,
|
|
522
|
-
* scope: 'read write',
|
|
557
|
+
* resourceToken, // its `scope` claim names the scope of the auth token
|
|
523
558
|
* agentToken,
|
|
524
559
|
* });
|
|
525
560
|
* if ('authorizationRequired' in result) {
|
|
@@ -546,7 +581,10 @@ declare class AAuthClient {
|
|
|
546
581
|
get issuer(): string;
|
|
547
582
|
/** The agent's public JWK derived from its private key. */
|
|
548
583
|
get publicJwk(): AAuthJwk;
|
|
549
|
-
/**
|
|
584
|
+
/**
|
|
585
|
+
* RFC 7638 thumbprint of the agent's public key. A resource names this
|
|
586
|
+
* value as `agent_jkt` when it asks for a resource token for the agent.
|
|
587
|
+
*/
|
|
550
588
|
get publicJwkThumbprint(): string;
|
|
551
589
|
/**
|
|
552
590
|
* Create RFC 9421 signature headers for a request per the AAuth profile.
|
|
@@ -557,19 +595,29 @@ declare class AAuthClient {
|
|
|
557
595
|
* Request an auth token (`request_type=auth` — direct authorization).
|
|
558
596
|
*
|
|
559
597
|
* Presents the resource token in the body and the agent token in the
|
|
560
|
-
* `Agent-Auth` header, signed with the
|
|
561
|
-
* requires user consent it
|
|
562
|
-
*
|
|
563
|
-
* `
|
|
598
|
+
* `Agent-Auth` header (never in the body), signed with the key in the
|
|
599
|
+
* agent token's `cnf`. If the server requires user consent it answers
|
|
600
|
+
* 200 with `request_token` and `authorization_uri`, returned here as
|
|
601
|
+
* `{ authorizationRequired: true, requestToken, authorizationUri }` —
|
|
602
|
+
* redirect the user, then call `exchangeCode()` with the code delivered
|
|
603
|
+
* to your `redirectUri`.
|
|
564
604
|
*/
|
|
565
605
|
requestAuthToken(params: {
|
|
566
606
|
/** Resource token (`resource+jwt`) obtained from the target resource. */
|
|
567
607
|
resourceToken: string;
|
|
568
|
-
/**
|
|
608
|
+
/**
|
|
609
|
+
* Sent as the body field `scope`, which the server ignores for
|
|
610
|
+
* `request_type=auth`: the scope of the auth token comes from the
|
|
611
|
+
* resource token's `scope` claim.
|
|
612
|
+
*/
|
|
569
613
|
scope?: string;
|
|
570
614
|
/** The `agent+jwt` presented in `Agent-Auth`. */
|
|
571
615
|
agentToken: string;
|
|
572
|
-
/**
|
|
616
|
+
/**
|
|
617
|
+
* Redirect URI, required when the user has to consent (the server
|
|
618
|
+
* answers 400 `invalid_request` without it). It must be registered
|
|
619
|
+
* for the agent.
|
|
620
|
+
*/
|
|
573
621
|
redirectUri?: string;
|
|
574
622
|
}): Promise<AAuthTokenResponse | AAuthAuthorizationRequired>;
|
|
575
623
|
/**
|
|
@@ -591,8 +639,9 @@ declare class AAuthClient {
|
|
|
591
639
|
/**
|
|
592
640
|
* Multi-hop token exchange (`request_type=exchange`): trade an upstream
|
|
593
641
|
* auth token plus a downstream resource token for a new auth token with
|
|
594
|
-
* an `act` actor chain.
|
|
595
|
-
*
|
|
642
|
+
* an `act` actor chain (`act.agent` names the upstream agent, `act.sub`
|
|
643
|
+
* the upstream user; at most 5 hops). Requires token exchange to be
|
|
644
|
+
* enabled for the agent.
|
|
596
645
|
*/
|
|
597
646
|
exchangeToken(params: {
|
|
598
647
|
/** The upstream `auth+jwt` addressed to this agent. */
|
|
@@ -602,16 +651,23 @@ declare class AAuthClient {
|
|
|
602
651
|
agentToken: string;
|
|
603
652
|
}): Promise<AAuthTokenResponse>;
|
|
604
653
|
/**
|
|
605
|
-
* Refresh an auth token (`request_type=refresh`). A
|
|
606
|
-
*
|
|
607
|
-
*
|
|
608
|
-
*
|
|
654
|
+
* Refresh an auth token (`request_type=refresh`). A resource token from
|
|
655
|
+
* the same resource as the original grant is required. The scopes of
|
|
656
|
+
* that grant are the ceiling: the resource token's `scope` claim may
|
|
657
|
+
* narrow them, and `scope` narrows the result once more. A refresh never
|
|
658
|
+
* widens the scope. The response carries no new refresh token (refresh
|
|
659
|
+
* tokens are not rotated).
|
|
609
660
|
*/
|
|
610
661
|
refresh(params: {
|
|
611
662
|
refreshToken: string;
|
|
612
|
-
/**
|
|
663
|
+
/** Resource token from the resource that the refresh token was granted for. */
|
|
613
664
|
resourceToken: string;
|
|
614
|
-
/**
|
|
665
|
+
/**
|
|
666
|
+
* Optional space-delimited scope. It narrows only: every scope must
|
|
667
|
+
* be in the grant (and in the resource token's scope, when it has
|
|
668
|
+
* one). A scope outside the grant is refused with 400
|
|
669
|
+
* `invalid_scope`.
|
|
670
|
+
*/
|
|
615
671
|
scope?: string;
|
|
616
672
|
agentToken: string;
|
|
617
673
|
}): Promise<AAuthTokenResponse>;
|
package/dist/index.d.ts
CHANGED
|
@@ -154,7 +154,7 @@ interface LumoAgentOptions {
|
|
|
154
154
|
* import { LumoAgent } from '@lumoauth/agent';
|
|
155
155
|
*
|
|
156
156
|
* const agent = new LumoAgent(); // reads env vars by default
|
|
157
|
-
* if (await agent.isAllowed('document
|
|
157
|
+
* if (await agent.isAllowed('document:read', { id: 'doc_99' })) {
|
|
158
158
|
* // ... do the thing
|
|
159
159
|
* }
|
|
160
160
|
*
|
|
@@ -293,7 +293,9 @@ interface AAuthKeypair {
|
|
|
293
293
|
declare function generateKeypair(kid?: string): AAuthKeypair;
|
|
294
294
|
/**
|
|
295
295
|
* Compute the RFC 7638 JWK thumbprint (base64url-encoded SHA-256) of a
|
|
296
|
-
* public JWK.
|
|
296
|
+
* public JWK. LumoAuth uses it as `agent_jkt` in resource tokens and as
|
|
297
|
+
* `cnf_jkt` in the answer of the token verify endpoint. Auth tokens carry
|
|
298
|
+
* the full key in `cnf.jwk`, not the thumbprint.
|
|
297
299
|
*/
|
|
298
300
|
declare function jwkThumbprint(jwk: AAuthJwk): string;
|
|
299
301
|
/** Derive the public JWK for a loaded private key. */
|
|
@@ -306,13 +308,24 @@ declare function publicJwkFromPrivateKey(pem: string, kid?: string): AAuthJwk;
|
|
|
306
308
|
*
|
|
307
309
|
* - Covered components: `@method @authority @path signature-key
|
|
308
310
|
* content-digest content-type authorization` (plus `@query` if and only if
|
|
309
|
-
* the target URI has a query string).
|
|
310
|
-
*
|
|
311
|
-
*
|
|
311
|
+
* the target URI has a query string). `signature-key` and `authorization`
|
|
312
|
+
* are the values of the `Signature-Key` and `Authorization` request
|
|
313
|
+
* headers, or the empty string when the header is not sent. `@target-uri`
|
|
314
|
+
* is not accepted in place of `@authority` and `@path`.
|
|
315
|
+
* - `Signature-Input` parameters: `created` (required, within ±60 s of the
|
|
316
|
+
* server clock) and a single-use `nonce` (required, base64url of at least
|
|
317
|
+
* 12 random bytes). The server also accepts `expires`, `alg`, `keyid` and
|
|
318
|
+
* `tag`, and refuses any other parameter. This signer sends only
|
|
319
|
+
* `created` and `nonce`.
|
|
312
320
|
* - `Content-Digest` per RFC 9530 with **standard** base64 (`sha-256=:…:`).
|
|
313
|
-
*
|
|
314
|
-
* -
|
|
315
|
-
*
|
|
321
|
+
* The header is mandatory and must match the body.
|
|
322
|
+
* - The `Signature` value (`label=:…:`) is sent **base64url** encoded. The
|
|
323
|
+
* server accepts base64url and standard base64.
|
|
324
|
+
* - The algorithm follows the key type: Ed25519 → `ed25519`, RSA →
|
|
325
|
+
* `rsa-pss-sha512` (MGF1-SHA512, 64-byte salt). The server also accepts
|
|
326
|
+
* EC P-256 keys (`ecdsa-p256-sha256`, raw r||s), which this signer does
|
|
327
|
+
* not support. An `alg` parameter is optional (it must then name the
|
|
328
|
+
* algorithm of the key); this signer declares none.
|
|
316
329
|
*/
|
|
317
330
|
/** Covered components required by the AAuth agent token endpoint, in order. */
|
|
318
331
|
declare const AAUTH_COVERED_COMPONENTS: readonly ["@method", "@authority", "@path", "signature-key", "content-digest", "content-type", "authorization"];
|
|
@@ -340,7 +353,10 @@ declare function signatureParams(components: readonly string[], created: number,
|
|
|
340
353
|
declare function signSignatureBase(signatureBase: string, privateKey: KeyObject): string;
|
|
341
354
|
/**
|
|
342
355
|
* Verify a base64url signature over a signature base (resource-server side).
|
|
343
|
-
* Dispatches on key type like the LumoAuth server does
|
|
356
|
+
* Dispatches on key type like the LumoAuth server does, for Ed25519 and RSA
|
|
357
|
+
* keys only: a signature made with an EC P-256 key, which the server also
|
|
358
|
+
* accepts from agents, does not verify here. The signature must be
|
|
359
|
+
* base64url (the form the LumoAuth SDKs send).
|
|
344
360
|
*/
|
|
345
361
|
declare function verifySignatureBase(signatureBase: string, signatureB64url: string, publicKey: KeyObject): boolean;
|
|
346
362
|
interface SignRequestOptions {
|
|
@@ -352,7 +368,13 @@ interface SignRequestOptions {
|
|
|
352
368
|
agentToken?: string;
|
|
353
369
|
/** Value of a covered `Authorization` header, if any (e.g. `Bearer …`). */
|
|
354
370
|
authorization?: string;
|
|
355
|
-
/**
|
|
371
|
+
/**
|
|
372
|
+
* Value of a covered `Signature-Key` header, if any. It is also sent as
|
|
373
|
+
* that header. Its label must be `sig1`, the label of `Signature-Input`
|
|
374
|
+
* and `Signature`. `POST /aauth/agent/issue` requires
|
|
375
|
+
* `sig1=jwks_uri;id="<agent identifier>";kid="<kid>"`; the agent token
|
|
376
|
+
* endpoint and `/aauth/token/revoke` need no `Signature-Key`.
|
|
377
|
+
*/
|
|
356
378
|
signatureKey?: string;
|
|
357
379
|
/**
|
|
358
380
|
* Override the `created` timestamp (seconds). Testing only — the server
|
|
@@ -390,13 +412,27 @@ interface AAuthTokenClaims {
|
|
|
390
412
|
exp: number;
|
|
391
413
|
iat: number;
|
|
392
414
|
jti: string;
|
|
415
|
+
/** The agent's full public JWK. Auth tokens carry no `cnf.jkt`. */
|
|
393
416
|
cnf: {
|
|
394
417
|
jwk: AAuthJwk;
|
|
395
418
|
};
|
|
419
|
+
/** The agent identifier. Present only when `aud` differs from it. */
|
|
396
420
|
agent?: string;
|
|
421
|
+
/** The delegate (the `sub` of the agent token) that made the request, if any. */
|
|
397
422
|
agent_delegate?: string;
|
|
423
|
+
/** Resource scopes only: openid, profile, email, phone and address are never listed. */
|
|
398
424
|
scope?: string;
|
|
425
|
+
/**
|
|
426
|
+
* The user. A pseudonym for this resource, not the user ID, when the
|
|
427
|
+
* resource's default auth level is `pseudonymous`, or `authorized`
|
|
428
|
+
* without a consent record.
|
|
429
|
+
*/
|
|
399
430
|
sub?: string;
|
|
431
|
+
/**
|
|
432
|
+
* Actor chain of an exchanged token: `{ agent, agent_delegate?, sub?,
|
|
433
|
+
* act? }`. `act.agent` names the upstream agent and `act.sub` the
|
|
434
|
+
* upstream user; a nested `act` holds the earlier hops (at most 5).
|
|
435
|
+
*/
|
|
400
436
|
act?: Record<string, unknown>;
|
|
401
437
|
[claim: string]: unknown;
|
|
402
438
|
}
|
|
@@ -518,8 +554,7 @@ interface AAuthResourceMetadata {
|
|
|
518
554
|
* });
|
|
519
555
|
*
|
|
520
556
|
* const result = await client.requestAuthToken({
|
|
521
|
-
* resourceToken,
|
|
522
|
-
* scope: 'read write',
|
|
557
|
+
* resourceToken, // its `scope` claim names the scope of the auth token
|
|
523
558
|
* agentToken,
|
|
524
559
|
* });
|
|
525
560
|
* if ('authorizationRequired' in result) {
|
|
@@ -546,7 +581,10 @@ declare class AAuthClient {
|
|
|
546
581
|
get issuer(): string;
|
|
547
582
|
/** The agent's public JWK derived from its private key. */
|
|
548
583
|
get publicJwk(): AAuthJwk;
|
|
549
|
-
/**
|
|
584
|
+
/**
|
|
585
|
+
* RFC 7638 thumbprint of the agent's public key. A resource names this
|
|
586
|
+
* value as `agent_jkt` when it asks for a resource token for the agent.
|
|
587
|
+
*/
|
|
550
588
|
get publicJwkThumbprint(): string;
|
|
551
589
|
/**
|
|
552
590
|
* Create RFC 9421 signature headers for a request per the AAuth profile.
|
|
@@ -557,19 +595,29 @@ declare class AAuthClient {
|
|
|
557
595
|
* Request an auth token (`request_type=auth` — direct authorization).
|
|
558
596
|
*
|
|
559
597
|
* Presents the resource token in the body and the agent token in the
|
|
560
|
-
* `Agent-Auth` header, signed with the
|
|
561
|
-
* requires user consent it
|
|
562
|
-
*
|
|
563
|
-
* `
|
|
598
|
+
* `Agent-Auth` header (never in the body), signed with the key in the
|
|
599
|
+
* agent token's `cnf`. If the server requires user consent it answers
|
|
600
|
+
* 200 with `request_token` and `authorization_uri`, returned here as
|
|
601
|
+
* `{ authorizationRequired: true, requestToken, authorizationUri }` —
|
|
602
|
+
* redirect the user, then call `exchangeCode()` with the code delivered
|
|
603
|
+
* to your `redirectUri`.
|
|
564
604
|
*/
|
|
565
605
|
requestAuthToken(params: {
|
|
566
606
|
/** Resource token (`resource+jwt`) obtained from the target resource. */
|
|
567
607
|
resourceToken: string;
|
|
568
|
-
/**
|
|
608
|
+
/**
|
|
609
|
+
* Sent as the body field `scope`, which the server ignores for
|
|
610
|
+
* `request_type=auth`: the scope of the auth token comes from the
|
|
611
|
+
* resource token's `scope` claim.
|
|
612
|
+
*/
|
|
569
613
|
scope?: string;
|
|
570
614
|
/** The `agent+jwt` presented in `Agent-Auth`. */
|
|
571
615
|
agentToken: string;
|
|
572
|
-
/**
|
|
616
|
+
/**
|
|
617
|
+
* Redirect URI, required when the user has to consent (the server
|
|
618
|
+
* answers 400 `invalid_request` without it). It must be registered
|
|
619
|
+
* for the agent.
|
|
620
|
+
*/
|
|
573
621
|
redirectUri?: string;
|
|
574
622
|
}): Promise<AAuthTokenResponse | AAuthAuthorizationRequired>;
|
|
575
623
|
/**
|
|
@@ -591,8 +639,9 @@ declare class AAuthClient {
|
|
|
591
639
|
/**
|
|
592
640
|
* Multi-hop token exchange (`request_type=exchange`): trade an upstream
|
|
593
641
|
* auth token plus a downstream resource token for a new auth token with
|
|
594
|
-
* an `act` actor chain.
|
|
595
|
-
*
|
|
642
|
+
* an `act` actor chain (`act.agent` names the upstream agent, `act.sub`
|
|
643
|
+
* the upstream user; at most 5 hops). Requires token exchange to be
|
|
644
|
+
* enabled for the agent.
|
|
596
645
|
*/
|
|
597
646
|
exchangeToken(params: {
|
|
598
647
|
/** The upstream `auth+jwt` addressed to this agent. */
|
|
@@ -602,16 +651,23 @@ declare class AAuthClient {
|
|
|
602
651
|
agentToken: string;
|
|
603
652
|
}): Promise<AAuthTokenResponse>;
|
|
604
653
|
/**
|
|
605
|
-
* Refresh an auth token (`request_type=refresh`). A
|
|
606
|
-
*
|
|
607
|
-
*
|
|
608
|
-
*
|
|
654
|
+
* Refresh an auth token (`request_type=refresh`). A resource token from
|
|
655
|
+
* the same resource as the original grant is required. The scopes of
|
|
656
|
+
* that grant are the ceiling: the resource token's `scope` claim may
|
|
657
|
+
* narrow them, and `scope` narrows the result once more. A refresh never
|
|
658
|
+
* widens the scope. The response carries no new refresh token (refresh
|
|
659
|
+
* tokens are not rotated).
|
|
609
660
|
*/
|
|
610
661
|
refresh(params: {
|
|
611
662
|
refreshToken: string;
|
|
612
|
-
/**
|
|
663
|
+
/** Resource token from the resource that the refresh token was granted for. */
|
|
613
664
|
resourceToken: string;
|
|
614
|
-
/**
|
|
665
|
+
/**
|
|
666
|
+
* Optional space-delimited scope. It narrows only: every scope must
|
|
667
|
+
* be in the grant (and in the resource token's scope, when it has
|
|
668
|
+
* one). A scope outside the grant is refused with 400
|
|
669
|
+
* `invalid_scope`.
|
|
670
|
+
*/
|
|
615
671
|
scope?: string;
|
|
616
672
|
agentToken: string;
|
|
617
673
|
}): Promise<AAuthTokenResponse>;
|
package/dist/index.js
CHANGED
|
@@ -734,7 +734,10 @@ var AAuthClient = class {
|
|
|
734
734
|
get publicJwk() {
|
|
735
735
|
return publicJwkFromPrivateKey(this.privateKeyPem, this.kid);
|
|
736
736
|
}
|
|
737
|
-
/**
|
|
737
|
+
/**
|
|
738
|
+
* RFC 7638 thumbprint of the agent's public key. A resource names this
|
|
739
|
+
* value as `agent_jkt` when it asks for a resource token for the agent.
|
|
740
|
+
*/
|
|
738
741
|
get publicJwkThumbprint() {
|
|
739
742
|
return jwkThumbprint(this.publicJwk);
|
|
740
743
|
}
|
|
@@ -751,10 +754,12 @@ var AAuthClient = class {
|
|
|
751
754
|
* Request an auth token (`request_type=auth` — direct authorization).
|
|
752
755
|
*
|
|
753
756
|
* Presents the resource token in the body and the agent token in the
|
|
754
|
-
* `Agent-Auth` header, signed with the
|
|
755
|
-
* requires user consent it
|
|
756
|
-
*
|
|
757
|
-
* `
|
|
757
|
+
* `Agent-Auth` header (never in the body), signed with the key in the
|
|
758
|
+
* agent token's `cnf`. If the server requires user consent it answers
|
|
759
|
+
* 200 with `request_token` and `authorization_uri`, returned here as
|
|
760
|
+
* `{ authorizationRequired: true, requestToken, authorizationUri }` —
|
|
761
|
+
* redirect the user, then call `exchangeCode()` with the code delivered
|
|
762
|
+
* to your `redirectUri`.
|
|
758
763
|
*/
|
|
759
764
|
async requestAuthToken(params) {
|
|
760
765
|
this.requireAgentToken(params.agentToken);
|
|
@@ -799,8 +804,9 @@ var AAuthClient = class {
|
|
|
799
804
|
/**
|
|
800
805
|
* Multi-hop token exchange (`request_type=exchange`): trade an upstream
|
|
801
806
|
* auth token plus a downstream resource token for a new auth token with
|
|
802
|
-
* an `act` actor chain.
|
|
803
|
-
*
|
|
807
|
+
* an `act` actor chain (`act.agent` names the upstream agent, `act.sub`
|
|
808
|
+
* the upstream user; at most 5 hops). Requires token exchange to be
|
|
809
|
+
* enabled for the agent.
|
|
804
810
|
*/
|
|
805
811
|
async exchangeToken(params) {
|
|
806
812
|
this.requireAgentToken(params.agentToken);
|
|
@@ -815,10 +821,12 @@ var AAuthClient = class {
|
|
|
815
821
|
return this.mapTokenResponse(data);
|
|
816
822
|
}
|
|
817
823
|
/**
|
|
818
|
-
* Refresh an auth token (`request_type=refresh`). A
|
|
819
|
-
*
|
|
820
|
-
*
|
|
821
|
-
*
|
|
824
|
+
* Refresh an auth token (`request_type=refresh`). A resource token from
|
|
825
|
+
* the same resource as the original grant is required. The scopes of
|
|
826
|
+
* that grant are the ceiling: the resource token's `scope` claim may
|
|
827
|
+
* narrow them, and `scope` narrows the result once more. A refresh never
|
|
828
|
+
* widens the scope. The response carries no new refresh token (refresh
|
|
829
|
+
* tokens are not rotated).
|
|
822
830
|
*/
|
|
823
831
|
async refresh(params) {
|
|
824
832
|
this.requireAgentToken(params.agentToken);
|