@productcraft/heimdall 0.1.0 → 0.2.0

package/README.md

@@ -206,11 +206,12 @@ import { jwtVerify } from "jose";
 
 const scope = heimdall.consumer("my-app-slug");
 const { payload } = await jwtVerify(token, scope.jwks.getKey, {
-  issuer: scope.expectedIssuer,
-  audience: "my-app",
+  issuer: scope.expectedIssuer, // the literal string "heimdall"
 });
 ```
 
+Heimdall Consumer-API tokens are not minted with an `aud` claim — the per-app boundary is enforced by the JWKS, not the issuer string or the audience. If you mint custom tokens with the heimdall key and want to enforce an audience, pass `audience` to `jose.jwtVerify` or `scope.verifyToken(token, { audience: "..." })` per-call.
+
 ### Passport integration
 
 Use the companion package [`@productcraft/heimdall-passport`](../heimdall-passport):
@@ -263,8 +264,6 @@ new Heimdall({
   baseUrl: "https://api.heimdall.example.test",
   // Custom fetch (undici with retry, mock in tests, ...)
   fetch: customFetch,
-  // Expected JWT `aud` claim for `consumer(slug).verifyToken(...)`. Optional.
-  expectedAudience: "my-app",
   // JWKS cache TTL — default 10 minutes
   jwksTtlMs: 10 * 60 * 1000,
 });

package/dist/index.cjs

@@ -1416,7 +1416,8 @@ function getConsumerVerifyControllerVerifyUrl({
 }
 async function consumerVerifyControllerVerify({
   appSlug,
-  data
+  data,
+  headers
 }, config = {}) {
   const { client: request = client, ...requestConfig } = config;
   const requestData = data;
@@ -1424,7 +1425,8 @@ async function consumerVerifyControllerVerify({
     method: "POST",
     url: getConsumerVerifyControllerVerifyUrl({ appSlug }).url.toString(),
     data: requestData,
-    ...requestConfig
+    ...requestConfig,
+    headers: { ...headers, ...requestConfig.headers }
   });
   return res.data;
 }
@@ -1439,7 +1441,8 @@ function getConsumerVerifyControllerAuthorizeUrl({
 }
 async function consumerVerifyControllerAuthorize({
   appSlug,
-  data
+  data,
+  headers
 }, config = {}) {
   const { client: request = client, ...requestConfig } = config;
   const requestData = data;
@@ -1447,7 +1450,8 @@ async function consumerVerifyControllerAuthorize({
     method: "POST",
     url: getConsumerVerifyControllerAuthorizeUrl({ appSlug }).url.toString(),
     data: requestData,
-    ...requestConfig
+    ...requestConfig,
+    headers: { ...headers, ...requestConfig.headers }
   });
   return res.data;
 }
@@ -1465,7 +1469,8 @@ function getConsumerVerifyControllerAuthorizeBatchUrl({
 }
 async function consumerVerifyControllerAuthorizeBatch({
   appSlug,
-  data
+  data,
+  headers
 }, config = {}) {
   const { client: request = client, ...requestConfig } = config;
   const requestData = data;
@@ -1475,7 +1480,8 @@ async function consumerVerifyControllerAuthorizeBatch({
       appSlug
     }).url.toString(),
     data: requestData,
-    ...requestConfig
+    ...requestConfig,
+    headers: { ...headers, ...requestConfig.headers }
   });
   return res.data;
 }
@@ -1656,21 +1662,49 @@ function translateJoseError(err) {
 }
 
 // src/scopes/consumer.ts
+var HEIMDALL_LEGACY_ISSUER = "heimdall";
 var ConsumerScope = class {
   /** The appSlug bound to this scope. */
   appSlug;
-  /** Default iss claim expected on tokens issued by this app's Heimdall instance. */
+  /**
+   * Issuer the Heimdall Consumer API stamps on every token for this
+   * app — the public Heimdall API base joined with the app slug
+   * (e.g. `https://api.heimdall.productcraft.co/acme`). Pin it in
+   * your local verifier so a token minted for another app on the
+   * platform cannot pass.
+   *
+   * `scope.verifyToken` already enforces this for you. Pass it as a
+   * second-position issuer if you're wiring `jose.jwtVerify`,
+   * `passport-jwt`, or PyJWT yourself.
+   */
   expectedIssuer;
-  /** Default aud claim. Undefined unless the caller sets it (skip aud check). */
+  /**
+   * Audience the Consumer API stamps on every token for this app —
+   * literally the app slug (e.g. `"acme"`). Pin it in your verifier
+   * the same way as `expectedIssuer`. `scope.verifyToken` enforces
+   * it by default.
+   */
   expectedAudience;
+  /**
+   * Both accepted issuer strings (`expectedIssuer` + the legacy
+   * `'heimdall'` literal). `verifyToken` passes this to jose so tokens
+   * minted before the 2026-05-24 per-app-issuer migration keep
+   * verifying alongside fresh ones — useful for the ~1-hour transition
+   * window per access-token TTL, and the longer session TTL on
+   * refresh tokens.
+   */
+  acceptedIssuers;
   /** jose-compatible JWKS resolver. Drop into `jose.jwtVerify`, passport-jwt, etc. */
   jwks;
   client;
   constructor(appSlug, internals, opts = {}) {
     this.appSlug = appSlug;
     this.client = internals.client;
-    this.expectedIssuer = `${internals.baseUrl}/${appSlug}`;
-    this.expectedAudience = opts.audience;
+    const apiOrigin = new URL(internals.baseUrl);
+    apiOrigin.pathname = `/${appSlug}`;
+    this.expectedIssuer = apiOrigin.toString().replace(/\/$/, "");
+    this.expectedAudience = appSlug;
+    this.acceptedIssuers = [this.expectedIssuer, HEIMDALL_LEGACY_ISSUER];
     this.jwks = new JwksCache({
       url: new URL(`/${appSlug}/v1/.well-known/jwks.json`, internals.baseUrl),
       ttlMs: opts.jwksTtlMs,
@@ -1686,10 +1720,20 @@ var ConsumerScope = class {
     const res = await this.client({ method, url, data: body, params });
     return res.data;
   }
-  /** Verify a Heimdall-issued JWT against this app's JWKS. */
+  /**
+   * Verify a Heimdall-issued JWT against this app's JWKS.
+   *
+   * Checks the signature, expiry, `iss`, and `aud`. Accepts both the
+   * per-app issuer URL (`expectedIssuer`) and the legacy `'heimdall'`
+   * literal during the issuer-migration transition window — callers
+   * who want to refuse legacy tokens can override with
+   * `{ issuer: scope.expectedIssuer }`. Audience defaults to the app
+   * slug (`expectedAudience`); pass `{ audience: false }` (in an
+   * options override) to skip the audience check entirely.
+   */
   verifyToken(token, opts = {}) {
     return verifyHeimdallToken(token, this.jwks.getKey, {
-      issuer: this.expectedIssuer,
+      issuer: this.acceptedIssuers,
       audience: this.expectedAudience,
       ...opts
     });
@@ -1802,16 +1846,23 @@ var ConsumerScope = class {
   // (typically called by the customer's backend, not the user agent)
   // ─────────────────────────────────────────────────────────────
   verify = {
+    /**
+     * The kubb-generated client makes `headers.authorization` a required
+     * arg because the server controllers accept the bearer as a fallback
+     * to `body.token`. We stub an empty string here — the HTTP client's
+     * auth middleware overrides whatever's passed with the configured
+     * credential (`PCAuth.apiKey` / `bearer` / `cookie`).
+     */
     verify: (data) => consumerVerifyControllerVerify(
-      { appSlug: this.appSlug, data },
+      { appSlug: this.appSlug, data, headers: { authorization: "" } },
       { client: this.client }
     ),
     authorize: (data) => consumerVerifyControllerAuthorize(
-      { appSlug: this.appSlug, data },
+      { appSlug: this.appSlug, data, headers: { authorization: "" } },
       { client: this.client }
     ),
     authorizeBatch: (data) => consumerVerifyControllerAuthorizeBatch(
-      { appSlug: this.appSlug, data },
+      { appSlug: this.appSlug, data, headers: { authorization: "" } },
       { client: this.client }
     )
   };
@@ -1831,7 +1882,7 @@ function getAppControllerListMyAppsUrl() {
   const res = { method: "GET", url: `/v1/apps` };
   return res;
 }
-async function appControllerListMyApps({ params }, config = {}) {
+async function appControllerListMyApps({ params } = {}, config = {}) {
   const { client: request = client, ...requestConfig } = config;
   const mappedParams = params ? {
     limit: params.limit,
@@ -1891,7 +1942,7 @@ function getStatsControllerGetMyStatsUrl() {
   const res = { method: "GET", url: `/v1/stats/me` };
   return res;
 }
-async function statsControllerGetMyStats({ params }, config = {}) {
+async function statsControllerGetMyStats({ params } = {}, config = {}) {
   const { client: request = client, ...requestConfig } = config;
   const mappedParams = params ? { workspace_id: params.workspaceId } : void 0;
   const res = await request({
@@ -1918,7 +1969,6 @@ var Heimdall = class {
       fetch: this.fetch
     });
     this.jwtConfig = {
-      audience: config.expectedAudience,
       jwksTtlMs: config.jwksTtlMs
     };
   }
@@ -1981,6 +2031,7 @@ var Heimdall = class {
 
 exports.AppScope = AppScope;
 exports.ConsumerScope = ConsumerScope;
+exports.HEIMDALL_LEGACY_ISSUER = HEIMDALL_LEGACY_ISSUER;
 exports.Heimdall = Heimdall;
 exports.HeimdallHttpError = HeimdallHttpError;
 exports.JwksCache = JwksCache;