@rudderjs/passport 1.0.0 → 1.1.1

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"}

package/dist/commands/keys.js

@@ -2,26 +2,56 @@ import { Passport } from '../Passport.js';
 /**
  * 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 async function generateKeys(opts = {}) {
     const { generateKeyPairSync } = await import('node:crypto');
-    const { writeFile, mkdir } = await import('node:fs/promises');
+    const { writeFile, mkdir, rename, copyFile } = await import('node:fs/promises');
     const { existsSync } = await import('node:fs');
     const { join } = await import('node:path');
     const keyDir = join(process.cwd(), Passport.keyPath());
     const privatePath = join(keyDir, 'oauth-private.key');
     const publicPath = join(keyDir, 'oauth-public.key');
-    if (!opts.force && existsSync(privatePath)) {
+    const previousPublicPath = join(keyDir, 'oauth-previous-public.key');
+    const privateExists = existsSync(privatePath);
+    const publicExists = existsSync(publicPath);
+    if (!opts.force && privateExists) {
         throw new Error(`Keys already exist at ${privatePath}. Use --force to overwrite.`);
     }
+    await mkdir(keyDir, { recursive: true });
+    let backup = null;
+    let previousPublicWritten = null;
+    if (opts.force && (privateExists || publicExists)) {
+        const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+        const privateBackup = `${privatePath}.bak.${stamp}`;
+        const publicBackup = `${publicPath}.bak.${stamp}`;
+        // Copy the public key to the rolling "previous" slot BEFORE renaming —
+        // the verifier loads from `oauth-previous-public.key` so JWTs signed by
+        // the about-to-rotate key keep verifying during their natural lifetime.
+        if (publicExists) {
+            await copyFile(publicPath, previousPublicPath);
+            previousPublicWritten = previousPublicPath;
+        }
+        if (privateExists)
+            await rename(privatePath, privateBackup);
+        if (publicExists)
+            await rename(publicPath, publicBackup);
+        backup = { privatePath: privateBackup, publicPath: publicBackup };
+    }
     const { privateKey, publicKey } = generateKeyPairSync('rsa', {
         modulusLength: 4096,
         publicKeyEncoding: { type: 'spki', format: 'pem' },
         privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
     });
-    await mkdir(keyDir, { recursive: true });
     await writeFile(privatePath, privateKey, { mode: 0o600 });
     await writeFile(publicPath, publicKey, { mode: 0o644 });
-    return { privatePath, publicPath };
+    return { privatePath, publicPath, backup, previousPublicPath: previousPublicWritten };
 }
 //# sourceMappingURL=keys.js.map

package/dist/commands/keys.js.map

@@ -1 +1 @@
-{"version":3,"file":"keys.js","sourceRoot":"","sources":["../../src/commands/keys.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAEzC;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,OAA4B,EAAE;IAC/D,MAAM,EAAE,mBAAmB,EAAE,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAA;IAC3D,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,kBAAkB,CAAC,CAAA;IAC7D,MAAM,EAAE,UAAU,EAAE,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,CAAA;IAC9C,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,CAAA;IAE1C,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAA;IACtD,MAAM,WAAW,GAAG,IAAI,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAA;IACrD,MAAM,UAAU,GAAI,IAAI,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAA;IAEpD,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;QAC3C,MAAM,IAAI,KAAK,CAAC,yBAAyB,WAAW,6BAA6B,CAAC,CAAA;IACpF,CAAC;IAED,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,GAAG,mBAAmB,CAAC,KAAK,EAAE;QAC3D,aAAa,EAAE,IAAI;QACnB,iBAAiB,EAAG,EAAE,IAAI,EAAE,MAAM,EAAG,MAAM,EAAE,KAAK,EAAE;QACpD,kBAAkB,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE;KACrD,CAAC,CAAA;IAEF,MAAM,KAAK,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IACxC,MAAM,SAAS,CAAC,WAAW,EAAE,UAAU,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAA;IACzD,MAAM,SAAS,CAAC,UAAU,EAAE,SAAS,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAA;IAEvD,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,CAAA;AACpC,CAAC"}
+{"version":3,"file":"keys.js","sourceRoot":"","sources":["../../src/commands/keys.ts"],"names":[],"mappings":"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"}

package/dist/commands/purge.d.ts

@@ -1,6 +1,11 @@
 /**
  * Remove expired and revoked tokens from the database.
- * Returns counts of purged records.
+ *
+ * Each model is purged with a single bulk `deleteAll()` against the
+ * QueryBuilder — one round-trip per model regardless of row count. No
+ * hydration, no per-row delete calls, no observers (counter-style data plane).
+ *
+ * Returns the number of rows deleted per model.
  */
 export declare function purgeTokens(): Promise<{
     accessTokens: number;

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

@@ -1 +1 @@
-{"version":3,"file":"purge.d.ts","sourceRoot":"","sources":["../../src/commands/purge.ts"],"names":[],"mappings":"AAMA;;;GAGG;AACH,wBAAsB,WAAW,IAAI,OAAO,CAAC;IAC3C,YAAY,EAAG,MAAM,CAAA;IACrB,aAAa,EAAE,MAAM,CAAA;IACrB,SAAS,EAAM,MAAM,CAAA;IACrB,WAAW,EAAI,MAAM,CAAA;CACtB,CAAC,CAgDD"}
+{"version":3,"file":"purge.d.ts","sourceRoot":"","sources":["../../src/commands/purge.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,wBAAsB,WAAW,IAAI,OAAO,CAAC;IAC3C,YAAY,EAAG,MAAM,CAAA;IACrB,aAAa,EAAE,MAAM,CAAA;IACrB,SAAS,EAAM,MAAM,CAAA;IACrB,WAAW,EAAI,MAAM,CAAA;CACtB,CAAC,CA2BD"}

package/dist/commands/purge.js

@@ -1,7 +1,12 @@
 import { Passport } from '../Passport.js';
 /**
  * Remove expired and revoked tokens from the database.
- * Returns counts of purged records.
+ *
+ * Each model is purged with a single bulk `deleteAll()` against the
+ * QueryBuilder — one round-trip per model regardless of row count. No
+ * hydration, no per-row delete calls, no observers (counter-style data plane).
+ *
+ * Returns the number of rows deleted per model.
  */
 export async function purgeTokens() {
     const now = new Date();
@@ -9,41 +14,20 @@ export async function purgeTokens() {
     const RefreshTokenCls = await Passport.refreshTokenModel();
     const AuthCodeCls = await Passport.authCodeModel();
     const DeviceCodeCls = await Passport.deviceCodeModel();
-    // Purge expired/revoked access tokens
-    const expiredAccess = await AccessTokenCls.query()
+    const accessTokens = await AccessTokenCls.query()
         .where('expiresAt', '<', now)
         .orWhere('revoked', true)
-        .get();
-    for (const t of expiredAccess) {
-        await AccessTokenCls.delete(t.id);
-    }
-    // Purge expired/revoked refresh tokens
-    const expiredRefresh = await RefreshTokenCls.query()
+        .deleteAll();
+    const refreshTokens = await RefreshTokenCls.query()
         .where('expiresAt', '<', now)
         .orWhere('revoked', true)
-        .get();
-    for (const t of expiredRefresh) {
-        await RefreshTokenCls.delete(t.id);
-    }
-    // Purge expired auth codes
-    const expiredCodes = await AuthCodeCls.query()
+        .deleteAll();
+    const authCodes = await AuthCodeCls.query()
         .where('expiresAt', '<', now)
-        .get();
-    for (const c of expiredCodes) {
-        await AuthCodeCls.delete(c.id);
-    }
-    // Purge expired device codes
-    const expiredDevices = await DeviceCodeCls.query()
+        .deleteAll();
+    const deviceCodes = await DeviceCodeCls.query()
         .where('expiresAt', '<', now)
-        .get();
-    for (const d of expiredDevices) {
-        await DeviceCodeCls.delete(d.id);
-    }
-    return {
-        accessTokens: expiredAccess.length,
-        refreshTokens: expiredRefresh.length,
-        authCodes: expiredCodes.length,
-        deviceCodes: expiredDevices.length,
-    };
+        .deleteAll();
+    return { accessTokens, refreshTokens, authCodes, deviceCodes };
 }
 //# sourceMappingURL=purge.js.map

package/dist/commands/purge.js.map

@@ -1 +1 @@
-{"version":3,"file":"purge.js","sourceRoot":"","sources":["../../src/commands/purge.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAMzC;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW;IAM/B,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAA;IAEtB,MAAM,cAAc,GAAI,MAAM,QAAQ,CAAC,UAAU,EAAE,CAAA;IACnD,MAAM,eAAe,GAAG,MAAM,QAAQ,CAAC,iBAAiB,EAAE,CAAA;IAC1D,MAAM,WAAW,GAAO,MAAM,QAAQ,CAAC,aAAa,EAAE,CAAA;IACtD,MAAM,aAAa,GAAK,MAAM,QAAQ,CAAC,eAAe,EAAE,CAAA;IAExD,sCAAsC;IACtC,MAAM,aAAa,GAAG,MAAM,cAAc,CAAC,KAAK,EAAE;SAC/C,KAAK,CAAC,WAAW,EAAE,GAAG,EAAE,GAAG,CAAC;SAC5B,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC;SACxB,GAAG,EAAmB,CAAA;IACzB,KAAK,MAAM,CAAC,IAAI,aAAa,EAAE,CAAC;QAC9B,MAAM,cAAc,CAAC,MAAM,CAAE,CAAS,CAAC,EAAY,CAAC,CAAA;IACtD,CAAC;IAED,uCAAuC;IACvC,MAAM,cAAc,GAAG,MAAM,eAAe,CAAC,KAAK,EAAE;SACjD,KAAK,CAAC,WAAW,EAAE,GAAG,EAAE,GAAG,CAAC;SAC5B,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC;SACxB,GAAG,EAAoB,CAAA;IAC1B,KAAK,MAAM,CAAC,IAAI,cAAc,EAAE,CAAC;QAC/B,MAAM,eAAe,CAAC,MAAM,CAAE,CAAS,CAAC,EAAY,CAAC,CAAA;IACvD,CAAC;IAED,2BAA2B;IAC3B,MAAM,YAAY,GAAG,MAAM,WAAW,CAAC,KAAK,EAAE;SAC3C,KAAK,CAAC,WAAW,EAAE,GAAG,EAAE,GAAG,CAAC;SAC5B,GAAG,EAAgB,CAAA;IACtB,KAAK,MAAM,CAAC,IAAI,YAAY,EAAE,CAAC;QAC7B,MAAM,WAAW,CAAC,MAAM,CAAE,CAAS,CAAC,EAAY,CAAC,CAAA;IACnD,CAAC;IAED,6BAA6B;IAC7B,MAAM,cAAc,GAAG,MAAM,aAAa,CAAC,KAAK,EAAE;SAC/C,KAAK,CAAC,WAAW,EAAE,GAAG,EAAE,GAAG,CAAC;SAC5B,GAAG,EAAkB,CAAA;IACxB,KAAK,MAAM,CAAC,IAAI,cAAc,EAAE,CAAC;QAC/B,MAAM,aAAa,CAAC,MAAM,CAAE,CAAS,CAAC,EAAY,CAAC,CAAA;IACrD,CAAC;IAED,OAAO;QACL,YAAY,EAAG,aAAa,CAAC,MAAM;QACnC,aAAa,EAAE,cAAc,CAAC,MAAM;QACpC,SAAS,EAAM,YAAY,CAAC,MAAM;QAClC,WAAW,EAAI,cAAc,CAAC,MAAM;KACrC,CAAA;AACH,CAAC"}
+{"version":3,"file":"purge.js","sourceRoot":"","sources":["../../src/commands/purge.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAEzC;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW;IAM/B,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAA;IAEtB,MAAM,cAAc,GAAI,MAAM,QAAQ,CAAC,UAAU,EAAE,CAAA;IACnD,MAAM,eAAe,GAAG,MAAM,QAAQ,CAAC,iBAAiB,EAAE,CAAA;IAC1D,MAAM,WAAW,GAAO,MAAM,QAAQ,CAAC,aAAa,EAAE,CAAA;IACtD,MAAM,aAAa,GAAK,MAAM,QAAQ,CAAC,eAAe,EAAE,CAAA;IAExD,MAAM,YAAY,GAAG,MAAM,cAAc,CAAC,KAAK,EAAE;SAC9C,KAAK,CAAC,WAAW,EAAE,GAAG,EAAE,GAAG,CAAC;SAC5B,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC;SACxB,SAAS,EAAE,CAAA;IAEd,MAAM,aAAa,GAAG,MAAM,eAAe,CAAC,KAAK,EAAE;SAChD,KAAK,CAAC,WAAW,EAAE,GAAG,EAAE,GAAG,CAAC;SAC5B,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC;SACxB,SAAS,EAAE,CAAA;IAEd,MAAM,SAAS,GAAG,MAAM,WAAW,CAAC,KAAK,EAAE;SACxC,KAAK,CAAC,WAAW,EAAE,GAAG,EAAE,GAAG,CAAC;SAC5B,SAAS,EAAE,CAAA;IAEd,MAAM,WAAW,GAAG,MAAM,aAAa,CAAC,KAAK,EAAE;SAC5C,KAAK,CAAC,WAAW,EAAE,GAAG,EAAE,GAAG,CAAC;SAC5B,SAAS,EAAE,CAAA;IAEd,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,WAAW,EAAE,CAAA;AAChE,CAAC"}

package/dist/device-code-secret.d.ts

@@ -0,0 +1,28 @@
+/**
+ * SHA-256 hashing for device-flow secrets (`device_code` + `user_code`).
+ *
+ * Different threat model from client secrets — we don't pepper here:
+ *
+ * - `deviceCode` is `randomBytes(32).toString('hex')` (256 bits CSPRNG).
+ *   `userCode` is 8 chars from a 32-symbol alphabet (~1.1×10^12 keyspace).
+ *   Both are already unguessable per request.
+ * - The threat being mitigated is **DB read leak**: an attacker with
+ *   `SELECT *` access on `oauth_device_codes` should not get usable codes
+ *   that they can replay against `/oauth/token` or `/oauth/device/approve`.
+ *   SHA-256 of the plaintext is sufficient — the attacker can't reverse it,
+ *   and brute-force by guessing the input is no easier than guessing the
+ *   original code without a DB leak at all.
+ * - Pepper would help against an offline attacker who learned a column hash
+ *   AND could test guesses against an online endpoint. Device codes are
+ *   TTL-limited (15 min) and the per-IP rate limit (#279 + the api-group
+ *   default) prevents online brute force, so the pepper buys nothing.
+ *
+ * This is intentionally simpler than `client-secret.ts` (which DOES pepper
+ * via APP_KEY) — long-lived client secrets across multiple confidential
+ * clients have a different risk profile from short-lived per-flow codes.
+ *
+ * Lazy-loads `node:crypto` so the package stays importable from non-Node
+ * runtimes that never reach this code path.
+ */
+export declare function hashDeviceSecret(plaintext: string): Promise<string>;
+//# sourceMappingURL=device-code-secret.d.ts.map

package/dist/device-code-secret.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-code-secret.d.ts","sourceRoot":"","sources":["../src/device-code-secret.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAGzE"}

package/dist/device-code-secret.js

@@ -0,0 +1,31 @@
+/**
+ * SHA-256 hashing for device-flow secrets (`device_code` + `user_code`).
+ *
+ * Different threat model from client secrets — we don't pepper here:
+ *
+ * - `deviceCode` is `randomBytes(32).toString('hex')` (256 bits CSPRNG).
+ *   `userCode` is 8 chars from a 32-symbol alphabet (~1.1×10^12 keyspace).
+ *   Both are already unguessable per request.
+ * - The threat being mitigated is **DB read leak**: an attacker with
+ *   `SELECT *` access on `oauth_device_codes` should not get usable codes
+ *   that they can replay against `/oauth/token` or `/oauth/device/approve`.
+ *   SHA-256 of the plaintext is sufficient — the attacker can't reverse it,
+ *   and brute-force by guessing the input is no easier than guessing the
+ *   original code without a DB leak at all.
+ * - Pepper would help against an offline attacker who learned a column hash
+ *   AND could test guesses against an online endpoint. Device codes are
+ *   TTL-limited (15 min) and the per-IP rate limit (#279 + the api-group
+ *   default) prevents online brute force, so the pepper buys nothing.
+ *
+ * This is intentionally simpler than `client-secret.ts` (which DOES pepper
+ * via APP_KEY) — long-lived client secrets across multiple confidential
+ * clients have a different risk profile from short-lived per-flow codes.
+ *
+ * Lazy-loads `node:crypto` so the package stays importable from non-Node
+ * runtimes that never reach this code path.
+ */
+export async function hashDeviceSecret(plaintext) {
+    const { createHash } = await import('node:crypto');
+    return createHash('sha256').update(plaintext).digest('hex');
+}
+//# sourceMappingURL=device-code-secret.js.map

package/dist/device-code-secret.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-code-secret.js","sourceRoot":"","sources":["../src/device-code-secret.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,SAAiB;IACtD,MAAM,EAAE,UAAU,EAAE,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAA;IAClD,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;AAC7D,CAAC"}

package/dist/grants/authorization-code.d.ts

@@ -46,6 +46,29 @@ export interface TokenExchangeRequest {
  * Exchange an authorization code for access + refresh tokens.
  */
 export declare function exchangeAuthCode(params: TokenExchangeRequest): Promise<IssuedTokens>;
+/**
+ * Validate requested scopes against two gates and throw `invalid_scope` per
+ * RFC 6749 §3.3 if any requested scope fails either:
+ *
+ *   1. **Global registry** — declared via `Passport.tokensCan({...})`.
+ *      Rejects scopes the operator hasn't acknowledged exist.
+ *   2. **Per-client allow-list** — `client.scopes`. Rejects scopes outside
+ *      the operator-configured subset for this specific client.
+ *
+ * Each gate is **only enforced when populated**:
+ *   - Empty global registry → no global gate (treated as "scopes not yet
+ *     declared"). Matches Laravel Passport's "no scopes defined → permissive"
+ *     default; existing apps that haven't called `tokensCan()` won't break.
+ *   - Empty `client.scopes` → no per-client gate ("client may request any
+ *     globally-known scope"). The vast majority of clients leave this empty.
+ *
+ * Used by the auth-code, device-code, and client-credentials grants. Refresh
+ * token already has its own narrowing logic (can only narrow vs. the original
+ * issuance, never widen) and skips this helper.
+ *
+ * The `*` wildcard is always allowed — same convention as `Passport.validScopes()`.
+ */
+export declare function validateScopes(client: OAuthClient, requested: string[]): void;
 export declare class OAuthError extends Error {
     readonly error: string;
     readonly errorDescription: string;

package/dist/grants/authorization-code.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"authorization-code.d.ts","sourceRoot":"","sources":["../../src/grants/authorization-code.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAA;AAG3D,OAAO,EAAe,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAIlE,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAO,MAAM,CAAA;IACrB,WAAW,EAAI,MAAM,CAAA;IACrB,YAAY,EAAG,MAAM,CAAA;IACrB,KAAK,EAAU,MAAM,CAAA;IACrB,KAAK,CAAC,EAAS,MAAM,CAAA;IACrB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,mBAAmB,CAAC,EAAE,MAAM,CAAA;CAC7B;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAS,WAAW,CAAA;IAC1B,WAAW,EAAI,MAAM,CAAA;IACrB,MAAM,EAAS,MAAM,EAAE,CAAA;IACvB,KAAK,CAAC,EAAS,MAAM,CAAA;IACrB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,mBAAmB,CAAC,EAAE,MAAM,CAAA;CAC7B;AAED;;;GAGG;AACH,wBAAsB,4BAA4B,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CA0C9G;AAID;;;GAGG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE;IACxC,MAAM,EAAK,MAAM,CAAA;IACjB,QAAQ,EAAG,MAAM,CAAA;IACjB,MAAM,EAAK,MAAM,EAAE,CAAA;IACnB,WAAW,EAAE,MAAM,CAAA;IACnB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,mBAAmB,CAAC,EAAE,MAAM,CAAA;CAC7B,GAAG,OAAO,CAAC,MAAM,CAAC,CAelB;AAID,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAK,MAAM,CAAA;IACpB,IAAI,EAAU,MAAM,CAAA;IACpB,QAAQ,EAAM,MAAM,CAAA;IACpB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,WAAW,EAAG,MAAM,CAAA;IACpB,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,YAAY,CAAC,CA0E1F;AAID,qBAAa,UAAW,SAAQ,KAAK;aAEjB,KAAK,EAAE,MAAM;aACb,gBAAgB,EAAE,MAAM;aACxB,UAAU,EAAE,MAAM;gBAFlB,KAAK,EAAE,MAAM,EACb,gBAAgB,EAAE,MAAM,EACxB,UAAU,GAAE,MAAY;IAM1C,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;CAMjC"}
+{"version":3,"file":"authorization-code.d.ts","sourceRoot":"","sources":["../../src/grants/authorization-code.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAA;AAM3D,OAAO,EAAe,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAIlE,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAO,MAAM,CAAA;IACrB,WAAW,EAAI,MAAM,CAAA;IACrB,YAAY,EAAG,MAAM,CAAA;IACrB,KAAK,EAAU,MAAM,CAAA;IACrB,KAAK,CAAC,EAAS,MAAM,CAAA;IACrB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,mBAAmB,CAAC,EAAE,MAAM,CAAA;CAC7B;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAS,WAAW,CAAA;IAC1B,WAAW,EAAI,MAAM,CAAA;IACrB,MAAM,EAAS,MAAM,EAAE,CAAA;IACvB,KAAK,CAAC,EAAS,MAAM,CAAA;IACrB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,mBAAmB,CAAC,EAAE,MAAM,CAAA;CAC7B;AAED;;;GAGG;AACH,wBAAsB,4BAA4B,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAoD9G;AAID;;;GAGG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE;IACxC,MAAM,EAAK,MAAM,CAAA;IACjB,QAAQ,EAAG,MAAM,CAAA;IACjB,MAAM,EAAK,MAAM,EAAE,CAAA;IACnB,WAAW,EAAE,MAAM,CAAA;IACnB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,mBAAmB,CAAC,EAAE,MAAM,CAAA;CAC7B,GAAG,OAAO,CAAC,MAAM,CAAC,CAwBlB;AAID,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAK,MAAM,CAAA;IACpB,IAAI,EAAU,MAAM,CAAA;IACpB,QAAQ,EAAM,MAAM,CAAA;IACpB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,WAAW,EAAG,MAAM,CAAA;IACpB,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,YAAY,CAAC,CA0H1F;AAID;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI,CA0B7E;AAID,qBAAa,UAAW,SAAQ,KAAK;aAEjB,KAAK,EAAE,MAAM;aACb,gBAAgB,EAAE,MAAM;aACxB,UAAU,EAAE,MAAM;gBAFlB,KAAK,EAAE,MAAM,EACb,gBAAgB,EAAE,MAAM,EACxB,UAAU,GAAE,MAAY;IAM1C,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;CAMjC"}

package/dist/grants/authorization-code.js

@@ -1,5 +1,8 @@
 import { Passport } from '../Passport.js';
 import { clientHelpers, authCodeHelpers } from '../models/helpers.js';
+import { safeCompare } from './safe-compare.js';
+import { verifyClientSecret } from '../client-secret.js';
+import { hashOpaqueToken, newOpaqueToken } from '../opaque-token.js';
 import { issueTokens } from './issue-tokens.js';
 /**
  * Validate an authorization request (GET /oauth/authorize).
@@ -22,15 +25,25 @@ export async function validateAuthorizationRequest(params) {
     }
     // PKCE validation
     if (params.codeChallenge) {
-        if (params.codeChallengeMethod && params.codeChallengeMethod !== 'S256' && params.codeChallengeMethod !== 'plain') {
+        const method = params.codeChallengeMethod ?? 'S256';
+        if (method !== 'S256' && method !== 'plain') {
             throw new OAuthError('invalid_request', 'Unsupported code_challenge_method. Use S256 or plain.');
         }
+        // Public clients must use S256. RFC 7636 §4.4.1 + OAuth 2.0 BCP recommend
+        // S256 over `plain` because `plain` makes verifier == challenge — a stolen
+        // authorization code is already enough to mint tokens, defeating PKCE's
+        // entire purpose. Confidential clients keep the `plain` option for
+        // backward-compat with non-RFC-7636-compliant integrations.
+        if (method === 'plain' && clientHelpers.isPublic(client)) {
+            throw new OAuthError('invalid_request', 'Public clients must use code_challenge_method=S256.');
+        }
     }
     else if (clientHelpers.isPublic(client)) {
         // Public clients MUST use PKCE
         throw new OAuthError('invalid_request', 'Public clients must use PKCE (code_challenge required).');
     }
     const scopes = params.scope ? params.scope.split(' ').filter(Boolean) : [];
+    validateScopes(client, scopes);
     const result = {
         client,
         redirectUri: params.redirectUri,
@@ -52,17 +65,25 @@ export async function validateAuthorizationRequest(params) {
  */
 export async function issueAuthCode(opts) {
     const expiresAt = new Date(Date.now() + 10 * 60 * 1000); // 10 minutes
+    // M5/P6: the plaintext returned to the redirect URI is freshly generated
+    // CSPRNG hex; only its SHA-256 is persisted. The previous shape returned
+    // the row's cuid `id` directly, so a DB read leak handed every in-flight
+    // auth code to anyone with `SELECT * ON oauth_auth_codes` privilege.
+    const codePlaintext = await newOpaqueToken();
+    const codeHash = await hashOpaqueToken(codePlaintext);
     const AuthCodeCls = await Passport.authCodeModel();
-    const code = await AuthCodeCls.create({
+    await AuthCodeCls.create({
         userId: opts.userId,
         clientId: opts.clientId,
+        tokenHash: codeHash,
         scopes: JSON.stringify(opts.scopes),
         revoked: false,
         expiresAt,
+        redirectUri: opts.redirectUri,
         codeChallenge: opts.codeChallenge ?? null,
         codeChallengeMethod: opts.codeChallengeMethod ?? null,
     });
-    return code.id;
+    return codePlaintext;
 }
 /**
  * Exchange an authorization code for access + refresh tokens.
@@ -73,24 +94,36 @@ export async function exchangeAuthCode(params) {
     }
     const ClientCls = await Passport.clientModel();
     const AuthCodeCls = await Passport.authCodeModel();
-    // Validate client
+    // Validate client. RFC 6749 §5.2 — client authentication failures at
+    // the token endpoint MUST return HTTP 401 with a `WWW-Authenticate`
+    // header (the latter is set in routes.ts on 401 responses). The
+    // refresh-token and client-credentials grants already return 401 here
+    // — auth-code was the inconsistent outlier.
     const client = await ClientCls.where('id', params.clientId).first();
     if (!client || client.revoked) {
-        throw new OAuthError('invalid_client', 'Client not found.');
+        throw new OAuthError('invalid_client', 'Client not found.', 401);
     }
     // Confidential clients must provide a valid secret
     if (client.confidential) {
         if (!params.clientSecret) {
-            throw new OAuthError('invalid_client', 'Client secret required.');
+            throw new OAuthError('invalid_client', 'Client secret required.', 401);
         }
-        const { createHash } = await import('node:crypto');
-        const hashed = createHash('sha256').update(params.clientSecret).digest('hex');
-        if (hashed !== client.secret) {
-            throw new OAuthError('invalid_client', 'Invalid client secret.');
+        // Schema allows `client.secret` to be null; explicit guard so a future
+        // refactor can't mask `secret = null` as authenticating. See
+        // `client-credentials.ts` for the longer-form rationale.
+        if (client.secret == null) {
+            throw new OAuthError('invalid_client', 'Confidential client has no secret on file.', 401);
+        }
+        if (!(await verifyClientSecret(params.clientSecret, client.secret))) {
+            throw new OAuthError('invalid_client', 'Invalid client secret.', 401);
         }
     }
-    // Validate auth code
-    const authCode = await AuthCodeCls.where('id', params.code).first();
+    // Validate auth code by hashed plaintext (M5/P6) — the row's `id` is no
+    // longer the bearer secret. Pre-migration codes won't match because their
+    // hashed form was never persisted; affected exchanges fall through to the
+    // 10-minute TTL drain window and the user simply re-clicks "Authorize".
+    const codeHash = await hashOpaqueToken(params.code);
+    const authCode = await AuthCodeCls.where('tokenHash', codeHash).first();
     if (!authCode) {
         throw new OAuthError('invalid_grant', 'Authorization code not found.');
     }
@@ -103,6 +136,20 @@ export async function exchangeAuthCode(params) {
     if (authCode.clientId !== params.clientId) {
         throw new OAuthError('invalid_grant', 'Authorization code was not issued to this client.');
     }
+    // RFC 6749 §4.1.3 — if a redirect_uri was bound at issuance, the exchange
+    // MUST present an identical value. Without this binding, an auth code
+    // obtained through one approved redirect can be exchanged via any other
+    // redirect registered to the same client, breaking the OAuth threat model.
+    // `redirectUri` is null only for codes issued before this column existed
+    // (≤10-minute legacy compat window after the migration lands).
+    if (authCode.redirectUri !== null && authCode.redirectUri !== undefined) {
+        if (!params.redirectUri) {
+            throw new OAuthError('invalid_grant', 'redirect_uri is required for this authorization code.');
+        }
+        if (authCode.redirectUri !== params.redirectUri) {
+            throw new OAuthError('invalid_grant', 'redirect_uri does not match the value used at authorization time.');
+        }
+    }
     // PKCE verification
     if (authCode.codeChallenge) {
         if (!params.codeVerifier) {
@@ -119,12 +166,33 @@ export async function exchangeAuthCode(params) {
             // plain
             expected = params.codeVerifier;
         }
-        if (expected !== authCode.codeChallenge) {
+        // Constant-time compare; both sides are equal-length encodings (S256 →
+        // base64url SHA-256, plain → identity). On mismatch the helper short-
+        // circuits the length check first, but the equal-length common path
+        // runs the full timingSafeEqual.
+        if (!(await safeCompare(expected, authCode.codeChallenge))) {
             throw new OAuthError('invalid_grant', 'PKCE code_verifier does not match.');
         }
     }
-    // Revoke the auth code (single-use)
-    await AuthCodeCls.update(authCode.id, { revoked: true });
+    // Atomically consume the auth code (M3). RFC 6749 §4.1.2 requires
+    // single-use codes. Without a conditional update, two concurrent
+    // exchanges of the same code can BOTH read `revoked=false`, BOTH pass
+    // PKCE / redirect_uri / client checks, and BOTH issue tokens. The
+    // unconditional update used previously was idempotent at the SQL level,
+    // so the second writer didn't see any error. We use a conditional
+    // `where('revoked', false).updateAll(...)` instead — the underlying
+    // `UPDATE ... WHERE revoked = false` is atomic in every SQL backend, so
+    // exactly one caller observes `count === 1`; the rest see `count === 0`
+    // and surface `invalid_grant`. (Tokens already minted from a prior
+    // successful exchange of the same code are NOT retroactively revoked
+    // here — that's a separate hardening, RFC §4.1.2's SHOULD clause.)
+    const consumed = await AuthCodeCls
+        .where('id', authCode.id)
+        .where('revoked', false)
+        .updateAll({ revoked: true });
+    if (consumed === 0) {
+        throw new OAuthError('invalid_grant', 'Authorization code has already been used.');
+    }
     // Issue tokens
     return issueTokens({
         userId: authCode.userId,
@@ -133,6 +201,49 @@ export async function exchangeAuthCode(params) {
         includeRefresh: true,
     });
 }
+// ─── Scope validation ─────────────────────────────────────
+/**
+ * Validate requested scopes against two gates and throw `invalid_scope` per
+ * RFC 6749 §3.3 if any requested scope fails either:
+ *
+ *   1. **Global registry** — declared via `Passport.tokensCan({...})`.
+ *      Rejects scopes the operator hasn't acknowledged exist.
+ *   2. **Per-client allow-list** — `client.scopes`. Rejects scopes outside
+ *      the operator-configured subset for this specific client.
+ *
+ * Each gate is **only enforced when populated**:
+ *   - Empty global registry → no global gate (treated as "scopes not yet
+ *     declared"). Matches Laravel Passport's "no scopes defined → permissive"
+ *     default; existing apps that haven't called `tokensCan()` won't break.
+ *   - Empty `client.scopes` → no per-client gate ("client may request any
+ *     globally-known scope"). The vast majority of clients leave this empty.
+ *
+ * Used by the auth-code, device-code, and client-credentials grants. Refresh
+ * token already has its own narrowing logic (can only narrow vs. the original
+ * issuance, never widen) and skips this helper.
+ *
+ * The `*` wildcard is always allowed — same convention as `Passport.validScopes()`.
+ */
+export function validateScopes(client, requested) {
+    if (requested.length === 0)
+        return;
+    const registered = Passport.scopes();
+    if (registered.length > 0) {
+        const validIds = new Set(registered.map(s => s.id));
+        const unknown = requested.filter(s => s !== '*' && !validIds.has(s));
+        if (unknown.length > 0) {
+            throw new OAuthError('invalid_scope', `The requested scope is invalid, unknown, or malformed: ${unknown.join(' ')}.`);
+        }
+    }
+    const clientScopes = clientHelpers.getScopes(client);
+    if (clientScopes.length > 0) {
+        const allow = new Set(clientScopes);
+        const denied = requested.filter(s => s !== '*' && !allow.has(s));
+        if (denied.length > 0) {
+            throw new OAuthError('invalid_scope', `The requested scope is not authorized for this client: ${denied.join(' ')}.`);
+        }
+    }
+}
 // ─── OAuth Error ──────────────────────────────────────────
 export class OAuthError extends Error {
     error;