@rudderjs/passport 1.0.0 → 1.1.0

package/dist/Passport.d.ts

@@ -28,6 +28,16 @@ export declare class Passport {
     private static _keyPath;
     private static _privateKey;
     private static _publicKey;
+    /**
+     * Previous public key, retained for verification only after a `passport:keys
+     * --force` rotation. Tokens minted before the rotation keep verifying via
+     * this slot during the grace window; new tokens are signed by the current
+     * private key. Single-slot — one rotation deep — by design (operators who
+     * need a longer history should stage rotations to land outside the
+     * configured access-token lifetime). See JWKS verifier design notes in
+     * `verificationKeys()` below.
+     */
+    private static _previousPublicKey;
     private static _clientModel;
     private static _tokenModel;
     private static _refreshTokenModel;
@@ -35,6 +45,16 @@ export declare class Passport {
     private static _deviceCodeModel;
     private static _authorizationView;
     private static _routesIgnored;
+    private static _issuer;
+    /**
+     * Maximum value (in seconds) the per-row `oauth_device_codes.interval` is
+     * allowed to grow to via repeated `slow_down` escalations (RFC 8628 §3.5
+     * doesn't specify a cap; we add one to keep degenerate clients from
+     * pushing the interval to absurd values). 60 seconds is the default — long
+     * enough to make a misbehaving client back off meaningfully, short enough
+     * that a legitimate user typing the user_code never hits it.
+     */
+    private static _deviceMaxInterval;
     /** Define available OAuth scopes. */
     static tokensCan(scopes: Record<string, string>): void;
     /** Check if a scope is defined. */
@@ -55,11 +75,53 @@ export declare class Passport {
     static keyPath(): string;
     /** Set keys directly (from environment variables). */
     static setKeys(privateKey: string, publicKey: string): void;
+    /**
+     * Stamp the previous public key for verification grace after a key
+     * rotation. Tokens carrying `kid` for this key — or any token whose
+     * signature happens to verify against it — keep working until they
+     * naturally expire. Pair with the env var `PASSPORT_PREVIOUS_PUBLIC_KEY`
+     * if you don't want to rely on the on-disk `oauth-previous-public.key`
+     * convention. Pass `null` to clear.
+     */
+    static setPreviousPublicKey(publicKey: string | null): void;
+    /**
+     * Probe whether an RSA keypair is reachable — either explicitly set via
+     * `setKeys()` (env vars) or readable on disk under the configured key path.
+     * Used by `PassportProvider.boot()` to surface a startup warning when keys
+     * are missing, before the first `/oauth/*` request fails with a confusing
+     * file-not-found error.
+     *
+     * Does NOT load or cache the keys; it only stats the files.
+     */
+    static keysAvailable(): Promise<boolean>;
     /** Load keys from files or env. Returns { privateKey, publicKey }. */
     static keys(): Promise<{
         privateKey: string;
         publicKey: string;
     }>;
+    /**
+     * All public keys that should be considered for JWT signature verification,
+     * ordered current-first. After `passport:keys --force` rotates the
+     * keypair, the previous public key lingers in this list (loaded from
+     * `oauth-previous-public.key` on disk or set via `setPreviousPublicKey()`)
+     * so JWTs signed before the rotation keep verifying during their natural
+     * lifetime — `verifyToken()` walks the list and accepts a match against
+     * any entry. Without this, every rotation forced an immediate global
+     * sign-out.
+     *
+     * Tokens minted by recent versions also carry a `kid` JWT header equal to
+     * the SHA-256 of the public key that signed them, so the verifier can
+     * pick the right key directly without trial-and-error. Legacy tokens with
+     * no `kid` fall through to "try each in order".
+     *
+     * Single previous-slot is intentional: one rotation deep. Operators who
+     * need a multi-step grace should stage rotations to land outside the
+     * configured access-token lifetime — at that point old tokens have
+     * expired anyway and a longer history buys nothing.
+     */
+    static verificationKeys(): Promise<string[]>;
+    /** Get the configured previous public key, if any. */
+    static previousPublicKey(): string | null;
     static useClientModel(cls: typeof OAuthClient): void;
     static useTokenModel(cls: typeof AccessToken): void;
     static useRefreshTokenModel(cls: typeof RefreshToken): void;
@@ -83,6 +145,37 @@ export declare class Passport {
      */
     static ignoreRoutes(): void;
     static routesIgnored(): boolean;
+    /**
+     * Configure the JWT `iss` claim that `createToken()` stamps on every new
+     * access token, and that `verifyToken()` validates when called with
+     * `expectedIssuer: Passport.issuer()` (BearerMiddleware does this
+     * automatically). Typically set to the canonical app URL — e.g.
+     * `Passport.useIssuer('https://app.example.com')`.
+     *
+     * RFC 8725 §3.10 recommends issuer validation once a deployment has more
+     * than one possible signer (multi-tenant, staging+prod sharing keys, etc.).
+     * Tokens minted before this is configured carry no `iss` claim and are
+     * exempt during the migration window — same pattern as redirect_uri (P1)
+     * and familyId (P4).
+     */
+    static useIssuer(url: string): void;
+    static issuer(): string | null;
+    /**
+     * Configure the maximum value (in seconds) the per-row device-code
+     * polling interval is allowed to grow to via repeated `slow_down`
+     * escalations. Must be >= 5 (the initial interval) and >= the increment
+     * step (5s) to make sense; values smaller than that disable escalation
+     * entirely and are clamped at 5.
+     *
+     * Defaults to 60 seconds. Raise it for niche flows where a misbehaving
+     * client should be backed off more aggressively (e.g. a daemon polling
+     * with no human in the loop). Lower it if your device-flow consumers can
+     * tolerate a quicker authorization handshake — but lowering below ~30
+     * gives legitimate users a small window to enter the user_code.
+     */
+    static deviceMaxInterval(seconds: number): void;
+    /** Current cap on `oauth_device_codes.interval` (seconds). */
+    static deviceMaxIntervalSeconds(): number;
     /** @internal */
     static reset(): void;
 }

package/dist/Passport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Passport.d.ts","sourceRoot":"","sources":["../src/Passport.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Passport.d.ts","sourceRoot":"","sources":["../src/Passport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAO,yBAAyB,CAAA;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAO,yBAAyB,CAAA;AAC3D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AAC5D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAU,sBAAsB,CAAA;AACxD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAQ,wBAAwB,CAAA;AAI1D,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAW,MAAM,CAAA;IACnB,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;IACpC,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,WAAW,EAAE,MAAM,CAAA;IACnB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B,OAAO,EAAE,OAAO,CAAA;CACjB;AAED,MAAM,MAAM,mBAAmB,GAAG,CAAC,GAAG,EAAE,wBAAwB,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;AAE/F,qBAAa,QAAQ;IACnB,OAAO,CAAC,MAAM,CAAC,OAAO,CAA4B;IAClD,OAAO,CAAC,MAAM,CAAC,cAAc,CAAiC;IAC9D,OAAO,CAAC,MAAM,CAAC,qBAAqB,CAA2B;IAC/D,OAAO,CAAC,MAAM,CAAC,sBAAsB,CAA+B;IACpE,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAY;IACnC,OAAO,CAAC,MAAM,CAAC,WAAW,CAAsB;IAChD,OAAO,CAAC,MAAM,CAAC,UAAU,CAAsB;IAC/C;;;;;;;;OAQG;IACH,OAAO,CAAC,MAAM,CAAC,kBAAkB,CAAsB;IAGvD,OAAO,CAAC,MAAM,CAAC,YAAY,CAAyC;IACpE,OAAO,CAAC,MAAM,CAAC,WAAW,CAA0C;IACpE,OAAO,CAAC,MAAM,CAAC,kBAAkB,CAAmC;IACpE,OAAO,CAAC,MAAM,CAAC,cAAc,CAAuC;IACpE,OAAO,CAAC,MAAM,CAAC,gBAAgB,CAAqC;IAGpE,OAAO,CAAC,MAAM,CAAC,kBAAkB,CAAmC;IAGpE,OAAO,CAAC,MAAM,CAAC,cAAc,CAAQ;IAMrC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAsB;IAE5C;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM,CAAC,kBAAkB,CAAK;IAItC,qCAAqC;IACrC,MAAM,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI;IAMtD,mCAAmC;IACnC,MAAM,CAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAIpC,8BAA8B;IAC9B,MAAM,CAAC,MAAM,IAAI,aAAa,EAAE;IAIhC,+DAA+D;IAC/D,MAAM,CAAC,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE;IAMjD,MAAM,CAAC,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IACvC,MAAM,CAAC,qBAAqB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAC9C,MAAM,CAAC,4BAA4B,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAErD,MAAM,CAAC,aAAa,IAAI,MAAM;IAC9B,MAAM,CAAC,oBAAoB,IAAI,MAAM;IACrC,MAAM,CAAC,qBAAqB,IAAI,MAAM;IAItC,mDAAmD;IACnD,MAAM,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAEvC,mCAAmC;IACnC,MAAM,CAAC,OAAO,IAAI,MAAM;IAExB,sDAAsD;IACtD,MAAM,CAAC,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAK3D;;;;;;;OAOG;IACH,MAAM,CAAC,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAI3D;;;;;;;;OAQG;WACU,aAAa,IAAI,OAAO,CAAC,OAAO,CAAC;IAgB9C,sEAAsE;WACzD,IAAI,IAAI,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAwBvE;;;;;;;;;;;;;;;;;;;OAmBG;WACU,gBAAgB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IA2BlD,sDAAsD;IACtD,MAAM,CAAC,iBAAiB,IAAI,MAAM,GAAG,IAAI;IAMzC,MAAM,CAAC,cAAc,CAAC,GAAG,EAAE,OAAO,WAAW,GAAU,IAAI;IAC3D,MAAM,CAAC,aAAa,CAAC,GAAG,EAAE,OAAO,WAAW,GAAW,IAAI;IAC3D,MAAM,CAAC,oBAAoB,CAAC,GAAG,EAAE,OAAO,YAAY,GAAG,IAAI;IAC3D,MAAM,CAAC,gBAAgB,CAAC,GAAG,EAAE,OAAO,QAAQ,GAAW,IAAI;IAC3D,MAAM,CAAC,kBAAkB,CAAC,GAAG,EAAE,OAAO,UAAU,GAAO,IAAI;WAE9C,WAAW,IAAI,OAAO,CAAC,OAAO,WAAW,CAAC;WAI1C,UAAU,IAAI,OAAO,CAAC,OAAO,WAAW,CAAC;WAIzC,iBAAiB,IAAI,OAAO,CAAC,OAAO,YAAY,CAAC;WAIjD,aAAa,IAAI,OAAO,CAAC,OAAO,QAAQ,CAAC;WAIzC,eAAe,IAAI,OAAO,CAAC,OAAO,UAAU,CAAC;IAO1D;;;;OAIG;IACH,MAAM,CAAC,iBAAiB,CAAC,EAAE,EAAE,mBAAmB,GAAG,IAAI;IAIvD,MAAM,CAAC,mBAAmB,IAAI,mBAAmB,GAAG,IAAI;IAMxD;;;OAGG;IACH,MAAM,CAAC,YAAY,IAAI,IAAI;IAI3B,MAAM,CAAC,aAAa,IAAI,OAAO;IAM/B;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IACnC,MAAM,CAAC,MAAM,IAAI,MAAM,GAAG,IAAI;IAI9B;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAM/C,8DAA8D;IAC9D,MAAM,CAAC,wBAAwB,IAAI,MAAM;IAMzC,gBAAgB;IAChB,MAAM,CAAC,KAAK,IAAI,IAAI;CAmBrB"}

package/dist/Passport.js

@@ -6,6 +6,16 @@ export class Passport {
     static _keyPath = 'storage';
     static _privateKey = null;
     static _publicKey = null;
+    /**
+     * Previous public key, retained for verification only after a `passport:keys
+     * --force` rotation. Tokens minted before the rotation keep verifying via
+     * this slot during the grace window; new tokens are signed by the current
+     * private key. Single-slot — one rotation deep — by design (operators who
+     * need a longer history should stage rotations to land outside the
+     * configured access-token lifetime). See JWKS verifier design notes in
+     * `verificationKeys()` below.
+     */
+    static _previousPublicKey = null;
     // Custom model overrides (lazy — resolved at use-site so the defaults aren't eagerly loaded).
     static _clientModel = null;
     static _tokenModel = null;
@@ -16,6 +26,20 @@ export class Passport {
     static _authorizationView = null;
     // Route auto-registration toggle
     static _routesIgnored = false;
+    // JWT issuer URL — when set, createToken stamps `iss` on the payload and
+    // verifyToken can validate it via `expectedIssuer`. Optional per RFC 7519
+    // but recommended by RFC 8725 §3.10 once the deployment has more than one
+    // possible issuer (e.g. multi-tenant or staging vs prod sharing keys).
+    static _issuer = null;
+    /**
+     * Maximum value (in seconds) the per-row `oauth_device_codes.interval` is
+     * allowed to grow to via repeated `slow_down` escalations (RFC 8628 §3.5
+     * doesn't specify a cap; we add one to keep degenerate clients from
+     * pushing the interval to absurd values). 60 seconds is the default — long
+     * enough to make a misbehaving client back off meaningfully, short enough
+     * that a legitimate user typing the user_code never hits it.
+     */
+    static _deviceMaxInterval = 60;
     // ── Scopes ──────────────────────────────────────────────
     /** Define available OAuth scopes. */
     static tokensCan(scopes) {
@@ -52,6 +76,39 @@ export class Passport {
         this._privateKey = privateKey;
         this._publicKey = publicKey;
     }
+    /**
+     * Stamp the previous public key for verification grace after a key
+     * rotation. Tokens carrying `kid` for this key — or any token whose
+     * signature happens to verify against it — keep working until they
+     * naturally expire. Pair with the env var `PASSPORT_PREVIOUS_PUBLIC_KEY`
+     * if you don't want to rely on the on-disk `oauth-previous-public.key`
+     * convention. Pass `null` to clear.
+     */
+    static setPreviousPublicKey(publicKey) {
+        this._previousPublicKey = publicKey && publicKey.length > 0 ? publicKey : null;
+    }
+    /**
+     * Probe whether an RSA keypair is reachable — either explicitly set via
+     * `setKeys()` (env vars) or readable on disk under the configured key path.
+     * Used by `PassportProvider.boot()` to surface a startup warning when keys
+     * are missing, before the first `/oauth/*` request fails with a confusing
+     * file-not-found error.
+     *
+     * Does NOT load or cache the keys; it only stats the files.
+     */
+    static async keysAvailable() {
+        if (this._privateKey && this._publicKey)
+            return true;
+        const { stat } = await import('node:fs/promises');
+        const { join } = await import('node:path');
+        const privatePath = join(process.cwd(), this._keyPath, 'oauth-private.key');
+        const publicPath = join(process.cwd(), this._keyPath, 'oauth-public.key');
+        const [priv, pub] = await Promise.all([
+            stat(privatePath).then(() => true, () => false),
+            stat(publicPath).then(() => true, () => false),
+        ]);
+        return priv && pub;
+    }
     /** Load keys from files or env. Returns { privateKey, publicKey }. */
     static async keys() {
         // Prefer explicitly set keys (from env vars)
@@ -71,6 +128,54 @@ export class Passport {
         this._publicKey = publicKey;
         return { privateKey, publicKey };
     }
+    /**
+     * All public keys that should be considered for JWT signature verification,
+     * ordered current-first. After `passport:keys --force` rotates the
+     * keypair, the previous public key lingers in this list (loaded from
+     * `oauth-previous-public.key` on disk or set via `setPreviousPublicKey()`)
+     * so JWTs signed before the rotation keep verifying during their natural
+     * lifetime — `verifyToken()` walks the list and accepts a match against
+     * any entry. Without this, every rotation forced an immediate global
+     * sign-out.
+     *
+     * Tokens minted by recent versions also carry a `kid` JWT header equal to
+     * the SHA-256 of the public key that signed them, so the verifier can
+     * pick the right key directly without trial-and-error. Legacy tokens with
+     * no `kid` fall through to "try each in order".
+     *
+     * Single previous-slot is intentional: one rotation deep. Operators who
+     * need a multi-step grace should stage rotations to land outside the
+     * configured access-token lifetime — at that point old tokens have
+     * expired anyway and a longer history buys nothing.
+     */
+    static async verificationKeys() {
+        const { publicKey } = await this.keys();
+        const keys = [publicKey];
+        if (this._previousPublicKey) {
+            keys.push(this._previousPublicKey);
+            return keys;
+        }
+        // Filesystem fallback — `oauth-previous-public.key` is written by
+        // `generateKeys({ force: true })` during a rotation, alongside the
+        // timestamped audit backup.
+        const { readFile } = await import('node:fs/promises');
+        const { join } = await import('node:path');
+        const previousPath = join(process.cwd(), this._keyPath, 'oauth-previous-public.key');
+        try {
+            const previous = await readFile(previousPath, 'utf8');
+            this._previousPublicKey = previous;
+            keys.push(previous);
+        }
+        catch {
+            // No previous key on disk — first rotation hasn't happened yet, or
+            // the operator deleted the file to drop the grace window.
+        }
+        return keys;
+    }
+    /** Get the configured previous public key, if any. */
+    static previousPublicKey() {
+        return this._previousPublicKey;
+    }
     // ── Custom Models ───────────────────────────────────────
     static useClientModel(cls) { this._clientModel = cls; }
     static useTokenModel(cls) { this._tokenModel = cls; }
@@ -125,6 +230,45 @@ export class Passport {
     static routesIgnored() {
         return this._routesIgnored;
     }
+    // ── JWT issuer ──────────────────────────────────────────
+    /**
+     * Configure the JWT `iss` claim that `createToken()` stamps on every new
+     * access token, and that `verifyToken()` validates when called with
+     * `expectedIssuer: Passport.issuer()` (BearerMiddleware does this
+     * automatically). Typically set to the canonical app URL — e.g.
+     * `Passport.useIssuer('https://app.example.com')`.
+     *
+     * RFC 8725 §3.10 recommends issuer validation once a deployment has more
+     * than one possible signer (multi-tenant, staging+prod sharing keys, etc.).
+     * Tokens minted before this is configured carry no `iss` claim and are
+     * exempt during the migration window — same pattern as redirect_uri (P1)
+     * and familyId (P4).
+     */
+    static useIssuer(url) { this._issuer = url || null; }
+    static issuer() { return this._issuer; }
+    // ── Device flow polling cap (RFC 8628 §3.5) ─────────────
+    /**
+     * Configure the maximum value (in seconds) the per-row device-code
+     * polling interval is allowed to grow to via repeated `slow_down`
+     * escalations. Must be >= 5 (the initial interval) and >= the increment
+     * step (5s) to make sense; values smaller than that disable escalation
+     * entirely and are clamped at 5.
+     *
+     * Defaults to 60 seconds. Raise it for niche flows where a misbehaving
+     * client should be backed off more aggressively (e.g. a daemon polling
+     * with no human in the loop). Lower it if your device-flow consumers can
+     * tolerate a quicker authorization handshake — but lowering below ~30
+     * gives legitimate users a small window to enter the user_code.
+     */
+    static deviceMaxInterval(seconds) {
+        // Never below the floor — escalation is by 5s, so a cap below 5
+        // would prevent any escalation from ever taking effect.
+        this._deviceMaxInterval = Math.max(5, Math.floor(seconds));
+    }
+    /** Current cap on `oauth_device_codes.interval` (seconds). */
+    static deviceMaxIntervalSeconds() {
+        return this._deviceMaxInterval;
+    }
     // ── Reset (testing) ─────────────────────────────────────
     /** @internal */
     static reset() {
@@ -135,6 +279,7 @@ export class Passport {
         this._keyPath = 'storage';
         this._privateKey = null;
         this._publicKey = null;
+        this._previousPublicKey = null;
         this._clientModel = null;
         this._tokenModel = null;
         this._refreshTokenModel = null;
@@ -142,6 +287,8 @@ export class Passport {
         this._deviceCodeModel = null;
         this._authorizationView = null;
         this._routesIgnored = false;
+        this._issuer = null;
+        this._deviceMaxInterval = 60;
     }
 }
 //# sourceMappingURL=Passport.js.map

package/dist/Passport.js.map

@@ -1 +1 @@
-{"version":3,"file":"Passport.js","sourceRoot":"","sources":["../src/Passport.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Passport.js","sourceRoot":"","sources":["../src/Passport.ts"],"names":[],"mappings":"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"}

package/dist/client-secret.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Hash a plain-text client secret for storage. Returns a peppered HMAC if
+ * `APP_KEY` is set, otherwise a plain SHA-256 hex digest.
+ */
+export declare function hashClientSecret(plainSecret: string): Promise<string>;
+/**
+ * Verify a plain-text client secret against a stored hash. Constant-time;
+ * format is auto-detected from the stored value's prefix so legacy plain
+ * SHA-256 rows continue to verify after `APP_KEY` is configured.
+ */
+export declare function verifyClientSecret(plainSecret: string, stored: string | null | undefined): Promise<boolean>;
+//# sourceMappingURL=client-secret.d.ts.map

package/dist/client-secret.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-secret.d.ts","sourceRoot":"","sources":["../src/client-secret.ts"],"names":[],"mappings":"AAkCA;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAQ3E;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAChC,OAAO,CAAC,OAAO,CAAC,CAclB"}

package/dist/client-secret.js

@@ -0,0 +1,63 @@
+import { safeCompare } from './grants/safe-compare.js';
+/**
+ * Hashing + verification of OAuth client secrets at rest.
+ *
+ * Two storage formats are supported:
+ *
+ *   - **Peppered** — `peppered:<HMAC-SHA256(secret, APP_KEY)>` (hex). Used
+ *     when `APP_KEY` is set at the time the client is created. A leaked DB
+ *     dump alone cannot be used to verify candidate secrets without also
+ *     knowing `APP_KEY`.
+ *   - **Plain SHA-256** — bare 64-char hex digest. Used when `APP_KEY` is
+ *     unset. This matches the historical (pre-2026-05) format and is what
+ *     Laravel Passport stores; client secrets are 256-bit CSPRNG so the
+ *     hash adds little cryptographic protection beyond defense-in-depth.
+ *
+ * The format is self-describing via the `peppered:` prefix, so existing
+ * rows minted before this change keep verifying against their plain
+ * SHA-256 hashes — there is no migration step. New rows use whichever
+ * format is available at creation time.
+ *
+ * Rotating `APP_KEY` invalidates every peppered client secret, the same
+ * way rotating the RSA keypair invalidates every live access token. The
+ * fallback path is to re-issue secrets via `passport:client` after the
+ * rotation; legacy plain-SHA-256 rows are unaffected.
+ */
+const PEPPERED_PREFIX = 'peppered:';
+function appKey() {
+    const key = process.env['APP_KEY'];
+    return key && key.length > 0 ? key : null;
+}
+/**
+ * Hash a plain-text client secret for storage. Returns a peppered HMAC if
+ * `APP_KEY` is set, otherwise a plain SHA-256 hex digest.
+ */
+export async function hashClientSecret(plainSecret) {
+    const { createHash, createHmac } = await import('node:crypto');
+    const pepper = appKey();
+    if (pepper) {
+        const mac = createHmac('sha256', pepper).update(plainSecret).digest('hex');
+        return `${PEPPERED_PREFIX}${mac}`;
+    }
+    return createHash('sha256').update(plainSecret).digest('hex');
+}
+/**
+ * Verify a plain-text client secret against a stored hash. Constant-time;
+ * format is auto-detected from the stored value's prefix so legacy plain
+ * SHA-256 rows continue to verify after `APP_KEY` is configured.
+ */
+export async function verifyClientSecret(plainSecret, stored) {
+    if (!stored)
+        return false;
+    const { createHash, createHmac } = await import('node:crypto');
+    if (stored.startsWith(PEPPERED_PREFIX)) {
+        const pepper = appKey();
+        if (!pepper)
+            return false;
+        const mac = createHmac('sha256', pepper).update(plainSecret).digest('hex');
+        return safeCompare(mac, stored.slice(PEPPERED_PREFIX.length));
+    }
+    const hashed = createHash('sha256').update(plainSecret).digest('hex');
+    return safeCompare(hashed, stored);
+}
+//# sourceMappingURL=client-secret.js.map

package/dist/client-secret.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-secret.js","sourceRoot":"","sources":["../src/client-secret.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAA;AAEtD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,MAAM,eAAe,GAAG,WAAW,CAAA;AAEnC,SAAS,MAAM;IACb,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAA;IAClC,OAAO,GAAG,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAA;AAC3C,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,WAAmB;IACxD,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAA;IAC9D,MAAM,MAAM,GAAG,MAAM,EAAE,CAAA;IACvB,IAAI,MAAM,EAAE,CAAC;QACX,MAAM,GAAG,GAAG,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;QAC1E,OAAO,GAAG,eAAe,GAAG,GAAG,EAAE,CAAA;IACnC,CAAC;IACD,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;AAC/D,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,WAAmB,EACnB,MAAiC;IAEjC,IAAI,CAAC,MAAM;QAAE,OAAO,KAAK,CAAA;IAEzB,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAA;IAE9D,IAAI,MAAM,CAAC,UAAU,CAAC,eAAe,CAAC,EAAE,CAAC;QACvC,MAAM,MAAM,GAAG,MAAM,EAAE,CAAA;QACvB,IAAI,CAAC,MAAM;YAAE,OAAO,KAAK,CAAA;QACzB,MAAM,GAAG,GAAG,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;QAC1E,OAAO,WAAW,CAAC,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,CAAA;IAC/D,CAAC;IAED,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IACrE,OAAO,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;AACpC,CAAC"}

package/dist/commands/client.d.ts

@@ -5,6 +5,27 @@ export interface CreateClientOpts {
     grantTypes?: string[];
     confidential?: boolean;
 }
+/**
+ * Resolve the grant-types array for a `passport:client` invocation, given
+ * the parsed CLI flags. Pure — exported so the CLI handler stays a thin
+ * wrapper and the flag → array mapping is unit-testable.
+ *
+ *   - `--device`  → `['urn:ietf:params:oauth:grant-type:device_code', 'refresh_token']`
+ *     (RFC 8628 doesn't mandate a fixed grant list; pairing `refresh_token`
+ *      with the device flow is the expected default — without it, the
+ *      tokens minted by polling can't be refreshed.)
+ *   - `--client-credentials` → `['client_credentials']`
+ *   - default → `['authorization_code', 'refresh_token']`
+ *
+ * `--personal` is intentionally NOT a case here — personal access tokens
+ * don't need a CLI-created OAuth client. `passport:client` short-circuits
+ * before this resolver runs and prints a hint pointing at
+ * `HasApiTokens.createToken()` instead.
+ */
+export declare function resolveClientGrantTypes(flags: {
+    isDevice?: boolean;
+    isM2M?: boolean;
+}): string[];
 /**
  * Create an OAuth client programmatically.
  * Returns the client and the plain-text secret (if confidential).

package/dist/commands/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/commands/client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAA;AAE3D,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAU,MAAM,CAAA;IACpB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,UAAU,CAAC,EAAG,MAAM,EAAE,CAAA;IACtB,YAAY,CAAC,EAAE,OAAO,CAAA;CACvB;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC;IAClE,MAAM,EAAE,WAAW,CAAA;IACnB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CACtB,CAAC,CAuBD"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/commands/client.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAA;AAE3D,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAU,MAAM,CAAA;IACpB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,UAAU,CAAC,EAAG,MAAM,EAAE,CAAA;IACtB,YAAY,CAAC,EAAE,OAAO,CAAA;CACvB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,MAAM,EAAE,CAIhG;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC;IAClE,MAAM,EAAE,WAAW,CAAA;IACnB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CACtB,CAAC,CAuBD"}

package/dist/commands/client.js

@@ -1,16 +1,41 @@
 import { Passport } from '../Passport.js';
+import { hashClientSecret } from '../client-secret.js';
+/**
+ * Resolve the grant-types array for a `passport:client` invocation, given
+ * the parsed CLI flags. Pure — exported so the CLI handler stays a thin
+ * wrapper and the flag → array mapping is unit-testable.
+ *
+ *   - `--device`  → `['urn:ietf:params:oauth:grant-type:device_code', 'refresh_token']`
+ *     (RFC 8628 doesn't mandate a fixed grant list; pairing `refresh_token`
+ *      with the device flow is the expected default — without it, the
+ *      tokens minted by polling can't be refreshed.)
+ *   - `--client-credentials` → `['client_credentials']`
+ *   - default → `['authorization_code', 'refresh_token']`
+ *
+ * `--personal` is intentionally NOT a case here — personal access tokens
+ * don't need a CLI-created OAuth client. `passport:client` short-circuits
+ * before this resolver runs and prints a hint pointing at
+ * `HasApiTokens.createToken()` instead.
+ */
+export function resolveClientGrantTypes(flags) {
+    if (flags.isDevice)
+        return ['urn:ietf:params:oauth:grant-type:device_code', 'refresh_token'];
+    if (flags.isM2M)
+        return ['client_credentials'];
+    return ['authorization_code', 'refresh_token'];
+}
 /**
  * Create an OAuth client programmatically.
  * Returns the client and the plain-text secret (if confidential).
  */
 export async function createClient(opts) {
-    const { randomBytes, createHash } = await import('node:crypto');
+    const { randomBytes } = await import('node:crypto');
     const confidential = opts.confidential ?? true;
     let plainSecret = null;
     let hashedSecret = null;
     if (confidential) {
         plainSecret = randomBytes(32).toString('hex');
-        hashedSecret = createHash('sha256').update(plainSecret).digest('hex');
+        hashedSecret = await hashClientSecret(plainSecret);
     }
     const ClientCls = await Passport.clientModel();
     const client = await ClientCls.create({

package/dist/commands/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/commands/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAUzC;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAAsB;IAIvD,MAAM,EAAE,WAAW,EAAE,UAAU,EAAE,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAA;IAE/D,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,IAAI,IAAI,CAAA;IAC9C,IAAI,WAAW,GAAkB,IAAI,CAAA;IACrC,IAAI,YAAY,GAAkB,IAAI,CAAA;IAEtC,IAAI,YAAY,EAAE,CAAC;QACjB,WAAW,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAA;QAC7C,YAAY,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IACvE,CAAC;IAED,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC,WAAW,EAAE,CAAA;IAC9C,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,MAAM,CAAC;QACpC,IAAI,EAAU,IAAI,CAAC,IAAI;QACvB,MAAM,EAAQ,YAAY;QAC1B,YAAY,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACxE,UAAU,EAAI,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,UAAU,IAAI,CAAC,oBAAoB,CAAC,CAAC;QACvE,MAAM,EAAQ,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;QAChC,YAAY;KACc,CAAgB,CAAA;IAE5C,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,CAAA;AACxC,CAAC"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/commands/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AACzC,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AAUtD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAA8C;IACpF,IAAI,KAAK,CAAC,QAAQ;QAAE,OAAO,CAAC,8CAA8C,EAAE,eAAe,CAAC,CAAA;IAC5F,IAAI,KAAK,CAAC,KAAK;QAAK,OAAO,CAAC,oBAAoB,CAAC,CAAA;IACjD,OAAO,CAAC,oBAAoB,EAAE,eAAe,CAAC,CAAA;AAChD,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAAsB;IAIvD,MAAM,EAAE,WAAW,EAAE,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAA;IAEnD,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,IAAI,IAAI,CAAA;IAC9C,IAAI,WAAW,GAAkB,IAAI,CAAA;IACrC,IAAI,YAAY,GAAkB,IAAI,CAAA;IAEtC,IAAI,YAAY,EAAE,CAAC;QACjB,WAAW,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAA;QAC7C,YAAY,GAAG,MAAM,gBAAgB,CAAC,WAAW,CAAC,CAAA;IACpD,CAAC;IAED,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC,WAAW,EAAE,CAAA;IAC9C,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,MAAM,CAAC;QACpC,IAAI,EAAU,IAAI,CAAC,IAAI;QACvB,MAAM,EAAQ,YAAY;QAC1B,YAAY,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACxE,UAAU,EAAI,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,UAAU,IAAI,CAAC,oBAAoB,CAAC,CAAC;QACvE,MAAM,EAAQ,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;QAChC,YAAY;KACc,CAAgB,CAAA;IAE5C,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,CAAA;AACxC,CAAC"}

package/dist/commands/keys.d.ts

@@ -1,11 +1,35 @@
+export interface GenerateKeysResult {
+    privatePath: string;
+    publicPath: string;
+    /** Backup paths if existing keys were rotated under --force; null otherwise. */
+    backup: {
+        privatePath: string;
+        publicPath: string;
+    } | null;
+    /**
+     * Path of the rolling "previous public key" written under --force. The
+     * verifier (Passport.verificationKeys()) picks this up automatically, so
+     * JWTs signed before the rotation keep verifying during their natural
+     * lifetime instead of all logging out at the next request. Distinct from
+     * the timestamped audit `backup` files — `previousPublicPath` always
+     * lives at `oauth-previous-public.key` and gets overwritten on the next
+     * rotation. Null on first generation (no prior key to retain).
+     */
+    previousPublicPath: string | null;
+}
 /**
  * Generate RSA keypair for JWT signing.
  * Writes to storage/oauth-private.key and storage/oauth-public.key.
+ *
+ * With `--force`, existing keys are renamed to `*.bak.<ISO-timestamp>` before
+ * being replaced AND the prior public key is also copied to
+ * `oauth-previous-public.key`. The verifier walks both keys during the
+ * grace window (until the prior tokens expire naturally), so a rotation no
+ * longer forces an immediate global sign-out. The audit backups live
+ * alongside for full recovery; the previous-public file is the operational
+ * one that the verifier consults.
  */
 export declare function generateKeys(opts?: {
     force?: boolean;
-}): Promise<{
-    privatePath: string;
-    publicPath: string;
-}>;
+}): Promise<GenerateKeysResult>;
 //# sourceMappingURL=keys.d.ts.map

package/dist/commands/keys.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../../src/commands/keys.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,wBAAsB,YAAY,CAAC,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,CAyBvH"}
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../../src/commands/keys.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,CAAA;IACnB,UAAU,EAAG,MAAM,CAAA;IACnB,gFAAgF;IAChF,MAAM,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAA;IAC1D;;;;;;;;OAQG;IACH,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAA;CAClC;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,YAAY,CAAC,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAgD9F"}