@productcraft/auth-passport 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ProductCraft
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,44 @@
+# @productcraft/auth-passport
+
+Passport-JWT adapter for [`@productcraft/auth`](../auth). Plug an Auth `ConsumerScope` into a `passport-jwt` Strategy so existing Passport setups can authenticate Auth-issued tokens.
+
+```bash
+npm install @productcraft/auth @productcraft/auth-passport passport-jwt
+```
+
+## Usage
+
+```ts
+import passportJwt from "passport-jwt";
+import { Auth } from "@productcraft/auth";
+import { createPassportSecretOrKeyProvider } from "@productcraft/auth-passport";
+
+const auth = new Auth({
+  auth: { type: "apiKey", key: process.env.PCFT_KEY! },
+});
+const scope = auth.consumer("my-app-slug");
+
+new passportJwt.Strategy(
+  {
+    jwtFromRequest: passportJwt.ExtractJwt.fromAuthHeaderAsBearerToken(),
+    secretOrKeyProvider: createPassportSecretOrKeyProvider(scope),
+    issuer: scope.expectedIssuer,
+    audience: "my-app", // optional
+    algorithms: ["ES256"],
+  },
+  (payload, done) => {
+    // payload is the verified Auth claims object (sub, role, permissions, ...)
+    return done(null, payload);
+  },
+);
+```
+
+The helper decodes the JWT header, asks the Auth `ConsumerScope` for the matching signing key via its cached JWKS, converts the resulting `CryptoKey` into a Node `KeyObject`, and hands it to passport-jwt.
+
+## How it relates to the main package
+
+`@productcraft/auth` already ships a `scope.verifyToken(token)` one-liner. Use **this** package only when you have an existing Passport setup you'd rather keep. For Express middleware without Passport, the direct verify is simpler.
+
+## License
+
+[MIT](../../LICENSE).

package/dist/index.cjs

@@ -0,0 +1,66 @@
+'use strict';
+
+var crypto = require('crypto');
+var jose = require('jose');
+
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+function createPassportSecretOrKeyProvider(scope) {
+  return (_request, rawJwt, done) => {
+    let header;
+    try {
+      header = jose.decodeProtectedHeader(rawJwt);
+    } catch (err) {
+      done(err);
+      return;
+    }
+    scope.jwks.getKey(header).then(
+      (cryptoKey) => {
+        try {
+          const keyObject = crypto.KeyObject.from(cryptoKey);
+          done(null, keyObject);
+        } catch (err) {
+          done(err);
+        }
+      },
+      (err) => done(err)
+    );
+  };
+}
+function loadPassportJwt() {
+  try {
+    const mod = __require("passport-jwt");
+    return {
+      Strategy: mod.Strategy ?? mod.default?.Strategy,
+      ExtractJwt: mod.ExtractJwt ?? mod.default?.ExtractJwt
+    };
+  } catch {
+    throw new Error(
+      "@productcraft/auth-passport: `passport-jwt` is not installed. Run `npm install passport-jwt @types/passport-jwt`."
+    );
+  }
+}
+function createAuthJwtStrategy(scope, verify, options = {}) {
+  const passportJwt = loadPassportJwt();
+  const issuer = options.strictIssuer ? scope.expectedIssuer : scope.acceptedIssuers;
+  return new passportJwt.Strategy(
+    {
+      jwtFromRequest: options.jwtFromRequest ?? passportJwt.ExtractJwt.fromAuthHeaderAsBearerToken(),
+      secretOrKeyProvider: createPassportSecretOrKeyProvider(scope),
+      issuer,
+      audience: scope.expectedAudience,
+      algorithms: options.algorithms ?? ["RS256"],
+      passReqToCallback: options.passReqToCallback ?? false
+    },
+    verify
+  );
+}
+
+exports.createAuthJwtStrategy = createAuthJwtStrategy;
+exports.createPassportSecretOrKeyProvider = createPassportSecretOrKeyProvider;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["decodeProtectedHeader","KeyObject"],"mappings":";;;;;;;;;;;AAsEO,SAAS,kCACd,KAAA,EAC6B;AAC7B,EAAA,OAAO,CAAC,QAAA,EAAU,MAAA,EAAQ,IAAA,KAAS;AACjC,IAAA,IAAI,MAAA;AACJ,IAAA,IAAI;AACF,MAAA,MAAA,GAASA,2BAAsB,MAAM,CAAA;AAAA,IACvC,SAAS,GAAA,EAAK;AACZ,MAAA,IAAA,CAAK,GAAG,CAAA;AACR,MAAA;AAAA,IACF;AAEA,IAAA,KAAA,CAAM,IAAA,CAAK,MAAA,CAAO,MAA6B,CAAA,CAAE,IAAA;AAAA,MAC/C,CAAC,SAAA,KAAc;AACb,QAAA,IAAI;AAKF,UAAA,MAAM,SAAA,GAAYC,gBAAA,CAAU,IAAA,CAAK,SAAS,CAAA;AAC1C,UAAA,IAAA,CAAK,MAAM,SAAS,CAAA;AAAA,QACtB,SAAS,GAAA,EAAK;AACZ,UAAA,IAAA,CAAK,GAAG,CAAA;AAAA,QACV;AAAA,MACF,CAAA;AAAA,MACA,CAAC,GAAA,KAAQ,IAAA,CAAK,GAAG;AAAA,KACnB;AAAA,EACF,CAAA;AACF;AA+DA,SAAS,eAAA,GAGP;AACA,EAAA,IAAI;AAEF,IAAA,MAAM,GAAA,GAAM,UAAQ,cAAc,CAAA;AAClC,IAAA,OAAO;AAAA,MACL,QAAA,EAAU,GAAA,CAAI,QAAA,IAAY,GAAA,CAAI,OAAA,EAAS,QAAA;AAAA,MACvC,UAAA,EAAY,GAAA,CAAI,UAAA,IAAc,GAAA,CAAI,OAAA,EAAS;AAAA,KAC7C;AAAA,EACF,CAAA,CAAA,MAAQ;AACN,IAAA,MAAM,IAAI,KAAA;AAAA,MACR;AAAA,KACF;AAAA,EACF;AACF;AAeO,SAAS,qBAAA,CACd,KAAA,EACA,MAAA,EACA,OAAA,GAAwC,EAAC,EACzC;AACA,EAAA,MAAM,cAAc,eAAA,EAAgB;AACpC,EAAA,MAAM,MAAA,GAAS,OAAA,CAAQ,YAAA,GACnB,KAAA,CAAM,iBACL,KAAA,CAAM,eAAA;AAEX,EAAA,OAAO,IAAI,WAAA,CAAY,QAAA;AAAA,IACrB;AAAA,MACE,cAAA,EACE,OAAA,CAAQ,cAAA,IAAkB,WAAA,CAAY,WAAW,2BAAA,EAA4B;AAAA,MAC/E,mBAAA,EAAqB,kCAAkC,KAAK,CAAA;AAAA,MAC5D,MAAA;AAAA,MACA,UAAU,KAAA,CAAM,gBAAA;AAAA,MAChB,UAAA,EAAY,OAAA,CAAQ,UAAA,IAAc,CAAC,OAAO,CAAA;AAAA,MAC1C,iBAAA,EAAmB,QAAQ,iBAAA,IAAqB;AAAA,KAClD;AAAA,IACA;AAAA,GACF;AACF","file":"index.cjs","sourcesContent":["/**\n * `@productcraft/auth-passport` — passport-jwt adapter for Auth.\n *\n * Install alongside `@productcraft/auth` + `passport-jwt`:\n *\n * ```bash\n * npm install @productcraft/auth @productcraft/auth-passport passport-jwt\n * ```\n *\n * Recommended one-call form:\n *\n * ```ts\n * import passportJwt from \"passport-jwt\";\n * import passport from \"passport\";\n * import { Auth } from \"@productcraft/auth\";\n * import { createAuthJwtStrategy } from \"@productcraft/auth-passport\";\n *\n * const auth = new Auth({ auth: { type: \"apiKey\", key: process.env.PCFT_KEY! } });\n * const scope = auth.consumer(\"my-app-slug\");\n *\n * passport.use(createAuthJwtStrategy(scope, (claims, done) => {\n *   // claims is the verified Auth claims object (sub, role, permissions, ...)\n *   return done(null, claims);\n * }));\n * ```\n *\n * The helper wires `secretOrKeyProvider` + `issuer` (per-app URL) +\n * `audience` (app slug) + algorithms automatically from the scope.\n *\n * If you need the underlying primitives — to compose with your own\n * options or pass a custom `jwtFromRequest` — use the lower-level\n * `createPassportSecretOrKeyProvider` directly:\n *\n * ```ts\n * new passportJwt.Strategy(\n *   {\n *     jwtFromRequest: passportJwt.ExtractJwt.fromAuthHeaderAsBearerToken(),\n *     secretOrKeyProvider: createPassportSecretOrKeyProvider(scope),\n *     issuer: scope.acceptedIssuers as string[],\n *     audience: scope.expectedAudience,\n *     algorithms: [\"RS256\", \"ES256\"],\n *   },\n *   (payload, done) => done(null, payload),\n * );\n * ```\n */\n\nimport { KeyObject } from \"node:crypto\";\nimport { decodeProtectedHeader, type JWTHeaderParameters } from \"jose\";\n\nimport type { ConsumerScope } from \"@productcraft/auth\";\n\n/**\n * passport-jwt's `secretOrKeyProvider` callback signature. We don't\n * depend on passport-jwt's types directly (to keep it a soft dep),\n * so this is the same shape as `SecretOrKeyProvider` in their typings.\n */\ntype PassportSecretOrKeyProvider = (\n  request: unknown,\n  rawJwtToken: string,\n  done: (err: unknown, secretOrKey?: string | Buffer | KeyObject) => void,\n) => void;\n\n/**\n * Returns a passport-jwt `secretOrKeyProvider` bound to an Auth\n * `ConsumerScope`. Decodes the protected header, looks up the matching\n * key via the scope's JWKS cache, and converts the resulting jose\n * `CryptoKey` into a Node `KeyObject` that `jsonwebtoken` (the library\n * passport-jwt delegates to) accepts.\n */\nexport function createPassportSecretOrKeyProvider(\n  scope: ConsumerScope,\n): PassportSecretOrKeyProvider {\n  return (_request, rawJwt, done) => {\n    let header;\n    try {\n      header = decodeProtectedHeader(rawJwt);\n    } catch (err) {\n      done(err);\n      return;\n    }\n\n    scope.jwks.getKey(header as JWTHeaderParameters).then(\n      (cryptoKey) => {\n        try {\n          // `jsonwebtoken` (passport-jwt's verifier) doesn't accept\n          // Web Crypto `CryptoKey`, but it does accept Node's\n          // `KeyObject`. `KeyObject.from(cryptoKey)` was added in\n          // Node 16.6 and is the right adapter.\n          const keyObject = KeyObject.from(cryptoKey);\n          done(null, keyObject);\n        } catch (err) {\n          done(err);\n        }\n      },\n      (err) => done(err),\n    );\n  };\n}\n\n/**\n * Shape of the verified-claims callback passport delegates to once a\n * token passes signature + issuer + audience + expiry checks. Mirrors\n * `passport-jwt`'s own `VerifyCallback` / `VerifyCallbackWithRequest`.\n */\nexport type AuthVerifyCallback = (\n  payload: Record<string, unknown>,\n  done: (err: unknown, user?: unknown, info?: unknown) => void,\n) => void;\n\n/**\n * Extra options for `createAuthJwtStrategy`. Defaults are the\n * Auth-recommended values; override here if you need a different\n * token source (cookie, custom header, ...), a stricter algorithm\n * allow-list, or want to skip the legacy-issuer acceptance window.\n */\nexport interface CreateAuthJwtStrategyOptions {\n  /**\n   * Where to read the bearer from. Defaults to\n   * `ExtractJwt.fromAuthHeaderAsBearerToken()`. Pass any\n   * passport-jwt extractor when you need a different source.\n   */\n  jwtFromRequest?: (req: unknown) => string | null;\n\n  /**\n   * JWS algorithms accepted by the underlying verifier. Defaults to\n   * the algorithms Auth mints today (`['RS256']`); set explicitly\n   * if your app is on a different signing alg or you also accept\n   * customer-minted tokens with a different alg.\n   */\n  algorithms?: string[];\n\n  /**\n   * Pin only the per-app issuer URL (skip the legacy `'heimdall'`\n   * literal). Defaults to `false` — verifying both keeps in-flight\n   * tokens minted before the per-app-issuer migration valid. Set to\n   * `true` once you're confident all old tokens have expired.\n   */\n  strictIssuer?: boolean;\n\n  /** Whether the request object should be passed to the verify callback. Defaults to `false`. */\n  passReqToCallback?: boolean;\n}\n\n/**\n * Constructor signature for `passport-jwt`'s `Strategy`. We don't take\n * a direct dep on passport-jwt to keep it a peer/soft dep — at runtime\n * the caller imports passportJwt and the helper does\n * `new passportJwt.Strategy(...)` via the constructor reference.\n */\nexport interface PassportJwtStrategyCtor {\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  new (options: Record<string, unknown>, verify: AuthVerifyCallback): any;\n}\n\n/**\n * Lazy passport-jwt loader. We try to `require('passport-jwt')` from\n * the caller's dep graph at first use. Throws a clear error if it's\n * missing so the user doesn't see a cryptic `Cannot find module`\n * deep in the strategy constructor.\n */\nfunction loadPassportJwt(): {\n  Strategy: PassportJwtStrategyCtor;\n  ExtractJwt: { fromAuthHeaderAsBearerToken: () => (req: unknown) => string | null };\n} {\n  try {\n    // dynamic require so passport-jwt stays a peer dep\n    const mod = require(\"passport-jwt\");\n    return {\n      Strategy: mod.Strategy ?? mod.default?.Strategy,\n      ExtractJwt: mod.ExtractJwt ?? mod.default?.ExtractJwt,\n    };\n  } catch {\n    throw new Error(\n      \"@productcraft/auth-passport: `passport-jwt` is not installed. Run `npm install passport-jwt @types/passport-jwt`.\",\n    );\n  }\n}\n\n/**\n * Build a fully-configured `passport-jwt` strategy from an Auth\n * `ConsumerScope`. Wires:\n *\n *   - `jwtFromRequest`     → `ExtractJwt.fromAuthHeaderAsBearerToken()` (override via opts)\n *   - `secretOrKeyProvider` → JWKS-backed key resolution via `scope.jwks`\n *   - `issuer`             → both `scope.expectedIssuer` AND the legacy `'heimdall'` literal (or only the per-app URL if `strictIssuer: true`)\n *   - `audience`           → `scope.expectedAudience` (the app slug)\n *   - `algorithms`         → `['RS256']` (override via opts)\n *\n * The verify callback you pass receives the parsed claims after\n * passport-jwt has finished its checks.\n */\nexport function createAuthJwtStrategy(\n  scope: ConsumerScope,\n  verify: AuthVerifyCallback,\n  options: CreateAuthJwtStrategyOptions = {},\n) {\n  const passportJwt = loadPassportJwt();\n  const issuer = options.strictIssuer\n    ? scope.expectedIssuer\n    : (scope.acceptedIssuers as string[]);\n\n  return new passportJwt.Strategy(\n    {\n      jwtFromRequest:\n        options.jwtFromRequest ?? passportJwt.ExtractJwt.fromAuthHeaderAsBearerToken(),\n      secretOrKeyProvider: createPassportSecretOrKeyProvider(scope),\n      issuer,\n      audience: scope.expectedAudience,\n      algorithms: options.algorithms ?? [\"RS256\"],\n      passReqToCallback: options.passReqToCallback ?? false,\n    },\n    verify,\n  );\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,125 @@
+import { KeyObject } from 'node:crypto';
+import { ConsumerScope } from '@productcraft/auth';
+
+/**
+ * `@productcraft/auth-passport` — passport-jwt adapter for Auth.
+ *
+ * Install alongside `@productcraft/auth` + `passport-jwt`:
+ *
+ * ```bash
+ * npm install @productcraft/auth @productcraft/auth-passport passport-jwt
+ * ```
+ *
+ * Recommended one-call form:
+ *
+ * ```ts
+ * import passportJwt from "passport-jwt";
+ * import passport from "passport";
+ * import { Auth } from "@productcraft/auth";
+ * import { createAuthJwtStrategy } from "@productcraft/auth-passport";
+ *
+ * const auth = new Auth({ auth: { type: "apiKey", key: process.env.PCFT_KEY! } });
+ * const scope = auth.consumer("my-app-slug");
+ *
+ * passport.use(createAuthJwtStrategy(scope, (claims, done) => {
+ *   // claims is the verified Auth claims object (sub, role, permissions, ...)
+ *   return done(null, claims);
+ * }));
+ * ```
+ *
+ * The helper wires `secretOrKeyProvider` + `issuer` (per-app URL) +
+ * `audience` (app slug) + algorithms automatically from the scope.
+ *
+ * If you need the underlying primitives — to compose with your own
+ * options or pass a custom `jwtFromRequest` — use the lower-level
+ * `createPassportSecretOrKeyProvider` directly:
+ *
+ * ```ts
+ * new passportJwt.Strategy(
+ *   {
+ *     jwtFromRequest: passportJwt.ExtractJwt.fromAuthHeaderAsBearerToken(),
+ *     secretOrKeyProvider: createPassportSecretOrKeyProvider(scope),
+ *     issuer: scope.acceptedIssuers as string[],
+ *     audience: scope.expectedAudience,
+ *     algorithms: ["RS256", "ES256"],
+ *   },
+ *   (payload, done) => done(null, payload),
+ * );
+ * ```
+ */
+
+/**
+ * passport-jwt's `secretOrKeyProvider` callback signature. We don't
+ * depend on passport-jwt's types directly (to keep it a soft dep),
+ * so this is the same shape as `SecretOrKeyProvider` in their typings.
+ */
+type PassportSecretOrKeyProvider = (request: unknown, rawJwtToken: string, done: (err: unknown, secretOrKey?: string | Buffer | KeyObject) => void) => void;
+/**
+ * Returns a passport-jwt `secretOrKeyProvider` bound to an Auth
+ * `ConsumerScope`. Decodes the protected header, looks up the matching
+ * key via the scope's JWKS cache, and converts the resulting jose
+ * `CryptoKey` into a Node `KeyObject` that `jsonwebtoken` (the library
+ * passport-jwt delegates to) accepts.
+ */
+declare function createPassportSecretOrKeyProvider(scope: ConsumerScope): PassportSecretOrKeyProvider;
+/**
+ * Shape of the verified-claims callback passport delegates to once a
+ * token passes signature + issuer + audience + expiry checks. Mirrors
+ * `passport-jwt`'s own `VerifyCallback` / `VerifyCallbackWithRequest`.
+ */
+type AuthVerifyCallback = (payload: Record<string, unknown>, done: (err: unknown, user?: unknown, info?: unknown) => void) => void;
+/**
+ * Extra options for `createAuthJwtStrategy`. Defaults are the
+ * Auth-recommended values; override here if you need a different
+ * token source (cookie, custom header, ...), a stricter algorithm
+ * allow-list, or want to skip the legacy-issuer acceptance window.
+ */
+interface CreateAuthJwtStrategyOptions {
+    /**
+     * Where to read the bearer from. Defaults to
+     * `ExtractJwt.fromAuthHeaderAsBearerToken()`. Pass any
+     * passport-jwt extractor when you need a different source.
+     */
+    jwtFromRequest?: (req: unknown) => string | null;
+    /**
+     * JWS algorithms accepted by the underlying verifier. Defaults to
+     * the algorithms Auth mints today (`['RS256']`); set explicitly
+     * if your app is on a different signing alg or you also accept
+     * customer-minted tokens with a different alg.
+     */
+    algorithms?: string[];
+    /**
+     * Pin only the per-app issuer URL (skip the legacy `'heimdall'`
+     * literal). Defaults to `false` — verifying both keeps in-flight
+     * tokens minted before the per-app-issuer migration valid. Set to
+     * `true` once you're confident all old tokens have expired.
+     */
+    strictIssuer?: boolean;
+    /** Whether the request object should be passed to the verify callback. Defaults to `false`. */
+    passReqToCallback?: boolean;
+}
+/**
+ * Constructor signature for `passport-jwt`'s `Strategy`. We don't take
+ * a direct dep on passport-jwt to keep it a peer/soft dep — at runtime
+ * the caller imports passportJwt and the helper does
+ * `new passportJwt.Strategy(...)` via the constructor reference.
+ */
+interface PassportJwtStrategyCtor {
+    new (options: Record<string, unknown>, verify: AuthVerifyCallback): any;
+}
+/**
+ * Build a fully-configured `passport-jwt` strategy from an Auth
+ * `ConsumerScope`. Wires:
+ *
+ *   - `jwtFromRequest`     → `ExtractJwt.fromAuthHeaderAsBearerToken()` (override via opts)
+ *   - `secretOrKeyProvider` → JWKS-backed key resolution via `scope.jwks`
+ *   - `issuer`             → both `scope.expectedIssuer` AND the legacy `'heimdall'` literal (or only the per-app URL if `strictIssuer: true`)
+ *   - `audience`           → `scope.expectedAudience` (the app slug)
+ *   - `algorithms`         → `['RS256']` (override via opts)
+ *
+ * The verify callback you pass receives the parsed claims after
+ * passport-jwt has finished its checks.
+ */
+declare function createAuthJwtStrategy(scope: ConsumerScope, verify: AuthVerifyCallback, options?: CreateAuthJwtStrategyOptions): any;
+
+export { type AuthVerifyCallback, type CreateAuthJwtStrategyOptions, type PassportJwtStrategyCtor, createAuthJwtStrategy, createPassportSecretOrKeyProvider };

package/dist/index.d.ts

@@ -0,0 +1,125 @@
+import { KeyObject } from 'node:crypto';
+import { ConsumerScope } from '@productcraft/auth';
+
+/**
+ * `@productcraft/auth-passport` — passport-jwt adapter for Auth.
+ *
+ * Install alongside `@productcraft/auth` + `passport-jwt`:
+ *
+ * ```bash
+ * npm install @productcraft/auth @productcraft/auth-passport passport-jwt
+ * ```
+ *
+ * Recommended one-call form:
+ *
+ * ```ts
+ * import passportJwt from "passport-jwt";
+ * import passport from "passport";
+ * import { Auth } from "@productcraft/auth";
+ * import { createAuthJwtStrategy } from "@productcraft/auth-passport";
+ *
+ * const auth = new Auth({ auth: { type: "apiKey", key: process.env.PCFT_KEY! } });
+ * const scope = auth.consumer("my-app-slug");
+ *
+ * passport.use(createAuthJwtStrategy(scope, (claims, done) => {
+ *   // claims is the verified Auth claims object (sub, role, permissions, ...)
+ *   return done(null, claims);
+ * }));
+ * ```
+ *
+ * The helper wires `secretOrKeyProvider` + `issuer` (per-app URL) +
+ * `audience` (app slug) + algorithms automatically from the scope.
+ *
+ * If you need the underlying primitives — to compose with your own
+ * options or pass a custom `jwtFromRequest` — use the lower-level
+ * `createPassportSecretOrKeyProvider` directly:
+ *
+ * ```ts
+ * new passportJwt.Strategy(
+ *   {
+ *     jwtFromRequest: passportJwt.ExtractJwt.fromAuthHeaderAsBearerToken(),
+ *     secretOrKeyProvider: createPassportSecretOrKeyProvider(scope),
+ *     issuer: scope.acceptedIssuers as string[],
+ *     audience: scope.expectedAudience,
+ *     algorithms: ["RS256", "ES256"],
+ *   },
+ *   (payload, done) => done(null, payload),
+ * );
+ * ```
+ */
+
+/**
+ * passport-jwt's `secretOrKeyProvider` callback signature. We don't
+ * depend on passport-jwt's types directly (to keep it a soft dep),
+ * so this is the same shape as `SecretOrKeyProvider` in their typings.
+ */
+type PassportSecretOrKeyProvider = (request: unknown, rawJwtToken: string, done: (err: unknown, secretOrKey?: string | Buffer | KeyObject) => void) => void;
+/**
+ * Returns a passport-jwt `secretOrKeyProvider` bound to an Auth
+ * `ConsumerScope`. Decodes the protected header, looks up the matching
+ * key via the scope's JWKS cache, and converts the resulting jose
+ * `CryptoKey` into a Node `KeyObject` that `jsonwebtoken` (the library
+ * passport-jwt delegates to) accepts.
+ */
+declare function createPassportSecretOrKeyProvider(scope: ConsumerScope): PassportSecretOrKeyProvider;
+/**
+ * Shape of the verified-claims callback passport delegates to once a
+ * token passes signature + issuer + audience + expiry checks. Mirrors
+ * `passport-jwt`'s own `VerifyCallback` / `VerifyCallbackWithRequest`.
+ */
+type AuthVerifyCallback = (payload: Record<string, unknown>, done: (err: unknown, user?: unknown, info?: unknown) => void) => void;
+/**
+ * Extra options for `createAuthJwtStrategy`. Defaults are the
+ * Auth-recommended values; override here if you need a different
+ * token source (cookie, custom header, ...), a stricter algorithm
+ * allow-list, or want to skip the legacy-issuer acceptance window.
+ */
+interface CreateAuthJwtStrategyOptions {
+    /**
+     * Where to read the bearer from. Defaults to
+     * `ExtractJwt.fromAuthHeaderAsBearerToken()`. Pass any
+     * passport-jwt extractor when you need a different source.
+     */
+    jwtFromRequest?: (req: unknown) => string | null;
+    /**
+     * JWS algorithms accepted by the underlying verifier. Defaults to
+     * the algorithms Auth mints today (`['RS256']`); set explicitly
+     * if your app is on a different signing alg or you also accept
+     * customer-minted tokens with a different alg.
+     */
+    algorithms?: string[];
+    /**
+     * Pin only the per-app issuer URL (skip the legacy `'heimdall'`
+     * literal). Defaults to `false` — verifying both keeps in-flight
+     * tokens minted before the per-app-issuer migration valid. Set to
+     * `true` once you're confident all old tokens have expired.
+     */
+    strictIssuer?: boolean;
+    /** Whether the request object should be passed to the verify callback. Defaults to `false`. */
+    passReqToCallback?: boolean;
+}
+/**
+ * Constructor signature for `passport-jwt`'s `Strategy`. We don't take
+ * a direct dep on passport-jwt to keep it a peer/soft dep — at runtime
+ * the caller imports passportJwt and the helper does
+ * `new passportJwt.Strategy(...)` via the constructor reference.
+ */
+interface PassportJwtStrategyCtor {
+    new (options: Record<string, unknown>, verify: AuthVerifyCallback): any;
+}
+/**
+ * Build a fully-configured `passport-jwt` strategy from an Auth
+ * `ConsumerScope`. Wires:
+ *
+ *   - `jwtFromRequest`     → `ExtractJwt.fromAuthHeaderAsBearerToken()` (override via opts)
+ *   - `secretOrKeyProvider` → JWKS-backed key resolution via `scope.jwks`
+ *   - `issuer`             → both `scope.expectedIssuer` AND the legacy `'heimdall'` literal (or only the per-app URL if `strictIssuer: true`)
+ *   - `audience`           → `scope.expectedAudience` (the app slug)
+ *   - `algorithms`         → `['RS256']` (override via opts)
+ *
+ * The verify callback you pass receives the parsed claims after
+ * passport-jwt has finished its checks.
+ */
+declare function createAuthJwtStrategy(scope: ConsumerScope, verify: AuthVerifyCallback, options?: CreateAuthJwtStrategyOptions): any;
+
+export { type AuthVerifyCallback, type CreateAuthJwtStrategyOptions, type PassportJwtStrategyCtor, createAuthJwtStrategy, createPassportSecretOrKeyProvider };

package/dist/index.js

@@ -0,0 +1,63 @@
+import { KeyObject } from 'crypto';
+import { decodeProtectedHeader } from 'jose';
+
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+function createPassportSecretOrKeyProvider(scope) {
+  return (_request, rawJwt, done) => {
+    let header;
+    try {
+      header = decodeProtectedHeader(rawJwt);
+    } catch (err) {
+      done(err);
+      return;
+    }
+    scope.jwks.getKey(header).then(
+      (cryptoKey) => {
+        try {
+          const keyObject = KeyObject.from(cryptoKey);
+          done(null, keyObject);
+        } catch (err) {
+          done(err);
+        }
+      },
+      (err) => done(err)
+    );
+  };
+}
+function loadPassportJwt() {
+  try {
+    const mod = __require("passport-jwt");
+    return {
+      Strategy: mod.Strategy ?? mod.default?.Strategy,
+      ExtractJwt: mod.ExtractJwt ?? mod.default?.ExtractJwt
+    };
+  } catch {
+    throw new Error(
+      "@productcraft/auth-passport: `passport-jwt` is not installed. Run `npm install passport-jwt @types/passport-jwt`."
+    );
+  }
+}
+function createAuthJwtStrategy(scope, verify, options = {}) {
+  const passportJwt = loadPassportJwt();
+  const issuer = options.strictIssuer ? scope.expectedIssuer : scope.acceptedIssuers;
+  return new passportJwt.Strategy(
+    {
+      jwtFromRequest: options.jwtFromRequest ?? passportJwt.ExtractJwt.fromAuthHeaderAsBearerToken(),
+      secretOrKeyProvider: createPassportSecretOrKeyProvider(scope),
+      issuer,
+      audience: scope.expectedAudience,
+      algorithms: options.algorithms ?? ["RS256"],
+      passReqToCallback: options.passReqToCallback ?? false
+    },
+    verify
+  );
+}
+
+export { createAuthJwtStrategy, createPassportSecretOrKeyProvider };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;AAsEO,SAAS,kCACd,KAAA,EAC6B;AAC7B,EAAA,OAAO,CAAC,QAAA,EAAU,MAAA,EAAQ,IAAA,KAAS;AACjC,IAAA,IAAI,MAAA;AACJ,IAAA,IAAI;AACF,MAAA,MAAA,GAAS,sBAAsB,MAAM,CAAA;AAAA,IACvC,SAAS,GAAA,EAAK;AACZ,MAAA,IAAA,CAAK,GAAG,CAAA;AACR,MAAA;AAAA,IACF;AAEA,IAAA,KAAA,CAAM,IAAA,CAAK,MAAA,CAAO,MAA6B,CAAA,CAAE,IAAA;AAAA,MAC/C,CAAC,SAAA,KAAc;AACb,QAAA,IAAI;AAKF,UAAA,MAAM,SAAA,GAAY,SAAA,CAAU,IAAA,CAAK,SAAS,CAAA;AAC1C,UAAA,IAAA,CAAK,MAAM,SAAS,CAAA;AAAA,QACtB,SAAS,GAAA,EAAK;AACZ,UAAA,IAAA,CAAK,GAAG,CAAA;AAAA,QACV;AAAA,MACF,CAAA;AAAA,MACA,CAAC,GAAA,KAAQ,IAAA,CAAK,GAAG;AAAA,KACnB;AAAA,EACF,CAAA;AACF;AA+DA,SAAS,eAAA,GAGP;AACA,EAAA,IAAI;AAEF,IAAA,MAAM,GAAA,GAAM,UAAQ,cAAc,CAAA;AAClC,IAAA,OAAO;AAAA,MACL,QAAA,EAAU,GAAA,CAAI,QAAA,IAAY,GAAA,CAAI,OAAA,EAAS,QAAA;AAAA,MACvC,UAAA,EAAY,GAAA,CAAI,UAAA,IAAc,GAAA,CAAI,OAAA,EAAS;AAAA,KAC7C;AAAA,EACF,CAAA,CAAA,MAAQ;AACN,IAAA,MAAM,IAAI,KAAA;AAAA,MACR;AAAA,KACF;AAAA,EACF;AACF;AAeO,SAAS,qBAAA,CACd,KAAA,EACA,MAAA,EACA,OAAA,GAAwC,EAAC,EACzC;AACA,EAAA,MAAM,cAAc,eAAA,EAAgB;AACpC,EAAA,MAAM,MAAA,GAAS,OAAA,CAAQ,YAAA,GACnB,KAAA,CAAM,iBACL,KAAA,CAAM,eAAA;AAEX,EAAA,OAAO,IAAI,WAAA,CAAY,QAAA;AAAA,IACrB;AAAA,MACE,cAAA,EACE,OAAA,CAAQ,cAAA,IAAkB,WAAA,CAAY,WAAW,2BAAA,EAA4B;AAAA,MAC/E,mBAAA,EAAqB,kCAAkC,KAAK,CAAA;AAAA,MAC5D,MAAA;AAAA,MACA,UAAU,KAAA,CAAM,gBAAA;AAAA,MAChB,UAAA,EAAY,OAAA,CAAQ,UAAA,IAAc,CAAC,OAAO,CAAA;AAAA,MAC1C,iBAAA,EAAmB,QAAQ,iBAAA,IAAqB;AAAA,KAClD;AAAA,IACA;AAAA,GACF;AACF","file":"index.js","sourcesContent":["/**\n * `@productcraft/auth-passport` — passport-jwt adapter for Auth.\n *\n * Install alongside `@productcraft/auth` + `passport-jwt`:\n *\n * ```bash\n * npm install @productcraft/auth @productcraft/auth-passport passport-jwt\n * ```\n *\n * Recommended one-call form:\n *\n * ```ts\n * import passportJwt from \"passport-jwt\";\n * import passport from \"passport\";\n * import { Auth } from \"@productcraft/auth\";\n * import { createAuthJwtStrategy } from \"@productcraft/auth-passport\";\n *\n * const auth = new Auth({ auth: { type: \"apiKey\", key: process.env.PCFT_KEY! } });\n * const scope = auth.consumer(\"my-app-slug\");\n *\n * passport.use(createAuthJwtStrategy(scope, (claims, done) => {\n *   // claims is the verified Auth claims object (sub, role, permissions, ...)\n *   return done(null, claims);\n * }));\n * ```\n *\n * The helper wires `secretOrKeyProvider` + `issuer` (per-app URL) +\n * `audience` (app slug) + algorithms automatically from the scope.\n *\n * If you need the underlying primitives — to compose with your own\n * options or pass a custom `jwtFromRequest` — use the lower-level\n * `createPassportSecretOrKeyProvider` directly:\n *\n * ```ts\n * new passportJwt.Strategy(\n *   {\n *     jwtFromRequest: passportJwt.ExtractJwt.fromAuthHeaderAsBearerToken(),\n *     secretOrKeyProvider: createPassportSecretOrKeyProvider(scope),\n *     issuer: scope.acceptedIssuers as string[],\n *     audience: scope.expectedAudience,\n *     algorithms: [\"RS256\", \"ES256\"],\n *   },\n *   (payload, done) => done(null, payload),\n * );\n * ```\n */\n\nimport { KeyObject } from \"node:crypto\";\nimport { decodeProtectedHeader, type JWTHeaderParameters } from \"jose\";\n\nimport type { ConsumerScope } from \"@productcraft/auth\";\n\n/**\n * passport-jwt's `secretOrKeyProvider` callback signature. We don't\n * depend on passport-jwt's types directly (to keep it a soft dep),\n * so this is the same shape as `SecretOrKeyProvider` in their typings.\n */\ntype PassportSecretOrKeyProvider = (\n  request: unknown,\n  rawJwtToken: string,\n  done: (err: unknown, secretOrKey?: string | Buffer | KeyObject) => void,\n) => void;\n\n/**\n * Returns a passport-jwt `secretOrKeyProvider` bound to an Auth\n * `ConsumerScope`. Decodes the protected header, looks up the matching\n * key via the scope's JWKS cache, and converts the resulting jose\n * `CryptoKey` into a Node `KeyObject` that `jsonwebtoken` (the library\n * passport-jwt delegates to) accepts.\n */\nexport function createPassportSecretOrKeyProvider(\n  scope: ConsumerScope,\n): PassportSecretOrKeyProvider {\n  return (_request, rawJwt, done) => {\n    let header;\n    try {\n      header = decodeProtectedHeader(rawJwt);\n    } catch (err) {\n      done(err);\n      return;\n    }\n\n    scope.jwks.getKey(header as JWTHeaderParameters).then(\n      (cryptoKey) => {\n        try {\n          // `jsonwebtoken` (passport-jwt's verifier) doesn't accept\n          // Web Crypto `CryptoKey`, but it does accept Node's\n          // `KeyObject`. `KeyObject.from(cryptoKey)` was added in\n          // Node 16.6 and is the right adapter.\n          const keyObject = KeyObject.from(cryptoKey);\n          done(null, keyObject);\n        } catch (err) {\n          done(err);\n        }\n      },\n      (err) => done(err),\n    );\n  };\n}\n\n/**\n * Shape of the verified-claims callback passport delegates to once a\n * token passes signature + issuer + audience + expiry checks. Mirrors\n * `passport-jwt`'s own `VerifyCallback` / `VerifyCallbackWithRequest`.\n */\nexport type AuthVerifyCallback = (\n  payload: Record<string, unknown>,\n  done: (err: unknown, user?: unknown, info?: unknown) => void,\n) => void;\n\n/**\n * Extra options for `createAuthJwtStrategy`. Defaults are the\n * Auth-recommended values; override here if you need a different\n * token source (cookie, custom header, ...), a stricter algorithm\n * allow-list, or want to skip the legacy-issuer acceptance window.\n */\nexport interface CreateAuthJwtStrategyOptions {\n  /**\n   * Where to read the bearer from. Defaults to\n   * `ExtractJwt.fromAuthHeaderAsBearerToken()`. Pass any\n   * passport-jwt extractor when you need a different source.\n   */\n  jwtFromRequest?: (req: unknown) => string | null;\n\n  /**\n   * JWS algorithms accepted by the underlying verifier. Defaults to\n   * the algorithms Auth mints today (`['RS256']`); set explicitly\n   * if your app is on a different signing alg or you also accept\n   * customer-minted tokens with a different alg.\n   */\n  algorithms?: string[];\n\n  /**\n   * Pin only the per-app issuer URL (skip the legacy `'heimdall'`\n   * literal). Defaults to `false` — verifying both keeps in-flight\n   * tokens minted before the per-app-issuer migration valid. Set to\n   * `true` once you're confident all old tokens have expired.\n   */\n  strictIssuer?: boolean;\n\n  /** Whether the request object should be passed to the verify callback. Defaults to `false`. */\n  passReqToCallback?: boolean;\n}\n\n/**\n * Constructor signature for `passport-jwt`'s `Strategy`. We don't take\n * a direct dep on passport-jwt to keep it a peer/soft dep — at runtime\n * the caller imports passportJwt and the helper does\n * `new passportJwt.Strategy(...)` via the constructor reference.\n */\nexport interface PassportJwtStrategyCtor {\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  new (options: Record<string, unknown>, verify: AuthVerifyCallback): any;\n}\n\n/**\n * Lazy passport-jwt loader. We try to `require('passport-jwt')` from\n * the caller's dep graph at first use. Throws a clear error if it's\n * missing so the user doesn't see a cryptic `Cannot find module`\n * deep in the strategy constructor.\n */\nfunction loadPassportJwt(): {\n  Strategy: PassportJwtStrategyCtor;\n  ExtractJwt: { fromAuthHeaderAsBearerToken: () => (req: unknown) => string | null };\n} {\n  try {\n    // dynamic require so passport-jwt stays a peer dep\n    const mod = require(\"passport-jwt\");\n    return {\n      Strategy: mod.Strategy ?? mod.default?.Strategy,\n      ExtractJwt: mod.ExtractJwt ?? mod.default?.ExtractJwt,\n    };\n  } catch {\n    throw new Error(\n      \"@productcraft/auth-passport: `passport-jwt` is not installed. Run `npm install passport-jwt @types/passport-jwt`.\",\n    );\n  }\n}\n\n/**\n * Build a fully-configured `passport-jwt` strategy from an Auth\n * `ConsumerScope`. Wires:\n *\n *   - `jwtFromRequest`     → `ExtractJwt.fromAuthHeaderAsBearerToken()` (override via opts)\n *   - `secretOrKeyProvider` → JWKS-backed key resolution via `scope.jwks`\n *   - `issuer`             → both `scope.expectedIssuer` AND the legacy `'heimdall'` literal (or only the per-app URL if `strictIssuer: true`)\n *   - `audience`           → `scope.expectedAudience` (the app slug)\n *   - `algorithms`         → `['RS256']` (override via opts)\n *\n * The verify callback you pass receives the parsed claims after\n * passport-jwt has finished its checks.\n */\nexport function createAuthJwtStrategy(\n  scope: ConsumerScope,\n  verify: AuthVerifyCallback,\n  options: CreateAuthJwtStrategyOptions = {},\n) {\n  const passportJwt = loadPassportJwt();\n  const issuer = options.strictIssuer\n    ? scope.expectedIssuer\n    : (scope.acceptedIssuers as string[]);\n\n  return new passportJwt.Strategy(\n    {\n      jwtFromRequest:\n        options.jwtFromRequest ?? passportJwt.ExtractJwt.fromAuthHeaderAsBearerToken(),\n      secretOrKeyProvider: createPassportSecretOrKeyProvider(scope),\n      issuer,\n      audience: scope.expectedAudience,\n      algorithms: options.algorithms ?? [\"RS256\"],\n      passReqToCallback: options.passReqToCallback ?? false,\n    },\n    verify,\n  );\n}\n"]}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@productcraft/auth-passport",
+  "version": "0.2.0",
+  "description": "Passport-JWT adapter for ProductCraft Auth. Plug an Auth ConsumerScope into a `passport-jwt` Strategy so existing Passport setups can authenticate Auth-issued tokens.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist/**",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "productcraft",
+    "sdk",
+    "auth",
+    "passport",
+    "passport-jwt",
+    "jwt"
+  ],
+  "author": "ProductCraft",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/clauderanelagh/productcraft-node.git",
+    "directory": "packages/auth-passport"
+  },
+  "homepage": "https://github.com/clauderanelagh/productcraft-node/tree/main/packages/auth-passport",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "jose": "^6.2.3",
+    "@productcraft/auth": "^0.5.0"
+  },
+  "peerDependencies": {
+    "passport-jwt": "^4.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run"
+  }
+}