@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 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.read', { id: 'doc_99' }))) {
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.write', { ticket: 'T-42' });
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:documents']);
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:documents'], {
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, scope: 'read write' });
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. `agentToken` is the agent's own `agent+jwt`, sent in the `Agent-Auth`
416
- header.
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 fresh resource token |
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.read', { id: 'doc_99' })) {
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. This is the `jkt` value AAuth uses to bind tokens to keys.
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
- * - `Signature-Input` parameters: exactly `created` (within ±60 s) and a
311
- * fresh `nonce` (≥ 12 bytes / 96 bits of entropy, base64url).
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
- * - The `Signature` value is **base64url** encoded (`label=:…:`).
314
- * - Algorithms: Ed25519 or RSA-PSS-SHA512 (MGF1-SHA512, 64-byte salt),
315
- * dispatched by key type — do NOT declare an `alg` parameter.
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
- /** Value of a covered `Signature-Key` header, if any. */
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
- /** RFC 7638 thumbprint of the agent's public key (the `jkt` binding value). */
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 agent's key. If the server
561
- * requires user consent it returns `{ authorizationRequired: true,
562
- * requestToken, authorizationUri }` — redirect the user, then call
563
- * `exchangeCode()` with the code delivered to your `redirectUri`.
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
- /** Space-separated scopes (informational; scopes bind via the resource token). */
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
- /** Redirect URI for user-consent flows (must be registered). */
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. Requires token exchange to be enabled for the
595
- * agent.
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 fresh resource token
606
- * for the target resource is required; scopes requested via the resource
607
- * token must be a subset of the original grant. Refresh tokens are not
608
- * rotated.
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
- /** Fresh resource token for the target resource. */
663
+ /** Resource token from the resource that the refresh token was granted for. */
613
664
  resourceToken: string;
614
- /** Optional scope narrowing. */
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.read', { id: 'doc_99' })) {
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. This is the `jkt` value AAuth uses to bind tokens to keys.
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
- * - `Signature-Input` parameters: exactly `created` (within ±60 s) and a
311
- * fresh `nonce` (≥ 12 bytes / 96 bits of entropy, base64url).
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
- * - The `Signature` value is **base64url** encoded (`label=:…:`).
314
- * - Algorithms: Ed25519 or RSA-PSS-SHA512 (MGF1-SHA512, 64-byte salt),
315
- * dispatched by key type — do NOT declare an `alg` parameter.
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
- /** Value of a covered `Signature-Key` header, if any. */
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
- /** RFC 7638 thumbprint of the agent's public key (the `jkt` binding value). */
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 agent's key. If the server
561
- * requires user consent it returns `{ authorizationRequired: true,
562
- * requestToken, authorizationUri }` — redirect the user, then call
563
- * `exchangeCode()` with the code delivered to your `redirectUri`.
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
- /** Space-separated scopes (informational; scopes bind via the resource token). */
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
- /** Redirect URI for user-consent flows (must be registered). */
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. Requires token exchange to be enabled for the
595
- * agent.
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 fresh resource token
606
- * for the target resource is required; scopes requested via the resource
607
- * token must be a subset of the original grant. Refresh tokens are not
608
- * rotated.
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
- /** Fresh resource token for the target resource. */
663
+ /** Resource token from the resource that the refresh token was granted for. */
613
664
  resourceToken: string;
614
- /** Optional scope narrowing. */
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
- /** RFC 7638 thumbprint of the agent's public key (the `jkt` binding value). */
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 agent's key. If the server
755
- * requires user consent it returns `{ authorizationRequired: true,
756
- * requestToken, authorizationUri }` — redirect the user, then call
757
- * `exchangeCode()` with the code delivered to your `redirectUri`.
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. Requires token exchange to be enabled for the
803
- * agent.
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 fresh resource token
819
- * for the target resource is required; scopes requested via the resource
820
- * token must be a subset of the original grant. Refresh tokens are not
821
- * rotated.
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);