@glideidentity/glide-be-sdk-node 2.0.1 → 2.1.0

package/dist/device-binding.d.ts

@@ -0,0 +1,110 @@
+/** Cookie name prefix for device binding codes. Append the session key for the full name. */
+export declare const BINDING_COOKIE_PREFIX = "_glide_bind_";
+/** Cookie max-age in seconds (10 minutes, matches session TTL). */
+export declare const BINDING_COOKIE_MAX_AGE = 600;
+/**
+ * Returns the full cookie name for a given session key.
+ *
+ * Using a session-scoped name (`_glide_bind_{sessionKey}`) ensures that
+ * parallel `prepare()` calls from the same browser don't overwrite each
+ * other's cookies — each session gets its own cookie.
+ */
+export declare function getBindingCookieName(sessionKey: string): string;
+/**
+ * Regex matching a valid 64-character hex string (case-insensitive).
+ *
+ * Accepts both lowercase and uppercase hex so that external inputs (URL
+ * fragments, cookie values) still pass validation even if a proxy or
+ * browser extension uppercases them.  Internal code normalises to
+ * lowercase before hashing or sending to the aggregator.
+ */
+export declare const HEX_64: RegExp;
+/**
+ * Asserts that the given value is a valid 64-character hex string.
+ * @throws {Error} If the value does not match.
+ */
+export declare function assertValidFeCode(feCode: string): void;
+/**
+ * Generates a cryptographically random device binding code.
+ * @returns 64-character lowercase hex string (32 random bytes).
+ */
+export declare function generateFeCode(): string;
+/**
+ * Computes the SHA-256 hash of a device binding code.
+ * @param feCode - The 64-character hex binding code (case-insensitive input, normalised to lowercase).
+ * @returns 64-character lowercase hex SHA-256 hash.
+ */
+export declare function computeFeHash(feCode: string): string;
+export interface BindingCookieOptions {
+    /** Cookie domain. Must match the completion redirect URL domain. */
+    domain?: string;
+    /** Cookie path. Defaults to '/'. */
+    path?: string;
+    /**
+     * Whether to set the Secure flag. Defaults to `true`.
+     *
+     * Set to `false` only for local development over plain HTTP.
+     * In production this MUST remain `true`.
+     */
+    secure?: boolean;
+}
+/**
+ * Builds the Set-Cookie header value to store the device binding code.
+ *
+ * @param feCode     - The binding code to store (64-char hex, normalised to lowercase).
+ * @param sessionKey - The session key — used in the cookie name to avoid collisions between parallel sessions.
+ * @param options    - Optional domain/path overrides.
+ * @returns A complete Set-Cookie header value string.
+ */
+export declare function buildSetBindingCookieHeader(feCode: string, sessionKey: string, options?: BindingCookieOptions): string;
+/**
+ * Builds the Set-Cookie header value to clear the device binding cookie.
+ *
+ * @param sessionKey - The session key — identifies which session's cookie to clear.
+ * @param options    - Optional domain/path (must match the original cookie).
+ * @returns A complete Set-Cookie header value string that expires the cookie.
+ */
+export declare function buildClearBindingCookieHeader(sessionKey: string, options?: BindingCookieOptions): string;
+/**
+ * Parses the device binding code from a raw Cookie header string for a specific session.
+ *
+ * Returns `undefined` if the cookie is not present or the value is not
+ * a valid 64-character hex string.  When found, the value is normalised
+ * to lowercase for deterministic hashing downstream.
+ *
+ * @param cookieHeader - The raw `Cookie` header value (e.g., "foo=bar; _glide_bind_abc123=...").
+ * @param sessionKey   - The session key that identifies the cookie to look for.
+ * @returns The fe_code value (lowercase), or undefined if the cookie is not present or invalid.
+ */
+export declare function parseBindingCookie(cookieHeader: string | undefined, sessionKey: string): string | undefined;
+/**
+ * Builds Set-Cookie headers that expire all previous device binding cookies
+ * found in the request.
+ *
+ * Only one Link flow can be active per browser at a time (App Clip is a
+ * single native process), so stale cookies from abandoned flows must be
+ * cleared to prevent the old redirect from completing with an outdated
+ * binding code.
+ *
+ * @param cookieHeader - The raw `Cookie` request header.
+ * @param options      - Cookie options (secure, domain, path) — must match the original set call.
+ * @returns Array of Set-Cookie header values that expire stale binding cookies.
+ */
+export declare function clearStaleBindingCookies(cookieHeader: string | undefined, options?: BindingCookieOptions): string[];
+/**
+ * Returns the HTML for the completion redirect page.
+ *
+ * This page extracts `agg_code` and `session_key` from the URL fragment,
+ * POSTs them to the developer's backend (which auto-includes the
+ * `_glide_bind_{sessionKey}` HttpOnly cookie), and displays the result.
+ *
+ * On successful completion, a **localStorage signal** is written
+ * (`glide_signal_{session_key}`) so the FE SDK in the original tab can
+ * detect completion via `StorageEvent` without polling.  The signal is
+ * automatically cleaned up after 5 seconds.
+ *
+ * @param completeEndpoint - The developer backend endpoint to POST to (e.g., "/api/glide/complete").
+ * @returns Complete HTML string ready to serve.
+ */
+export declare function getCompletionPageHtml(completeEndpoint: string): string;
+//# sourceMappingURL=device-binding.d.ts.map

package/dist/device-binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-binding.d.ts","sourceRoot":"","sources":["../src/device-binding.ts"],"names":[],"mappings":"AAMA,6FAA6F;AAC7F,eAAO,MAAM,qBAAqB,iBAAiB,CAAC;AAEpD,mEAAmE;AACnE,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAE1C;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAK/D;AAMD;;;;;;;GAOG;AACH,eAAO,MAAM,MAAM,QAAsB,CAAC;AAE1C;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAItD;AAMD;;;GAGG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAIpD;AAMD,MAAM,WAAW,oBAAoB;IACjC,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oCAAoC;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CACpB;AAeD;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,MAAM,CAoBtH;AAED;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,MAAM,CAoBxG;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAU3G;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,MAAM,EAAE,CAmBnH;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,gBAAgB,EAAE,MAAM,GAAG,MAAM,CAqGtE"}

package/dist/device-binding.js

@@ -0,0 +1,321 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HEX_64 = exports.BINDING_COOKIE_MAX_AGE = exports.BINDING_COOKIE_PREFIX = void 0;
+exports.getBindingCookieName = getBindingCookieName;
+exports.assertValidFeCode = assertValidFeCode;
+exports.generateFeCode = generateFeCode;
+exports.computeFeHash = computeFeHash;
+exports.buildSetBindingCookieHeader = buildSetBindingCookieHeader;
+exports.buildClearBindingCookieHeader = buildClearBindingCookieHeader;
+exports.parseBindingCookie = parseBindingCookie;
+exports.clearStaleBindingCookies = clearStaleBindingCookies;
+exports.getCompletionPageHtml = getCompletionPageHtml;
+const crypto_1 = require("crypto");
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Cookie name prefix for device binding codes. Append the session key for the full name. */
+exports.BINDING_COOKIE_PREFIX = '_glide_bind_';
+/** Cookie max-age in seconds (10 minutes, matches session TTL). */
+exports.BINDING_COOKIE_MAX_AGE = 600;
+/**
+ * Returns the full cookie name for a given session key.
+ *
+ * Using a session-scoped name (`_glide_bind_{sessionKey}`) ensures that
+ * parallel `prepare()` calls from the same browser don't overwrite each
+ * other's cookies — each session gets its own cookie.
+ */
+function getBindingCookieName(sessionKey) {
+    if (!sessionKey || UNSAFE_COOKIE_ATTR.test(sessionKey) || sessionKey.includes('=')) {
+        throw new Error('Invalid sessionKey for cookie name: must not be empty or contain ";", "=", "\\r", or "\\n"');
+    }
+    return `${exports.BINDING_COOKIE_PREFIX}${sessionKey}`;
+}
+// ---------------------------------------------------------------------------
+// Shared validation
+// ---------------------------------------------------------------------------
+/**
+ * Regex matching a valid 64-character hex string (case-insensitive).
+ *
+ * Accepts both lowercase and uppercase hex so that external inputs (URL
+ * fragments, cookie values) still pass validation even if a proxy or
+ * browser extension uppercases them.  Internal code normalises to
+ * lowercase before hashing or sending to the aggregator.
+ */
+exports.HEX_64 = /^[0-9a-fA-F]{64}$/;
+/**
+ * Asserts that the given value is a valid 64-character hex string.
+ * @throws {Error} If the value does not match.
+ */
+function assertValidFeCode(feCode) {
+    if (!exports.HEX_64.test(feCode)) {
+        throw new Error('feCode must be a 64-character hex string');
+    }
+}
+// ---------------------------------------------------------------------------
+// Crypto utilities
+// ---------------------------------------------------------------------------
+/**
+ * Generates a cryptographically random device binding code.
+ * @returns 64-character lowercase hex string (32 random bytes).
+ */
+function generateFeCode() {
+    return (0, crypto_1.randomBytes)(32).toString('hex');
+}
+/**
+ * Computes the SHA-256 hash of a device binding code.
+ * @param feCode - The 64-character hex binding code (case-insensitive input, normalised to lowercase).
+ * @returns 64-character lowercase hex SHA-256 hash.
+ */
+function computeFeHash(feCode) {
+    assertValidFeCode(feCode);
+    // Normalise to lowercase so the hash is deterministic regardless of input case.
+    return (0, crypto_1.createHash)('sha256').update(feCode.toLowerCase()).digest('hex');
+}
+/** Characters that must not appear in cookie attribute values (prevents header/cookie injection). */
+const UNSAFE_COOKIE_ATTR = /[;\r\n]/;
+function validateCookieAttr(name, value) {
+    if (value === undefined)
+        return;
+    if (UNSAFE_COOKIE_ATTR.test(value)) {
+        throw new Error(`Invalid cookie ${name}: must not contain ';', '\\r', or '\\n'`);
+    }
+    if (name === 'path' && (value.length === 0 || !value.startsWith('/'))) {
+        throw new Error(`Invalid cookie path: must start with '/'`);
+    }
+}
+/**
+ * Builds the Set-Cookie header value to store the device binding code.
+ *
+ * @param feCode     - The binding code to store (64-char hex, normalised to lowercase).
+ * @param sessionKey - The session key — used in the cookie name to avoid collisions between parallel sessions.
+ * @param options    - Optional domain/path overrides.
+ * @returns A complete Set-Cookie header value string.
+ */
+function buildSetBindingCookieHeader(feCode, sessionKey, options) {
+    assertValidFeCode(feCode);
+    validateCookieAttr('domain', options?.domain);
+    validateCookieAttr('path', options?.path);
+    const secure = options?.secure ?? true;
+    const cookieName = getBindingCookieName(sessionKey);
+    const parts = [
+        `${cookieName}=${feCode.toLowerCase()}`,
+        'HttpOnly',
+        'SameSite=Lax',
+        `Path=${options?.path ?? '/'}`,
+        `Max-Age=${exports.BINDING_COOKIE_MAX_AGE}`,
+    ];
+    if (secure) {
+        parts.push('Secure');
+    }
+    if (options?.domain) {
+        parts.push(`Domain=${options.domain}`);
+    }
+    return parts.join('; ');
+}
+/**
+ * Builds the Set-Cookie header value to clear the device binding cookie.
+ *
+ * @param sessionKey - The session key — identifies which session's cookie to clear.
+ * @param options    - Optional domain/path (must match the original cookie).
+ * @returns A complete Set-Cookie header value string that expires the cookie.
+ */
+function buildClearBindingCookieHeader(sessionKey, options) {
+    validateCookieAttr('domain', options?.domain);
+    validateCookieAttr('path', options?.path);
+    const secure = options?.secure ?? true;
+    const cookieName = getBindingCookieName(sessionKey);
+    const parts = [
+        `${cookieName}=`,
+        'HttpOnly',
+        'SameSite=Lax',
+        `Path=${options?.path ?? '/'}`,
+        'Max-Age=0',
+        'Expires=Thu, 01 Jan 1970 00:00:00 GMT',
+    ];
+    if (secure) {
+        parts.push('Secure');
+    }
+    if (options?.domain) {
+        parts.push(`Domain=${options.domain}`);
+    }
+    return parts.join('; ');
+}
+/**
+ * Parses the device binding code from a raw Cookie header string for a specific session.
+ *
+ * Returns `undefined` if the cookie is not present or the value is not
+ * a valid 64-character hex string.  When found, the value is normalised
+ * to lowercase for deterministic hashing downstream.
+ *
+ * @param cookieHeader - The raw `Cookie` header value (e.g., "foo=bar; _glide_bind_abc123=...").
+ * @param sessionKey   - The session key that identifies the cookie to look for.
+ * @returns The fe_code value (lowercase), or undefined if the cookie is not present or invalid.
+ */
+function parseBindingCookie(cookieHeader, sessionKey) {
+    if (!cookieHeader)
+        return undefined;
+    const cookieName = getBindingCookieName(sessionKey);
+    const prefix = `${cookieName}=`;
+    const match = cookieHeader.split(';')
+        .map(c => c.trim())
+        .find(c => c.startsWith(prefix));
+    if (!match)
+        return undefined;
+    const value = match.substring(prefix.length);
+    return exports.HEX_64.test(value) ? value.toLowerCase() : undefined;
+}
+/**
+ * Builds Set-Cookie headers that expire all previous device binding cookies
+ * found in the request.
+ *
+ * Only one Link flow can be active per browser at a time (App Clip is a
+ * single native process), so stale cookies from abandoned flows must be
+ * cleared to prevent the old redirect from completing with an outdated
+ * binding code.
+ *
+ * @param cookieHeader - The raw `Cookie` request header.
+ * @param options      - Cookie options (secure, domain, path) — must match the original set call.
+ * @returns Array of Set-Cookie header values that expire stale binding cookies.
+ */
+function clearStaleBindingCookies(cookieHeader, options) {
+    if (!cookieHeader)
+        return [];
+    const headers = [];
+    for (const pair of cookieHeader.split(';')) {
+        const name = pair.trim().split('=')[0];
+        if (name.startsWith(exports.BINDING_COOKIE_PREFIX)) {
+            const sessionSuffix = name.substring(exports.BINDING_COOKIE_PREFIX.length);
+            if (!sessionSuffix)
+                continue; // Skip empty suffix (malformed cookie name)
+            try {
+                headers.push(buildClearBindingCookieHeader(sessionSuffix, options));
+            }
+            catch (_) {
+                // Malformed session suffix (injection chars) — skip silently.
+                // Option validation errors (domain/path) also caught here, but since
+                // options are caller-provided and identical for every iteration,
+                // an invalid option means ALL iterations would throw anyway.
+            }
+        }
+    }
+    return headers;
+}
+// ---------------------------------------------------------------------------
+// Completion redirect page
+// ---------------------------------------------------------------------------
+/**
+ * Returns the HTML for the completion redirect page.
+ *
+ * This page extracts `agg_code` and `session_key` from the URL fragment,
+ * POSTs them to the developer's backend (which auto-includes the
+ * `_glide_bind_{sessionKey}` HttpOnly cookie), and displays the result.
+ *
+ * On successful completion, a **localStorage signal** is written
+ * (`glide_signal_{session_key}`) so the FE SDK in the original tab can
+ * detect completion via `StorageEvent` without polling.  The signal is
+ * automatically cleaned up after 5 seconds.
+ *
+ * @param completeEndpoint - The developer backend endpoint to POST to (e.g., "/api/glide/complete").
+ * @returns Complete HTML string ready to serve.
+ */
+function getCompletionPageHtml(completeEndpoint) {
+    if (!completeEndpoint.startsWith('/') || completeEndpoint.startsWith('//')) {
+        throw new Error('completeEndpoint must be a relative path starting with "/" (e.g., "/api/glide/complete"). ' +
+            'Cross-origin and protocol-relative endpoints (e.g., "//evil.com/...") are not supported because ' +
+            'the page relies on credentials: "include" for cookie-based device binding, which requires same-origin requests.');
+    }
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; connect-src 'self'">
+<title>Completing verification...</title>
+<style>
+  body { font-family: system-ui, -apple-system, sans-serif; display: flex; justify-content: center; align-items: center; min-height: 100vh; margin: 0; background: #fafafa; color: #333; }
+  .card { text-align: center; padding: 2rem; max-width: 400px; }
+  .spinner { width: 40px; height: 40px; border: 3px solid #e0e0e0; border-top-color: #333; border-radius: 50%; animation: spin 0.8s linear infinite; margin: 0 auto 1rem; }
+  @keyframes spin { to { transform: rotate(360deg); } }
+  .hidden { display: none; }
+  .error { color: #c62828; }
+  .success { color: #2e7d32; }
+  .close-hint { margin-top: 0.75rem; font-size: 0.875rem; color: #888; }
+</style>
+</head>
+<body>
+<div class="card">
+  <div id="loading" role="status" aria-live="polite">
+    <div class="spinner"></div>
+    <p>Completing verification&hellip;</p>
+  </div>
+  <div id="success" class="hidden" role="status" aria-live="polite">
+    <p class="success">Verification complete.</p>
+    <p id="close-hint" class="close-hint hidden">You may now close this tab.</p>
+  </div>
+  <div id="error" class="hidden" role="alert" aria-live="assertive">
+    <p class="error" id="error-message">Verification failed.</p>
+  </div>
+</div>
+<script>
+(async function() {
+  var fragment = new URLSearchParams(window.location.hash.substring(1));
+  var aggCode = fragment.get('agg_code');
+  var sessionKey = fragment.get('session_key');
+
+  window.history.replaceState(null, '', window.location.pathname + window.location.search);
+
+  if (!aggCode || !sessionKey) {
+    show('error', 'Invalid completion link.');
+    return;
+  }
+
+  try {
+    var res = await fetch(${JSON.stringify(completeEndpoint)}, {
+      method: 'POST',
+      credentials: 'include',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ agg_code: aggCode, session_key: sessionKey, user_agent: navigator.userAgent })
+    });
+
+    if (res.ok) {
+      var signalKey = 'glide_signal_' + sessionKey;
+      try {
+        localStorage.setItem(signalKey, sessionKey);
+        setTimeout(function() {
+          try { localStorage.removeItem(signalKey); } catch(e) {}
+        }, 5000);
+      } catch(e) {}
+
+      show('success');
+      setTimeout(function() { tryClose(); }, 1500);
+    } else {
+      var errMsg = 'Verification failed. Please try again.';
+      try {
+        var data = await res.json();
+        if (data && data.message) errMsg = data.message;
+      } catch (_) {}
+      show('error', errMsg);
+    }
+  } catch (e) {
+    show('error', 'Network error. Please try again.');
+  }
+
+  function tryClose() {
+    window.close();
+    try { window.open('', '_self').close(); } catch(e) {}
+    setTimeout(function() {
+      document.getElementById('close-hint').classList.remove('hidden');
+    }, 200);
+  }
+
+  function show(id, msg) {
+    document.getElementById('loading').classList.add('hidden');
+    document.getElementById(id).classList.remove('hidden');
+    if (msg) document.getElementById('error-message').textContent = msg;
+  }
+})();
+</script>
+</body>
+</html>`;
+}

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uCAAuC,CAAC;AAClE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uCAAuC,CAAC;AAE3E,OAAO,EAAE,SAAS,EAAE,CAAC;AACrB,YAAY,EAAE,aAAa,EAAE,CAAC;AAE9B;;;;;;;;;;;GAWG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACvC,SAAgB,IAAI,sBAAsB;IAC1C,+CAA+C;IAC/C,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,wBAAwB;IACxB,SAAgB,MAAM,EAAE,MAAM,CAAC;IAC/B,gCAAgC;IAChC,SAAgB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnC,SAAgB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnC,SAAgB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjC,SAAgB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChC,SAAgB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjC,SAAgB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAEtC,aAAa,EAAE;QACvB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACrC;IAsBD,kDAAkD;IAClD,EAAE,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO;IAIhC,MAAM;;;;;;;;;;;CAqBT"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uCAAuC,CAAC;AAClE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uCAAuC,CAAC;AAE3E,OAAO,EAAE,SAAS,EAAE,CAAC;AACrB,YAAY,EAAE,aAAa,EAAE,CAAC;AAE9B;;;;;;;;;;;GAWG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACvC,SAAgB,IAAI,sBAAsB;IAC1C,+CAA+C;IAC/C,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,wBAAwB;IACxB,SAAgB,MAAM,EAAE,MAAM,CAAC;IAC/B,gCAAgC;IAChC,SAAgB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnC,SAAgB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnC,SAAgB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjC,SAAgB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChC,SAAgB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjC,SAAgB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAEtC,aAAa,EAAE;QACvB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACrC;IAsBD,kDAAkD;IAClD,EAAE,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO;IAIhC,MAAM;;;;;;;;;;;CAaT"}

package/dist/errors.js

@@ -52,14 +52,5 @@ class MagicalAuthError extends Error {
             details: this.details
         };
     }
-    /** Custom inspect for cleaner console output (Node.js). */
-    [Symbol.for('nodejs.util.inspect.custom')]() {
-        const props = [`code: '${this.code}'`, `status: ${this.status}`];
-        if (this.requestId)
-            props.push(`requestId: '${this.requestId}'`);
-        if (this.details)
-            props.push(`details: ${JSON.stringify(this.details)}`);
-        return `MagicalAuthError: ${this.message} { ${props.join(', ')} }`;
-    }
 }
 exports.MagicalAuthError = MagicalAuthError;

package/dist/index.d.ts

@@ -1,11 +1,13 @@
 export * from '@glideidentity/glide-be-sdk-node-core';
-export type { GlideSdkSettings, LogFormat, TokenResponse, CachedToken } from './types';
+export type { GlideSdkSettings, LogFormat, TokenResponse, CachedToken, PrepareResult } from './types';
 export { GlideClient } from './glide';
 export type { Logger, LogField } from './logger';
 export { LogLevel, createLogger, generateRequestId } from './logger';
 export { MagicalAuthError } from './errors';
 export { validatePhoneNumber, validatePlmn, validateUseCaseRequirements } from './validation';
 export type { ValidationResult } from './validation';
+export { BINDING_COOKIE_PREFIX, BINDING_COOKIE_MAX_AGE, getBindingCookieName, HEX_64, assertValidFeCode, generateFeCode, computeFeHash, buildSetBindingCookieHeader, buildClearBindingCookieHeader, parseBindingCookie, clearStaleBindingCookies, getCompletionPageHtml, } from './device-binding';
+export type { BindingCookieOptions } from './device-binding';
 export { request, FetchError } from './internal/http';
 export type { RequestOptions, HttpResponse } from './internal/http';
 export { getStatusUrl } from './utils';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,uCAAuC,CAAC;AAGtD,YAAY,EAAE,gBAAgB,EAAE,SAAS,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAGvF,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAGtC,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACjD,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAGrE,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAG5C,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,2BAA2B,EAAE,MAAM,cAAc,CAAC;AAC9F,YAAY,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGrD,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACtD,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAGpE,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,uCAAuC,CAAC;AAGtD,YAAY,EAAE,gBAAgB,EAAE,SAAS,EAAE,aAAa,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAGtG,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAGtC,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACjD,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAGrE,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAG5C,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,2BAA2B,EAAE,MAAM,cAAc,CAAC;AAC9F,YAAY,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGrD,OAAO,EACH,qBAAqB,EACrB,sBAAsB,EACtB,oBAAoB,EACpB,MAAM,EACN,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,2BAA2B,EAC3B,6BAA6B,EAC7B,kBAAkB,EAClB,wBAAwB,EACxB,qBAAqB,GACxB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAG7D,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACtD,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAGpE,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getStatusUrl = exports.FetchError = exports.request = exports.validateUseCaseRequirements = exports.validatePlmn = exports.validatePhoneNumber = exports.MagicalAuthError = exports.generateRequestId = exports.createLogger = exports.LogLevel = exports.GlideClient = void 0;
+exports.getStatusUrl = exports.FetchError = exports.request = exports.getCompletionPageHtml = exports.clearStaleBindingCookies = exports.parseBindingCookie = exports.buildClearBindingCookieHeader = exports.buildSetBindingCookieHeader = exports.computeFeHash = exports.generateFeCode = exports.assertValidFeCode = exports.HEX_64 = exports.getBindingCookieName = exports.BINDING_COOKIE_MAX_AGE = exports.BINDING_COOKIE_PREFIX = exports.validateUseCaseRequirements = exports.validatePlmn = exports.validatePhoneNumber = exports.MagicalAuthError = exports.generateRequestId = exports.createLogger = exports.LogLevel = exports.GlideClient = void 0;
 // Re-export all core types and constants (single source of truth)
 __exportStar(require("@glideidentity/glide-be-sdk-node-core"), exports);
 // Main client
@@ -32,6 +32,20 @@ var validation_1 = require("./validation");
 Object.defineProperty(exports, "validatePhoneNumber", { enumerable: true, get: function () { return validation_1.validatePhoneNumber; } });
 Object.defineProperty(exports, "validatePlmn", { enumerable: true, get: function () { return validation_1.validatePlmn; } });
 Object.defineProperty(exports, "validateUseCaseRequirements", { enumerable: true, get: function () { return validation_1.validateUseCaseRequirements; } });
+// Device binding utilities
+var device_binding_1 = require("./device-binding");
+Object.defineProperty(exports, "BINDING_COOKIE_PREFIX", { enumerable: true, get: function () { return device_binding_1.BINDING_COOKIE_PREFIX; } });
+Object.defineProperty(exports, "BINDING_COOKIE_MAX_AGE", { enumerable: true, get: function () { return device_binding_1.BINDING_COOKIE_MAX_AGE; } });
+Object.defineProperty(exports, "getBindingCookieName", { enumerable: true, get: function () { return device_binding_1.getBindingCookieName; } });
+Object.defineProperty(exports, "HEX_64", { enumerable: true, get: function () { return device_binding_1.HEX_64; } });
+Object.defineProperty(exports, "assertValidFeCode", { enumerable: true, get: function () { return device_binding_1.assertValidFeCode; } });
+Object.defineProperty(exports, "generateFeCode", { enumerable: true, get: function () { return device_binding_1.generateFeCode; } });
+Object.defineProperty(exports, "computeFeHash", { enumerable: true, get: function () { return device_binding_1.computeFeHash; } });
+Object.defineProperty(exports, "buildSetBindingCookieHeader", { enumerable: true, get: function () { return device_binding_1.buildSetBindingCookieHeader; } });
+Object.defineProperty(exports, "buildClearBindingCookieHeader", { enumerable: true, get: function () { return device_binding_1.buildClearBindingCookieHeader; } });
+Object.defineProperty(exports, "parseBindingCookie", { enumerable: true, get: function () { return device_binding_1.parseBindingCookie; } });
+Object.defineProperty(exports, "clearStaleBindingCookies", { enumerable: true, get: function () { return device_binding_1.clearStaleBindingCookies; } });
+Object.defineProperty(exports, "getCompletionPageHtml", { enumerable: true, get: function () { return device_binding_1.getCompletionPageHtml; } });
 // HTTP utilities - for advanced usage and dev-server
 var http_1 = require("./internal/http");
 Object.defineProperty(exports, "request", { enumerable: true, get: function () { return http_1.request; } });

package/dist/logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC,2BAA2B;AAC3B,oBAAY,QAAQ;IAChB,KAAK,IAAI;IACT,IAAI,IAAI;IACR,IAAI,IAAI;IACR,KAAK,IAAI;CACZ;AAED,4BAA4B;AAC5B,MAAM,WAAW,QAAQ;IACrB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AAED,mDAAmD;AACnD,MAAM,WAAW,MAAM;IACnB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;IAChD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC/C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC/C,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;CACnD;AAiHD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,QAAQ,CAAC,EAAE,QAAQ,EAAE,SAAS,CAAC,EAAE,SAAS,GAAG,MAAM,CAG/E;AAED,qCAAqC;AACrC,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C"}
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC,2BAA2B;AAC3B,oBAAY,QAAQ;IAChB,KAAK,IAAI;IACT,IAAI,IAAI;IACR,IAAI,IAAI;IACR,KAAK,IAAI;CACZ;AAED,4BAA4B;AAC5B,MAAM,WAAW,QAAQ;IACrB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AAED,mDAAmD;AACnD,MAAM,WAAW,MAAM;IACnB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;IAChD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC/C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC/C,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;CACnD;AAmHD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,QAAQ,CAAC,EAAE,QAAQ,EAAE,SAAS,CAAC,EAAE,SAAS,GAAG,MAAM,CAG/E;AAED,qCAAqC;AACrC,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C"}

package/dist/logger.js

@@ -13,7 +13,9 @@ var LogLevel;
 })(LogLevel || (exports.LogLevel = LogLevel = {}));
 const SENSITIVE_KEYS = [
     'apikey', 'api_key', 'api-key', 'token', 'password', 'secret',
-    'credential', 'authorization', 'bearer', 'key'
+    'credential', 'authorization', 'bearer', 'key',
+    'fe_code', 'fecode', 'fe_hash', 'fehash', 'agg_code', 'aggcode',
+    '_glide_bind', 'glide_bind'
 ];
 const SENSITIVE_PATTERN = new RegExp(`(${SENSITIVE_KEYS.join('|')})([=:\\s"']+)([^\\s"'&,}{\\]\\)]+)`, 'gi');
 function sanitizeMessage(message) {

package/dist/services/magical-auth.d.ts

@@ -1,15 +1,22 @@
-import { GlideSdkSettings } from '../types';
+import { GlideSdkSettings, PrepareResult } from '../types';
 import { Logger } from '../logger';
 import { OAuthManager } from '../internal/oauth';
-import type { PrepareRequest, PrepareResponse, VerifyPhoneNumberRequest, VerifyPhoneNumberResponse, GetPhoneNumberRequest, GetPhoneNumberResponse, ReportInvocationRequest, ReportInvocationResponse } from '@glideidentity/glide-be-sdk-node-core';
+import type { PrepareRequest, CompleteRequest, VerifyPhoneNumberRequest, VerifyPhoneNumberResponse, GetPhoneNumberRequest, GetPhoneNumberResponse, ReportInvocationRequest, ReportInvocationResponse, StatusResponse } from '@glideidentity/glide-be-sdk-node-core';
 /** Handles SIM-based phone authentication via the Glide API. */
 export declare class MagicalAuth {
     private settings;
     private oauthClient;
     private logger;
     constructor(settings: GlideSdkSettings, oauthClient: OAuthManager, logger: Logger);
-    /** Initiates a phone authentication session. */
-    prepare(req: PrepareRequest): Promise<PrepareResponse>;
+    /**
+     * Initiates a phone authentication session.
+     *
+     * For link protocol sessions, this method automatically generates a device
+     * binding code (`feCode`) and includes its hash in the aggregator request.
+     * When `feCode` is present in the result, the caller MUST set it as an
+     * HttpOnly cookie — use `buildSetBindingCookieHeader()` from `device-binding`.
+     */
+    prepare(req: PrepareRequest): Promise<PrepareResult>;
     /** Verifies a phone number matches the device. */
     verifyPhoneNumber(req: VerifyPhoneNumberRequest): Promise<VerifyPhoneNumberResponse>;
     /** Retrieves the phone number. */
@@ -27,6 +34,28 @@ export declare class MagicalAuth {
      * @returns Response with success status
      */
     reportInvocation(req: ReportInvocationRequest): Promise<ReportInvocationResponse>;
+    /**
+     * Completes a device-bound authentication session.
+     *
+     * Call this after the completion redirect page POSTs `agg_code` and `session_key`
+     * to the developer backend. The `fe_code` should be read from the `_glide_bind`
+     * HttpOnly cookie — use `parseBindingCookie()` from `device-binding`.
+     *
+     * The complete endpoint does not return verification results. The client-side
+     * poller detects the session status change to `completed` and calls `/process`.
+     *
+     * @param req - The complete request containing session_key, fe_code, and agg_code.
+     */
+    complete(req: CompleteRequest): Promise<void>;
+    /**
+     * Checks the status of an authentication session.
+     *
+     * Use this to poll for completion of async flows (link/desktop).
+     * This is the authenticated version — requires a Bearer token.
+     *
+     * @param sessionKey - The 16-character hex session key from the prepare response.
+     */
+    checkStatus(sessionKey: string): Promise<StatusResponse>;
     private handleError;
 }
 //# sourceMappingURL=magical-auth.d.ts.map

package/dist/services/magical-auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"magical-auth.d.ts","sourceRoot":"","sources":["../../src/services/magical-auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAEnC,OAAO,EAAE,YAAY,EAAc,MAAM,mBAAmB,CAAC;AAG7D,OAAO,KAAK,EACR,cAAc,EACd,eAAe,EACf,wBAAwB,EACxB,yBAAyB,EACzB,qBAAqB,EACrB,sBAAsB,EACtB,uBAAuB,EACvB,wBAAwB,EAC3B,MAAM,uCAAuC,CAAC;AAa/C,gEAAgE;AAChE,qBAAa,WAAW;IACpB,OAAO,CAAC,QAAQ,CAAmB;IACnC,OAAO,CAAC,WAAW,CAAe;IAClC,OAAO,CAAC,MAAM,CAAS;gBAEX,QAAQ,EAAE,gBAAgB,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM;IAMjF,gDAAgD;IAC1C,OAAO,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC;IAkF5D,kDAAkD;IAC5C,iBAAiB,CAAC,GAAG,EAAE,wBAAwB,GAAG,OAAO,CAAC,yBAAyB,CAAC;IA8C1F,kCAAkC;IAC5B,cAAc,CAAC,GAAG,EAAE,qBAAqB,GAAG,OAAO,CAAC,sBAAsB,CAAC;IA8CjF;;;;;;;;;;;OAWG;IACG,gBAAgB,CAAC,GAAG,EAAE,uBAAuB,GAAG,OAAO,CAAC,wBAAwB,CAAC;IAsCvF,OAAO,CAAC,WAAW;CAyCtB"}
+{"version":3,"file":"magical-auth.d.ts","sourceRoot":"","sources":["../../src/services/magical-auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC3D,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAEnC,OAAO,EAAE,YAAY,EAAc,MAAM,mBAAmB,CAAC;AAK7D,OAAO,KAAK,EACR,cAAc,EAEd,eAAe,EACf,wBAAwB,EACxB,yBAAyB,EACzB,qBAAqB,EACrB,sBAAsB,EACtB,uBAAuB,EACvB,wBAAwB,EACxB,cAAc,EACjB,MAAM,uCAAuC,CAAC;AAa/C,gEAAgE;AAChE,qBAAa,WAAW;IACpB,OAAO,CAAC,QAAQ,CAAmB;IACnC,OAAO,CAAC,WAAW,CAAe;IAClC,OAAO,CAAC,MAAM,CAAS;gBAEX,QAAQ,EAAE,gBAAgB,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM;IAMjF;;;;;;;OAOG;IACG,OAAO,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IAkG1D,kDAAkD;IAC5C,iBAAiB,CAAC,GAAG,EAAE,wBAAwB,GAAG,OAAO,CAAC,yBAAyB,CAAC;IA8C1F,kCAAkC;IAC5B,cAAc,CAAC,GAAG,EAAE,qBAAqB,GAAG,OAAO,CAAC,sBAAsB,CAAC;IA8CjF;;;;;;;;;;;OAWG;IACG,gBAAgB,CAAC,GAAG,EAAE,uBAAuB,GAAG,OAAO,CAAC,wBAAwB,CAAC;IAsCvF;;;;;;;;;;;OAWG;IACG,QAAQ,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAiEnD;;;;;;;OAOG;IACG,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAgC9D,OAAO,CAAC,WAAW;CAyCtB"}

package/dist/services/magical-auth.js

@@ -5,6 +5,8 @@ const http_1 = require("../internal/http");
 const oauth_1 = require("../internal/oauth");
 const errors_1 = require("../errors");
 const validation_1 = require("../validation");
+const device_binding_1 = require("../device-binding");
+const glide_be_sdk_node_core_1 = require("@glideidentity/glide-be-sdk-node-core");
 function generateNonce(length = 32) {
     const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
     let result = '';
@@ -22,7 +24,14 @@ class MagicalAuth {
         this.oauthClient = oauthClient;
         this.logger = logger;
     }
-    /** Initiates a phone authentication session. */
+    /**
+     * Initiates a phone authentication session.
+     *
+     * For link protocol sessions, this method automatically generates a device
+     * binding code (`feCode`) and includes its hash in the aggregator request.
+     * When `feCode` is present in the result, the caller MUST set it as an
+     * HttpOnly cookie — use `buildSetBindingCookieHeader()` from `device-binding`.
+     */
     async prepare(req) {
         const hasParentSession = req.options?.parent_session_id;
         if (!hasParentSession) {
@@ -31,8 +40,7 @@ class MagicalAuth {
                 throw new errors_1.MagicalAuthError({
                     code: useCaseValidation.errorCode || errors_1.ErrorCode.INVALID_USE_CASE,
                     message: useCaseValidation.error,
-                    status: 400,
-                    details: useCaseValidation.details
+                    status: 400
                 });
             }
         }
@@ -56,24 +64,29 @@ class MagicalAuth {
                 });
             }
         }
+        // Generate device binding code and hash for potential link protocol sessions.
+        // Always sent — the aggregator ignores it for non-link strategies (TS43, desktop).
+        const feCode = (0, device_binding_1.generateFeCode)();
+        const feHash = (0, device_binding_1.computeFeHash)(feCode);
         const nonce = req.nonce || generateNonce();
-        const body = { nonce };
-        if (req.use_case)
-            body.use_case = req.use_case;
-        if (req.phone_number)
-            body.phone_number = req.phone_number;
-        if (req.plmn)
-            body.plmn = req.plmn;
-        if (req.consent_data)
-            body.consent_data = req.consent_data;
-        if (req.client_info) {
-            body.client_info = {
-                user_agent: req.client_info.user_agent || 'unknown',
-                platform: req.client_info.platform || 'unknown'
-            };
-        }
-        if (req.options)
-            body.options = req.options;
+        // Only include optional fields when truthy to avoid sending null / ""
+        // to the aggregator — JSON.stringify serializes null and "" but the
+        // aggregator may reject or misinterpret them.
+        const body = {
+            nonce,
+            fe_hash: feHash,
+            ...(req.use_case ? { use_case: req.use_case } : undefined),
+            ...(req.phone_number ? { phone_number: req.phone_number } : undefined),
+            ...(req.plmn ? { plmn: req.plmn } : undefined),
+            ...(req.consent_data ? { consent_data: req.consent_data } : undefined),
+            ...(req.options ? { options: req.options } : undefined),
+        };
+        // Always include client_info so the aggregator can compare the
+        // browser user-agent between /prepare and /complete (browser mismatch detection).
+        body.client_info = {
+            user_agent: req.client_info?.user_agent || 'unknown',
+            platform: req.client_info?.platform || 'unknown'
+        };
         const url = `${this.settings.baseUrl}/magic-auth/v2/auth/prepare`;
         this.logger.debug('Prepare request', { url });
         try {
@@ -89,7 +102,12 @@ class MagicalAuth {
             });
             const result = response.json();
             this.logger.debug('Prepare completed', { strategy: result.authentication_strategy });
-            return result;
+            // Only expose feCode when the session uses link protocol (device binding).
+            const prepareResult = { ...result };
+            if (result.authentication_strategy === glide_be_sdk_node_core_1.AuthenticationStrategy.LINK) {
+                prepareResult.feCode = feCode;
+            }
+            return prepareResult;
         }
         catch (error) {
             this.handleError(error);
@@ -214,7 +232,112 @@ class MagicalAuth {
                 body: JSON.stringify(body),
             });
             const result = await response.json();
-            this.logger.debug('ReportInvocation completed', { session_id: req.session_id, success: result.success });
+            this.logger.debug('ReportInvocation completed', { session_id: req.session_id, status: result.status });
+            return result;
+        }
+        catch (error) {
+            this.handleError(error);
+        }
+    }
+    /**
+     * Completes a device-bound authentication session.
+     *
+     * Call this after the completion redirect page POSTs `agg_code` and `session_key`
+     * to the developer backend. The `fe_code` should be read from the `_glide_bind`
+     * HttpOnly cookie — use `parseBindingCookie()` from `device-binding`.
+     *
+     * The complete endpoint does not return verification results. The client-side
+     * poller detects the session status change to `completed` and calls `/process`.
+     *
+     * @param req - The complete request containing session_key, fe_code, and agg_code.
+     */
+    async complete(req) {
+        if (!req.session_key) {
+            throw new errors_1.MagicalAuthError({
+                code: errors_1.ErrorCode.MISSING_REQUIRED_FIELD,
+                message: 'session_key is required',
+                status: 400
+            });
+        }
+        if (!req.fe_code) {
+            throw new errors_1.MagicalAuthError({
+                code: errors_1.ErrorCode.MISSING_BINDING_COOKIE,
+                message: 'fe_code is required (from _glide_bind cookie)',
+                status: 403
+            });
+        }
+        if (!req.agg_code) {
+            throw new errors_1.MagicalAuthError({
+                code: errors_1.ErrorCode.MISSING_REQUIRED_FIELD,
+                message: 'agg_code is required',
+                status: 400
+            });
+        }
+        // Validate format — both codes must be 64-char lowercase hex.
+        // Use a generic 403 to avoid leaking which value failed.
+        if (!device_binding_1.HEX_64.test(req.fe_code) || !device_binding_1.HEX_64.test(req.agg_code)) {
+            throw new errors_1.MagicalAuthError({
+                code: errors_1.ErrorCode.DEVICE_BINDING_FAILED,
+                message: 'Invalid device binding inputs',
+                status: 403
+            });
+        }
+        const body = {
+            session_key: req.session_key,
+            fe_code: req.fe_code,
+            agg_code: req.agg_code,
+        };
+        if (req.user_agent) {
+            body.user_agent = req.user_agent;
+        }
+        const url = `${this.settings.baseUrl}/magic-auth/v2/auth/complete`;
+        this.logger.debug('Complete request', { url });
+        try {
+            const accessToken = await this.oauthClient.getAccessToken();
+            await (0, http_1.request)(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Accept': 'application/json',
+                    'Authorization': `Bearer ${accessToken}`,
+                },
+                body: JSON.stringify(body),
+            });
+            this.logger.debug('Complete succeeded');
+        }
+        catch (error) {
+            this.handleError(error);
+        }
+    }
+    /**
+     * Checks the status of an authentication session.
+     *
+     * Use this to poll for completion of async flows (link/desktop).
+     * This is the authenticated version — requires a Bearer token.
+     *
+     * @param sessionKey - The 16-character hex session key from the prepare response.
+     */
+    async checkStatus(sessionKey) {
+        if (!sessionKey) {
+            throw new errors_1.MagicalAuthError({
+                code: errors_1.ErrorCode.MISSING_REQUIRED_FIELD,
+                message: 'sessionKey is required',
+                status: 400
+            });
+        }
+        const url = `${this.settings.baseUrl}/magic-auth/v2/auth/status/${sessionKey}`;
+        this.logger.debug('CheckStatus request', { url, sessionKey });
+        try {
+            const accessToken = await this.oauthClient.getAccessToken();
+            const response = await (0, http_1.request)(url, {
+                method: 'GET',
+                headers: {
+                    'Accept': 'application/json',
+                    'Authorization': `Bearer ${accessToken}`,
+                },
+            });
+            const result = response.json();
+            this.logger.debug('CheckStatus completed', { sessionKey, status: result.status });
             return result;
         }
         catch (error) {

package/dist/types.d.ts

@@ -1,4 +1,5 @@
 import { Logger, LogLevel } from './logger';
+import type { PrepareResponse } from '@glideidentity/glide-be-sdk-node-core';
 /** Log output format. */
 export type LogFormat = 'json' | 'text';
 /** OAuth2 token response from the token endpoint. */
@@ -19,6 +20,24 @@ export interface CachedToken {
     /** Timestamp (ms) when the token expires. */
     expiresAt: number;
 }
+/**
+ * Extended prepare response that includes the device binding code for link protocol.
+ *
+ * Compatible with `PrepareResponse` — existing code that expects `PrepareResponse` will
+ * continue to work unchanged. The `feCode` field is only present when the session uses
+ * the link authentication strategy.
+ */
+export interface PrepareResult extends PrepareResponse {
+    /**
+     * Device binding code for link protocol sessions.
+     *
+     * When present, the caller MUST set this as an HttpOnly cookie using
+     * `buildSetBindingCookieHeader(feCode)` from `device-binding.ts`.
+     *
+     * `undefined` for non-link strategies (TS43, desktop).
+     */
+    feCode?: string;
+}
 /** Client configuration options. */
 export interface GlideSdkSettings {
     /** OAuth2 Client ID (required). */

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAE5C,yBAAyB;AACzB,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;AAExC,qDAAqD;AACrD,MAAM,WAAW,aAAa;IAC1B,6CAA6C;IAC7C,YAAY,EAAE,MAAM,CAAC;IACrB,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,uBAAuB;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,iCAAiC;IACjC,UAAU,EAAE,MAAM,CAAC;CACtB;AAED,6CAA6C;AAC7C,MAAM,WAAW,WAAW;IACxB,wBAAwB;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAC;CACrB;AAED,oCAAoC;AACpC,MAAM,WAAW,gBAAgB;IAC7B,mCAAmC;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,uCAAuC;IACvC,YAAY,EAAE,MAAM,CAAC;IACrB,4CAA4C;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yBAAyB;IACzB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,iBAAiB;IACjB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,oCAAoC;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qFAAqF;IACrF,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC/B"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uCAAuC,CAAC;AAE7E,yBAAyB;AACzB,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;AAExC,qDAAqD;AACrD,MAAM,WAAW,aAAa;IAC1B,6CAA6C;IAC7C,YAAY,EAAE,MAAM,CAAC;IACrB,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,uBAAuB;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,iCAAiC;IACjC,UAAU,EAAE,MAAM,CAAC;CACtB;AAED,6CAA6C;AAC7C,MAAM,WAAW,WAAW;IACxB,wBAAwB;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAc,SAAQ,eAAe;IAClD;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,oCAAoC;AACpC,MAAM,WAAW,gBAAgB;IAC7B,mCAAmC;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,uCAAuC;IACvC,YAAY,EAAE,MAAM,CAAC;IACrB,4CAA4C;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yBAAyB;IACzB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,iBAAiB;IACjB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,oCAAoC;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qFAAqF;IACrF,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC/B"}

package/dist/validation.d.ts

@@ -4,7 +4,6 @@ export interface ValidationResult {
     valid: boolean;
     error?: string;
     errorCode?: string;
-    details?: Record<string, unknown>;
 }
 /** Validates phone number format (E.164). */
 export declare function validatePhoneNumber(phoneNumber?: string): ValidationResult;

package/dist/validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,uCAAuC,CAAC;AAE/E,yBAAyB;AACzB,MAAM,WAAW,gBAAgB;IAC7B,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED,6CAA6C;AAC7C,wBAAgB,mBAAmB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAyC1E;AAED,uCAAuC;AACvC,wBAAgB,YAAY,CAAC,IAAI,CAAC,EAAE,IAAI,GAAG,gBAAgB,CAoB1D;AAED,+EAA+E;AAC/E,wBAAgB,2BAA2B,CACvC,OAAO,CAAC,EAAE,WAAW,EACrB,WAAW,CAAC,EAAE,MAAM,EACpB,IAAI,CAAC,EAAE,IAAI,GACZ,gBAAgB,CA0ClB"}
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,uCAAuC,CAAC;AAE/E,yBAAyB;AACzB,MAAM,WAAW,gBAAgB;IAC7B,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,6CAA6C;AAC7C,wBAAgB,mBAAmB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAyC1E;AAED,uCAAuC;AACvC,wBAAgB,YAAY,CAAC,IAAI,CAAC,EAAE,IAAI,GAAG,gBAAgB,CAoB1D;AAED,+EAA+E;AAC/E,wBAAgB,2BAA2B,CACvC,OAAO,CAAC,EAAE,WAAW,EACrB,WAAW,CAAC,EAAE,MAAM,EACpB,IAAI,CAAC,EAAE,IAAI,GACZ,gBAAgB,CAuClB"}

package/dist/validation.js

@@ -75,16 +75,14 @@ function validateUseCaseRequirements(useCase, phoneNumber, plmn) {
                 return {
                     valid: false,
                     error: 'Phone number should not be provided for GetPhoneNumber use case',
-                    errorCode: glide_be_sdk_node_core_1.ErrorCode.INVALID_USE_CASE,
-                    details: { invalid_field: 'phone_number', reason: 'not_allowed_for_use_case' }
+                    errorCode: glide_be_sdk_node_core_1.ErrorCode.INVALID_USE_CASE
                 };
             }
             if (!plmn) {
                 return {
                     valid: false,
                     error: 'PLMN (MCC/MNC) is required for GetPhoneNumber use case',
-                    errorCode: glide_be_sdk_node_core_1.ErrorCode.MISSING_REQUIRED_FIELD,
-                    details: { missing_field: 'plmn' }
+                    errorCode: glide_be_sdk_node_core_1.ErrorCode.MISSING_REQUIRED_FIELD
                 };
             }
             break;
@@ -93,8 +91,7 @@ function validateUseCaseRequirements(useCase, phoneNumber, plmn) {
                 return {
                     valid: false,
                     error: 'Phone number is required for VerifyPhoneNumber use case',
-                    errorCode: glide_be_sdk_node_core_1.ErrorCode.MISSING_REQUIRED_FIELD,
-                    details: { missing_field: 'phone_number' }
+                    errorCode: glide_be_sdk_node_core_1.ErrorCode.MISSING_REQUIRED_FIELD
                 };
             }
             break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glideidentity/glide-be-sdk-node",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "Glide SDK for Node.js - carrier-based phone verification",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -21,8 +21,17 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@glideidentity/glide-be-sdk-node-core": "2.0.1"
+    "@glideidentity/glide-be-sdk-node-core": "2.1.0"
   },
-  "keywords": ["glide", "sdk", "phone", "verification", "magic-auth"],
+  "publishConfig": {
+    "registry": "https://us-central1-npm.pkg.dev/platform-devops-09ff133a/npm-packages/"
+  },
+  "keywords": [
+    "glide",
+    "sdk",
+    "phone",
+    "verification",
+    "magic-auth"
+  ],
   "license": "SEE LICENSE IN LICENSE"
 }