@licenseseat/js 0.1.0 → 0.2.1

package/src/cache.js

@@ -0,0 +1,189 @@
+/**
+ * LicenseSeat SDK Cache Manager
+ * Handles persistent storage of license data, offline licenses, and public keys.
+ * @module cache
+ */
+
+/**
+ * License Cache Manager
+ * Manages persistent storage of license data using localStorage.
+ */
+export class LicenseCache {
+  /**
+   * Create a LicenseCache instance
+   * @param {string} [prefix="licenseseat_"] - Prefix for all localStorage keys
+   */
+  constructor(prefix = "licenseseat_") {
+    /** @type {string} */
+    this.prefix = prefix;
+    /** @type {string} */
+    this.publicKeyCacheKey = this.prefix + "public_keys";
+  }
+
+  /**
+   * Get the cached license data
+   * @returns {import('./types.js').CachedLicense|null} Cached license or null if not found
+   */
+  getLicense() {
+    try {
+      const data = localStorage.getItem(this.prefix + "license");
+      return data ? JSON.parse(data) : null;
+    } catch (e) {
+      console.error("Failed to read license cache:", e);
+      return null;
+    }
+  }
+
+  /**
+   * Store license data in cache
+   * @param {import('./types.js').CachedLicense} data - License data to cache
+   * @returns {void}
+   */
+  setLicense(data) {
+    try {
+      localStorage.setItem(this.prefix + "license", JSON.stringify(data));
+    } catch (e) {
+      console.error("Failed to cache license:", e);
+    }
+  }
+
+  /**
+   * Update the validation data for the cached license
+   * @param {import('./types.js').ValidationResult} validationData - Validation result to store
+   * @returns {void}
+   */
+  updateValidation(validationData) {
+    const license = this.getLicense();
+    if (license) {
+      license.validation = validationData;
+      license.last_validated = new Date().toISOString();
+      this.setLicense(license);
+    }
+  }
+
+  /**
+   * Get the device identifier from the cached license
+   * @returns {string|null} Device identifier or null if not found
+   */
+  getDeviceId() {
+    const license = this.getLicense();
+    return license ? license.device_identifier : null;
+  }
+
+  /**
+   * Clear the cached license data
+   * @returns {void}
+   */
+  clearLicense() {
+    localStorage.removeItem(this.prefix + "license");
+  }
+
+  /**
+   * Get the cached offline license
+   * @returns {import('./types.js').SignedOfflineLicense|null} Offline license or null if not found
+   */
+  getOfflineLicense() {
+    try {
+      const data = localStorage.getItem(this.prefix + "offline_license");
+      return data ? JSON.parse(data) : null;
+    } catch (e) {
+      console.error("Failed to read offline license cache:", e);
+      return null;
+    }
+  }
+
+  /**
+   * Store offline license data in cache
+   * @param {import('./types.js').SignedOfflineLicense} data - Signed offline license to cache
+   * @returns {void}
+   */
+  setOfflineLicense(data) {
+    try {
+      localStorage.setItem(
+        this.prefix + "offline_license",
+        JSON.stringify(data)
+      );
+    } catch (e) {
+      console.error("Failed to cache offline license:", e);
+    }
+  }
+
+  /**
+   * Clear the cached offline license
+   * @returns {void}
+   */
+  clearOfflineLicense() {
+    localStorage.removeItem(this.prefix + "offline_license");
+  }
+
+  /**
+   * Get a cached public key by key ID
+   * @param {string} keyId - The key ID to look up
+   * @returns {string|null} Base64-encoded public key or null if not found
+   */
+  getPublicKey(keyId) {
+    try {
+      const cache = JSON.parse(
+        localStorage.getItem(this.publicKeyCacheKey) || "{}"
+      );
+      return cache[keyId] || null;
+    } catch (e) {
+      console.error("Failed to read public key cache:", e);
+      return null;
+    }
+  }
+
+  /**
+   * Store a public key in cache
+   * @param {string} keyId - The key ID
+   * @param {string} publicKeyB64 - Base64-encoded public key
+   * @returns {void}
+   */
+  setPublicKey(keyId, publicKeyB64) {
+    try {
+      const cache = JSON.parse(
+        localStorage.getItem(this.publicKeyCacheKey) || "{}"
+      );
+      cache[keyId] = publicKeyB64;
+      localStorage.setItem(this.publicKeyCacheKey, JSON.stringify(cache));
+    } catch (e) {
+      console.error("Failed to cache public key:", e);
+    }
+  }
+
+  /**
+   * Clear all LicenseSeat SDK data for this prefix
+   * @returns {void}
+   */
+  clear() {
+    Object.keys(localStorage).forEach((key) => {
+      if (key.startsWith(this.prefix)) {
+        localStorage.removeItem(key);
+      }
+    });
+    this.clearOfflineLicense();
+    localStorage.removeItem(this.prefix + "last_seen_ts");
+  }
+
+  /**
+   * Get the last seen timestamp (for clock tamper detection)
+   * @returns {number|null} Unix timestamp in milliseconds or null if not set
+   */
+  getLastSeenTimestamp() {
+    const v = localStorage.getItem(this.prefix + "last_seen_ts");
+    return v ? parseInt(v, 10) : null;
+  }
+
+  /**
+   * Store the last seen timestamp
+   * @param {number} ts - Unix timestamp in milliseconds
+   * @returns {void}
+   */
+  setLastSeenTimestamp(ts) {
+    try {
+      localStorage.setItem(this.prefix + "last_seen_ts", String(ts));
+    } catch (e) {
+      // Ignore storage errors for timestamp
+    }
+  }
+}

package/src/errors.js

@@ -0,0 +1,77 @@
+/**
+ * LicenseSeat SDK Error Classes
+ * @module errors
+ */
+
+/**
+ * Custom API Error class for HTTP request failures
+ * @extends Error
+ */
+export class APIError extends Error {
+  /**
+   * Create an APIError
+   * @param {string} message - Error message
+   * @param {number} status - HTTP status code (0 for network failures)
+   * @param {import('./types.js').APIErrorData} [data] - Additional error data from the API response
+   */
+  constructor(message, status, data) {
+    super(message);
+    /** @type {string} */
+    this.name = "APIError";
+    /** @type {number} */
+    this.status = status;
+    /** @type {import('./types.js').APIErrorData|undefined} */
+    this.data = data;
+  }
+}
+
+/**
+ * Error thrown when SDK operations are attempted without proper configuration
+ * @extends Error
+ */
+export class ConfigurationError extends Error {
+  /**
+   * Create a ConfigurationError
+   * @param {string} message - Error message
+   */
+  constructor(message) {
+    super(message);
+    /** @type {string} */
+    this.name = "ConfigurationError";
+  }
+}
+
+/**
+ * Error thrown when license operations fail
+ * @extends Error
+ */
+export class LicenseError extends Error {
+  /**
+   * Create a LicenseError
+   * @param {string} message - Error message
+   * @param {string} [code] - Machine-readable error code
+   */
+  constructor(message, code) {
+    super(message);
+    /** @type {string} */
+    this.name = "LicenseError";
+    /** @type {string|undefined} */
+    this.code = code;
+  }
+}
+
+/**
+ * Error thrown when cryptographic operations fail
+ * @extends Error
+ */
+export class CryptoError extends Error {
+  /**
+   * Create a CryptoError
+   * @param {string} message - Error message
+   */
+  constructor(message) {
+    super(message);
+    /** @type {string} */
+    this.name = "CryptoError";
+  }
+}

package/src/index.js

@@ -0,0 +1,62 @@
+/**
+ * LicenseSeat JavaScript SDK
+ *
+ * Official JavaScript client for LicenseSeat - the simple, secure licensing platform
+ * for apps, games, and plugins.
+ *
+ * @module @licenseseat/js
+ * @version 0.2.0
+ *
+ * @example
+ * ```js
+ * import LicenseSeat from '@licenseseat/js';
+ *
+ * const sdk = new LicenseSeat({
+ *   apiKey: 'your-api-key',
+ *   debug: true
+ * });
+ *
+ * // Activate a license
+ * await sdk.activate('LICENSE-KEY-HERE');
+ *
+ * // Check entitlements
+ * if (sdk.hasEntitlement('pro')) {
+ *   // Enable pro features
+ * }
+ *
+ * // Get license status
+ * const status = sdk.getStatus();
+ * console.log(status);
+ * ```
+ */
+
+// Re-export the main SDK class
+export {
+  LicenseSeatSDK,
+  getSharedInstance,
+  configure,
+  resetSharedInstance,
+} from "./LicenseSeat.js";
+
+// Re-export types (empty module, but useful for documentation)
+export {} from "./types.js";
+
+// Re-export error classes
+export { APIError, ConfigurationError, LicenseError, CryptoError } from "./errors.js";
+
+// Re-export cache (for advanced use cases)
+export { LicenseCache } from "./cache.js";
+
+// Re-export utility functions (for advanced use cases)
+export {
+  parseActiveEntitlements,
+  constantTimeEqual,
+  canonicalJsonStringify,
+  base64UrlDecode,
+  generateDeviceId,
+  getCsrfToken,
+} from "./utils.js";
+
+// Default export - the main SDK class
+import { LicenseSeatSDK } from "./LicenseSeat.js";
+export default LicenseSeatSDK;

package/src/types.js

@@ -0,0 +1,148 @@
+/**
+ * LicenseSeat SDK Type Definitions
+ * These JSDoc types enable TypeScript support via declaration file generation.
+ * @module types
+ */
+
+/**
+ * SDK Configuration options
+ * @typedef {Object} LicenseSeatConfig
+ * @property {string} [apiBaseUrl="https://licenseseat.com/api"] - Base URL for the LicenseSeat API
+ * @property {string} [apiKey] - API key for authentication (required for most operations)
+ * @property {string} [storagePrefix="licenseseat_"] - Prefix for localStorage keys
+ * @property {number} [autoValidateInterval=3600000] - Interval in ms for automatic license validation (default: 1 hour)
+ * @property {number} [networkRecheckInterval=30000] - Interval in ms to check network connectivity when offline (default: 30s)
+ * @property {number} [maxRetries=3] - Maximum number of retry attempts for failed API calls
+ * @property {number} [retryDelay=1000] - Initial delay in ms between retries (exponential backoff applied)
+ * @property {boolean} [debug=false] - Enable debug logging to console
+ * @property {number} [offlineLicenseRefreshInterval=259200000] - Interval in ms to refresh offline license (default: 72 hours)
+ * @property {boolean} [offlineFallbackEnabled=false] - Enable offline validation fallback on network errors
+ * @property {number} [maxOfflineDays=0] - Maximum days a license can be used offline (0 = disabled)
+ * @property {number} [maxClockSkewMs=300000] - Maximum allowed clock skew in ms for offline validation (default: 5 minutes)
+ * @property {boolean} [autoInitialize=true] - Automatically initialize and validate cached license on construction
+ */
+
+/**
+ * License activation options
+ * @typedef {Object} ActivationOptions
+ * @property {string} [deviceIdentifier] - Custom device identifier (auto-generated if not provided)
+ * @property {string} [softwareReleaseDate] - ISO8601 date string for version-aware activation
+ * @property {Object} [metadata] - Additional metadata to include with the activation
+ */
+
+/**
+ * License validation options
+ * @typedef {Object} ValidationOptions
+ * @property {string} [deviceIdentifier] - Device identifier to validate against
+ * @property {string} [productSlug] - Product slug for product-specific validation
+ */
+
+/**
+ * Activation response from the API
+ * @typedef {Object} ActivationResponse
+ * @property {string} id - Activation ID
+ * @property {string} license_key - The activated license key
+ * @property {string} device_identifier - Device identifier used for activation
+ * @property {string} activated_at - ISO8601 timestamp of activation
+ * @property {Object} [metadata] - Additional metadata
+ */
+
+/**
+ * Cached license data
+ * @typedef {Object} CachedLicense
+ * @property {string} license_key - The license key
+ * @property {string} device_identifier - Device identifier
+ * @property {ActivationResponse} [activation] - Original activation response
+ * @property {string} activated_at - ISO8601 timestamp of activation
+ * @property {string} last_validated - ISO8601 timestamp of last validation
+ * @property {ValidationResult} [validation] - Latest validation result
+ */
+
+/**
+ * Entitlement object
+ * Note: API returns only key, expires_at, and metadata. Name/description are not provided.
+ * @typedef {Object} Entitlement
+ * @property {string} key - Unique entitlement key
+ * @property {string|null} expires_at - ISO8601 expiration timestamp
+ * @property {Object|null} metadata - Additional metadata
+ */
+
+/**
+ * Validation result from API or offline verification
+ * @typedef {Object} ValidationResult
+ * @property {boolean} valid - Whether the license is valid
+ * @property {boolean} [offline] - Whether this was an offline validation
+ * @property {string} [reason] - Reason for invalid status (online)
+ * @property {string} [reason_code] - Machine-readable reason code (offline)
+ * @property {Entitlement[]} [active_entitlements] - List of active entitlements
+ * @property {boolean} [optimistic] - Whether this is an optimistic validation (pending server confirmation)
+ */
+
+/**
+ * Entitlement check result
+ * @typedef {Object} EntitlementCheckResult
+ * @property {boolean} active - Whether the entitlement is active
+ * @property {string} [reason] - Reason if not active ("no_license" | "not_found" | "expired")
+ * @property {string} [expires_at] - ISO8601 expiration timestamp if expired
+ * @property {Entitlement} [entitlement] - Full entitlement object if active
+ */
+
+/**
+ * License status object
+ * @typedef {Object} LicenseStatus
+ * @property {string} status - Status string ("inactive" | "pending" | "invalid" | "offline-invalid" | "offline-valid" | "active")
+ * @property {string} [message] - Human-readable status message
+ * @property {string} [license] - License key (if active)
+ * @property {string} [device] - Device identifier (if active)
+ * @property {string} [activated_at] - ISO8601 activation timestamp
+ * @property {string} [last_validated] - ISO8601 last validation timestamp
+ * @property {Entitlement[]} [entitlements] - List of active entitlements
+ */
+
+/**
+ * Offline license payload
+ * @typedef {Object} OfflineLicensePayload
+ * @property {number} [v] - Payload version (currently 1)
+ * @property {string} [lic_k] - License key
+ * @property {string} [prod_s] - Product slug
+ * @property {string} [plan_k] - License plan key
+ * @property {string|null} [exp_at] - ISO8601 expiration timestamp (null for perpetual)
+ * @property {number|null} [sl] - Seat limit (null for unlimited)
+ * @property {string} [kid] - Key ID for public key lookup
+ * @property {Array<{key: string, expires_at: string|null, metadata: Object|null}>} [active_ents] - Active entitlements
+ * @property {Array<{key: string, expires_at: string|null, metadata: Object|null}>} [active_entitlements] - Active entitlements (alternative key)
+ * @property {Object} [metadata] - Additional metadata
+ */
+
+/**
+ * Signed offline license data
+ * @typedef {Object} SignedOfflineLicense
+ * @property {OfflineLicensePayload} payload - The license payload
+ * @property {string} signature_b64u - Base64URL-encoded Ed25519 signature
+ * @property {string} [kid] - Key ID for public key lookup
+ */
+
+/**
+ * Event callback function
+ * @callback EventCallback
+ * @param {*} data - Event data
+ * @returns {void}
+ */
+
+/**
+ * Event unsubscribe function
+ * @callback EventUnsubscribe
+ * @returns {void}
+ */
+
+/**
+ * API Error data
+ * @typedef {Object} APIErrorData
+ * @property {string} [error] - Error message
+ * @property {string} [reason_code] - Machine-readable reason code (e.g., "license_not_found", "expired", "revoked")
+ * @property {string} [code] - Legacy error code (deprecated, use reason_code)
+ * @property {Object} [details] - Additional error details
+ */
+
+// Export empty object to make this a module
+export {};

package/src/utils.js

@@ -0,0 +1,154 @@
+/**
+ * LicenseSeat SDK Utility Functions
+ * @module utils
+ */
+
+// @ts-ignore - canonical-json has a default export that is the stringify function
+import CJSON from "canonical-json";
+
+/**
+ * Parse active entitlements from a raw API payload into a consistent shape
+ * @param {Object} [payload={}] - Raw payload from API or offline license
+ * @returns {import('./types.js').Entitlement[]} Normalized entitlements array
+ */
+export function parseActiveEntitlements(payload = {}) {
+  const raw = payload.active_ents || payload.active_entitlements || [];
+  return raw.map((e) => ({
+    key: e.key,
+    expires_at: e.expires_at ?? null,
+    metadata: e.metadata ?? null,
+  }));
+}
+
+/**
+ * Constant-time string comparison to mitigate timing attacks
+ * @param {string} [a=""] - First string
+ * @param {string} [b=""] - Second string
+ * @returns {boolean} True if strings are equal
+ */
+export function constantTimeEqual(a = "", b = "") {
+  if (a.length !== b.length) return false;
+  let res = 0;
+  for (let i = 0; i < a.length; i++) {
+    res |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return res === 0;
+}
+
+/**
+ * Generate a canonical JSON string from an object (keys sorted)
+ * This is crucial for consistent signature verification.
+ * @param {Object} obj - The object to stringify
+ * @returns {string} Canonical JSON string
+ */
+export function canonicalJsonStringify(obj) {
+  // canonical-json exports the stringify function directly as default
+  /** @type {Function|undefined} */
+  const stringify = typeof CJSON === "function" ? CJSON : (CJSON && typeof CJSON === "object" ? /** @type {any} */ (CJSON).stringify : undefined);
+  if (!stringify || typeof stringify !== "function") {
+    console.warn(
+      "[LicenseSeat SDK] canonical-json library not loaded correctly. Falling back to basic JSON.stringify. Signature verification might be unreliable if server uses different canonicalization."
+    );
+    try {
+      const sortedObj = {};
+      Object.keys(obj)
+        .sort()
+        .forEach((key) => {
+          sortedObj[key] = obj[key];
+        });
+      return JSON.stringify(sortedObj);
+    } catch (e) {
+      return JSON.stringify(obj);
+    }
+  }
+  return stringify(obj);
+}
+
+/**
+ * Decode a Base64URL string to a Uint8Array
+ * @param {string} base64UrlString - The Base64URL encoded string
+ * @returns {Uint8Array} Decoded bytes
+ */
+export function base64UrlDecode(base64UrlString) {
+  let base64 = base64UrlString.replace(/-/g, "+").replace(/_/g, "/");
+  while (base64.length % 4) {
+    base64 += "=";
+  }
+  const raw = window.atob(base64);
+  const outputArray = new Uint8Array(raw.length);
+  for (let i = 0; i < raw.length; ++i) {
+    outputArray[i] = raw.charCodeAt(i);
+  }
+  return outputArray;
+}
+
+/**
+ * Simple hash function for generating device fingerprints
+ * @param {string} str - String to hash
+ * @returns {string} Base36 encoded hash
+ */
+export function hashCode(str) {
+  let hash = 0;
+  for (let i = 0; i < str.length; i++) {
+    const char = str.charCodeAt(i);
+    hash = (hash << 5) - hash + char;
+    hash = hash & hash;
+  }
+  return Math.abs(hash).toString(36);
+}
+
+/**
+ * Get canvas fingerprint for device identification
+ * @returns {string} Canvas fingerprint or "no-canvas" if unavailable
+ */
+export function getCanvasFingerprint() {
+  try {
+    const canvas = document.createElement("canvas");
+    const ctx = canvas.getContext("2d");
+    ctx.textBaseline = "top";
+    ctx.font = "14px Arial";
+    ctx.fillText("LicenseSeat SDK", 2, 2);
+    return canvas.toDataURL().slice(-50);
+  } catch (e) {
+    return "no-canvas";
+  }
+}
+
+/**
+ * Generate a unique device identifier based on browser characteristics
+ * @returns {string} Unique device identifier
+ */
+export function generateDeviceId() {
+  const nav = window.navigator;
+  const screen = window.screen;
+  const data = [
+    nav.userAgent,
+    nav.language,
+    screen.colorDepth,
+    screen.width + "x" + screen.height,
+    new Date().getTimezoneOffset(),
+    nav.hardwareConcurrency,
+    getCanvasFingerprint(),
+  ].join("|");
+
+  return `web-${hashCode(data)}-${Date.now().toString(36)}`;
+}
+
+/**
+ * Sleep for a specified duration
+ * @param {number} ms - Duration in milliseconds
+ * @returns {Promise<void>} Resolves after the specified duration
+ */
+export function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Get CSRF token from meta tag (for browser form submissions)
+ * @returns {string} CSRF token or empty string if not found
+ */
+export function getCsrfToken() {
+  /** @type {HTMLMetaElement|null} */
+  const token = document.querySelector('meta[name="csrf-token"]');
+  return token ? token.content : "";
+}