@memberjunction/auth-providers 5.44.0 → 5.45.1

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @memberjunction/auth-providers@5.44.0 build
+> @memberjunction/auth-providers@5.45.1 build
 > tsc && tsc-alias -f
 

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @memberjunction/auth-providers
 
+## 5.45.1
+
+### Patch Changes
+
+- @memberjunction/core@5.45.1
+- @memberjunction/global@5.45.1
+
+## 5.45.0
+
+### Patch Changes
+
+- Updated dependencies [45d121b]
+- Updated dependencies [21e33fe]
+- Updated dependencies [b7cf50f]
+- Updated dependencies [f4f11fa]
+- Updated dependencies [e370816]
+- Updated dependencies [fbee64c]
+- Updated dependencies [b2927f1]
+- Updated dependencies [c1f2d3d]
+- Updated dependencies [0b1e009]
+  - @memberjunction/core@5.45.0
+  - @memberjunction/global@5.45.0
+
 ## 5.44.0
 
 ### Minor Changes

package/dist/index.d.ts

@@ -3,5 +3,6 @@ export { BaseAuthProvider } from './BaseAuthProvider.js';
 export { AuthProviderFactory } from './AuthProviderFactory.js';
 export { TokenExpiredError } from './tokenExpiredError.js';
 export { MagicLinkProvider } from './providers/MagicLinkProvider.js';
+export { HostIdentityProvider, type HostAssertionVerifyResult, type HostAssertionError, } from './providers/HostIdentityProvider.js';
 export type { AuthProviderConfig, AuthUserInfo } from '@memberjunction/core';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AAGrE,YAAY,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AACrE,OAAO,EACL,oBAAoB,EACpB,KAAK,yBAAyB,EAC9B,KAAK,kBAAkB,GACxB,MAAM,qCAAqC,CAAC;AAG7C,YAAY,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -2,4 +2,5 @@ export { BaseAuthProvider } from './BaseAuthProvider.js';
 export { AuthProviderFactory } from './AuthProviderFactory.js';
 export { TokenExpiredError } from './tokenExpiredError.js';
 export { MagicLinkProvider } from './providers/MagicLinkProvider.js';
+export { HostIdentityProvider, } from './providers/HostIdentityProvider.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AACrE,OAAO,EACL,oBAAoB,GAGrB,MAAM,qCAAqC,CAAC"}

package/dist/providers/HostIdentityProvider.d.ts

@@ -0,0 +1,59 @@
+import { JwtPayload } from 'jsonwebtoken';
+import { AuthProviderConfig, AuthUserInfo } from '@memberjunction/core';
+import { BaseAuthProvider } from '../BaseAuthProvider.js';
+/** Why a host-assertion verification failed (mirrors the public web-widget mint error codes). */
+export type HostAssertionError = 'missing' | 'bad_signature' | 'expired' | 'no_email' | 'no_key';
+/** Result of verifying a host-signed identity assertion. `userInfo` is present iff `ok` is true. */
+export interface HostAssertionVerifyResult {
+    ok: boolean;
+    userInfo?: AuthUserInfo;
+    /** The host's opaque user id for the visitor (assertion `sub`) — audit correlation, not an MJ user id. */
+    hostUserId?: string;
+    errorCode?: HostAssertionError;
+}
+/**
+ * Authentication provider for the public web-widget **host-identity** strategy (D1).
+ *
+ * When a widget is embedded in an already-authenticated host portal, the host signs a short-lived
+ * RS256 assertion (with ITS OWN key) describing the visitor. Unlike Auth0/magic-link tokens — validated
+ * by the standard issuer→JWKS path — a host assertion is verified against a STATIC per-widget public key
+ * (stored on `WidgetInstance.HostPublicKey`) and exchanged at `POST /widget/session` for an MJ guest JWT.
+ * So this provider does NOT use the JWKS machinery: it exposes {@link VerifyHostAssertion} (static-PEM
+ * RS256 verification) + {@link extractUserInfo}, and the widget mint resolves it via the ClassFactory.
+ *
+ * SECURITY INVARIANT — key/assertion provenance MUST be independent. The party that presents a signed
+ * assertion must NOT also be able to provide or influence the public key used to verify it. If one party
+ * controlled both, the signature would prove nothing: an attacker could mint a fresh keypair, sign any
+ * claims with the private key, hand over the matching public key, and the check would trivially pass. The
+ * verifying key must therefore come from an independent trust path — here, out-of-band administrator
+ * configuration on `WidgetInstance.HostPublicKey` (the analog, for a static PEM, of pinning a trusted
+ * issuer's JWKS endpoint). That is why {@link VerifyHostAssertion} takes the PEM as a caller-supplied
+ * argument rather than reading any key material from the assertion itself: the caller (the widget mint)
+ * is responsible for sourcing the PEM from the registered widget record, never from the request payload.
+ *
+ * It still subclasses {@link BaseAuthProvider} (and registers in the same factory) so host-identity is a
+ * first-class, discoverable provider rather than ad-hoc mint code — the architecture the widget plan calls
+ * for. The base constructor builds a JWKS client from `jwksUri`; host-identity has no JWKS, so callers pass
+ * a placeholder `jwksUri` that is never contacted (verification goes through {@link VerifyHostAssertion}).
+ */
+export declare class HostIdentityProvider extends BaseAuthProvider {
+    constructor(config: AuthProviderConfig);
+    /** Host identity never uses JWKS — config is valid as long as it names the provider. */
+    validateConfig(): boolean;
+    /**
+     * Verifies a host-signed RS256 assertion against the host's STATIC public key (PEM) and extracts the
+     * asserted visitor identity. The assertion's `aud` must equal `expectedAudience` (the widget key, bound
+     * at the host) and it must carry an `email`. It must also be short-lived: it must declare its own `exp`
+     * AND be no older than {@link HOST_ASSERTION_MAX_AGE_SECONDS} since `iat` — so a misbehaving host cannot
+     * mint an unbounded token. Never throws — returns a structured result.
+     *
+     * SECURITY: `hostPublicKeyPem` MUST originate from an independent trust path (the registered
+     * `WidgetInstance.HostPublicKey`, set out-of-band by an administrator) — NEVER from the same request
+     * that carries `assertion`. Passing a key the assertion's presenter could influence defeats the
+     * signature check entirely (see the class-level SECURITY INVARIANT note).
+     */
+    VerifyHostAssertion(assertion: string | undefined, hostPublicKeyPem: string | undefined, expectedAudience: string): HostAssertionVerifyResult;
+    /** Maps a verified host-assertion payload to standard MJ identity fields. */
+    extractUserInfo(payload: JwtPayload): AuthUserInfo;
+}
+//# sourceMappingURL=HostIdentityProvider.d.ts.map

package/dist/providers/HostIdentityProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HostIdentityProvider.d.ts","sourceRoot":"","sources":["../../src/providers/HostIdentityProvider.ts"],"names":[],"mappings":"AAAA,OAAY,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACxE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1D,iGAAiG;AACjG,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,eAAe,GAAG,SAAS,GAAG,UAAU,GAAG,QAAQ,CAAC;AAUjG,oGAAoG;AACpG,MAAM,WAAW,yBAAyB;IACxC,EAAE,EAAE,OAAO,CAAC;IACZ,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,0GAA0G;IAC1G,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,kBAAkB,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBACa,oBAAqB,SAAQ,gBAAgB;gBAC5C,MAAM,EAAE,kBAAkB;IAItC,wFAAwF;IAC/E,cAAc,IAAI,OAAO;IAIlC;;;;;;;;;;;OAWG;IACH,mBAAmB,CACjB,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,gBAAgB,EAAE,MAAM,GAAG,SAAS,EACpC,gBAAgB,EAAE,MAAM,GACvB,yBAAyB;IAiC5B,6EAA6E;IAC7E,eAAe,CAAC,OAAO,EAAE,UAAU,GAAG,YAAY;CAanD"}

package/dist/providers/HostIdentityProvider.js

@@ -0,0 +1,118 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import jwt from 'jsonwebtoken';
+import { RegisterClass } from '@memberjunction/global';
+import { BaseAuthProvider } from '../BaseAuthProvider.js';
+/**
+ * Absolute ceiling on a host assertion's age (measured from its `iat`), independent of the host-chosen
+ * `exp`. Even if a host mints a long-lived — or `exp`-less — assertion, MJ refuses to accept it beyond
+ * this window. Enforces the "short-lived" contract the strategy assumes rather than trusting the host to
+ * honor it. Effective lifetime is therefore min(assertion `exp`, `iat` + this).
+ */
+const HOST_ASSERTION_MAX_AGE_SECONDS = 600; // 10 minutes
+/**
+ * Authentication provider for the public web-widget **host-identity** strategy (D1).
+ *
+ * When a widget is embedded in an already-authenticated host portal, the host signs a short-lived
+ * RS256 assertion (with ITS OWN key) describing the visitor. Unlike Auth0/magic-link tokens — validated
+ * by the standard issuer→JWKS path — a host assertion is verified against a STATIC per-widget public key
+ * (stored on `WidgetInstance.HostPublicKey`) and exchanged at `POST /widget/session` for an MJ guest JWT.
+ * So this provider does NOT use the JWKS machinery: it exposes {@link VerifyHostAssertion} (static-PEM
+ * RS256 verification) + {@link extractUserInfo}, and the widget mint resolves it via the ClassFactory.
+ *
+ * SECURITY INVARIANT — key/assertion provenance MUST be independent. The party that presents a signed
+ * assertion must NOT also be able to provide or influence the public key used to verify it. If one party
+ * controlled both, the signature would prove nothing: an attacker could mint a fresh keypair, sign any
+ * claims with the private key, hand over the matching public key, and the check would trivially pass. The
+ * verifying key must therefore come from an independent trust path — here, out-of-band administrator
+ * configuration on `WidgetInstance.HostPublicKey` (the analog, for a static PEM, of pinning a trusted
+ * issuer's JWKS endpoint). That is why {@link VerifyHostAssertion} takes the PEM as a caller-supplied
+ * argument rather than reading any key material from the assertion itself: the caller (the widget mint)
+ * is responsible for sourcing the PEM from the registered widget record, never from the request payload.
+ *
+ * It still subclasses {@link BaseAuthProvider} (and registers in the same factory) so host-identity is a
+ * first-class, discoverable provider rather than ad-hoc mint code — the architecture the widget plan calls
+ * for. The base constructor builds a JWKS client from `jwksUri`; host-identity has no JWKS, so callers pass
+ * a placeholder `jwksUri` that is never contacted (verification goes through {@link VerifyHostAssertion}).
+ */
+let HostIdentityProvider = class HostIdentityProvider extends BaseAuthProvider {
+    constructor(config) {
+        super(config);
+    }
+    /** Host identity never uses JWKS — config is valid as long as it names the provider. */
+    validateConfig() {
+        return !!this.name;
+    }
+    /**
+     * Verifies a host-signed RS256 assertion against the host's STATIC public key (PEM) and extracts the
+     * asserted visitor identity. The assertion's `aud` must equal `expectedAudience` (the widget key, bound
+     * at the host) and it must carry an `email`. It must also be short-lived: it must declare its own `exp`
+     * AND be no older than {@link HOST_ASSERTION_MAX_AGE_SECONDS} since `iat` — so a misbehaving host cannot
+     * mint an unbounded token. Never throws — returns a structured result.
+     *
+     * SECURITY: `hostPublicKeyPem` MUST originate from an independent trust path (the registered
+     * `WidgetInstance.HostPublicKey`, set out-of-band by an administrator) — NEVER from the same request
+     * that carries `assertion`. Passing a key the assertion's presenter could influence defeats the
+     * signature check entirely (see the class-level SECURITY INVARIANT note).
+     */
+    VerifyHostAssertion(assertion, hostPublicKeyPem, expectedAudience) {
+        if (!assertion) {
+            return { ok: false, errorCode: 'missing' };
+        }
+        if (!hostPublicKeyPem) {
+            return { ok: false, errorCode: 'no_key' };
+        }
+        let payload;
+        try {
+            // maxAge caps the assertion's age from `iat` regardless of the host-chosen `exp` (and requires `iat`
+            // to be present); jsonwebtoken surfaces a breach as TokenExpiredError, same as a normal expiry.
+            payload = jwt.verify(assertion, hostPublicKeyPem, {
+                algorithms: ['RS256'],
+                audience: expectedAudience,
+                maxAge: HOST_ASSERTION_MAX_AGE_SECONDS,
+            });
+        }
+        catch (e) {
+            // jsonwebtoken throws TokenExpiredError for expiry / maxAge; everything else is a signature/format fault.
+            return { ok: false, errorCode: e instanceof jwt.TokenExpiredError ? 'expired' : 'bad_signature' };
+        }
+        // Require an explicit expiry: we refuse to treat an unbounded assertion as valid even inside the maxAge
+        // window, so the host's "short-lived" contract is enforced, not merely assumed.
+        if (typeof payload.exp !== 'number') {
+            return { ok: false, errorCode: 'expired' };
+        }
+        const userInfo = this.extractUserInfo(payload);
+        if (!userInfo.email) {
+            return { ok: false, errorCode: 'no_email' };
+        }
+        const sub = typeof payload.sub === 'string' ? payload.sub : undefined;
+        return { ok: true, userInfo, hostUserId: sub };
+    }
+    /** Maps a verified host-assertion payload to standard MJ identity fields. */
+    extractUserInfo(payload) {
+        const str = (v) => (typeof v === 'string' && v ? v : undefined);
+        const email = str(payload.email);
+        const firstName = str(payload.given_name) ?? str(payload['firstName']);
+        const lastName = str(payload.family_name) ?? str(payload['lastName']);
+        return {
+            email,
+            firstName,
+            lastName,
+            fullName: str(payload.name) ?? ([firstName, lastName].filter(Boolean).join(' ') || undefined),
+            preferredUsername: email,
+        };
+    }
+};
+HostIdentityProvider = __decorate([
+    RegisterClass(BaseAuthProvider, 'host-identity'),
+    __metadata("design:paramtypes", [Object])
+], HostIdentityProvider);
+export { HostIdentityProvider };
+//# sourceMappingURL=HostIdentityProvider.js.map

package/dist/providers/HostIdentityProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HostIdentityProvider.js","sourceRoot":"","sources":["../../src/providers/HostIdentityProvider.ts"],"names":[],"mappings":";;;;;;;;;AAAA,OAAO,GAAmB,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAEvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAK1D;;;;;GAKG;AACH,MAAM,8BAA8B,GAAG,GAAG,CAAC,CAAC,aAAa;AAWzD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEI,IAAM,oBAAoB,GAA1B,MAAM,oBAAqB,SAAQ,gBAAgB;IACxD,YAAY,MAA0B;QACpC,KAAK,CAAC,MAAM,CAAC,CAAC;IAChB,CAAC;IAED,wFAAwF;IAC/E,cAAc;QACrB,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;IACrB,CAAC;IAED;;;;;;;;;;;OAWG;IACH,mBAAmB,CACjB,SAA6B,EAC7B,gBAAoC,EACpC,gBAAwB;QAExB,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC;QAC7C,CAAC;QACD,IAAI,CAAC,gBAAgB,EAAE,CAAC;YACtB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC;QAC5C,CAAC;QACD,IAAI,OAAmB,CAAC;QACxB,IAAI,CAAC;YACH,qGAAqG;YACrG,gGAAgG;YAChG,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,SAAS,EAAE,gBAAgB,EAAE;gBAChD,UAAU,EAAE,CAAC,OAAO,CAAC;gBACrB,QAAQ,EAAE,gBAAgB;gBAC1B,MAAM,EAAE,8BAA8B;aACvC,CAAe,CAAC;QACnB,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,0GAA0G;YAC1G,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,YAAY,GAAG,CAAC,iBAAiB,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,eAAe,EAAE,CAAC;QACpG,CAAC;QACD,wGAAwG;QACxG,gFAAgF;QAChF,IAAI,OAAO,OAAO,CAAC,GAAG,KAAK,QAAQ,EAAE,CAAC;YACpC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC;QAC7C,CAAC;QACD,MAAM,QAAQ,GAAG,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;QAC/C,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;YACpB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,CAAC;QAC9C,CAAC;QACD,MAAM,GAAG,GAAG,OAAO,OAAO,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;QACtE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC;IACjD,CAAC;IAED,6EAA6E;IAC7E,eAAe,CAAC,OAAmB;QACjC,MAAM,GAAG,GAAG,CAAC,CAAU,EAAsB,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QAC7F,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACjC,MAAM,SAAS,GAAG,GAAG,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC;QACvE,MAAM,QAAQ,GAAG,GAAG,CAAC,OAAO,CAAC,WAAW,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC;QACtE,OAAO;YACL,KAAK;YACL,SAAS;YACT,QAAQ;YACR,QAAQ,EAAE,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,SAAS,CAAC;YAC7F,iBAAiB,EAAE,KAAK;SACzB,CAAC;IACJ,CAAC;CACF,CAAA;AAzEY,oBAAoB;IADhC,aAAa,CAAC,gBAAgB,EAAE,eAAe,CAAC;;GACpC,oBAAoB,CAyEhC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memberjunction/auth-providers",
-  "version": "5.44.0",
+  "version": "5.45.1",
   "description": "Authentication provider interfaces, base classes, and implementations for MemberJunction",
   "type": "module",
   "main": "./dist/index.js",
@@ -11,8 +11,8 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@memberjunction/core": "5.44.0",
-    "@memberjunction/global": "5.44.0",
+    "@memberjunction/core": "5.45.1",
+    "@memberjunction/global": "5.45.1",
     "graphql": "^16.12.0",
     "jsonwebtoken": "9.0.3",
     "jwks-rsa": "^3.2.2"

package/src/index.ts

@@ -3,6 +3,11 @@ export { BaseAuthProvider } from './BaseAuthProvider.js';
 export { AuthProviderFactory } from './AuthProviderFactory.js';
 export { TokenExpiredError } from './tokenExpiredError.js';
 export { MagicLinkProvider } from './providers/MagicLinkProvider.js';
+export {
+  HostIdentityProvider,
+  type HostAssertionVerifyResult,
+  type HostAssertionError,
+} from './providers/HostIdentityProvider.js';
 
 // Re-export types consumers commonly need alongside the auth providers
 export type { AuthProviderConfig, AuthUserInfo } from '@memberjunction/core';

package/src/providers/HostIdentityProvider.ts

@@ -0,0 +1,125 @@
+import jwt, { JwtPayload } from 'jsonwebtoken';
+import { RegisterClass } from '@memberjunction/global';
+import { AuthProviderConfig, AuthUserInfo } from '@memberjunction/core';
+import { BaseAuthProvider } from '../BaseAuthProvider.js';
+
+/** Why a host-assertion verification failed (mirrors the public web-widget mint error codes). */
+export type HostAssertionError = 'missing' | 'bad_signature' | 'expired' | 'no_email' | 'no_key';
+
+/**
+ * Absolute ceiling on a host assertion's age (measured from its `iat`), independent of the host-chosen
+ * `exp`. Even if a host mints a long-lived — or `exp`-less — assertion, MJ refuses to accept it beyond
+ * this window. Enforces the "short-lived" contract the strategy assumes rather than trusting the host to
+ * honor it. Effective lifetime is therefore min(assertion `exp`, `iat` + this).
+ */
+const HOST_ASSERTION_MAX_AGE_SECONDS = 600; // 10 minutes
+
+/** Result of verifying a host-signed identity assertion. `userInfo` is present iff `ok` is true. */
+export interface HostAssertionVerifyResult {
+  ok: boolean;
+  userInfo?: AuthUserInfo;
+  /** The host's opaque user id for the visitor (assertion `sub`) — audit correlation, not an MJ user id. */
+  hostUserId?: string;
+  errorCode?: HostAssertionError;
+}
+
+/**
+ * Authentication provider for the public web-widget **host-identity** strategy (D1).
+ *
+ * When a widget is embedded in an already-authenticated host portal, the host signs a short-lived
+ * RS256 assertion (with ITS OWN key) describing the visitor. Unlike Auth0/magic-link tokens — validated
+ * by the standard issuer→JWKS path — a host assertion is verified against a STATIC per-widget public key
+ * (stored on `WidgetInstance.HostPublicKey`) and exchanged at `POST /widget/session` for an MJ guest JWT.
+ * So this provider does NOT use the JWKS machinery: it exposes {@link VerifyHostAssertion} (static-PEM
+ * RS256 verification) + {@link extractUserInfo}, and the widget mint resolves it via the ClassFactory.
+ *
+ * SECURITY INVARIANT — key/assertion provenance MUST be independent. The party that presents a signed
+ * assertion must NOT also be able to provide or influence the public key used to verify it. If one party
+ * controlled both, the signature would prove nothing: an attacker could mint a fresh keypair, sign any
+ * claims with the private key, hand over the matching public key, and the check would trivially pass. The
+ * verifying key must therefore come from an independent trust path — here, out-of-band administrator
+ * configuration on `WidgetInstance.HostPublicKey` (the analog, for a static PEM, of pinning a trusted
+ * issuer's JWKS endpoint). That is why {@link VerifyHostAssertion} takes the PEM as a caller-supplied
+ * argument rather than reading any key material from the assertion itself: the caller (the widget mint)
+ * is responsible for sourcing the PEM from the registered widget record, never from the request payload.
+ *
+ * It still subclasses {@link BaseAuthProvider} (and registers in the same factory) so host-identity is a
+ * first-class, discoverable provider rather than ad-hoc mint code — the architecture the widget plan calls
+ * for. The base constructor builds a JWKS client from `jwksUri`; host-identity has no JWKS, so callers pass
+ * a placeholder `jwksUri` that is never contacted (verification goes through {@link VerifyHostAssertion}).
+ */
+@RegisterClass(BaseAuthProvider, 'host-identity')
+export class HostIdentityProvider extends BaseAuthProvider {
+  constructor(config: AuthProviderConfig) {
+    super(config);
+  }
+
+  /** Host identity never uses JWKS — config is valid as long as it names the provider. */
+  override validateConfig(): boolean {
+    return !!this.name;
+  }
+
+  /**
+   * Verifies a host-signed RS256 assertion against the host's STATIC public key (PEM) and extracts the
+   * asserted visitor identity. The assertion's `aud` must equal `expectedAudience` (the widget key, bound
+   * at the host) and it must carry an `email`. It must also be short-lived: it must declare its own `exp`
+   * AND be no older than {@link HOST_ASSERTION_MAX_AGE_SECONDS} since `iat` — so a misbehaving host cannot
+   * mint an unbounded token. Never throws — returns a structured result.
+   *
+   * SECURITY: `hostPublicKeyPem` MUST originate from an independent trust path (the registered
+   * `WidgetInstance.HostPublicKey`, set out-of-band by an administrator) — NEVER from the same request
+   * that carries `assertion`. Passing a key the assertion's presenter could influence defeats the
+   * signature check entirely (see the class-level SECURITY INVARIANT note).
+   */
+  VerifyHostAssertion(
+    assertion: string | undefined,
+    hostPublicKeyPem: string | undefined,
+    expectedAudience: string,
+  ): HostAssertionVerifyResult {
+    if (!assertion) {
+      return { ok: false, errorCode: 'missing' };
+    }
+    if (!hostPublicKeyPem) {
+      return { ok: false, errorCode: 'no_key' };
+    }
+    let payload: JwtPayload;
+    try {
+      // maxAge caps the assertion's age from `iat` regardless of the host-chosen `exp` (and requires `iat`
+      // to be present); jsonwebtoken surfaces a breach as TokenExpiredError, same as a normal expiry.
+      payload = jwt.verify(assertion, hostPublicKeyPem, {
+        algorithms: ['RS256'],
+        audience: expectedAudience,
+        maxAge: HOST_ASSERTION_MAX_AGE_SECONDS,
+      }) as JwtPayload;
+    } catch (e) {
+      // jsonwebtoken throws TokenExpiredError for expiry / maxAge; everything else is a signature/format fault.
+      return { ok: false, errorCode: e instanceof jwt.TokenExpiredError ? 'expired' : 'bad_signature' };
+    }
+    // Require an explicit expiry: we refuse to treat an unbounded assertion as valid even inside the maxAge
+    // window, so the host's "short-lived" contract is enforced, not merely assumed.
+    if (typeof payload.exp !== 'number') {
+      return { ok: false, errorCode: 'expired' };
+    }
+    const userInfo = this.extractUserInfo(payload);
+    if (!userInfo.email) {
+      return { ok: false, errorCode: 'no_email' };
+    }
+    const sub = typeof payload.sub === 'string' ? payload.sub : undefined;
+    return { ok: true, userInfo, hostUserId: sub };
+  }
+
+  /** Maps a verified host-assertion payload to standard MJ identity fields. */
+  extractUserInfo(payload: JwtPayload): AuthUserInfo {
+    const str = (v: unknown): string | undefined => (typeof v === 'string' && v ? v : undefined);
+    const email = str(payload.email);
+    const firstName = str(payload.given_name) ?? str(payload['firstName']);
+    const lastName = str(payload.family_name) ?? str(payload['lastName']);
+    return {
+      email,
+      firstName,
+      lastName,
+      fullName: str(payload.name) ?? ([firstName, lastName].filter(Boolean).join(' ') || undefined),
+      preferredUsername: email,
+    };
+  }
+}