@productcraft/heimdall 0.1.0 → 0.2.1

package/README.md

@@ -23,11 +23,17 @@ The SDK splits into three caller contexts.
 ### 1. Workspace-wide admin
 
 ```ts
-// /v1/apps, /v1/idp/*, /v1/stats/me
+// /v1/apps, /v1/stats/me
 const apps = await heimdall.apps.list();
-await heimdall.apps.create({ name: "My App", slug: "my-app" });
-await heimdall.idp.list();
-await heimdall.stats.get();
+
+// Create requires display_name + workspace_id (not `name`).
+await heimdall.apps.create({
+  display_name: "My App",
+  slug: "my-app",
+  workspace_id: "<workspace-uuid>",
+});
+
+const stats = await heimdall.stats.get();
 ```
 
 ### 2. App-scoped admin — `heimdall.app(appId)`
@@ -35,25 +41,31 @@ await heimdall.stats.get();
 Pre-binds the appId path param so resource methods read like `app.endUsers.list()`.
 
 ```ts
-const app = heimdall.app("app_xyz_uuid");
+const app = heimdall.app("<app-uuid>");
 
-// EndUsers
+// EndUsers — profile updates only carry { display_name?, email? }.
+// Status / role transitions are separate calls.
 const users = await app.endUsers.list({ limit: "20", cursor: "..." });
-await app.endUsers.update(userId, { status: "active" });
+await app.endUsers.update(userId, { display_name: "Alice Smith" });
+await app.endUsers.updateStatus(userId, { status: "active" });
 await app.endUsers.revokeAllSessions(userId);
 
-// Roles / Permissions
-await app.roles.create({ name: "admin", permissions: ["billing.read"] });
+// Roles — `CreateRoleDto` is { name, description? }. Permissions are
+// bound separately, after the role exists.
+await app.roles.create({ name: "admin", description: "Billing admin" });
+await app.roles.setPermissions("admin", { permissions: ["billing.read"] });
 await app.roles.assign({ userId, roleName: "admin" });
 await app.permissions.list();
 
-// API keys + M2M creds
-await app.apiKeys.create({ name: "ci" });
+// API keys — permissions[] is required even if empty.
+await app.apiKeys.create({ name: "ci", permissions: [] });
+
+// M2M credentials
 const m2m = await app.credentials.create({ name: "backend-svc" });
 
-// Audit + invites + auth config
+// Audit + invites + auth config (camelCase post-pipe)
 await app.auditLogs.list({ limit: "100" });
-await app.authConfig.update({ passwordPolicy: { minLength: 12 } });
+await app.authConfig.update({ passwordMinLength: 12 });
 ```
 
 ### 3. Consumer-side (BFF) — `heimdall.consumer(appSlug)`
@@ -63,16 +75,23 @@ For backend route handlers mediating auth between your SPA and Heimdall. Pre-bin
 ```ts
 const consumer = heimdall.consumer("my-app-slug");
 
-// Sign-in flows
+// Sign-in
 const { access_token, refresh_token } = await consumer.auth.signin({
   identifier: "alice@example.com",
   password: "...",
 });
-await consumer.auth.signup({ identifier, password });
+
+// Sign-up requires { email, password, username, display_name? } — not `identifier`.
+await consumer.auth.signup({
+  email: "alice@example.com",
+  password: "...",
+  username: "alice",
+});
+
 await consumer.auth.refresh({ refresh_token });
 await consumer.auth.logout({ refresh_token });
 await consumer.auth.requestReset({ email });
-await consumer.auth.resetPassword({ code, newPassword });
+await consumer.auth.resetPassword({ token, new_password: "..." });
 
 // Sign in with Apple (native iOS flow). See "Federated sign-in" below.
 await consumer.auth.signinWithProvider({
@@ -206,11 +225,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 +283,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;