@gydr-ai/mcp-oauth 0.1.2 → 0.1.4

package/dist/types/core/grant-expiry.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/helpers/responses.d.ts

@@ -1 +1,5 @@
-export {};
+/**
+ * `Strict-Transport-Security` value: two years, subdomains included
+ * (RFC 6797). No `preload`: that is a decision for the domain owner.
+ */
+export declare const STRICT_TRANSPORT_SECURITY = "max-age=63072000; includeSubDomains";

package/dist/types/interfaces/options.d.ts

@@ -57,6 +57,13 @@ export interface Lifetimes {
      * (90 days).
      */
     readonly grant?: number;
+    /**
+     * Sliding limit on a grant: it also ends when it has not been renewed with
+     * a refresh token for this long, and each renewal extends it again, never
+     * beyond `grant`. `0` (off), or from `accessToken` up to 34,560,000.
+     * Default: 0.
+     */
+    readonly grantIdle?: number;
     /** Authorization code lifetime, 1 to 600. Default: 60. */
     readonly authorizationCode?: number;
     /** Time allowed for sign-in plus consent, 1 to 3600. Default: 900 (15 minutes). */
@@ -291,6 +298,16 @@ export interface McpAuthOptions {
     readonly scopes?: readonly string[];
     /** Scopes granted when a client asks for none. Default: all `scopes`. */
     readonly defaultScopes?: readonly string[];
+    /**
+     * Grant types a registered client or metadata document gets when it names
+     * none. RFC 7591 § 2 reads an absent `grant_types` as
+     * `["authorization_code"]`, so such a client receives no refresh token;
+     * `["authorization_code", "refresh_token"]` gives it one. Must include
+     * `authorization_code`. Applies when a client registers or a metadata
+     * document is fetched, not to clients already registered, and not to
+     * `clients`, which default to both. Default: `["authorization_code"]`.
+     */
+    readonly defaultGrantTypes?: readonly ("authorization_code" | "refresh_token")[];
     /**
      * Plain-language description per scope, shown on the consent screen (and
      * escaped). Keys must be listed in `scopes`. Default: none.
@@ -318,8 +335,10 @@ export interface McpAuthOptions {
     readonly lifetimes?: Lifetimes;
     /**
      * Seconds after a refresh token is used during which presenting it again
-     * returns another token pair (a lost response, a retried request) instead
-     * of ending the grant; `0` turns the window off. Default: 10.
+     * (a lost response, a retried request) returns the pair the first use
+     * issued instead of ending the grant; with a store that lacks
+     * `putRefreshTokenReplacement`, a new access token only. Never a second
+     * refresh token chain. `0` turns the window off. Default: 10.
      */
     readonly refreshReuseGraceSeconds?: number;
     /** Accept Client ID Metadata Document client ids. Default: `true`. */
@@ -566,6 +585,14 @@ export interface McpAuthOptions {
      * issuer and resource, for development. Default: `false`.
      */
     readonly allowInsecureLocalhost?: boolean;
+    /**
+     * Send `Strict-Transport-Security: max-age=63072000; includeSubDomains`
+     * on every response this package builds (endpoints, pages, redirects and
+     * `authenticate` / `unauthorized` refusals). Set `false` only when a proxy
+     * in front already sets the header, or when the issuer's subdomains must
+     * stay reachable over plain HTTP. Default: `true`.
+     */
+    readonly strictTransportSecurity?: boolean;
     /**
      * Clock in milliseconds since the epoch, for tests. A non-finite value
      * makes the request fail instead of disabling expiry checks.

package/dist/types/interfaces/records.d.ts

@@ -279,9 +279,14 @@ export interface GrantRecord {
      * or `McpAuth.updateGrantData` (JSON, at most `limits.grantDataBytes`).
      */
     readonly data?: unknown;
+    /** The redirect URI the approved authorization was sent to. */
+    readonly redirectUri?: string;
     /** When the person approved. */
     readonly createdAt: number;
-    /** Absolute end of the grant; no token outlives it. */
+    /**
+     * End of the grant; no token outlives it. With `lifetimes.grantIdle` it
+     * moves forward on each refresh, never past `createdAt + lifetimes.grant`.
+     */
     readonly expiresAt: number;
 }
 /**
@@ -305,6 +310,8 @@ export interface GrantUpstreamUpdate {
     readonly upstreamAccessTokenExpiresAt?: number;
     /** New integrator data for the grant (see `GrantRecord.data`). */
     readonly data?: unknown;
+    /** New end of the grant, after a refresh under `lifetimes.grantIdle`. */
+    readonly expiresAt?: number;
 }
 /**
  * An issued access token, stored by hash.
@@ -359,6 +366,14 @@ export interface RefreshTokenRecord {
     readonly expiresAt: number;
     /** Set once, atomically, by `OAuthStore.useRefreshToken`. */
     readonly usedAt?: number;
+    /**
+     * The access and refresh token pair this token was exchanged for,
+     * encrypted by the `SecretSealer`. Set by the optional
+     * `OAuthStore.putRefreshTokenReplacement` after the token is spent, and
+     * returned by `getRefreshToken` and `useRefreshToken` from then on, so a
+     * retry inside `refreshReuseGraceSeconds` receives that same pair.
+     */
+    readonly sealedReplacement?: string;
 }
 /**
  * Result of `OAuthStore.useRefreshToken`.

package/dist/types/interfaces/store.d.ts

@@ -35,8 +35,9 @@ import type { AccessTokenRecord, AuthorizationCodeRecord, ClientRecord, ConsentR
  * an idle period, and when a size cap is reached evict the least recently
  * used grant-less dynamic client first; never evict `static` clients.
  *
- * Only hashes of tokens and codes reach the store. Upstream tokens arrive
- * already encrypted by the `SecretSealer`.
+ * Only hashes of tokens and codes reach the store. Upstream tokens, and the
+ * pair a refresh token was exchanged for (`putRefreshTokenReplacement`),
+ * arrive already encrypted by the `SecretSealer`.
  *
  * @example
  * ```ts
@@ -147,8 +148,10 @@ export interface OAuthStore {
     /** Read a grant. */
     getGrant(grantId: string): Promise<GrantRecord | undefined>;
     /**
-     * Update the upstream-token fields of an existing grant. Resolves `false`,
-     * writing nothing, when the grant no longer exists.
+     * Update fields of an existing grant: the upstream tokens, `data`, or
+     * `expiresAt` (a refresh under `lifetimes.grantIdle`). Save every field
+     * given. Resolves `false`, writing nothing, when the grant no longer
+     * exists.
      */
     updateGrant(grantId: string, update: GrantUpstreamUpdate): Promise<boolean>;
     /**
@@ -177,6 +180,20 @@ export interface OAuthStore {
     getRefreshToken(tokenHash: string): Promise<RefreshTokenRecord | undefined>;
     /** Atomically set `usedAt` if it is not set yet. */
     useRefreshToken(tokenHash: string, now: number): Promise<UsedRefreshToken | undefined>;
+    /**
+     * Optional, recommended: save `sealedReplacement` on the (already used)
+     * refresh token record `tokenHash`, keeping every other field, `usedAt`
+     * included. `getRefreshToken` and `useRefreshToken` must return it from
+     * then on. A later write replaces an earlier one; nothing happens when the
+     * record is gone.
+     *
+     * With it, a refresh token presented again inside
+     * `refreshReuseGraceSeconds` receives exactly the pair its first exchange
+     * issued, so a copied refresh token can never start a second token chain.
+     * Without it, such a retry receives a new access token only, with no
+     * refresh token.
+     */
+    putRefreshTokenReplacement?(tokenHash: string, sealedReplacement: string): Promise<void>;
     /**
      * Optional: remember the answer to a consent submission for a few
      * seconds, keyed by a hash of the browser cookie and the form token, so a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gydr-ai/mcp-oauth",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "OAuth 2.1 authorization server and resource-server guard for remote MCP servers, in front of any OIDC identity provider. No token passthrough, consent on every authorization, DCR and Client ID Metadata Documents.",
   "keywords": [
     "mcp",