@eventferry/kafka-iam 0.1.0

package/README.md

@@ -0,0 +1,77 @@
+# @eventferry/kafka-iam
+
+[![npm](https://img.shields.io/npm/v/@eventferry/kafka-iam.svg)](https://www.npmjs.com/package/@eventferry/kafka-iam)
+
+**AWS MSK IAM** authentication for [`@eventferry/kafka`](../kafka). MSK exposes IAM auth via SASL/OAUTHBEARER — the bearer token is an AWS Signature V4 signature, not a JWT. This helper wraps the official `aws-msk-iam-sasl-signer-js` library and gives you a one-liner `sasl` block for the publisher.
+
+## Install
+
+```bash
+npm i @eventferry/kafka-iam aws-msk-iam-sasl-signer-js
+```
+
+`aws-msk-iam-sasl-signer-js` is an optional peer (the AWS-official SigV4 signer).
+
+## Usage
+
+```ts
+import { KafkaPublisher } from "@eventferry/kafka";
+import { createMskIamSasl } from "@eventferry/kafka-iam";
+
+const publisher = new KafkaPublisher({
+  brokers: ["b-1.cluster.us-east-1.amazonaws.com:9098"],
+  ssl: true,
+  sasl: createMskIamSasl({ region: "us-east-1" }),
+});
+
+await publisher.connect();
+```
+
+With a named AWS profile or an assumed IAM role:
+
+```ts
+createMskIamSasl({ region: "us-east-1", awsProfile: "prod" });
+
+createMskIamSasl({
+  region: "us-east-1",
+  awsRoleArn: "arn:aws:iam::123456789012:role/eventferry-publisher",
+  awsRoleSessionName: "eventferry-prod",
+});
+```
+
+## Token caching & refresh
+
+MSK IAM tokens have a 15-minute lifetime. This helper memoizes the most recent token and refreshes it shortly before expiry. Both kafkajs and librdkafka invoke the provider on demand (no fixed timer), so process-local caching is the natural place:
+
+- Default `refreshAheadMs: 60_000` — token is regenerated when its remaining lifetime drops below 60 seconds.
+- Concurrent invocations during a refresh dedupe onto a single in-flight `generateAuthToken` call (no thundering herd at the SigV4 signer).
+- Transient signer failures clear the in-flight slot so the next call retries cleanly.
+
+Tighten or loosen the refresh window:
+
+```ts
+createMskIamSasl({ region: "us-east-1", refreshAheadMs: 120_000 });
+```
+
+## Custom signer (DI)
+
+For tests or non-standard signers, inject your own:
+
+```ts
+createMskIamSasl({
+  region: "us-east-1",
+  signer: {
+    async generateAuthToken({ region }) {
+      return { token: await mySignerFor(region), expiryTime: Date.now() + 15 * 60 * 1000 };
+    },
+  },
+});
+```
+
+The helper does not dynamically import `aws-msk-iam-sasl-signer-js` when a `signer` is supplied.
+
+📖 **Full documentation:** [github.com/SametGoktepe/eventferry](https://github.com/SametGoktepe/eventferry#readme)
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,105 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createMskIamSasl: () => createMskIamSasl
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/iam-provider.ts
+function createMskIamSasl(opts) {
+  if (!opts.region) {
+    throw new Error("createMskIamSasl: `region` is required");
+  }
+  const refreshAheadMs = opts.refreshAheadMs ?? 6e4;
+  const principal = opts.principal ?? "eventferry";
+  let cached = null;
+  let inFlight = null;
+  let signer = opts.signer ?? null;
+  async function refresh() {
+    if (!signer) signer = await importDefaultSigner();
+    const { region, awsProfile, awsRoleArn, awsRoleSessionName, awsStsRegion } = opts;
+    const result = await signer.generateAuthToken({
+      region,
+      ...awsProfile !== void 0 ? { awsProfile } : {},
+      ...awsRoleArn !== void 0 ? { awsRoleArn } : {},
+      ...awsRoleSessionName !== void 0 ? { awsRoleSessionName } : {},
+      ...awsStsRegion !== void 0 ? { awsStsRegion } : {}
+    });
+    const expiryMs = result.expiryTime > 1e12 ? result.expiryTime : result.expiryTime * 1e3;
+    cached = { token: result.token, expiryMs };
+    return tokenFor(cached, principal);
+  }
+  return {
+    mechanism: "oauthbearer",
+    async oauthBearerProvider() {
+      const now = Date.now();
+      if (cached && cached.expiryMs - now > refreshAheadMs) {
+        return tokenFor(cached, principal);
+      }
+      if (!inFlight) {
+        inFlight = refresh().finally(() => {
+          inFlight = null;
+        });
+      }
+      return inFlight;
+    }
+  };
+}
+function tokenFor(cached, principal) {
+  const lifetime = Math.max(cached.expiryMs - Date.now(), 0);
+  return {
+    value: cached.token,
+    principal,
+    lifetime
+  };
+}
+async function importDefaultSigner() {
+  try {
+    const mod = await import("aws-msk-iam-sasl-signer-js");
+    if (typeof mod?.generateAuthToken === "function") {
+      return { generateAuthToken: mod.generateAuthToken };
+    }
+    if (typeof mod?.default?.generateAuthToken === "function") {
+      return { generateAuthToken: mod.default.generateAuthToken };
+    }
+    throw new Error("module shape mismatch \u2014 no generateAuthToken export found");
+  } catch (err) {
+    throw new Error(
+      `createMskIamSasl requires the "aws-msk-iam-sasl-signer-js" package. Run: npm i aws-msk-iam-sasl-signer-js. (underlying error: ${err.message})`
+    );
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createMskIamSasl
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/iam-provider.ts"],"sourcesContent":["export * from \"./iam-provider.js\";\n","import type {\n  OauthBearerToken,\n  SaslOauthbearerConfig,\n} from \"@eventferry/kafka\";\n\n/**\n * AWS MSK IAM authentication for @eventferry/kafka.\n *\n * AWS MSK exposes IAM auth via SASL/OAUTHBEARER — the bearer token is an AWS\n * Signature V4 signature, not a JWT. This helper produces a token provider\n * compatible with eventferry's {@link SaslOauthbearerConfig.oauthBearerProvider}\n * shape, backed by the official `aws-msk-iam-sasl-signer-js` library.\n *\n * Wire it into the publisher's `sasl` option directly:\n *\n *   import { createMskIamSasl } from \"@eventferry/kafka-iam\";\n *\n *   new KafkaPublisher({\n *     brokers: [\"b.cluster.us-east-1.amazonaws.com:9098\"],\n *     ssl: true,\n *     sasl: createMskIamSasl({ region: \"us-east-1\" }),\n *   });\n */\n\n/**\n * Minimal structural shape of the official AWS signer. The real module's\n * `generateAuthToken` matches this — we keep the interface here so the\n * helper compiles without `aws-msk-iam-sasl-signer-js` installed (it's\n * an optional peer).\n */\nexport interface MskIamSigner {\n  generateAuthToken(opts: {\n    region: string;\n    // The signer accepts other fields (awsProfile, awsRoleArn, awsRoleSessionName);\n    // we forward whatever the caller supplied via `signerOptions`.\n    [k: string]: unknown;\n  }): Promise<{ token: string; expiryTime: number }>;\n}\n\n/** Options forwarded to `aws-msk-iam-sasl-signer-js`'s `generateAuthToken`. */\nexport interface MskIamSaslOptions {\n  /** AWS region of the MSK cluster (e.g. \"us-east-1\"). REQUIRED. */\n  region: string;\n  /**\n   * Optional named AWS profile to use (resolved by the signer the same way\n   * the AWS SDK does). Mutually exclusive with `awsRoleArn`.\n   */\n  awsProfile?: string;\n  /**\n   * Optional IAM role to assume before signing. The signer calls\n   * `AssumeRole` itself. Mutually exclusive with `awsProfile`.\n   */\n  awsRoleArn?: string;\n  /** Session name to use with `awsRoleArn`. Default `\"MSKSASLDefaultSession\"`. */\n  awsRoleSessionName?: string;\n  /**\n   * Optional signer endpoint override. Useful for VPC endpoints / FIPS\n   * regions. Forwarded as-is to the signer.\n   */\n  awsStsRegion?: string;\n  /**\n   * Optional pre-built signer (DI for tests). When set, the helper does NOT\n   * dynamically import `aws-msk-iam-sasl-signer-js`.\n   */\n  signer?: MskIamSigner;\n  /**\n   * Optional override for the SASL principal. AWS MSK accepts any string;\n   * default `\"eventferry\"` is the conventional name.\n   */\n  principal?: string;\n  /**\n   * Refresh-ahead window. Token is regenerated when its remaining lifetime\n   * drops below this many milliseconds. Default 60_000 (60 s) — the\n   * signer's default token lifetime is 15 minutes, so this leaves ~14 min\n   * of usable cache between refreshes.\n   */\n  refreshAheadMs?: number;\n}\n\n/**\n * Construct the `sasl` block for `KafkaPublisher`. The returned config\n * memoizes the most recent token and refreshes it shortly before expiry —\n * librdkafka and kafkajs both invoke the provider on demand (no fixed\n * timer), so a process-local cache is the natural place for this.\n *\n * Concurrent invocations during a refresh dedupe onto a single in-flight\n * `generateAuthToken` call.\n */\nexport function createMskIamSasl(\n  opts: MskIamSaslOptions,\n): SaslOauthbearerConfig {\n  if (!opts.region) {\n    throw new Error(\"createMskIamSasl: `region` is required\");\n  }\n  const refreshAheadMs = opts.refreshAheadMs ?? 60_000;\n  const principal = opts.principal ?? \"eventferry\";\n\n  let cached: { token: string; expiryMs: number } | null = null;\n  let inFlight: Promise<OauthBearerToken> | null = null;\n  let signer: MskIamSigner | null = opts.signer ?? null;\n\n  async function refresh(): Promise<OauthBearerToken> {\n    if (!signer) signer = await importDefaultSigner();\n    const { region, awsProfile, awsRoleArn, awsRoleSessionName, awsStsRegion } =\n      opts;\n    const result = await signer.generateAuthToken({\n      region,\n      ...(awsProfile !== undefined ? { awsProfile } : {}),\n      ...(awsRoleArn !== undefined ? { awsRoleArn } : {}),\n      ...(awsRoleSessionName !== undefined ? { awsRoleSessionName } : {}),\n      ...(awsStsRegion !== undefined ? { awsStsRegion } : {}),\n    });\n    // Some signers return expiry in seconds, some in ms. The official\n    // aws-msk-iam-sasl-signer-js returns ms. Be defensive: anything below\n    // year-2001 (in ms) is treated as seconds and rescaled.\n    const expiryMs =\n      result.expiryTime > 1_000_000_000_000\n        ? result.expiryTime\n        : result.expiryTime * 1000;\n    cached = { token: result.token, expiryMs };\n    return tokenFor(cached, principal);\n  }\n\n  return {\n    mechanism: \"oauthbearer\",\n    async oauthBearerProvider(): Promise<OauthBearerToken> {\n      const now = Date.now();\n      // Fast path: cached token still has plenty of headroom.\n      if (cached && cached.expiryMs - now > refreshAheadMs) {\n        return tokenFor(cached, principal);\n      }\n      // Dedup concurrent refresh attempts so a thundering herd hits the\n      // signer once, not N times.\n      if (!inFlight) {\n        inFlight = refresh().finally(() => {\n          inFlight = null;\n        });\n      }\n      return inFlight;\n    },\n  };\n}\n\nfunction tokenFor(\n  cached: { token: string; expiryMs: number },\n  principal: string,\n): OauthBearerToken {\n  // Confluent driver requires {value, principal, lifetime}. kafkajs ignores\n  // everything but `value` — supplying the extras is a no-op there.\n  // Lifetime is in MILLISECONDS per the eventferry contract.\n  const lifetime = Math.max(cached.expiryMs - Date.now(), 0);\n  return {\n    value: cached.token,\n    principal,\n    lifetime,\n  };\n}\n\nasync function importDefaultSigner(): Promise<MskIamSigner> {\n  try {\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    const mod: any = await import(\"aws-msk-iam-sasl-signer-js\");\n    // The package exports either `generateAuthToken` directly OR a default\n    // object containing it. Normalize both shapes into an MskIamSigner.\n    if (typeof mod?.generateAuthToken === \"function\") {\n      return { generateAuthToken: mod.generateAuthToken };\n    }\n    if (typeof mod?.default?.generateAuthToken === \"function\") {\n      return { generateAuthToken: mod.default.generateAuthToken };\n    }\n    throw new Error(\"module shape mismatch — no generateAuthToken export found\");\n  } catch (err) {\n    throw new Error(\n      'createMskIamSasl requires the \"aws-msk-iam-sasl-signer-js\" package. ' +\n        'Run: npm i aws-msk-iam-sasl-signer-js. ' +\n        `(underlying error: ${(err as Error).message})`,\n    );\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACwFO,SAAS,iBACd,MACuB;AACvB,MAAI,CAAC,KAAK,QAAQ;AAChB,UAAM,IAAI,MAAM,wCAAwC;AAAA,EAC1D;AACA,QAAM,iBAAiB,KAAK,kBAAkB;AAC9C,QAAM,YAAY,KAAK,aAAa;AAEpC,MAAI,SAAqD;AACzD,MAAI,WAA6C;AACjD,MAAI,SAA8B,KAAK,UAAU;AAEjD,iBAAe,UAAqC;AAClD,QAAI,CAAC,OAAQ,UAAS,MAAM,oBAAoB;AAChD,UAAM,EAAE,QAAQ,YAAY,YAAY,oBAAoB,aAAa,IACvE;AACF,UAAM,SAAS,MAAM,OAAO,kBAAkB;AAAA,MAC5C;AAAA,MACA,GAAI,eAAe,SAAY,EAAE,WAAW,IAAI,CAAC;AAAA,MACjD,GAAI,eAAe,SAAY,EAAE,WAAW,IAAI,CAAC;AAAA,MACjD,GAAI,uBAAuB,SAAY,EAAE,mBAAmB,IAAI,CAAC;AAAA,MACjE,GAAI,iBAAiB,SAAY,EAAE,aAAa,IAAI,CAAC;AAAA,IACvD,CAAC;AAID,UAAM,WACJ,OAAO,aAAa,OAChB,OAAO,aACP,OAAO,aAAa;AAC1B,aAAS,EAAE,OAAO,OAAO,OAAO,SAAS;AACzC,WAAO,SAAS,QAAQ,SAAS;AAAA,EACnC;AAEA,SAAO;AAAA,IACL,WAAW;AAAA,IACX,MAAM,sBAAiD;AACrD,YAAM,MAAM,KAAK,IAAI;AAErB,UAAI,UAAU,OAAO,WAAW,MAAM,gBAAgB;AACpD,eAAO,SAAS,QAAQ,SAAS;AAAA,MACnC;AAGA,UAAI,CAAC,UAAU;AACb,mBAAW,QAAQ,EAAE,QAAQ,MAAM;AACjC,qBAAW;AAAA,QACb,CAAC;AAAA,MACH;AACA,aAAO;AAAA,IACT;AAAA,EACF;AACF;AAEA,SAAS,SACP,QACA,WACkB;AAIlB,QAAM,WAAW,KAAK,IAAI,OAAO,WAAW,KAAK,IAAI,GAAG,CAAC;AACzD,SAAO;AAAA,IACL,OAAO,OAAO;AAAA,IACd;AAAA,IACA;AAAA,EACF;AACF;AAEA,eAAe,sBAA6C;AAC1D,MAAI;AAEF,UAAM,MAAW,MAAM,OAAO,4BAA4B;AAG1D,QAAI,OAAO,KAAK,sBAAsB,YAAY;AAChD,aAAO,EAAE,mBAAmB,IAAI,kBAAkB;AAAA,IACpD;AACA,QAAI,OAAO,KAAK,SAAS,sBAAsB,YAAY;AACzD,aAAO,EAAE,mBAAmB,IAAI,QAAQ,kBAAkB;AAAA,IAC5D;AACA,UAAM,IAAI,MAAM,gEAA2D;AAAA,EAC7E,SAAS,KAAK;AACZ,UAAM,IAAI;AAAA,MACR,iIAEyB,IAAc,OAAO;AAAA,IAChD;AAAA,EACF;AACF;","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,86 @@
+import { SaslOauthbearerConfig } from '@eventferry/kafka';
+
+/**
+ * AWS MSK IAM authentication for @eventferry/kafka.
+ *
+ * AWS MSK exposes IAM auth via SASL/OAUTHBEARER — the bearer token is an AWS
+ * Signature V4 signature, not a JWT. This helper produces a token provider
+ * compatible with eventferry's {@link SaslOauthbearerConfig.oauthBearerProvider}
+ * shape, backed by the official `aws-msk-iam-sasl-signer-js` library.
+ *
+ * Wire it into the publisher's `sasl` option directly:
+ *
+ *   import { createMskIamSasl } from "@eventferry/kafka-iam";
+ *
+ *   new KafkaPublisher({
+ *     brokers: ["b.cluster.us-east-1.amazonaws.com:9098"],
+ *     ssl: true,
+ *     sasl: createMskIamSasl({ region: "us-east-1" }),
+ *   });
+ */
+/**
+ * Minimal structural shape of the official AWS signer. The real module's
+ * `generateAuthToken` matches this — we keep the interface here so the
+ * helper compiles without `aws-msk-iam-sasl-signer-js` installed (it's
+ * an optional peer).
+ */
+interface MskIamSigner {
+    generateAuthToken(opts: {
+        region: string;
+        [k: string]: unknown;
+    }): Promise<{
+        token: string;
+        expiryTime: number;
+    }>;
+}
+/** Options forwarded to `aws-msk-iam-sasl-signer-js`'s `generateAuthToken`. */
+interface MskIamSaslOptions {
+    /** AWS region of the MSK cluster (e.g. "us-east-1"). REQUIRED. */
+    region: string;
+    /**
+     * Optional named AWS profile to use (resolved by the signer the same way
+     * the AWS SDK does). Mutually exclusive with `awsRoleArn`.
+     */
+    awsProfile?: string;
+    /**
+     * Optional IAM role to assume before signing. The signer calls
+     * `AssumeRole` itself. Mutually exclusive with `awsProfile`.
+     */
+    awsRoleArn?: string;
+    /** Session name to use with `awsRoleArn`. Default `"MSKSASLDefaultSession"`. */
+    awsRoleSessionName?: string;
+    /**
+     * Optional signer endpoint override. Useful for VPC endpoints / FIPS
+     * regions. Forwarded as-is to the signer.
+     */
+    awsStsRegion?: string;
+    /**
+     * Optional pre-built signer (DI for tests). When set, the helper does NOT
+     * dynamically import `aws-msk-iam-sasl-signer-js`.
+     */
+    signer?: MskIamSigner;
+    /**
+     * Optional override for the SASL principal. AWS MSK accepts any string;
+     * default `"eventferry"` is the conventional name.
+     */
+    principal?: string;
+    /**
+     * Refresh-ahead window. Token is regenerated when its remaining lifetime
+     * drops below this many milliseconds. Default 60_000 (60 s) — the
+     * signer's default token lifetime is 15 minutes, so this leaves ~14 min
+     * of usable cache between refreshes.
+     */
+    refreshAheadMs?: number;
+}
+/**
+ * Construct the `sasl` block for `KafkaPublisher`. The returned config
+ * memoizes the most recent token and refreshes it shortly before expiry —
+ * librdkafka and kafkajs both invoke the provider on demand (no fixed
+ * timer), so a process-local cache is the natural place for this.
+ *
+ * Concurrent invocations during a refresh dedupe onto a single in-flight
+ * `generateAuthToken` call.
+ */
+declare function createMskIamSasl(opts: MskIamSaslOptions): SaslOauthbearerConfig;
+
+export { type MskIamSaslOptions, type MskIamSigner, createMskIamSasl };

package/dist/index.d.ts

@@ -0,0 +1,86 @@
+import { SaslOauthbearerConfig } from '@eventferry/kafka';
+
+/**
+ * AWS MSK IAM authentication for @eventferry/kafka.
+ *
+ * AWS MSK exposes IAM auth via SASL/OAUTHBEARER — the bearer token is an AWS
+ * Signature V4 signature, not a JWT. This helper produces a token provider
+ * compatible with eventferry's {@link SaslOauthbearerConfig.oauthBearerProvider}
+ * shape, backed by the official `aws-msk-iam-sasl-signer-js` library.
+ *
+ * Wire it into the publisher's `sasl` option directly:
+ *
+ *   import { createMskIamSasl } from "@eventferry/kafka-iam";
+ *
+ *   new KafkaPublisher({
+ *     brokers: ["b.cluster.us-east-1.amazonaws.com:9098"],
+ *     ssl: true,
+ *     sasl: createMskIamSasl({ region: "us-east-1" }),
+ *   });
+ */
+/**
+ * Minimal structural shape of the official AWS signer. The real module's
+ * `generateAuthToken` matches this — we keep the interface here so the
+ * helper compiles without `aws-msk-iam-sasl-signer-js` installed (it's
+ * an optional peer).
+ */
+interface MskIamSigner {
+    generateAuthToken(opts: {
+        region: string;
+        [k: string]: unknown;
+    }): Promise<{
+        token: string;
+        expiryTime: number;
+    }>;
+}
+/** Options forwarded to `aws-msk-iam-sasl-signer-js`'s `generateAuthToken`. */
+interface MskIamSaslOptions {
+    /** AWS region of the MSK cluster (e.g. "us-east-1"). REQUIRED. */
+    region: string;
+    /**
+     * Optional named AWS profile to use (resolved by the signer the same way
+     * the AWS SDK does). Mutually exclusive with `awsRoleArn`.
+     */
+    awsProfile?: string;
+    /**
+     * Optional IAM role to assume before signing. The signer calls
+     * `AssumeRole` itself. Mutually exclusive with `awsProfile`.
+     */
+    awsRoleArn?: string;
+    /** Session name to use with `awsRoleArn`. Default `"MSKSASLDefaultSession"`. */
+    awsRoleSessionName?: string;
+    /**
+     * Optional signer endpoint override. Useful for VPC endpoints / FIPS
+     * regions. Forwarded as-is to the signer.
+     */
+    awsStsRegion?: string;
+    /**
+     * Optional pre-built signer (DI for tests). When set, the helper does NOT
+     * dynamically import `aws-msk-iam-sasl-signer-js`.
+     */
+    signer?: MskIamSigner;
+    /**
+     * Optional override for the SASL principal. AWS MSK accepts any string;
+     * default `"eventferry"` is the conventional name.
+     */
+    principal?: string;
+    /**
+     * Refresh-ahead window. Token is regenerated when its remaining lifetime
+     * drops below this many milliseconds. Default 60_000 (60 s) — the
+     * signer's default token lifetime is 15 minutes, so this leaves ~14 min
+     * of usable cache between refreshes.
+     */
+    refreshAheadMs?: number;
+}
+/**
+ * Construct the `sasl` block for `KafkaPublisher`. The returned config
+ * memoizes the most recent token and refreshes it shortly before expiry —
+ * librdkafka and kafkajs both invoke the provider on demand (no fixed
+ * timer), so a process-local cache is the natural place for this.
+ *
+ * Concurrent invocations during a refresh dedupe onto a single in-flight
+ * `generateAuthToken` call.
+ */
+declare function createMskIamSasl(opts: MskIamSaslOptions): SaslOauthbearerConfig;
+
+export { type MskIamSaslOptions, type MskIamSigner, createMskIamSasl };

package/dist/index.js

@@ -0,0 +1,68 @@
+// src/iam-provider.ts
+function createMskIamSasl(opts) {
+  if (!opts.region) {
+    throw new Error("createMskIamSasl: `region` is required");
+  }
+  const refreshAheadMs = opts.refreshAheadMs ?? 6e4;
+  const principal = opts.principal ?? "eventferry";
+  let cached = null;
+  let inFlight = null;
+  let signer = opts.signer ?? null;
+  async function refresh() {
+    if (!signer) signer = await importDefaultSigner();
+    const { region, awsProfile, awsRoleArn, awsRoleSessionName, awsStsRegion } = opts;
+    const result = await signer.generateAuthToken({
+      region,
+      ...awsProfile !== void 0 ? { awsProfile } : {},
+      ...awsRoleArn !== void 0 ? { awsRoleArn } : {},
+      ...awsRoleSessionName !== void 0 ? { awsRoleSessionName } : {},
+      ...awsStsRegion !== void 0 ? { awsStsRegion } : {}
+    });
+    const expiryMs = result.expiryTime > 1e12 ? result.expiryTime : result.expiryTime * 1e3;
+    cached = { token: result.token, expiryMs };
+    return tokenFor(cached, principal);
+  }
+  return {
+    mechanism: "oauthbearer",
+    async oauthBearerProvider() {
+      const now = Date.now();
+      if (cached && cached.expiryMs - now > refreshAheadMs) {
+        return tokenFor(cached, principal);
+      }
+      if (!inFlight) {
+        inFlight = refresh().finally(() => {
+          inFlight = null;
+        });
+      }
+      return inFlight;
+    }
+  };
+}
+function tokenFor(cached, principal) {
+  const lifetime = Math.max(cached.expiryMs - Date.now(), 0);
+  return {
+    value: cached.token,
+    principal,
+    lifetime
+  };
+}
+async function importDefaultSigner() {
+  try {
+    const mod = await import("aws-msk-iam-sasl-signer-js");
+    if (typeof mod?.generateAuthToken === "function") {
+      return { generateAuthToken: mod.generateAuthToken };
+    }
+    if (typeof mod?.default?.generateAuthToken === "function") {
+      return { generateAuthToken: mod.default.generateAuthToken };
+    }
+    throw new Error("module shape mismatch \u2014 no generateAuthToken export found");
+  } catch (err) {
+    throw new Error(
+      `createMskIamSasl requires the "aws-msk-iam-sasl-signer-js" package. Run: npm i aws-msk-iam-sasl-signer-js. (underlying error: ${err.message})`
+    );
+  }
+}
+export {
+  createMskIamSasl
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/iam-provider.ts"],"sourcesContent":["import type {\n  OauthBearerToken,\n  SaslOauthbearerConfig,\n} from \"@eventferry/kafka\";\n\n/**\n * AWS MSK IAM authentication for @eventferry/kafka.\n *\n * AWS MSK exposes IAM auth via SASL/OAUTHBEARER — the bearer token is an AWS\n * Signature V4 signature, not a JWT. This helper produces a token provider\n * compatible with eventferry's {@link SaslOauthbearerConfig.oauthBearerProvider}\n * shape, backed by the official `aws-msk-iam-sasl-signer-js` library.\n *\n * Wire it into the publisher's `sasl` option directly:\n *\n *   import { createMskIamSasl } from \"@eventferry/kafka-iam\";\n *\n *   new KafkaPublisher({\n *     brokers: [\"b.cluster.us-east-1.amazonaws.com:9098\"],\n *     ssl: true,\n *     sasl: createMskIamSasl({ region: \"us-east-1\" }),\n *   });\n */\n\n/**\n * Minimal structural shape of the official AWS signer. The real module's\n * `generateAuthToken` matches this — we keep the interface here so the\n * helper compiles without `aws-msk-iam-sasl-signer-js` installed (it's\n * an optional peer).\n */\nexport interface MskIamSigner {\n  generateAuthToken(opts: {\n    region: string;\n    // The signer accepts other fields (awsProfile, awsRoleArn, awsRoleSessionName);\n    // we forward whatever the caller supplied via `signerOptions`.\n    [k: string]: unknown;\n  }): Promise<{ token: string; expiryTime: number }>;\n}\n\n/** Options forwarded to `aws-msk-iam-sasl-signer-js`'s `generateAuthToken`. */\nexport interface MskIamSaslOptions {\n  /** AWS region of the MSK cluster (e.g. \"us-east-1\"). REQUIRED. */\n  region: string;\n  /**\n   * Optional named AWS profile to use (resolved by the signer the same way\n   * the AWS SDK does). Mutually exclusive with `awsRoleArn`.\n   */\n  awsProfile?: string;\n  /**\n   * Optional IAM role to assume before signing. The signer calls\n   * `AssumeRole` itself. Mutually exclusive with `awsProfile`.\n   */\n  awsRoleArn?: string;\n  /** Session name to use with `awsRoleArn`. Default `\"MSKSASLDefaultSession\"`. */\n  awsRoleSessionName?: string;\n  /**\n   * Optional signer endpoint override. Useful for VPC endpoints / FIPS\n   * regions. Forwarded as-is to the signer.\n   */\n  awsStsRegion?: string;\n  /**\n   * Optional pre-built signer (DI for tests). When set, the helper does NOT\n   * dynamically import `aws-msk-iam-sasl-signer-js`.\n   */\n  signer?: MskIamSigner;\n  /**\n   * Optional override for the SASL principal. AWS MSK accepts any string;\n   * default `\"eventferry\"` is the conventional name.\n   */\n  principal?: string;\n  /**\n   * Refresh-ahead window. Token is regenerated when its remaining lifetime\n   * drops below this many milliseconds. Default 60_000 (60 s) — the\n   * signer's default token lifetime is 15 minutes, so this leaves ~14 min\n   * of usable cache between refreshes.\n   */\n  refreshAheadMs?: number;\n}\n\n/**\n * Construct the `sasl` block for `KafkaPublisher`. The returned config\n * memoizes the most recent token and refreshes it shortly before expiry —\n * librdkafka and kafkajs both invoke the provider on demand (no fixed\n * timer), so a process-local cache is the natural place for this.\n *\n * Concurrent invocations during a refresh dedupe onto a single in-flight\n * `generateAuthToken` call.\n */\nexport function createMskIamSasl(\n  opts: MskIamSaslOptions,\n): SaslOauthbearerConfig {\n  if (!opts.region) {\n    throw new Error(\"createMskIamSasl: `region` is required\");\n  }\n  const refreshAheadMs = opts.refreshAheadMs ?? 60_000;\n  const principal = opts.principal ?? \"eventferry\";\n\n  let cached: { token: string; expiryMs: number } | null = null;\n  let inFlight: Promise<OauthBearerToken> | null = null;\n  let signer: MskIamSigner | null = opts.signer ?? null;\n\n  async function refresh(): Promise<OauthBearerToken> {\n    if (!signer) signer = await importDefaultSigner();\n    const { region, awsProfile, awsRoleArn, awsRoleSessionName, awsStsRegion } =\n      opts;\n    const result = await signer.generateAuthToken({\n      region,\n      ...(awsProfile !== undefined ? { awsProfile } : {}),\n      ...(awsRoleArn !== undefined ? { awsRoleArn } : {}),\n      ...(awsRoleSessionName !== undefined ? { awsRoleSessionName } : {}),\n      ...(awsStsRegion !== undefined ? { awsStsRegion } : {}),\n    });\n    // Some signers return expiry in seconds, some in ms. The official\n    // aws-msk-iam-sasl-signer-js returns ms. Be defensive: anything below\n    // year-2001 (in ms) is treated as seconds and rescaled.\n    const expiryMs =\n      result.expiryTime > 1_000_000_000_000\n        ? result.expiryTime\n        : result.expiryTime * 1000;\n    cached = { token: result.token, expiryMs };\n    return tokenFor(cached, principal);\n  }\n\n  return {\n    mechanism: \"oauthbearer\",\n    async oauthBearerProvider(): Promise<OauthBearerToken> {\n      const now = Date.now();\n      // Fast path: cached token still has plenty of headroom.\n      if (cached && cached.expiryMs - now > refreshAheadMs) {\n        return tokenFor(cached, principal);\n      }\n      // Dedup concurrent refresh attempts so a thundering herd hits the\n      // signer once, not N times.\n      if (!inFlight) {\n        inFlight = refresh().finally(() => {\n          inFlight = null;\n        });\n      }\n      return inFlight;\n    },\n  };\n}\n\nfunction tokenFor(\n  cached: { token: string; expiryMs: number },\n  principal: string,\n): OauthBearerToken {\n  // Confluent driver requires {value, principal, lifetime}. kafkajs ignores\n  // everything but `value` — supplying the extras is a no-op there.\n  // Lifetime is in MILLISECONDS per the eventferry contract.\n  const lifetime = Math.max(cached.expiryMs - Date.now(), 0);\n  return {\n    value: cached.token,\n    principal,\n    lifetime,\n  };\n}\n\nasync function importDefaultSigner(): Promise<MskIamSigner> {\n  try {\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    const mod: any = await import(\"aws-msk-iam-sasl-signer-js\");\n    // The package exports either `generateAuthToken` directly OR a default\n    // object containing it. Normalize both shapes into an MskIamSigner.\n    if (typeof mod?.generateAuthToken === \"function\") {\n      return { generateAuthToken: mod.generateAuthToken };\n    }\n    if (typeof mod?.default?.generateAuthToken === \"function\") {\n      return { generateAuthToken: mod.default.generateAuthToken };\n    }\n    throw new Error(\"module shape mismatch — no generateAuthToken export found\");\n  } catch (err) {\n    throw new Error(\n      'createMskIamSasl requires the \"aws-msk-iam-sasl-signer-js\" package. ' +\n        'Run: npm i aws-msk-iam-sasl-signer-js. ' +\n        `(underlying error: ${(err as Error).message})`,\n    );\n  }\n}\n"],"mappings":";AAwFO,SAAS,iBACd,MACuB;AACvB,MAAI,CAAC,KAAK,QAAQ;AAChB,UAAM,IAAI,MAAM,wCAAwC;AAAA,EAC1D;AACA,QAAM,iBAAiB,KAAK,kBAAkB;AAC9C,QAAM,YAAY,KAAK,aAAa;AAEpC,MAAI,SAAqD;AACzD,MAAI,WAA6C;AACjD,MAAI,SAA8B,KAAK,UAAU;AAEjD,iBAAe,UAAqC;AAClD,QAAI,CAAC,OAAQ,UAAS,MAAM,oBAAoB;AAChD,UAAM,EAAE,QAAQ,YAAY,YAAY,oBAAoB,aAAa,IACvE;AACF,UAAM,SAAS,MAAM,OAAO,kBAAkB;AAAA,MAC5C;AAAA,MACA,GAAI,eAAe,SAAY,EAAE,WAAW,IAAI,CAAC;AAAA,MACjD,GAAI,eAAe,SAAY,EAAE,WAAW,IAAI,CAAC;AAAA,MACjD,GAAI,uBAAuB,SAAY,EAAE,mBAAmB,IAAI,CAAC;AAAA,MACjE,GAAI,iBAAiB,SAAY,EAAE,aAAa,IAAI,CAAC;AAAA,IACvD,CAAC;AAID,UAAM,WACJ,OAAO,aAAa,OAChB,OAAO,aACP,OAAO,aAAa;AAC1B,aAAS,EAAE,OAAO,OAAO,OAAO,SAAS;AACzC,WAAO,SAAS,QAAQ,SAAS;AAAA,EACnC;AAEA,SAAO;AAAA,IACL,WAAW;AAAA,IACX,MAAM,sBAAiD;AACrD,YAAM,MAAM,KAAK,IAAI;AAErB,UAAI,UAAU,OAAO,WAAW,MAAM,gBAAgB;AACpD,eAAO,SAAS,QAAQ,SAAS;AAAA,MACnC;AAGA,UAAI,CAAC,UAAU;AACb,mBAAW,QAAQ,EAAE,QAAQ,MAAM;AACjC,qBAAW;AAAA,QACb,CAAC;AAAA,MACH;AACA,aAAO;AAAA,IACT;AAAA,EACF;AACF;AAEA,SAAS,SACP,QACA,WACkB;AAIlB,QAAM,WAAW,KAAK,IAAI,OAAO,WAAW,KAAK,IAAI,GAAG,CAAC;AACzD,SAAO;AAAA,IACL,OAAO,OAAO;AAAA,IACd;AAAA,IACA;AAAA,EACF;AACF;AAEA,eAAe,sBAA6C;AAC1D,MAAI;AAEF,UAAM,MAAW,MAAM,OAAO,4BAA4B;AAG1D,QAAI,OAAO,KAAK,sBAAsB,YAAY;AAChD,aAAO,EAAE,mBAAmB,IAAI,kBAAkB;AAAA,IACpD;AACA,QAAI,OAAO,KAAK,SAAS,sBAAsB,YAAY;AACzD,aAAO,EAAE,mBAAmB,IAAI,QAAQ,kBAAkB;AAAA,IAC5D;AACA,UAAM,IAAI,MAAM,gEAA2D;AAAA,EAC7E,SAAS,KAAK;AACZ,UAAM,IAAI;AAAA,MACR,iIAEyB,IAAc,OAAO;AAAA,IAChD;AAAA,EACF;AACF;","names":[]}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@eventferry/kafka-iam",
+  "version": "0.1.0",
+  "description": "AWS MSK IAM (SASL/OAUTHBEARER over SigV4) helper for @eventferry/kafka",
+  "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",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "outbox",
+    "transactional-outbox",
+    "kafka",
+    "msk",
+    "aws-msk",
+    "aws-iam",
+    "sasl-oauthbearer",
+    "sigv4",
+    "event-driven",
+    "nodejs",
+    "typescript"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SametGoktepe/eventferry.git",
+    "directory": "packages/kafka-iam"
+  },
+  "homepage": "https://github.com/SametGoktepe/eventferry/tree/main/packages/kafka-iam#readme",
+  "bugs": "https://github.com/SametGoktepe/eventferry/issues",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@eventferry/kafka": "workspace:*"
+  },
+  "peerDependencies": {
+    "aws-msk-iam-sasl-signer-js": "^1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "aws-msk-iam-sasl-signer-js": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@eventferry/kafka": "workspace:*",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  }
+}