@learncard/partner-connect 0.2.16 → 0.3.0

package/dist/index.d.ts

@@ -10,44 +10,73 @@ export { AppEvent, AppEventResponse, CheckCredentialEvent, SendCredentialEvent }
  */
 interface PartnerConnectOptions {
     /**
-     * The origin(s) of the LearnCard host
-     *
-     * This can be a single string or an array of strings to serve as a whitelist for
-     * the `lc_host_override` query parameter.
-     *
-     * **Origin Configuration Hierarchy:**
-     * 1. **Hardcoded Default**: `https://learncard.app` (security anchor)
-     * 2. **Query Parameter Override**: `?lc_host_override=https://staging.learncard.app`
-     *    - Checked against whitelist if `hostOrigin` is provided
-     *    - Used for staging/testing environments
-     * 3. **Configured Origin**: First value in array or single string value
-     *
-     * **Security Model:**
-     * - The SDK enforces STRICT origin validation
-     * - Incoming messages must EXACTLY match the active host origin
-     * - Prevents origin spoofing: even if malicious query param is added,
-     *   messages from unauthorized origins are rejected
+     * The origin(s) of the LearnCard host.
+     *
+     * Each entry may be either an **exact origin** (`https://learncard.app`) or a
+     * **wildcard pattern** where `*` stands in for a single DNS label portion in
+     * the host portion of the origin (e.g. `https://*.learncard.app`,
+     * `https://*.vetpass.app`). Wildcards are **only** allowed in the host and
+     * only as label(s); the protocol and port must always match exactly.
+     *
+     * Wildcard patterns match any non-empty chain of labels. So
+     * `https://*.learncard.app` matches both `https://staging.learncard.app` and
+     * `https://pr-123.preview.learncard.app`, but **not** `https://learncard.app`
+     * itself (include the bare origin explicitly if you need it) and **not**
+     * `https://evil.learncard.app.attacker.com` (the suffix must match).
+     *
+     * **Origin Configuration Hierarchy at runtime:**
+     * 1. `window.location.ancestorOrigins[0]` (when available) — the real parent
+     *    origin as reported by the browser, validated against the effective
+     *    whitelist. This source cannot be spoofed by a malicious query param.
+     * 2. `?lc_host_override=<origin>` query parameter — validated against the
+     *    whitelist. Used by the LearnCard host to tell the SDK which origin it
+     *    is loading from.
+     * 3. `sessionStorage['lc_host_override']` — a previously-validated override
+     *    persisted across in-iframe navigation.
+     * 4. First value in the configured `hostOrigin` array / single string.
+     * 5. `PartnerConnect.DEFAULT_HOST_ORIGIN` (`https://learncard.app`).
+     *
+     * The partner app's configured whitelist is combined with a small built-in
+     * list of LearnCard tenant domains (see `disableDefaultTenants` to opt out).
+     * This lets a partner app work out-of-the-box inside any current or future
+     * `*.learncard.app`, `*.learncard.ai`, or `*.vetpass.app` tenant without a
+     * re-deploy.
      *
      * **Examples:**
      *
-     * Single origin (production):
+     * Single origin (production only):
      * ```typescript
      * hostOrigin: 'https://learncard.app'
-     * // Uses: https://learncard.app
-     * // Override: ?lc_host_override=https://staging.learncard.app (not validated)
      * ```
      *
-     * Multiple origins (whitelist for staging):
+     * Wildcard whitelist (covers staging + preview):
+     * ```typescript
+     * hostOrigin: ['https://learncard.app', 'https://*.learncard.app']
+     * ```
+     *
+     * Custom tenant alongside the built-in LearnCard defaults:
      * ```typescript
-     * hostOrigin: ['https://learncard.app', 'https://staging.learncard.app']
-     * // Default: https://learncard.app
-     * // Override: ?lc_host_override=https://staging.learncard.app (validated)
-     * // Invalid: ?lc_host_override=https://evil.com (rejected)
+     * hostOrigin: ['https://partner.example.com']
+     * // learncard.app / *.learncard.app / *.learncard.ai / vetpass.app / *.vetpass.app
+     * // are ALSO trusted because disableDefaultTenants is false.
      * ```
      *
      * @default 'https://learncard.app'
      */
     hostOrigin?: string | string[];
+    /**
+     * Opt out of the built-in LearnCard tenant whitelist.
+     *
+     * By default, the SDK merges `hostOrigin` with a curated list of LearnCard
+     * and tenant domains (see `PartnerConnect.DEFAULT_TRUSTED_TENANTS`) so that
+     * partner apps work on any LearnCard-managed tenant without reconfiguration.
+     *
+     * Set to `true` if you want the partner app to **only** trust the origins
+     * you pass in `hostOrigin`.
+     *
+     * @default false
+     */
+    disableDefaultTenants?: boolean;
     /**
      * Whether to allow native app origins (default: true)
      *
@@ -325,11 +354,14 @@ interface SummaryCredentialSkill {
 }
 /**
  * Next step item in summary credential data
+ *
+ * `keywords` is optional. Omit it entirely (or pass `undefined`) when you do not
+ * have taxonomy data — you no longer need to pass a struct of `null` fields.
  */
 interface SummaryCredentialNextStep {
     title: string;
     description: string;
-    keywords: SummaryCredentialKeyword;
+    keywords?: SummaryCredentialKeyword;
 }
 /**
  * Reflection item in summary credential data
@@ -431,12 +463,55 @@ interface GetCountersResponse {
  */
 type ErrorCode = 'LC_TIMEOUT' | 'LC_UNAUTHENTICATED' | 'CREDENTIAL_NOT_FOUND' | 'USER_REJECTED' | 'UNAUTHORIZED' | 'TEMPLATE_NOT_FOUND' | 'BOOST_NOT_FOUND' | 'INSUFFICIENT_PERMISSIONS' | string;
 /**
- * Error object returned when a request fails
+ * Error object returned when a request fails.
+ *
+ * Historically the SDK rejected with a plain `{ code, message }` object. As of
+ * v0.3.0 we reject with a {@link PartnerConnectError} instance instead, which
+ * still satisfies this interface (it has both `code` and `message` fields), so
+ * existing consumers that do `if (err.code === '...')` continue to work
+ * unchanged.
  */
 interface LearnCardError {
     code: ErrorCode;
     message: string;
 }
+/**
+ * Typed error class for all Partner Connect SDK rejections.
+ *
+ * Use `instanceof PartnerConnectError` to narrow caught errors and unlock
+ * exhaustive `switch` checks on `code`. Both `code` and `message` are present
+ * (so the legacy `LearnCardError` object shape is preserved), and `name` is
+ * always `'PartnerConnectError'`.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await learnCard.requestLearnerContext();
+ * } catch (err) {
+ *   if (err instanceof PartnerConnectError) {
+ *     switch (err.code) {
+ *       case 'LC_UNAUTHENTICATED': showLogin(); break;
+ *       case 'USER_REJECTED':      showPrivacyNotice(); break;
+ *       case 'UNAUTHORIZED':       showPermissionsError(); break;
+ *       default:                   console.error(err);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare class PartnerConnectError extends Error implements LearnCardError {
+    readonly code: ErrorCode;
+    constructor(code: ErrorCode, message: string);
+    /**
+     * Wrap any incoming `LearnCardError`-shaped value into a `PartnerConnectError`.
+     * Returns the value unchanged if it is already an instance.
+     *
+     * Used internally at every reject site so callers always receive a typed
+     * `PartnerConnectError`, regardless of whether the failure originated from
+     * the host (over postMessage), an SDK timeout, or `destroy()`.
+     */
+    static from(input: LearnCardError | unknown): PartnerConnectError;
+}
 /**
  * Internal message structure sent via postMessage
  */
@@ -491,6 +566,19 @@ interface PendingRequest {
 declare class PartnerConnect {
     /** Default host origin (security anchor) */
     static readonly DEFAULT_HOST_ORIGIN = "https://learncard.app";
+    /**
+     * Built-in list of LearnCard-managed tenant origins.
+     *
+     * These are merged with the partner app's configured `hostOrigin` whitelist
+     * unless `disableDefaultTenants: true` is passed. This lets a partner app
+     * run inside any current or future LearnCard tenant (staging, preview,
+     * VetPass, etc.) without needing a re-deploy each time a new tenant is
+     * onboarded.
+     *
+     * Patterns follow the same rules as user-supplied `hostOrigin` entries:
+     * `*` is a wildcard for one or more DNS labels in the host portion.
+     */
+    static readonly DEFAULT_TRUSTED_TENANTS: readonly string[];
     private hostOrigins;
     private activeHostOrigin;
     private allowNativeAppOrigins;
@@ -502,22 +590,60 @@ declare class PartnerConnect {
     constructor(options?: PartnerConnectOptions);
     /**
      * Configure the active host origin using the following hierarchy:
-     * 1. Check for `lc_host_override` query parameter (for staging/testing)
-     * 2. Check sessionStorage for a previously stored override (survives in-app navigation)
-     * 3. Fall back to first configured origin
-     * 4. Fall back to DEFAULT_HOST_ORIGIN
-     *
-     * When a valid override is found in the query parameter, it is persisted to
-     * sessionStorage so that subsequent page navigations within the same tab
-     * automatically use the same override without requiring it in every URL.
-     *
-     * This origin will be used for all outgoing messages and incoming message validation.
+     * 1. `window.location.ancestorOrigins[0]` (when supported) — the browser's
+     *    view of who our parent frame is. Cannot be forged by a malicious
+     *    `lc_host_override` query param and therefore takes precedence.
+     * 2. `?lc_host_override=<origin>` query param (for staging / cross-tenant).
+     * 3. `sessionStorage` value saved from a previously-validated override.
+     * 4. First configured origin.
+     * 5. `DEFAULT_HOST_ORIGIN`.
+     *
+     * When a valid override is found in the query parameter, it is persisted
+     * to sessionStorage so subsequent in-iframe navigations in the same tab
+     * continue to use the same active origin.
      */
     private static readonly SESSION_STORAGE_KEY;
+    /**
+     * Read `window.location.ancestorOrigins[0]` without throwing if the
+     * property is unavailable (Firefox) or the list is empty (top-level
+     * context, e.g. running outside of an iframe).
+     */
+    private readAncestorOrigin;
     private configureActiveOrigin;
+    private persistOverride;
     private isOriginNativeApp;
     /**
-     * Check if an origin is in the configured whitelist
+     * Internal placeholder substituted in for `*` so that `new URL(...)` can
+     * parse a wildcard pattern. Chosen to be a syntactically-valid DNS label
+     * that cannot collide with a real hostname.
+     */
+    private static readonly WILDCARD_PLACEHOLDER;
+    /** `*` (any number of occurrences) for replacement in the pattern. */
+    private static readonly WILDCARD_REGEX;
+    /** The required leading-label form a wildcard pattern must take. */
+    private static readonly WILDCARD_LEADING_PREFIX;
+    /**
+     * Check whether a candidate origin matches a configured whitelist entry.
+     *
+     * Supports exact matches and wildcard patterns. A wildcard entry has the
+     * form `<protocol>://*.<domain>` and matches any origin with the same
+     * protocol, same port, and a host ending in `.<domain>` with at least
+     * one non-empty DNS label in place of the `*`.
+     *
+     * Examples with pattern `https://*.learncard.app`:
+     * - `https://staging.learncard.app`      → match
+     * - `https://pr-1.preview.learncard.app` → match
+     * - `https://learncard.app`              → no match (no subdomain)
+     * - `http://staging.learncard.app`       → no match (protocol mismatch)
+     * - `https://learncard.app.attacker.com` → no match (suffix mismatch)
+     *
+     * Exposed as a public static so it can be unit-tested directly without
+     * standing up a full SDK instance.
+     */
+    static matchesOriginPattern(candidate: string, pattern: string): boolean;
+    /**
+     * Check if an origin is in the effective whitelist (exact origins +
+     * wildcard patterns + optional native-app origins).
      */
     private isOriginInWhitelist;
     /**
@@ -851,4 +977,4 @@ declare class PartnerConnect {
  */
 declare function createPartnerConnect(options?: PartnerConnectOptions): PartnerConnect;
 
-export { AppNotificationInput, AppNotificationResponse, CheckCredentialInput, CheckCredentialResponse, CheckIssuanceStatusInput, ConsentResponse, CredentialSearchResponse, CredentialSpecificResponse, ErrorCode, GetCounterResponse, GetCountersResponse, GetTemplateRecipientsInput, IdentityResponse, IncrementCounterResponse, LearnCardError, LearnerContextRawData, LearnerContextResponse, PartnerConnect, PartnerConnectOptions, PendingRequest, PostMessageRequest, PostMessageResponse, RequestConsentOptions, RequestConsentPayload, RequestLearnerContextOptions, SendAiSessionCredentialInput, SendAiSessionCredentialResponse, SendCredentialResponse, SummaryCredentialData, SummaryCredentialKeyword, SummaryCredentialNextStep, SummaryCredentialReflection, SummaryCredentialSkill, TemplateCredentialInput, TemplateCredentialResponse, TemplateIssuanceStatusResponse, TemplateIssueResponse, TemplateRecipientRecord, TemplateRecipientsResponse, VPRQuery, VerifiablePresentationRequest, createPartnerConnect, createPartnerConnect as default };
+export { AppNotificationInput, AppNotificationResponse, CheckCredentialInput, CheckCredentialResponse, CheckIssuanceStatusInput, ConsentResponse, CredentialSearchResponse, CredentialSpecificResponse, ErrorCode, GetCounterResponse, GetCountersResponse, GetTemplateRecipientsInput, IdentityResponse, IncrementCounterResponse, LearnCardError, LearnerContextRawData, LearnerContextResponse, PartnerConnect, PartnerConnectError, PartnerConnectOptions, PendingRequest, PostMessageRequest, PostMessageResponse, RequestConsentOptions, RequestConsentPayload, RequestLearnerContextOptions, SendAiSessionCredentialInput, SendAiSessionCredentialResponse, SendCredentialResponse, SummaryCredentialData, SummaryCredentialKeyword, SummaryCredentialNextStep, SummaryCredentialReflection, SummaryCredentialSkill, TemplateCredentialInput, TemplateCredentialResponse, TemplateIssuanceStatusResponse, TemplateIssueResponse, TemplateRecipientRecord, TemplateRecipientsResponse, VPRQuery, VerifiablePresentationRequest, createPartnerConnect, createPartnerConnect as default };

package/dist/partner-connect.esm.js

@@ -1,3 +1,36 @@
+var __defProp$1 = Object.defineProperty;
+var __defNormalProp$1 = (obj, key, value) => key in obj ? __defProp$1(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField$1 = (obj, key, value) => __defNormalProp$1(obj, typeof key !== "symbol" ? key + "" : key, value);
+class PartnerConnectError extends Error {
+  constructor(code, message) {
+    super(message);
+    __publicField$1(this, "code");
+    this.name = "PartnerConnectError";
+    this.code = code;
+    Object.setPrototypeOf(this, PartnerConnectError.prototype);
+  }
+  /**
+   * Wrap any incoming `LearnCardError`-shaped value into a `PartnerConnectError`.
+   * Returns the value unchanged if it is already an instance.
+   *
+   * Used internally at every reject site so callers always receive a typed
+   * `PartnerConnectError`, regardless of whether the failure originated from
+   * the host (over postMessage), an SDK timeout, or `destroy()`.
+   */
+  static from(input) {
+    if (input instanceof PartnerConnectError) return input;
+    if (input && typeof input === "object" && "code" in input && typeof input.code === "string") {
+      const candidate = input;
+      const message = typeof candidate.message === "string" ? candidate.message : "Partner Connect request failed";
+      return new PartnerConnectError(candidate.code, message);
+    }
+    return new PartnerConnectError(
+      "UNKNOWN_ERROR",
+      input instanceof Error ? input.message : "An unknown error occurred"
+    );
+  }
+}
+
 var __defProp = Object.defineProperty;
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
@@ -11,68 +44,160 @@ const _PartnerConnect = class _PartnerConnect {
     __publicField(this, "pendingRequests");
     __publicField(this, "messageListener", null);
     __publicField(this, "isInitialized", false);
-    var _a;
-    const hostOrigin = (options == null ? void 0 : options.hostOrigin) || _PartnerConnect.DEFAULT_HOST_ORIGIN;
-    this.hostOrigins = Array.isArray(hostOrigin) ? hostOrigin : [hostOrigin];
+    var _a, _b;
+    const hostOrigin = (_a = options == null ? void 0 : options.hostOrigin) != null ? _a : _PartnerConnect.DEFAULT_HOST_ORIGIN;
+    const configured = Array.isArray(hostOrigin) ? hostOrigin : [hostOrigin];
+    const disableDefaults = (options == null ? void 0 : options.disableDefaultTenants) === true;
+    const merged = disableDefaults ? [...configured] : [...configured, ..._PartnerConnect.DEFAULT_TRUSTED_TENANTS];
+    this.hostOrigins = Array.from(new Set(merged));
     this.protocol = (options == null ? void 0 : options.protocol) || "LEARNCARD_V1";
     this.requestTimeout = (options == null ? void 0 : options.requestTimeout) || 3e4;
-    this.allowNativeAppOrigins = (_a = options == null ? void 0 : options.allowNativeAppOrigins) != null ? _a : true;
+    this.allowNativeAppOrigins = (_b = options == null ? void 0 : options.allowNativeAppOrigins) != null ? _b : true;
     this.pendingRequests = /* @__PURE__ */ new Map();
     this.configureActiveOrigin();
     this.setupMessageListener();
   }
+  /**
+   * Read `window.location.ancestorOrigins[0]` without throwing if the
+   * property is unavailable (Firefox) or the list is empty (top-level
+   * context, e.g. running outside of an iframe).
+   */
+  readAncestorOrigin() {
+    if (typeof window === "undefined") return null;
+    try {
+      const ancestors = window.location.ancestorOrigins;
+      if (ancestors && ancestors.length > 0) {
+        const parent = ancestors[0];
+        if (typeof parent === "string" && parent.length > 0) {
+          return parent;
+        }
+      }
+    } catch {
+    }
+    return null;
+  }
   configureActiveOrigin() {
     if (typeof window === "undefined") {
       this.activeHostOrigin = this.hostOrigins[0] || _PartnerConnect.DEFAULT_HOST_ORIGIN;
       return;
     }
     try {
+      const ancestorOrigin = this.readAncestorOrigin();
       const urlParams = new URLSearchParams(window.location.search);
       const hostOverride = urlParams.get("lc_host_override");
-      if (hostOverride) {
-        if (this.hostOrigins.length > 0 && !this.isOriginInWhitelist(hostOverride)) {
+      if (ancestorOrigin && this.isOriginInWhitelist(ancestorOrigin)) {
+        if (hostOverride && hostOverride !== ancestorOrigin) {
           console.warn(
-            "[LearnCard SDK] lc_host_override value is not in the configured whitelist:",
-            hostOverride,
-            "Allowed:",
-            this.hostOrigins
+            "[LearnCard SDK] lc_host_override does not match the real parent origin; preferring parent.",
+            { override: hostOverride, parent: ancestorOrigin }
           );
-          this.activeHostOrigin = this.hostOrigins[0] || _PartnerConnect.DEFAULT_HOST_ORIGIN;
-        } else {
+        }
+        this.activeHostOrigin = ancestorOrigin;
+        this.persistOverride(ancestorOrigin);
+        console.log("[LearnCard SDK] Using parent origin:", ancestorOrigin);
+        return;
+      }
+      if (hostOverride) {
+        if (this.isOriginInWhitelist(hostOverride)) {
           this.activeHostOrigin = hostOverride;
-          try {
-            sessionStorage.setItem(_PartnerConnect.SESSION_STORAGE_KEY, hostOverride);
-          } catch {
-          }
+          this.persistOverride(hostOverride);
           console.log("[LearnCard SDK] Using lc_host_override:", hostOverride);
+          return;
         }
-      } else {
-        let storedOverride = null;
-        try {
-          storedOverride = sessionStorage.getItem(_PartnerConnect.SESSION_STORAGE_KEY);
-        } catch {
-        }
-        if (storedOverride && this.isOriginInWhitelist(storedOverride)) {
-          this.activeHostOrigin = storedOverride;
-          console.log("[LearnCard SDK] Using stored lc_host_override:", storedOverride);
-        } else {
-          this.activeHostOrigin = this.hostOrigins[0] || _PartnerConnect.DEFAULT_HOST_ORIGIN;
-          console.log("[LearnCard SDK] Using configured origin:", this.activeHostOrigin);
-        }
+        console.warn(
+          "[LearnCard SDK] lc_host_override value is not in the configured whitelist:",
+          hostOverride,
+          "Allowed:",
+          this.hostOrigins
+        );
       }
+      let storedOverride = null;
+      try {
+        storedOverride = sessionStorage.getItem(_PartnerConnect.SESSION_STORAGE_KEY);
+      } catch {
+      }
+      if (storedOverride && this.isOriginInWhitelist(storedOverride)) {
+        this.activeHostOrigin = storedOverride;
+        console.log("[LearnCard SDK] Using stored lc_host_override:", storedOverride);
+        return;
+      }
+      this.activeHostOrigin = this.hostOrigins[0] || _PartnerConnect.DEFAULT_HOST_ORIGIN;
+      console.log("[LearnCard SDK] Using configured origin:", this.activeHostOrigin);
     } catch (error) {
       console.error("[LearnCard SDK] Error configuring active origin:", error);
       this.activeHostOrigin = this.hostOrigins[0] || _PartnerConnect.DEFAULT_HOST_ORIGIN;
     }
   }
+  persistOverride(origin) {
+    try {
+      sessionStorage.setItem(_PartnerConnect.SESSION_STORAGE_KEY, origin);
+    } catch {
+    }
+  }
   isOriginNativeApp(origin) {
     return origin.startsWith("capacitor://") || origin.startsWith("ionic://") || origin.startsWith("https://localhost") || origin.startsWith("http://localhost") || origin.startsWith("http://127.0.0.1");
   }
   /**
-   * Check if an origin is in the configured whitelist
+   * Check whether a candidate origin matches a configured whitelist entry.
+   *
+   * Supports exact matches and wildcard patterns. A wildcard entry has the
+   * form `<protocol>://*.<domain>` and matches any origin with the same
+   * protocol, same port, and a host ending in `.<domain>` with at least
+   * one non-empty DNS label in place of the `*`.
+   *
+   * Examples with pattern `https://*.learncard.app`:
+   * - `https://staging.learncard.app`      → match
+   * - `https://pr-1.preview.learncard.app` → match
+   * - `https://learncard.app`              → no match (no subdomain)
+   * - `http://staging.learncard.app`       → no match (protocol mismatch)
+   * - `https://learncard.app.attacker.com` → no match (suffix mismatch)
+   *
+   * Exposed as a public static so it can be unit-tested directly without
+   * standing up a full SDK instance.
+   */
+  static matchesOriginPattern(candidate, pattern) {
+    if (candidate === pattern) return true;
+    if (!pattern.includes("*")) return false;
+    let patternUrl;
+    let candidateUrl;
+    try {
+      patternUrl = new URL(
+        pattern.replace(
+          _PartnerConnect.WILDCARD_REGEX,
+          _PartnerConnect.WILDCARD_PLACEHOLDER
+        )
+      );
+      candidateUrl = new URL(candidate);
+    } catch {
+      return false;
+    }
+    if (patternUrl.protocol !== candidateUrl.protocol) return false;
+    if (patternUrl.port !== candidateUrl.port) return false;
+    const patternHost = patternUrl.hostname;
+    const candidateHost = candidateUrl.hostname;
+    if (!patternHost.startsWith(_PartnerConnect.WILDCARD_LEADING_PREFIX)) return false;
+    const patternSuffix = patternHost.slice(_PartnerConnect.WILDCARD_LEADING_PREFIX.length);
+    if (patternSuffix.length === 0) return false;
+    if (patternSuffix.includes(_PartnerConnect.WILDCARD_PLACEHOLDER)) return false;
+    const required = "." + patternSuffix;
+    if (!candidateHost.endsWith(required)) return false;
+    const prefix = candidateHost.slice(0, candidateHost.length - required.length);
+    if (prefix.length === 0) return false;
+    if (prefix.startsWith(".") || prefix.endsWith(".")) return false;
+    if (prefix.split(".").some((label) => label.length === 0)) return false;
+    return true;
+  }
+  /**
+   * Check if an origin is in the effective whitelist (exact origins +
+   * wildcard patterns + optional native-app origins).
    */
   isOriginInWhitelist(origin) {
-    return this.hostOrigins.includes(origin) || this.allowNativeAppOrigins && this.isOriginNativeApp(origin);
+    if (!origin) return false;
+    for (const entry of this.hostOrigins) {
+      if (_PartnerConnect.matchesOriginPattern(origin, entry)) return true;
+    }
+    if (this.allowNativeAppOrigins && this.isOriginNativeApp(origin)) return true;
+    return false;
   }
   /**
    * Check if an event origin is valid against the active host origin
@@ -111,7 +236,12 @@ const _PartnerConnect = class _PartnerConnect {
         pending.resolve(data.data);
       } else if (data.type === "ERROR") {
         pending.reject(
-          data.error || { code: "UNKNOWN_ERROR", message: "An unknown error occurred" }
+          PartnerConnectError.from(
+            data.error || {
+              code: "UNKNOWN_ERROR",
+              message: "An unknown error occurred"
+            }
+          )
         );
       }
     };
@@ -129,20 +259,21 @@ const _PartnerConnect = class _PartnerConnect {
    */
   sendMessage(action, payload) {
     if (!this.isInitialized) {
-      return Promise.reject({
-        code: "SDK_NOT_INITIALIZED",
-        message: "SDK is not initialized"
-      });
+      return Promise.reject(
+        new PartnerConnectError("SDK_NOT_INITIALIZED", "SDK is not initialized")
+      );
     }
     return new Promise((resolve, reject) => {
       const requestId = this.generateRequestId(action);
       const timeoutId = setTimeout(() => {
         if (this.pendingRequests.has(requestId)) {
           this.pendingRequests.delete(requestId);
-          reject({
-            code: "LC_TIMEOUT",
-            message: `Request ${action} timed out after ${this.requestTimeout}ms`
-          });
+          reject(
+            new PartnerConnectError(
+              "LC_TIMEOUT",
+              `Request ${action} timed out after ${this.requestTimeout}ms`
+            )
+          );
         }
       }, this.requestTimeout);
       this.pendingRequests.set(requestId, {
@@ -544,10 +675,12 @@ const _PartnerConnect = class _PartnerConnect {
     }
     for (const [requestId, pending] of this.pendingRequests.entries()) {
       clearTimeout(pending.timeoutId);
-      pending.reject({
-        code: "SDK_DESTROYED",
-        message: "SDK was destroyed before request completed"
-      });
+      pending.reject(
+        new PartnerConnectError(
+          "SDK_DESTROYED",
+          "SDK was destroyed before request completed"
+        )
+      );
     }
     this.pendingRequests.clear();
     this.isInitialized = false;
@@ -556,23 +689,53 @@ const _PartnerConnect = class _PartnerConnect {
 /** Default host origin (security anchor) */
 __publicField(_PartnerConnect, "DEFAULT_HOST_ORIGIN", "https://learncard.app");
 /**
- * Configure the active host origin using the following hierarchy:
- * 1. Check for `lc_host_override` query parameter (for staging/testing)
- * 2. Check sessionStorage for a previously stored override (survives in-app navigation)
- * 3. Fall back to first configured origin
- * 4. Fall back to DEFAULT_HOST_ORIGIN
+ * Built-in list of LearnCard-managed tenant origins.
  *
- * When a valid override is found in the query parameter, it is persisted to
- * sessionStorage so that subsequent page navigations within the same tab
- * automatically use the same override without requiring it in every URL.
+ * These are merged with the partner app's configured `hostOrigin` whitelist
+ * unless `disableDefaultTenants: true` is passed. This lets a partner app
+ * run inside any current or future LearnCard tenant (staging, preview,
+ * VetPass, etc.) without needing a re-deploy each time a new tenant is
+ * onboarded.
  *
- * This origin will be used for all outgoing messages and incoming message validation.
+ * Patterns follow the same rules as user-supplied `hostOrigin` entries:
+ * `*` is a wildcard for one or more DNS labels in the host portion.
+ */
+__publicField(_PartnerConnect, "DEFAULT_TRUSTED_TENANTS", [
+  "https://learncard.app",
+  "https://*.learncard.app",
+  "https://*.learncard.ai",
+  "https://vetpass.app",
+  "https://*.vetpass.app"
+]);
+/**
+ * Configure the active host origin using the following hierarchy:
+ * 1. `window.location.ancestorOrigins[0]` (when supported) — the browser's
+ *    view of who our parent frame is. Cannot be forged by a malicious
+ *    `lc_host_override` query param and therefore takes precedence.
+ * 2. `?lc_host_override=<origin>` query param (for staging / cross-tenant).
+ * 3. `sessionStorage` value saved from a previously-validated override.
+ * 4. First configured origin.
+ * 5. `DEFAULT_HOST_ORIGIN`.
+ *
+ * When a valid override is found in the query parameter, it is persisted
+ * to sessionStorage so subsequent in-iframe navigations in the same tab
+ * continue to use the same active origin.
  */
 __publicField(_PartnerConnect, "SESSION_STORAGE_KEY", "lc_host_override");
+/**
+ * Internal placeholder substituted in for `*` so that `new URL(...)` can
+ * parse a wildcard pattern. Chosen to be a syntactically-valid DNS label
+ * that cannot collide with a real hostname.
+ */
+__publicField(_PartnerConnect, "WILDCARD_PLACEHOLDER", "__lc_wildcard__");
+/** `*` (any number of occurrences) for replacement in the pattern. */
+__publicField(_PartnerConnect, "WILDCARD_REGEX", /\*/g);
+/** The required leading-label form a wildcard pattern must take. */
+__publicField(_PartnerConnect, "WILDCARD_LEADING_PREFIX", `${_PartnerConnect.WILDCARD_PLACEHOLDER}.`);
 let PartnerConnect = _PartnerConnect;
 function createPartnerConnect(options) {
   return new PartnerConnect(options);
 }
 
-export { PartnerConnect, createPartnerConnect, createPartnerConnect as default };
+export { PartnerConnect, PartnerConnectError, createPartnerConnect, createPartnerConnect as default };
 //# sourceMappingURL=partner-connect.esm.js.map