@productcraft/heimdall 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -1260,13 +1260,13 @@ type SetScopesDto = {
 
 type AppControllerListInvitesQueryParams = {
     /**
-     * @type string
+     * @type string | undefined
      */
-    limit: string;
+    limit?: string;
     /**
-     * @type string
+     * @type string | undefined
      */
-    cursor: string;
+    cursor?: string;
 };
 
 /**
@@ -1276,13 +1276,13 @@ type AppControllerListInvitesQueryParams = {
 
 type AppControllerListMembersQueryParams = {
     /**
-     * @type string
+     * @type string | undefined
      */
-    limit: string;
+    limit?: string;
     /**
-     * @type string
+     * @type string | undefined
      */
-    cursor: string;
+    cursor?: string;
 };
 
 /**
@@ -1292,21 +1292,21 @@ type AppControllerListMembersQueryParams = {
 
 type EndUserControllerListEndUsersQueryParams = {
     /**
-     * @type string
+     * @type string | undefined
      */
-    limit: string;
+    limit?: string;
     /**
-     * @type string
+     * @type string | undefined
      */
-    cursor: string;
+    cursor?: string;
     /**
-     * @type string
+     * @type string | undefined
      */
-    status: string;
+    status?: string;
     /**
-     * @type string
+     * @type string | undefined
      */
-    search: string;
+    search?: string;
 };
 
 /**
@@ -1316,21 +1316,21 @@ type EndUserControllerListEndUsersQueryParams = {
 
 type AppAuditControllerGetAuditLogsQueryParams = {
     /**
-     * @type string
+     * @type string | undefined
      */
-    limit: string;
+    limit?: string;
     /**
-     * @type string
+     * @type string | undefined
      */
-    cursor: string;
+    cursor?: string;
     /**
-     * @type string
+     * @type string | undefined
      */
-    action: string;
+    action?: string;
     /**
-     * @type string
+     * @type string | undefined
      */
-    actor_id: string;
+    actor_id?: string;
 };
 
 /**
@@ -1340,13 +1340,13 @@ type AppAuditControllerGetAuditLogsQueryParams = {
 
 type M2MControllerListClientsQueryParams = {
     /**
-     * @type string
+     * @type string | undefined
      */
-    limit: string;
+    limit?: string;
     /**
-     * @type string
+     * @type string | undefined
      */
-    cursor: string;
+    cursor?: string;
 };
 
 /**
@@ -1356,13 +1356,13 @@ type M2MControllerListClientsQueryParams = {
 
 type RoleControllerListRolesQueryParams = {
     /**
-     * @type string
+     * @type string | undefined
      */
-    limit: string;
+    limit?: string;
     /**
-     * @type string
+     * @type string | undefined
      */
-    cursor: string;
+    cursor?: string;
 };
 
 declare class AppScope {
@@ -1477,6 +1477,11 @@ type AuthorizeBatchResultDto = {
      * @type boolean
      */
     authorized: boolean;
+    /**
+     * @description Caller-supplied id from the corresponding check entry. Echoed back so callers can correlate results to inputs without relying on array order.
+     * @type string | undefined
+     */
+    id?: string;
     /**
      * @type array
      */
@@ -1798,10 +1803,10 @@ type UpdateMeDto = {
  */
 type VerifyBody = {
     /**
-     * @description EndUser or M2M JWT to verify against the app JWKS.
-     * @type string
+     * @description EndUser or M2M JWT to verify against the app JWKS. Optional — if omitted, the token is read from the `Authorization: Bearer <jwt>` header instead.
+     * @type string | undefined
      */
-    token: string;
+    token?: string;
 };
 
 /**
@@ -1820,10 +1825,10 @@ type AuthorizeBody = {
      */
     permissions?: string[];
     /**
-     * @description JWT to verify and authorize.
-     * @type string
+     * @description JWT to verify and authorize. Optional — if omitted, the token is read from the `Authorization: Bearer <jwt>` header.
+     * @type string | undefined
      */
-    token: string;
+    token?: string;
 };
 
 /**
@@ -1832,10 +1837,20 @@ type AuthorizeBody = {
  */
 type AuthorizeBatchEntry = {
     /**
-     * @description Permissions for this check; ALL must be held.
-     * @type array
+     * @description Caller-chosen correlation id for this check. Echoed back on the matching result so the caller can map results to inputs without relying on array order.
+     * @type string | undefined
      */
-    permissions: string[];
+    id?: string;
+    /**
+     * @description Single permission to check, e.g. \'invoice.read\'. Use this OR `permissions`.
+     * @type string | undefined
+     */
+    permission?: string;
+    /**
+     * @description Multiple permissions; ALL must be held for this check to pass.
+     * @type array | undefined
+     */
+    permissions?: string[];
 };
 
 /**
@@ -1845,15 +1860,15 @@ type AuthorizeBatchEntry = {
 
 type AuthorizeBatchBody = {
     /**
-     * @description List of checks. Each returns { authorized, missing_permissions }.
+     * @description List of checks. Each returns { id?, authorized, missing_permissions }.
      * @type array
      */
     checks: AuthorizeBatchEntry[];
     /**
-     * @description JWT to verify and authorize against each check.
-     * @type string
+     * @description JWT to verify and authorize against each check. Optional — if omitted, the token is read from the `Authorization: Bearer <jwt>` header.
+     * @type string | undefined
      */
-    token: string;
+    token?: string;
 };
 
 /**
@@ -2077,6 +2092,15 @@ interface VerifyOptions {
  */
 declare function verifyHeimdallToken(token: string, getKey: HeimdallGetKeyFn, opts?: VerifyOptions): Promise<HeimdallClaims>;
 
+/**
+ * Legacy `iss` claim Heimdall Consumer-API tokens used to be minted
+ * with. Kept exported so consumers verifying tokens issued before the
+ * 2026-05-24 per-app-issuer migration can still match `iss` while a
+ * deployment cycles to fresh tokens. New tokens carry the per-app
+ * issuer URL — `${baseUrl}/${appSlug}` — accessible via
+ * `scope.expectedIssuer`.
+ */
+declare const HEIMDALL_LEGACY_ISSUER = "heimdall";
 interface ConsumerScopeInternals {
     client: Client;
     baseUrl: string;
@@ -2086,15 +2110,38 @@ interface ConsumerScopeInternals {
 declare class ConsumerScope {
     /** The appSlug bound to this scope. */
     readonly appSlug: string;
-    /** 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.
+     */
     readonly expectedIssuer: string;
-    /** Default aud claim. Undefined unless the caller sets it (skip aud check). */
-    readonly expectedAudience: string | undefined;
+    /**
+     * 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.
+     */
+    readonly expectedAudience: string;
+    /**
+     * 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.
+     */
+    readonly acceptedIssuers: readonly string[];
     /** jose-compatible JWKS resolver. Drop into `jose.jwtVerify`, passport-jwt, etc. */
     readonly jwks: JwksCache;
     private readonly client;
     constructor(appSlug: string, internals: ConsumerScopeInternals, opts?: {
-        audience?: string;
         jwksTtlMs?: number;
     });
     /**
@@ -2103,7 +2150,17 @@ declare class ConsumerScope {
      * upstream; remove once the spec is fixed.
      */
     private callDirect;
-    /** 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: string, opts?: VerifyOptions): Promise<HeimdallClaims>;
     readonly auth: {
         signin: (data: ConsumerSigninDto) => Promise<ConsumerAuthControllerSignin200>;
@@ -2170,6 +2227,13 @@ declare class ConsumerScope {
         deleteAccount: () => Promise<void>;
     };
     readonly 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: VerifyBody) => Promise<VerifyResponseDto>;
         authorize: (data: AuthorizeBody) => Promise<AuthorizeResponseDto>;
         authorizeBatch: (data: AuthorizeBatchBody) => Promise<AuthorizeBatchResponseDto>;
@@ -2224,17 +2288,17 @@ type AcceptInviteDto = {
 
 type AppControllerListMyAppsQueryParams = {
     /**
-     * @type string
+     * @type string | undefined
      */
-    limit: string;
+    limit?: string;
     /**
-     * @type string
+     * @type string | undefined
      */
-    cursor: string;
+    cursor?: string;
     /**
-     * @type string
+     * @type string | undefined
      */
-    workspace_id: string;
+    workspace_id?: string;
 };
 
 /**
@@ -2244,9 +2308,9 @@ type AppControllerListMyAppsQueryParams = {
 
 type StatsControllerGetMyStatsQueryParams = {
     /**
-     * @type string
+     * @type string | undefined
      */
-    workspace_id: string;
+    workspace_id?: string;
 };
 
 /**
@@ -2306,12 +2370,6 @@ declare class JwksFetchError extends JwtVerifyError {
 }
 
 interface HeimdallConfig extends PCClientConfig {
-    /**
-     * Override the default `audience` claim expected on tokens verified
-     * via `consumer(slug).verifyToken(...)`. Per-call override is also
-     * available on `verifyToken`'s options.
-     */
-    expectedAudience?: string;
     /** Per-app JWKS cache lifetime in ms. Default 10 minutes. */
     jwksTtlMs?: number;
 }
@@ -2351,4 +2409,4 @@ declare class Heimdall {
     };
 }
 
-export { type AcceptInviteDto, AppScope, type AssignRoleDto, type AuthorizeBatchBody, type AuthorizeBody, type ClientCredentialsDto, type ConsumerLogoutDto, type ConsumerRefreshDto, type ConsumerRequestPasswordResetDto, type ConsumerResetPasswordDto, ConsumerScope, type ConsumerSigninDto, type ConsumerSignupDto, type ConsumerTokenResponseDto, type CreateApiKeyDto, type CreateAppDto, type CreateInviteDto, type CreateM2MClientDto, type CreatePermissionDto, type CreateRoleDto, Heimdall, type HeimdallClaims, type HeimdallConfig, HeimdallHttpError, type IdpNativeSigninDto, type IdpNativeUserHintDto, type IdpTokenResponseDto, JwksCache, JwksFetchError, JwksKeyNotFoundError, JwtAudienceMismatchError, JwtExpiredError, JwtInvalidError, JwtIssuerMismatchError, JwtNotYetValidError, JwtVerifyError, type SetPermissionsDto, type SetScopesDto, type UpdateAppDto, type UpdateAppStatusDto, type UpdateAuthConfigDto, type UpdateEndUserDto, type UpdateEndUserRoleDto, type UpdateEndUserStatusDto, type UpdateM2MClientDto, type UpdateMeDto, type UpdateRoleDto, type VerifyBody, type VerifyOptions, verifyHeimdallToken };
+export { type AcceptInviteDto, AppScope, type AssignRoleDto, type AuthorizeBatchBody, type AuthorizeBody, type ClientCredentialsDto, type ConsumerLogoutDto, type ConsumerRefreshDto, type ConsumerRequestPasswordResetDto, type ConsumerResetPasswordDto, ConsumerScope, type ConsumerSigninDto, type ConsumerSignupDto, type ConsumerTokenResponseDto, type CreateApiKeyDto, type CreateAppDto, type CreateInviteDto, type CreateM2MClientDto, type CreatePermissionDto, type CreateRoleDto, HEIMDALL_LEGACY_ISSUER, Heimdall, type HeimdallClaims, type HeimdallConfig, HeimdallHttpError, type IdpNativeSigninDto, type IdpNativeUserHintDto, type IdpTokenResponseDto, JwksCache, JwksFetchError, JwksKeyNotFoundError, JwtAudienceMismatchError, JwtExpiredError, JwtInvalidError, JwtIssuerMismatchError, JwtNotYetValidError, JwtVerifyError, type SetPermissionsDto, type SetScopesDto, type UpdateAppDto, type UpdateAppStatusDto, type UpdateAuthConfigDto, type UpdateEndUserDto, type UpdateEndUserRoleDto, type UpdateEndUserStatusDto, type UpdateM2MClientDto, type UpdateMeDto, type UpdateRoleDto, type VerifyBody, type VerifyOptions, verifyHeimdallToken };

package/dist/index.js

@@ -1414,7 +1414,8 @@ function getConsumerVerifyControllerVerifyUrl({
 }
 async function consumerVerifyControllerVerify({
   appSlug,
-  data
+  data,
+  headers
 }, config = {}) {
   const { client: request = client, ...requestConfig } = config;
   const requestData = data;
@@ -1422,7 +1423,8 @@ async function consumerVerifyControllerVerify({
     method: "POST",
     url: getConsumerVerifyControllerVerifyUrl({ appSlug }).url.toString(),
     data: requestData,
-    ...requestConfig
+    ...requestConfig,
+    headers: { ...headers, ...requestConfig.headers }
   });
   return res.data;
 }
@@ -1437,7 +1439,8 @@ function getConsumerVerifyControllerAuthorizeUrl({
 }
 async function consumerVerifyControllerAuthorize({
   appSlug,
-  data
+  data,
+  headers
 }, config = {}) {
   const { client: request = client, ...requestConfig } = config;
   const requestData = data;
@@ -1445,7 +1448,8 @@ async function consumerVerifyControllerAuthorize({
     method: "POST",
     url: getConsumerVerifyControllerAuthorizeUrl({ appSlug }).url.toString(),
     data: requestData,
-    ...requestConfig
+    ...requestConfig,
+    headers: { ...headers, ...requestConfig.headers }
   });
   return res.data;
 }
@@ -1463,7 +1467,8 @@ function getConsumerVerifyControllerAuthorizeBatchUrl({
 }
 async function consumerVerifyControllerAuthorizeBatch({
   appSlug,
-  data
+  data,
+  headers
 }, config = {}) {
   const { client: request = client, ...requestConfig } = config;
   const requestData = data;
@@ -1473,7 +1478,8 @@ async function consumerVerifyControllerAuthorizeBatch({
       appSlug
     }).url.toString(),
     data: requestData,
-    ...requestConfig
+    ...requestConfig,
+    headers: { ...headers, ...requestConfig.headers }
   });
   return res.data;
 }
@@ -1654,21 +1660,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,
@@ -1684,10 +1718,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
     });
@@ -1800,16 +1844,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 }
     )
   };
@@ -1829,7 +1880,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,
@@ -1889,7 +1940,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({
@@ -1916,7 +1967,6 @@ var Heimdall = class {
       fetch: this.fetch
     });
     this.jwtConfig = {
-      audience: config.expectedAudience,
       jwksTtlMs: config.jwksTtlMs
     };
   }
@@ -1977,6 +2027,6 @@ var Heimdall = class {
   };
 };
 
-export { AppScope, ConsumerScope, Heimdall, HeimdallHttpError, JwksCache, JwksFetchError, JwksKeyNotFoundError, JwtAudienceMismatchError, JwtExpiredError, JwtInvalidError, JwtIssuerMismatchError, JwtNotYetValidError, JwtVerifyError, verifyHeimdallToken };
+export { AppScope, ConsumerScope, HEIMDALL_LEGACY_ISSUER, Heimdall, HeimdallHttpError, JwksCache, JwksFetchError, JwksKeyNotFoundError, JwtAudienceMismatchError, JwtExpiredError, JwtInvalidError, JwtIssuerMismatchError, JwtNotYetValidError, JwtVerifyError, verifyHeimdallToken };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map