@gydr-ai/mcp-oauth 0.1.3 → 0.1.4

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

@@ -335,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`. */
@@ -583,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

@@ -366,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
@@ -179,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.3",
+  "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",