@gydr-ai/mcp-oauth 0.1.2 → 0.1.3

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.
Files changed (8) hide show
  1. package/README.md +54 -41
  2. package/dist/index.js +15 -15
  3. package/dist/index.js.map +4 -4
  4. package/dist/types/core/grant-expiry.d.ts +1 -0
  5. package/dist/types/interfaces/options.d.ts +17 -0
  6. package/dist/types/interfaces/records.d.ts +8 -1
  7. package/dist/types/interfaces/store.d.ts +4 -2
  8. package/package.json +1 -1
package/README.md CHANGED
@@ -365,7 +365,11 @@ const auth = createMcpAuth({
365
365
  `consentReplaySeconds` (default 10, at most 60) receives the same
366
366
  redirect again, when the store implements the optional
367
367
  `putConsentOutcome` / `getConsentOutcome`; otherwise a repeat sees an
368
- error page. The remembered redirect is stored encrypted.
368
+ error page. A repeat that arrives while the first is still being decided
369
+ (in `beforeGrant` or `afterGrant`) waits for its answer, within the same
370
+ window; the first leaves a short "being decided" mark for that, so a
371
+ forged repeat, which finds none, is answered at once. Everything
372
+ remembered is stored encrypted.
369
373
 
370
374
  **Pages**
371
375
 
@@ -423,9 +427,14 @@ the deleted record so the last stored upstream token is the one revoked.
423
427
  the token endpoint checks the client, redirect URI, resource and PKCE
424
428
  verifier against it first.
425
429
 
430
+ `updateGrant` must save every field it is given, including `expiresAt`
431
+ (sent on refresh under `lifetimes.grantIdle`); `putGrant` must keep the
432
+ whole record, including the optional `redirectUri`.
433
+
426
434
  Three methods are optional: `putConsentOutcome` / `getConsentOutcome`
427
- (answering a repeated consent submission) and `listGrantsBySubject`
428
- (`revokeGrantsForSubject`).
435
+ (answering a repeated consent submission; one submission writes twice, the
436
+ "being decided" mark and then the answer, so a later write replaces an
437
+ earlier one) and `listGrantsBySubject` (`revokeGrantsForSubject`).
429
438
 
430
439
  Good fits: PostgreSQL or MySQL (`UPDATE … WHERE used_at IS NULL`,
431
440
  `DELETE … RETURNING`), Redis (`GETDEL`, Lua), MongoDB (`findOneAndUpdate`),
@@ -476,47 +485,49 @@ evict the least recently used grant-less dynamic client first when full.
476
485
 
477
486
  ### Options
478
487
 
479
- | Option | Default | Meaning |
480
- | --------------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
481
- | `issuer` | required | HTTPS URL; endpoints live under its path. |
482
- | `resource` | required | Canonical URL of your MCP endpoint, the audience of every token. |
483
- | `identityProvider` | required | `createOidcProvider(…)` or your own `IdentityProvider`. |
484
- | `store` | required | Your `OAuthStore`. |
485
- | `sealer` | required | `createAesGcmSealer(…)` or your own `SecretSealer`. |
486
- | `scopes` / `defaultScopes` | `["mcp"]` / all | Scopes offered, and those granted when none are asked for. |
487
- | `scopeDescriptions` | none | Consent-screen text per scope. |
488
- | `resourceName` | none | RFC 9728 `resource_name`. |
489
- | `clients` | none | Pre-registered public clients. |
490
- | `dynamicClientRegistration` | `true` | Serve `POST /register`. Deprecated by MCP 2026-07-28 in favour of metadata documents; `dynamicClientRegistration: false` turns it off. |
491
- | `clientIdMetadataDocuments` | `true` | Accept HTTPS URL client ids. |
492
- | `fetchClientMetadata(url, { signal })` | SSRF-safe fetcher | Replace how metadata documents are downloaded. Must stay SSRF-safe. |
493
- | `lifetimes` | see below | Token and flow lifetimes, in seconds. |
494
- | `limits` | see below | Sizes and counts. |
495
- | `refreshReuseGraceSeconds` | `10` | Retry window (0–300) for a just-used refresh token. `0` treats any reuse as replay. |
496
- | `consentReplaySeconds` | `10` | Window (0–60) in which a repeated consent submission from the same browser gets the same redirect. |
497
- | `scriptHashes` | none | `sha256-…` hashes of inline scripts a custom consent page may run. |
498
- | `paths` | `/authorize`, `/callback`, `/consent`, `/token`, `/register`, `/revoke` | Route paths under the issuer path: one leading `/`, no `//`, `\`, dot segments or whitespace, distinct, and never a metadata path or the resource path. |
499
- | `cookiePrefix` | `__Host-mcp-auth-` | Must start with `__Host-`. |
500
- | `rateLimit(key, scope)` | none | Resolve `true` to continue; anything else (including a throw) answers 429. |
501
- | `getClientIp(request)` / `trustProxy` | none / `false` | Rate-limit key. `trustProxy` uses the right-most `X-Forwarded-For` entry. |
502
- | `renderConsentPage` / `renderErrorPage` | built in | Your own pages; see `ConsentPageContext`. |
503
- | `onEvent(event)` | none | Typed audit events; never contain secrets. |
504
- | policy and enrichment hooks | none | See [Extending safely](#extending-safely). |
505
- | `allowInsecureLocalhost` | `false` | Allow an `http://localhost` issuer and resource in development. |
506
- | `now` | `Date.now` | Clock, for tests. A non-finite value fails the request instead of disabling expiry checks. |
488
+ | Option | Default | Meaning |
489
+ | --------------------------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
490
+ | `issuer` | required | HTTPS URL; endpoints live under its path. |
491
+ | `resource` | required | Canonical URL of your MCP endpoint, the audience of every token. |
492
+ | `identityProvider` | required | `createOidcProvider(…)` or your own `IdentityProvider`. |
493
+ | `store` | required | Your `OAuthStore`. |
494
+ | `sealer` | required | `createAesGcmSealer(…)` or your own `SecretSealer`. |
495
+ | `scopes` / `defaultScopes` | `["mcp"]` / all | Scopes offered, and those granted when none are asked for. |
496
+ | `scopeDescriptions` | none | Consent-screen text per scope. |
497
+ | `resourceName` | none | RFC 9728 `resource_name`. |
498
+ | `clients` | none | Pre-registered public clients. |
499
+ | `dynamicClientRegistration` | `true` | Serve `POST /register`. Deprecated by MCP 2026-07-28 in favour of metadata documents; `dynamicClientRegistration: false` turns it off. |
500
+ | `clientIdMetadataDocuments` | `true` | Accept HTTPS URL client ids. |
501
+ | `fetchClientMetadata(url, { signal })` | SSRF-safe fetcher | Replace how metadata documents are downloaded. Must stay SSRF-safe. |
502
+ | `lifetimes` | see below | Token and flow lifetimes, in seconds. |
503
+ | `limits` | see below | Sizes and counts. |
504
+ | `defaultGrantTypes` | `["authorization_code"]` | Grant types for a client that registers or publishes none, applied at registration or fetch. Must include `authorization_code`. `clients` default to both. |
505
+ | `refreshReuseGraceSeconds` | `10` | Retry window (0–300) for a just-used refresh token. `0` treats any reuse as replay. |
506
+ | `consentReplaySeconds` | `10` | Window (0–60) in which a repeated consent submission from the same browser gets the same redirect. |
507
+ | `scriptHashes` | none | `sha256-…` hashes of inline scripts a custom consent page may run. |
508
+ | `paths` | `/authorize`, `/callback`, `/consent`, `/token`, `/register`, `/revoke` | Route paths under the issuer path: one leading `/`, no `//`, `\`, dot segments or whitespace, distinct, and never a metadata path or the resource path. |
509
+ | `cookiePrefix` | `__Host-mcp-auth-` | Must start with `__Host-`. |
510
+ | `rateLimit(key, scope)` | none | Resolve `true` to continue; anything else (including a throw) answers 429. |
511
+ | `getClientIp(request)` / `trustProxy` | none / `false` | Rate-limit key. `trustProxy` uses the right-most `X-Forwarded-For` entry. |
512
+ | `renderConsentPage` / `renderErrorPage` | built in | Your own pages; see `ConsentPageContext`. |
513
+ | `onEvent(event)` | none | Typed audit events; never contain secrets. |
514
+ | policy and enrichment hooks | none | See [Extending safely](#extending-safely). |
515
+ | `allowInsecureLocalhost` | `false` | Allow an `http://localhost` issuer and resource in development. |
516
+ | `now` | `Date.now` | Clock, for tests. A non-finite value fails the request instead of disabling expiry checks. |
507
517
 
508
518
  <details>
509
519
  <summary><strong><code>lifetimes</code></strong> (seconds)</summary>
510
520
 
511
- | Key | Default | Allowed |
512
- | ----------------------- | ---------------------------------------------------------------------------- | ------------ |
513
- | `accessToken` | 1,800 (30 minutes) | 1–86,400 |
514
- | `refreshToken` | 1,209,600 (14 days, renewed on every rotation) | 1–34,560,000 |
515
- | `grant` | 7,776,000 (90 days, absolute; then consent again) | 1–34,560,000 |
516
- | `authorizationCode` | 60 | 1–600 |
517
- | `pendingAuthorization` | 900 (sign-in plus consent) | 1–3,600 |
518
- | `clientMetadataCache` | 1,800 (`0` disables the cache); a document's own `Cache-Control` shortens it | 0–86,400 |
519
- | `clientMetadataFailure` | 60 (back-off for a failed metadata URL; `0` disables) | 0–3,600 |
521
+ | Key | Default | Allowed |
522
+ | ----------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
523
+ | `accessToken` | 1,800 (30 minutes) | 1–86,400 |
524
+ | `refreshToken` | 1,209,600 (14 days, renewed on every rotation) | 1–34,560,000 |
525
+ | `grant` | 7,776,000 (90 days, absolute; then consent again) | 1–34,560,000 |
526
+ | `grantIdle` | 0 (off). When set, a grant also ends after this long without a refresh; each refresh extends it, never past `grant` | 0, or `accessToken`–34,560,000 |
527
+ | `authorizationCode` | 60 | 1–600 |
528
+ | `pendingAuthorization` | 900 (sign-in plus consent) | 1–3,600 |
529
+ | `clientMetadataCache` | 1,800 (`0` disables the cache); a document's own `Cache-Control` shortens it | 0–86,400 |
530
+ | `clientMetadataFailure` | 60 (back-off for a failed metadata URL; `0` disables) | 0–3,600 |
520
531
 
521
532
  </details>
522
533
 
@@ -582,7 +593,9 @@ OAuth errors or error pages instead. No error message contains a token.
582
593
  - **`grant_types`**: a client that omits it gets `authorization_code` only
583
594
  (RFC 7591 § 2) and **no refresh token**. Clients that want refresh tokens
584
595
  register `["authorization_code", "refresh_token"]`. Metadata documents
585
- are treated the same way.
596
+ are treated the same way. Set `defaultGrantTypes:
597
+ ["authorization_code", "refresh_token"]` to give such clients refresh
598
+ tokens anyway.
586
599
  - **`scope`**: a client that registers a scope can only request scopes
587
600
  within it. Unknown scopes are refused at registration and ignored in a
588
601
  metadata document.