@whatalo/plugin-sdk 1.0.0 → 1.1.0

package/dist/session-token.cjs

@@ -0,0 +1,134 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/session-token.ts
+var session_token_exports = {};
+__export(session_token_exports, {
+  signSessionToken: () => signSessionToken,
+  verifySessionToken: () => verifySessionToken
+});
+module.exports = __toCommonJS(session_token_exports);
+var import_node_crypto = require("crypto");
+var TOKEN_TTL_SECONDS = 300;
+var HEADER_B64 = Buffer.from(
+  JSON.stringify({ alg: "HS256", typ: "JWT" })
+).toString("base64url");
+function encodeB64(obj) {
+  return Buffer.from(JSON.stringify(obj)).toString("base64url");
+}
+function decodeB64(encoded) {
+  const json = Buffer.from(encoded, "base64url").toString("utf8");
+  return JSON.parse(json);
+}
+function computeHmac(data, secret) {
+  return (0, import_node_crypto.createHmac)("sha256", secret).update(data, "utf8").digest("hex");
+}
+function signSessionToken(payload, clientSecret) {
+  if (!clientSecret || clientSecret.length === 0) {
+    throw new Error("client_secret must be a non-empty string");
+  }
+  const now = Math.floor(Date.now() / 1e3);
+  const exp = now + TOKEN_TTL_SECONDS;
+  const claims = {
+    iss: "whatalo",
+    aud: payload.aud,
+    sub: payload.sub,
+    iat: now,
+    exp,
+    // 16 random bytes → 32-char hex string used as the JWT ID (jti)
+    jti: (0, import_node_crypto.randomBytes)(16).toString("hex"),
+    storeId: payload.storeId,
+    appId: payload.appId,
+    scopes: payload.scopes,
+    installationId: payload.installationId
+  };
+  const payloadB64 = encodeB64(claims);
+  const signingInput = `${HEADER_B64}.${payloadB64}`;
+  const signature = computeHmac(signingInput, clientSecret);
+  return {
+    token: `${signingInput}.${signature}`,
+    expiresAt: exp
+  };
+}
+function verifySessionToken(token, clientSecret) {
+  if (!token || !clientSecret) {
+    throw new Error("Token and client_secret are required");
+  }
+  const parts = token.split(".");
+  if (parts.length !== 3) {
+    throw new Error("Invalid token structure: expected header.payload.signature");
+  }
+  const [headerB64, payloadB64, receivedSig] = parts;
+  let header;
+  try {
+    header = decodeB64(headerB64);
+  } catch {
+    throw new Error("Invalid token: malformed header");
+  }
+  if (header.alg !== "HS256" || header.typ !== "JWT") {
+    throw new Error("Invalid token: unsupported algorithm or type");
+  }
+  const signingInput = `${headerB64}.${payloadB64}`;
+  const expectedSig = computeHmac(signingInput, clientSecret);
+  const normalizeKey = expectedSig;
+  const receivedNorm = (0, import_node_crypto.createHmac)("sha256", normalizeKey).update(receivedSig).digest();
+  const expectedNorm = (0, import_node_crypto.createHmac)("sha256", normalizeKey).update(expectedSig).digest();
+  if (!(0, import_node_crypto.timingSafeEqual)(receivedNorm, expectedNorm)) {
+    throw new Error("Invalid token: signature mismatch");
+  }
+  let claims;
+  try {
+    claims = decodeB64(payloadB64);
+  } catch {
+    throw new Error("Invalid token: malformed payload");
+  }
+  const now = Math.floor(Date.now() / 1e3);
+  const CLOCK_SKEW_SECONDS = 30;
+  if (typeof claims.exp !== "number" || claims.exp + CLOCK_SKEW_SECONDS <= now) {
+    throw new Error("Token has expired");
+  }
+  if (claims.iss !== "whatalo") {
+    throw new Error(`Invalid token: unexpected issuer "${claims.iss}"`);
+  }
+  const required = [
+    "aud",
+    "sub",
+    "iat",
+    "jti",
+    "storeId",
+    "appId",
+    "scopes",
+    "installationId"
+  ];
+  for (const key of required) {
+    if (claims[key] === void 0 || claims[key] === null) {
+      throw new Error(`Invalid token: missing required claim "${key}"`);
+    }
+  }
+  if (!Array.isArray(claims.scopes)) {
+    throw new Error("Invalid token: scopes must be an array");
+  }
+  return claims;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  signSessionToken,
+  verifySessionToken
+});
+//# sourceMappingURL=session-token.cjs.map

package/dist/session-token.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/session-token.ts"],"sourcesContent":["/**\n * Session Token — server-side only.\n *\n * Signs and verifies short-lived HMAC-SHA256 JWTs used by plugin iframes to\n * authenticate against their own backend. The token is issued by the Whatalo\n * admin host and forwarded by the plugin frontend to its server, which\n * validates the signature using the app's client_secret.\n *\n * Architecture:\n *   Admin host  ──issues──►  iframe (via App Bridge)\n *   iframe frontend  ──sends──►  plugin backend\n *   plugin backend  ──validates──►  calls Whatalo public API with its own key\n *\n * This module uses ONLY Node.js built-in `node:crypto`. No external dependencies.\n * It must NEVER be imported in browser code (import from server entry points only).\n */\n\nimport { createHmac, timingSafeEqual, randomBytes } from \"node:crypto\";\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\n/**\n * JWT claims embedded in every session token.\n * All string fields are required so the verifier can validate them fully.\n */\nexport interface SessionTokenClaims {\n  /** Issuer — always \"whatalo\" */\n  iss: \"whatalo\";\n  /** Audience — the app's client_id (marketplace_apps.slug) */\n  aud: string;\n  /** Subject — the store's public_id */\n  sub: string;\n  /** Expiration time (Unix seconds) */\n  exp: number;\n  /** Issued-at time (Unix seconds) */\n  iat: number;\n  /** JWT ID — unique nonce to prevent replay attacks */\n  jti: string;\n  /** Store public identifier (same as sub, kept explicit for SDK consumers) */\n  storeId: string;\n  /** App/plugin public identifier (slug) */\n  appId: string;\n  /** Permission scopes granted at install time */\n  scopes: string[];\n  /** app_installations.id for the specific install record */\n  installationId: string;\n}\n\n/** Output of signSessionToken — includes the raw token and its expiry. */\nexport interface SignedSessionToken {\n  /** Compact JWT string (header.payload.signature) */\n  token: string;\n  /** Expiration as Unix seconds (same as claims.exp) */\n  expiresAt: number;\n}\n\n// ---------------------------------------------------------------------------\n// Constants\n// ---------------------------------------------------------------------------\n\n/** Token lifetime in seconds. Short by design — the bridge auto-refreshes. */\nconst TOKEN_TTL_SECONDS = 300; // 5 minutes\n\n/** Fixed header for all session tokens (alg=HS256, typ=JWT). */\nconst HEADER_B64 = Buffer.from(\n  JSON.stringify({ alg: \"HS256\", typ: \"JWT\" }),\n).toString(\"base64url\");\n\n// ---------------------------------------------------------------------------\n// Internal helpers\n// ---------------------------------------------------------------------------\n\n/** Encodes an object as a base64url JSON string (no padding). */\nfunction encodeB64(obj: unknown): string {\n  return Buffer.from(JSON.stringify(obj)).toString(\"base64url\");\n}\n\n/** Decodes a base64url string to a plain object. Throws on malformed input. */\nfunction decodeB64<T>(encoded: string): T {\n  const json = Buffer.from(encoded, \"base64url\").toString(\"utf8\");\n  return JSON.parse(json) as T;\n}\n\n/**\n * Computes HMAC-SHA256 over `data` using `secret` and returns the hex digest.\n * Uses the app's client_secret as the key — never a platform-wide secret.\n */\nfunction computeHmac(data: string, secret: string): string {\n  return createHmac(\"sha256\", secret).update(data, \"utf8\").digest(\"hex\");\n}\n\n// ---------------------------------------------------------------------------\n// Public API\n// ---------------------------------------------------------------------------\n\n/**\n * Signs a session token for the given claims using the app's client_secret.\n *\n * @param payload - Token claims (storeId, appId, scopes, installationId, aud).\n *                  exp/iat/jti/iss are injected automatically.\n * @param clientSecret - The app's client_secret from marketplace_apps table.\n * @returns Signed JWT and its expiry timestamp.\n */\nexport function signSessionToken(\n  payload: Omit<SessionTokenClaims, \"iss\" | \"iat\" | \"exp\" | \"jti\">,\n  clientSecret: string,\n): SignedSessionToken {\n  if (!clientSecret || clientSecret.length === 0) {\n    throw new Error(\"client_secret must be a non-empty string\");\n  }\n\n  const now = Math.floor(Date.now() / 1000);\n  const exp = now + TOKEN_TTL_SECONDS;\n\n  const claims: SessionTokenClaims = {\n    iss: \"whatalo\",\n    aud: payload.aud,\n    sub: payload.sub,\n    iat: now,\n    exp,\n    // 16 random bytes → 32-char hex string used as the JWT ID (jti)\n    jti: randomBytes(16).toString(\"hex\"),\n    storeId: payload.storeId,\n    appId: payload.appId,\n    scopes: payload.scopes,\n    installationId: payload.installationId,\n  };\n\n  const payloadB64 = encodeB64(claims);\n  const signingInput = `${HEADER_B64}.${payloadB64}`;\n  const signature = computeHmac(signingInput, clientSecret);\n\n  return {\n    token: `${signingInput}.${signature}`,\n    expiresAt: exp,\n  };\n}\n\n/**\n * Verifies a session token previously issued by signSessionToken.\n *\n * Checks (in order):\n *   1. Token structure (3 parts separated by \".\")\n *   2. Header declares HS256 + JWT\n *   3. HMAC-SHA256 signature matches (constant-time comparison)\n *   4. Token has not expired\n *   5. Issuer is \"whatalo\"\n *   6. Required claims are present\n *\n * @param token - Compact JWT string from the plugin frontend.\n * @param clientSecret - The app's client_secret used to sign the original token.\n * @returns Decoded and validated SessionTokenClaims.\n * @throws Error with a descriptive message on any validation failure.\n */\nexport function verifySessionToken(\n  token: string,\n  clientSecret: string,\n): SessionTokenClaims {\n  if (!token || !clientSecret) {\n    throw new Error(\"Token and client_secret are required\");\n  }\n\n  const parts = token.split(\".\");\n  if (parts.length !== 3) {\n    throw new Error(\"Invalid token structure: expected header.payload.signature\");\n  }\n\n  const [headerB64, payloadB64, receivedSig] = parts as [string, string, string];\n\n  // 1. Validate header\n  let header: { alg?: string; typ?: string };\n  try {\n    header = decodeB64<{ alg?: string; typ?: string }>(headerB64);\n  } catch {\n    throw new Error(\"Invalid token: malformed header\");\n  }\n  if (header.alg !== \"HS256\" || header.typ !== \"JWT\") {\n    throw new Error(\"Invalid token: unsupported algorithm or type\");\n  }\n\n  // 2. Verify HMAC signature (constant-time to prevent timing attacks)\n  const signingInput = `${headerB64}.${payloadB64}`;\n  const expectedSig = computeHmac(signingInput, clientSecret);\n\n  // Re-HMAC both sides to normalize to a fixed-length buffer regardless of\n  // the received signature's actual length. This eliminates the timing\n  // side-channel that would otherwise leak whether lengths match.\n  const normalizeKey = expectedSig; // use expected sig as HMAC key for normalization\n  const receivedNorm = createHmac(\"sha256\", normalizeKey).update(receivedSig).digest();\n  const expectedNorm = createHmac(\"sha256\", normalizeKey).update(expectedSig).digest();\n\n  if (!timingSafeEqual(receivedNorm, expectedNorm)) {\n    throw new Error(\"Invalid token: signature mismatch\");\n  }\n\n  // 3. Decode claims\n  let claims: SessionTokenClaims;\n  try {\n    claims = decodeB64<SessionTokenClaims>(payloadB64);\n  } catch {\n    throw new Error(\"Invalid token: malformed payload\");\n  }\n\n  // 4. Check expiration (with 30-second clock skew tolerance for distributed systems)\n  const now = Math.floor(Date.now() / 1000);\n  const CLOCK_SKEW_SECONDS = 30;\n  if (typeof claims.exp !== \"number\" || claims.exp + CLOCK_SKEW_SECONDS <= now) {\n    throw new Error(\"Token has expired\");\n  }\n\n  // 5. Check issuer\n  if (claims.iss !== \"whatalo\") {\n    throw new Error(`Invalid token: unexpected issuer \"${claims.iss}\"`);\n  }\n\n  // 6. Validate required claims\n  const required: Array<keyof SessionTokenClaims> = [\n    \"aud\", \"sub\", \"iat\", \"jti\", \"storeId\", \"appId\", \"scopes\", \"installationId\",\n  ];\n  for (const key of required) {\n    if (claims[key] === undefined || claims[key] === null) {\n      throw new Error(`Invalid token: missing required claim \"${key}\"`);\n    }\n  }\n\n  if (!Array.isArray(claims.scopes)) {\n    throw new Error(\"Invalid token: scopes must be an array\");\n  }\n\n  return claims;\n}\n"],"mappings":"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","names":[]}

package/dist/session-token.d.cts

@@ -0,0 +1,77 @@
+/**
+ * Session Token — server-side only.
+ *
+ * Signs and verifies short-lived HMAC-SHA256 JWTs used by plugin iframes to
+ * authenticate against their own backend. The token is issued by the Whatalo
+ * admin host and forwarded by the plugin frontend to its server, which
+ * validates the signature using the app's client_secret.
+ *
+ * Architecture:
+ *   Admin host  ──issues──►  iframe (via App Bridge)
+ *   iframe frontend  ──sends──►  plugin backend
+ *   plugin backend  ──validates──►  calls Whatalo public API with its own key
+ *
+ * This module uses ONLY Node.js built-in `node:crypto`. No external dependencies.
+ * It must NEVER be imported in browser code (import from server entry points only).
+ */
+/**
+ * JWT claims embedded in every session token.
+ * All string fields are required so the verifier can validate them fully.
+ */
+interface SessionTokenClaims {
+    /** Issuer — always "whatalo" */
+    iss: "whatalo";
+    /** Audience — the app's client_id (marketplace_apps.slug) */
+    aud: string;
+    /** Subject — the store's public_id */
+    sub: string;
+    /** Expiration time (Unix seconds) */
+    exp: number;
+    /** Issued-at time (Unix seconds) */
+    iat: number;
+    /** JWT ID — unique nonce to prevent replay attacks */
+    jti: string;
+    /** Store public identifier (same as sub, kept explicit for SDK consumers) */
+    storeId: string;
+    /** App/plugin public identifier (slug) */
+    appId: string;
+    /** Permission scopes granted at install time */
+    scopes: string[];
+    /** app_installations.id for the specific install record */
+    installationId: string;
+}
+/** Output of signSessionToken — includes the raw token and its expiry. */
+interface SignedSessionToken {
+    /** Compact JWT string (header.payload.signature) */
+    token: string;
+    /** Expiration as Unix seconds (same as claims.exp) */
+    expiresAt: number;
+}
+/**
+ * Signs a session token for the given claims using the app's client_secret.
+ *
+ * @param payload - Token claims (storeId, appId, scopes, installationId, aud).
+ *                  exp/iat/jti/iss are injected automatically.
+ * @param clientSecret - The app's client_secret from marketplace_apps table.
+ * @returns Signed JWT and its expiry timestamp.
+ */
+declare function signSessionToken(payload: Omit<SessionTokenClaims, "iss" | "iat" | "exp" | "jti">, clientSecret: string): SignedSessionToken;
+/**
+ * Verifies a session token previously issued by signSessionToken.
+ *
+ * Checks (in order):
+ *   1. Token structure (3 parts separated by ".")
+ *   2. Header declares HS256 + JWT
+ *   3. HMAC-SHA256 signature matches (constant-time comparison)
+ *   4. Token has not expired
+ *   5. Issuer is "whatalo"
+ *   6. Required claims are present
+ *
+ * @param token - Compact JWT string from the plugin frontend.
+ * @param clientSecret - The app's client_secret used to sign the original token.
+ * @returns Decoded and validated SessionTokenClaims.
+ * @throws Error with a descriptive message on any validation failure.
+ */
+declare function verifySessionToken(token: string, clientSecret: string): SessionTokenClaims;
+
+export { type SessionTokenClaims, type SignedSessionToken, signSessionToken, verifySessionToken };

package/dist/session-token.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Session Token — server-side only.
+ *
+ * Signs and verifies short-lived HMAC-SHA256 JWTs used by plugin iframes to
+ * authenticate against their own backend. The token is issued by the Whatalo
+ * admin host and forwarded by the plugin frontend to its server, which
+ * validates the signature using the app's client_secret.
+ *
+ * Architecture:
+ *   Admin host  ──issues──►  iframe (via App Bridge)
+ *   iframe frontend  ──sends──►  plugin backend
+ *   plugin backend  ──validates──►  calls Whatalo public API with its own key
+ *
+ * This module uses ONLY Node.js built-in `node:crypto`. No external dependencies.
+ * It must NEVER be imported in browser code (import from server entry points only).
+ */
+/**
+ * JWT claims embedded in every session token.
+ * All string fields are required so the verifier can validate them fully.
+ */
+interface SessionTokenClaims {
+    /** Issuer — always "whatalo" */
+    iss: "whatalo";
+    /** Audience — the app's client_id (marketplace_apps.slug) */
+    aud: string;
+    /** Subject — the store's public_id */
+    sub: string;
+    /** Expiration time (Unix seconds) */
+    exp: number;
+    /** Issued-at time (Unix seconds) */
+    iat: number;
+    /** JWT ID — unique nonce to prevent replay attacks */
+    jti: string;
+    /** Store public identifier (same as sub, kept explicit for SDK consumers) */
+    storeId: string;
+    /** App/plugin public identifier (slug) */
+    appId: string;
+    /** Permission scopes granted at install time */
+    scopes: string[];
+    /** app_installations.id for the specific install record */
+    installationId: string;
+}
+/** Output of signSessionToken — includes the raw token and its expiry. */
+interface SignedSessionToken {
+    /** Compact JWT string (header.payload.signature) */
+    token: string;
+    /** Expiration as Unix seconds (same as claims.exp) */
+    expiresAt: number;
+}
+/**
+ * Signs a session token for the given claims using the app's client_secret.
+ *
+ * @param payload - Token claims (storeId, appId, scopes, installationId, aud).
+ *                  exp/iat/jti/iss are injected automatically.
+ * @param clientSecret - The app's client_secret from marketplace_apps table.
+ * @returns Signed JWT and its expiry timestamp.
+ */
+declare function signSessionToken(payload: Omit<SessionTokenClaims, "iss" | "iat" | "exp" | "jti">, clientSecret: string): SignedSessionToken;
+/**
+ * Verifies a session token previously issued by signSessionToken.
+ *
+ * Checks (in order):
+ *   1. Token structure (3 parts separated by ".")
+ *   2. Header declares HS256 + JWT
+ *   3. HMAC-SHA256 signature matches (constant-time comparison)
+ *   4. Token has not expired
+ *   5. Issuer is "whatalo"
+ *   6. Required claims are present
+ *
+ * @param token - Compact JWT string from the plugin frontend.
+ * @param clientSecret - The app's client_secret used to sign the original token.
+ * @returns Decoded and validated SessionTokenClaims.
+ * @throws Error with a descriptive message on any validation failure.
+ */
+declare function verifySessionToken(token: string, clientSecret: string): SessionTokenClaims;
+
+export { type SessionTokenClaims, type SignedSessionToken, signSessionToken, verifySessionToken };

package/dist/session-token.mjs

@@ -0,0 +1,108 @@
+// src/session-token.ts
+import { createHmac, timingSafeEqual, randomBytes } from "crypto";
+var TOKEN_TTL_SECONDS = 300;
+var HEADER_B64 = Buffer.from(
+  JSON.stringify({ alg: "HS256", typ: "JWT" })
+).toString("base64url");
+function encodeB64(obj) {
+  return Buffer.from(JSON.stringify(obj)).toString("base64url");
+}
+function decodeB64(encoded) {
+  const json = Buffer.from(encoded, "base64url").toString("utf8");
+  return JSON.parse(json);
+}
+function computeHmac(data, secret) {
+  return createHmac("sha256", secret).update(data, "utf8").digest("hex");
+}
+function signSessionToken(payload, clientSecret) {
+  if (!clientSecret || clientSecret.length === 0) {
+    throw new Error("client_secret must be a non-empty string");
+  }
+  const now = Math.floor(Date.now() / 1e3);
+  const exp = now + TOKEN_TTL_SECONDS;
+  const claims = {
+    iss: "whatalo",
+    aud: payload.aud,
+    sub: payload.sub,
+    iat: now,
+    exp,
+    // 16 random bytes → 32-char hex string used as the JWT ID (jti)
+    jti: randomBytes(16).toString("hex"),
+    storeId: payload.storeId,
+    appId: payload.appId,
+    scopes: payload.scopes,
+    installationId: payload.installationId
+  };
+  const payloadB64 = encodeB64(claims);
+  const signingInput = `${HEADER_B64}.${payloadB64}`;
+  const signature = computeHmac(signingInput, clientSecret);
+  return {
+    token: `${signingInput}.${signature}`,
+    expiresAt: exp
+  };
+}
+function verifySessionToken(token, clientSecret) {
+  if (!token || !clientSecret) {
+    throw new Error("Token and client_secret are required");
+  }
+  const parts = token.split(".");
+  if (parts.length !== 3) {
+    throw new Error("Invalid token structure: expected header.payload.signature");
+  }
+  const [headerB64, payloadB64, receivedSig] = parts;
+  let header;
+  try {
+    header = decodeB64(headerB64);
+  } catch {
+    throw new Error("Invalid token: malformed header");
+  }
+  if (header.alg !== "HS256" || header.typ !== "JWT") {
+    throw new Error("Invalid token: unsupported algorithm or type");
+  }
+  const signingInput = `${headerB64}.${payloadB64}`;
+  const expectedSig = computeHmac(signingInput, clientSecret);
+  const normalizeKey = expectedSig;
+  const receivedNorm = createHmac("sha256", normalizeKey).update(receivedSig).digest();
+  const expectedNorm = createHmac("sha256", normalizeKey).update(expectedSig).digest();
+  if (!timingSafeEqual(receivedNorm, expectedNorm)) {
+    throw new Error("Invalid token: signature mismatch");
+  }
+  let claims;
+  try {
+    claims = decodeB64(payloadB64);
+  } catch {
+    throw new Error("Invalid token: malformed payload");
+  }
+  const now = Math.floor(Date.now() / 1e3);
+  const CLOCK_SKEW_SECONDS = 30;
+  if (typeof claims.exp !== "number" || claims.exp + CLOCK_SKEW_SECONDS <= now) {
+    throw new Error("Token has expired");
+  }
+  if (claims.iss !== "whatalo") {
+    throw new Error(`Invalid token: unexpected issuer "${claims.iss}"`);
+  }
+  const required = [
+    "aud",
+    "sub",
+    "iat",
+    "jti",
+    "storeId",
+    "appId",
+    "scopes",
+    "installationId"
+  ];
+  for (const key of required) {
+    if (claims[key] === void 0 || claims[key] === null) {
+      throw new Error(`Invalid token: missing required claim "${key}"`);
+    }
+  }
+  if (!Array.isArray(claims.scopes)) {
+    throw new Error("Invalid token: scopes must be an array");
+  }
+  return claims;
+}
+export {
+  signSessionToken,
+  verifySessionToken
+};
+//# sourceMappingURL=session-token.mjs.map

package/dist/session-token.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/session-token.ts"],"sourcesContent":["/**\n * Session Token — server-side only.\n *\n * Signs and verifies short-lived HMAC-SHA256 JWTs used by plugin iframes to\n * authenticate against their own backend. The token is issued by the Whatalo\n * admin host and forwarded by the plugin frontend to its server, which\n * validates the signature using the app's client_secret.\n *\n * Architecture:\n *   Admin host  ──issues──►  iframe (via App Bridge)\n *   iframe frontend  ──sends──►  plugin backend\n *   plugin backend  ──validates──►  calls Whatalo public API with its own key\n *\n * This module uses ONLY Node.js built-in `node:crypto`. No external dependencies.\n * It must NEVER be imported in browser code (import from server entry points only).\n */\n\nimport { createHmac, timingSafeEqual, randomBytes } from \"node:crypto\";\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\n/**\n * JWT claims embedded in every session token.\n * All string fields are required so the verifier can validate them fully.\n */\nexport interface SessionTokenClaims {\n  /** Issuer — always \"whatalo\" */\n  iss: \"whatalo\";\n  /** Audience — the app's client_id (marketplace_apps.slug) */\n  aud: string;\n  /** Subject — the store's public_id */\n  sub: string;\n  /** Expiration time (Unix seconds) */\n  exp: number;\n  /** Issued-at time (Unix seconds) */\n  iat: number;\n  /** JWT ID — unique nonce to prevent replay attacks */\n  jti: string;\n  /** Store public identifier (same as sub, kept explicit for SDK consumers) */\n  storeId: string;\n  /** App/plugin public identifier (slug) */\n  appId: string;\n  /** Permission scopes granted at install time */\n  scopes: string[];\n  /** app_installations.id for the specific install record */\n  installationId: string;\n}\n\n/** Output of signSessionToken — includes the raw token and its expiry. */\nexport interface SignedSessionToken {\n  /** Compact JWT string (header.payload.signature) */\n  token: string;\n  /** Expiration as Unix seconds (same as claims.exp) */\n  expiresAt: number;\n}\n\n// ---------------------------------------------------------------------------\n// Constants\n// ---------------------------------------------------------------------------\n\n/** Token lifetime in seconds. Short by design — the bridge auto-refreshes. */\nconst TOKEN_TTL_SECONDS = 300; // 5 minutes\n\n/** Fixed header for all session tokens (alg=HS256, typ=JWT). */\nconst HEADER_B64 = Buffer.from(\n  JSON.stringify({ alg: \"HS256\", typ: \"JWT\" }),\n).toString(\"base64url\");\n\n// ---------------------------------------------------------------------------\n// Internal helpers\n// ---------------------------------------------------------------------------\n\n/** Encodes an object as a base64url JSON string (no padding). */\nfunction encodeB64(obj: unknown): string {\n  return Buffer.from(JSON.stringify(obj)).toString(\"base64url\");\n}\n\n/** Decodes a base64url string to a plain object. Throws on malformed input. */\nfunction decodeB64<T>(encoded: string): T {\n  const json = Buffer.from(encoded, \"base64url\").toString(\"utf8\");\n  return JSON.parse(json) as T;\n}\n\n/**\n * Computes HMAC-SHA256 over `data` using `secret` and returns the hex digest.\n * Uses the app's client_secret as the key — never a platform-wide secret.\n */\nfunction computeHmac(data: string, secret: string): string {\n  return createHmac(\"sha256\", secret).update(data, \"utf8\").digest(\"hex\");\n}\n\n// ---------------------------------------------------------------------------\n// Public API\n// ---------------------------------------------------------------------------\n\n/**\n * Signs a session token for the given claims using the app's client_secret.\n *\n * @param payload - Token claims (storeId, appId, scopes, installationId, aud).\n *                  exp/iat/jti/iss are injected automatically.\n * @param clientSecret - The app's client_secret from marketplace_apps table.\n * @returns Signed JWT and its expiry timestamp.\n */\nexport function signSessionToken(\n  payload: Omit<SessionTokenClaims, \"iss\" | \"iat\" | \"exp\" | \"jti\">,\n  clientSecret: string,\n): SignedSessionToken {\n  if (!clientSecret || clientSecret.length === 0) {\n    throw new Error(\"client_secret must be a non-empty string\");\n  }\n\n  const now = Math.floor(Date.now() / 1000);\n  const exp = now + TOKEN_TTL_SECONDS;\n\n  const claims: SessionTokenClaims = {\n    iss: \"whatalo\",\n    aud: payload.aud,\n    sub: payload.sub,\n    iat: now,\n    exp,\n    // 16 random bytes → 32-char hex string used as the JWT ID (jti)\n    jti: randomBytes(16).toString(\"hex\"),\n    storeId: payload.storeId,\n    appId: payload.appId,\n    scopes: payload.scopes,\n    installationId: payload.installationId,\n  };\n\n  const payloadB64 = encodeB64(claims);\n  const signingInput = `${HEADER_B64}.${payloadB64}`;\n  const signature = computeHmac(signingInput, clientSecret);\n\n  return {\n    token: `${signingInput}.${signature}`,\n    expiresAt: exp,\n  };\n}\n\n/**\n * Verifies a session token previously issued by signSessionToken.\n *\n * Checks (in order):\n *   1. Token structure (3 parts separated by \".\")\n *   2. Header declares HS256 + JWT\n *   3. HMAC-SHA256 signature matches (constant-time comparison)\n *   4. Token has not expired\n *   5. Issuer is \"whatalo\"\n *   6. Required claims are present\n *\n * @param token - Compact JWT string from the plugin frontend.\n * @param clientSecret - The app's client_secret used to sign the original token.\n * @returns Decoded and validated SessionTokenClaims.\n * @throws Error with a descriptive message on any validation failure.\n */\nexport function verifySessionToken(\n  token: string,\n  clientSecret: string,\n): SessionTokenClaims {\n  if (!token || !clientSecret) {\n    throw new Error(\"Token and client_secret are required\");\n  }\n\n  const parts = token.split(\".\");\n  if (parts.length !== 3) {\n    throw new Error(\"Invalid token structure: expected header.payload.signature\");\n  }\n\n  const [headerB64, payloadB64, receivedSig] = parts as [string, string, string];\n\n  // 1. Validate header\n  let header: { alg?: string; typ?: string };\n  try {\n    header = decodeB64<{ alg?: string; typ?: string }>(headerB64);\n  } catch {\n    throw new Error(\"Invalid token: malformed header\");\n  }\n  if (header.alg !== \"HS256\" || header.typ !== \"JWT\") {\n    throw new Error(\"Invalid token: unsupported algorithm or type\");\n  }\n\n  // 2. Verify HMAC signature (constant-time to prevent timing attacks)\n  const signingInput = `${headerB64}.${payloadB64}`;\n  const expectedSig = computeHmac(signingInput, clientSecret);\n\n  // Re-HMAC both sides to normalize to a fixed-length buffer regardless of\n  // the received signature's actual length. This eliminates the timing\n  // side-channel that would otherwise leak whether lengths match.\n  const normalizeKey = expectedSig; // use expected sig as HMAC key for normalization\n  const receivedNorm = createHmac(\"sha256\", normalizeKey).update(receivedSig).digest();\n  const expectedNorm = createHmac(\"sha256\", normalizeKey).update(expectedSig).digest();\n\n  if (!timingSafeEqual(receivedNorm, expectedNorm)) {\n    throw new Error(\"Invalid token: signature mismatch\");\n  }\n\n  // 3. Decode claims\n  let claims: SessionTokenClaims;\n  try {\n    claims = decodeB64<SessionTokenClaims>(payloadB64);\n  } catch {\n    throw new Error(\"Invalid token: malformed payload\");\n  }\n\n  // 4. Check expiration (with 30-second clock skew tolerance for distributed systems)\n  const now = Math.floor(Date.now() / 1000);\n  const CLOCK_SKEW_SECONDS = 30;\n  if (typeof claims.exp !== \"number\" || claims.exp + CLOCK_SKEW_SECONDS <= now) {\n    throw new Error(\"Token has expired\");\n  }\n\n  // 5. Check issuer\n  if (claims.iss !== \"whatalo\") {\n    throw new Error(`Invalid token: unexpected issuer \"${claims.iss}\"`);\n  }\n\n  // 6. Validate required claims\n  const required: Array<keyof SessionTokenClaims> = [\n    \"aud\", \"sub\", \"iat\", \"jti\", \"storeId\", \"appId\", \"scopes\", \"installationId\",\n  ];\n  for (const key of required) {\n    if (claims[key] === undefined || claims[key] === null) {\n      throw new Error(`Invalid token: missing required claim \"${key}\"`);\n    }\n  }\n\n  if (!Array.isArray(claims.scopes)) {\n    throw new Error(\"Invalid token: scopes must be an array\");\n  }\n\n  return claims;\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@whatalo/plugin-sdk",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "type": "module",
   "license": "MIT",
   "description": "Official TypeScript SDK for building Whatalo plugins",
@@ -46,49 +46,45 @@
       "types": "./dist/bridge/index.d.ts",
       "import": "./dist/bridge/index.mjs",
       "require": "./dist/bridge/index.cjs"
+    },
+    "./session-token": {
+      "types": "./dist/session-token.d.ts",
+      "import": "./dist/session-token.mjs",
+      "require": "./dist/session-token.cjs"
+    },
+    "./server": {
+      "types": "./dist/server/verify-session-token.d.ts",
+      "import": "./dist/server/verify-session-token.mjs",
+      "require": "./dist/server/verify-session-token.cjs"
     }
   },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ],
+  "files": ["dist", "README.md", "LICENSE"],
   "publishConfig": {
     "access": "public"
   },
-  "keywords": [
-    "whatalo",
-    "plugin-sdk",
-    "api",
-    "ecommerce",
-    "latam",
-    "cod"
-  ],
+  "keywords": ["whatalo", "plugin-sdk", "api", "ecommerce", "latam", "cod"],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "vitest": "vitest",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "type-check": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "pnpm build"
+  },
   "peerDependencies": {
     "react": ">=18",
     "react-dom": ">=18"
   },
   "peerDependenciesMeta": {
-    "react": {
-      "optional": false
-    },
-    "react-dom": {
-      "optional": false
-    }
+    "react": { "optional": false },
+    "react-dom": { "optional": false }
   },
   "devDependencies": {
     "@types/react": "^19.0.0",
     "tsup": "^8.0.0",
     "typescript": "^5.7.0",
     "vitest": "^3.2.4"
-  },
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "vitest": "vitest",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "type-check": "tsc --noEmit",
-    "clean": "rm -rf dist"
   }
-}
+}